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.

There is no TLS underneath, so the server speaks plain http only.

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¶

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