Module ReWeb.Response

a header X-Client-Id: 1 is represented as: [("x-client-id", "1")].

See Httpaf.Status for valid statuses.

Possible issues with pulling a message from the incoming messages stream.

pull(timeout_s) asynchronously gets the next message from the WebSocket if there is any, with a timeout in seconds of timeout_s. If it doesn't time out it returns Some string, otherwise None.

push(response) pushes the string response to the WebSocket client.

handler(pull, push) is an asynchronous callback that manages the WS from the server side. The WS will shut down from the server side as soon as handler exits, so if you want to keep it open you need to make it call itself recursively. Because the call will be tail-recursive, OCaml's tail-call elimination takes care of stack memory use.

A WebSocket response.

Response type, can be an HTTP or a WebSocket response. Many of the functions below work with either HTTP or WebSocket responses, and some with only one or the other. This is enforced at the type level.

add_cookie(cookie, response) returns a response with a cookie cookie added to the original response.

add_cookies(cookies, response) returns a response with the cookies added to the original response.

add_header(?replace, ~name, ~value, response) returns a response with a header name with value value added to the original response. If the response already contains the header, then it is replaced only if replace is true, which is the default.

add_headers(headers, response) returns a response with the headers added to the end of the original response's header list.

add_headers_multi(headers_multi, response) returns a response with headers_multi added to the end of the original response's header list.

header(name, request) gets the last value corresponding to the given header, if present.

headers(name, request) gets all the values corresponding to the given header.

of_file(?status, ?content_type, ?headers, ?cookies, file_name) responds with the contents of file_name, which is a relative or absolute path, with HTTP response code status and content-type header content_type.

If the file is not found, responds with a 404 Not Found status and an appropriate message.

Warning this function maps the entire file into memory. Don't use it for files larger than memory.

of_http(~status, ~headers, body) responds with an HTTP response composed of status, headers, and body.

of_redirect(?content_type, ?body, location) responds with an HTTP redirect response to the new location, with an optional content_type (defaulting to text/plain) and body (defaulting to an empty body).

of_status(?content_type, ?headers, ?cookies, ?message, status) responds with a standard boilerplate response message based on the content_type and status. content_type defaults to `text. The boilerplate message can be overridden by message if present.

of_view(?status, ?content_type, ?headers, ?cookies, view) responds with a rendered body as per the view function. The view is a function that takes a 'printer' function (string -> unit) as a parameter and 'prints' (i.e. renders piecemeal) strings to it. These strings are pushed out as they are rendered.

The difference from of_html, of_binary, and the other functions is that those hold the entire response in memory before sending it to the client, while of_view holds only each piece of the response as it is streamed out.

of_websocket(?headers, handler) is an open WebSocket response. Optionally you can pass along extra headers which will be sent to the client when opening the WS.

Warning it can be a little tricky to write a completely asynchronous WebSocket handler correctly. Be sure to read the reference documentation above, and the manual, carefully.

Note OCaml strings are un-encoded byte arrays, and ReWeb treats all incoming and outgoing WebSocket data as such--even if the client is sending UTF-8 encoded text format (see https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API/Writing_WebSocket_servers#Format). It's up to you as the WebSocket handler writer to encode/decode them as necessary.