Http Server¶

1

import "std/net/http-server";

HttpServer struct¶

A blocking HTTP/1.1 server, built on the plain TCP sockets of "std/net/socket".

Requests are served one at a time on the thread that drives the server: run keeps serving until stop is called, while handleNextRequest serves a single connection and hands control back, so the caller can weave the server into a loop of its own. Every connection is answered with Connection: close and closed afterwards.

Routing is exact-match on the path of the request target, so "/a" and "/a/" are different routes and the query string never takes part in the match. A path that is registered for some other method answers 405 instead of 404, and a HEAD request falls back to the GET route of the same path, with the body dropped again afterwards.

The server speaks plain http by default. Call useTls with a certificate and private key (before start) to serve https instead - every connection is then TLS-handshaked (see "std/net/tls") before its request is read and its response is written.

Note on handlers: a handler is stored in a Lambda (see "std/type/lambda"), which relocates the captures of the lambda onto the heap with a shallow copy. A handler may therefore capture plain values, but it must not capture a String, a container or anything else that owns memory, since only the owner itself would free it. Fixed content belongs into serve, and anything else into a global or into the request itself.

Fields¶

Constructors¶

ctor¶

1

public p HttpServer.ctor(unsigned short port = HTTP_PORT_FALLBACK)

Constructs a server for the given port. Nothing is bound yet - that happens in start.

Parameters

dtor¶

1

public p HttpServer.dtor()

Closes the listening socket if the server is still up

Methods¶

useTls¶

1

public f<Result<bool>> HttpServer.useTls(string certFile, string keyFile)

Switches the server from plain http to https: every connection accepted from here on is TLS-handshaked with the given certificate before its request is read.

Must be called before start, since the listening socket itself is unaffected - only what happens to a connection right after it is accepted changes.

Parameters

Returns: Result<bool> — true once TLS is configured, or an error describing why it could not be

route¶

1

public p HttpServer.route(HttpMethod method, string path, p(const HttpRequest&, HttpResponse&) handler)

Registers a handler for a method and path

Parameters

get¶

1

public p HttpServer.get(string path, p(const HttpRequest&, HttpResponse&) handler)

Registers a GET handler for a path. HEAD requests for the same path are answered from it as well.

Parameters

post¶

1

public p HttpServer.post(string path, p(const HttpRequest&, HttpResponse&) handler)

Registers a POST handler for a path

Parameters

put¶

1

public p HttpServer.put(string path, p(const HttpRequest&, HttpResponse&) handler)

Registers a PUT handler for a path

Parameters

patch¶

1

public p HttpServer.patch(string path, p(const HttpRequest&, HttpResponse&) handler)

Registers a PATCH handler for a path

Parameters

delete¶

1

public p HttpServer.delete(string path, p(const HttpRequest&, HttpResponse&) handler)

Registers a DELETE handler for a path

Parameters

serve¶

1

public p HttpServer.serve(string path, string content, string contentType = CONTENT_TYPE_HTML)

Registers a route that answers a path with a fixed piece of content

Parameters

serve¶

1

public p HttpServer.serve(string path, const String& content, string contentType = CONTENT_TYPE_HTML)

Registers a route that answers a path with a fixed piece of content

Parameters

setNotFoundHandler¶

1

public p HttpServer.setNotFoundHandler(p(const HttpRequest&, HttpResponse&) handler)

Registers the handler that answers requests no route matches. Without one, unmatched requests are answered with a plain 404.

Parameters

start¶

1

public f<Result<bool>> HttpServer.start(int connectionBacklog = DEFAULT_CONNECTION_BACKLOG)

Binds the configured port and starts listening on it

Parameters

Returns: Result<bool> — true once the server listens, or an error describing why it could not

handleNextRequest¶

1

public f<Result<bool>> HttpServer.handleNextRequest()

Accepts a single connection, answers the request on it and closes it again.

A request that cannot be parsed is answered with 400 rather than being dropped silently, so a confused client learns what happened.

Returns: Result<bool> — true if a request was served, or an error if the connection could not be accepted

run¶

1

public f<Result<bool>> HttpServer.run()

Serves connections until stop is called or a connection cannot be accepted.

The stop flag is checked between connections, so a stop from another thread takes effect once the connection that is currently being served is done.

Returns: Result<bool> — true if the loop ended through stop, or an error if a connection could not be accepted

stop¶

1

public p HttpServer.stop()

Asks a running run loop to end once the connection it is serving is done

isRunning¶

1

public f<bool> HttpServer.isRunning()

Checks whether a run loop is currently serving

Returns: bool

isListening¶

1

public f<bool> HttpServer.isListening()

Checks whether the server holds a listening socket

Returns: bool

close¶

1

public p HttpServer.close()

Closes the listening socket. The server can be started again afterwards.

Returns: Closing the socket was successful or not