Module Tiny_httpd_server

A HTTP server. See create for more details.

Create a new webserver.

The server will not do anything until run is called on it. Before starting the server, one can use add_path_handler and set_top_handler to specify how to handle incoming requests.

• parameter masksigpipe

  if true, block the signal Sys.sigpipe which otherwise tends to kill client threads when they try to write on broken sockets. Default: true.

• parameter buf_size

  size for buffers (since 0.11)

• parameter new_thread

  a function used to spawn a new thread to handle a new client connection. By default it is Thread.create but one could use a thread pool instead.

• parameter middlewares

  see add_middleware for more details.

• parameter max_connections

  maximum number of simultaneous connections.

• parameter timeout

  connection is closed if the socket does not do read or write for the amount of second. Default: 0.0 which means no timeout. timeout is not recommended when using proxy.

• parameter addr

  address (IPv4 or IPv6) to listen on. Default "127.0.0.1".

• parameter port

  to listen on. Default 8080.

• parameter sock

  an existing socket given to the server to listen on, e.g. by systemd on Linux (or launchd on macOS). If passed in, this socket will be used instead of the addr and port. If not passed in, those will be used. This parameter exists since 0.10.

• parameter get_time_s

  obtain the current timestamp in seconds. This parameter exists since 0.11.

Address on which the server listens.

is_ipv6 server returns true iff the address of the server is an IPv6 address.

• since 0.3

Port on which the server listens.

Number of active connections

Add a callback for every request. The callback can provide a stream transformer and a new request (with modified headers, typically). A possible use is to handle decompression by looking for a Transfer-Encoding header and returning a stream transformer that decompresses on the fly.

• deprecated

  use add_middleware instead

Add a callback for every request/response pair. Similarly to add_encode_response_cb the callback can return a new response, for example to compress it. The callback is given the query with only its headers, as well as the current response.

• deprecated

  use add_middleware instead

Add a middleware to every request/response pair.

• parameter stage

  specify when middleware applies. Encoding comes first (outermost layer), then stages in increasing order.

• raises Invalid_argument

  if stage is `Stage n where n < 1

• since 0.11

Setup a handler called by default.

This handler is called with any request not accepted by any handler installed via add_path_handler. If no top handler is installed, unhandled paths will return a 404 not found.

add_route_handler server Route.(exact "path" @/ string @/ int @/ return) f calls f "foo" 42 request when a request with path "path/foo/42/" is received.

Note that the handlers are called in the reverse order of their addition, so the last registered handler can override previously registered ones.

• parameter meth

  if provided, only accept requests with the given method. Typically one could react to `GET or `PUT.

• parameter accept

  should return Ok() if the given request (before its body is read) should be accepted, Error (code,message) if it's to be rejected (e.g. because its content is too big, or for some permission error). See the http_of_dir program for an example of how to use accept to filter uploads that are too large before the upload even starts. The default always returns Ok(), i.e. it accepts all requests.

• since 0.6

Similar to add_route_handler, but where the body of the request is a stream of bytes that has not been read yet. This is useful when one wants to stream the body directly into a parser, json decoder (such as Jsonm) or into a file.

• since 0.6

A server-side function to generate of Server-sent events.

Server-sent event generator

• since 0.9

Add a handler on an endpoint, that serves server-sent events.

The callback is given a generator that can be used to send events as it pleases. The connection is always closed by the client, and the accepted method is always GET. This will set the header "content-type" to "text/event-stream" automatically and reply with a 200 immediately. See server_sent_generator for more details.

This handler stays on the original thread (it is synchronous).

• since 0.9

Ask the server to stop. This might not have an immediate effect as run might currently be waiting on IO.

Run the main loop of the server, listening on a socket described at the server's creation time, using new_thread to start a thread for each new client.

This returns Ok () if the server exits gracefully, or Error e if it exits with an error.