package dream

HTTP requests, such as GET /something HTTP/1.1. See Requests.

HTTP responses, such as 200 OK. See Responses.

Handlers are asynchronous functions from requests to responses. Example 1-hello shows the simplest handler, an anonymous function which we pass to Dream.run. This creates a complete Web server! You can also see the Reason version in example r-hello.

let () =
  Dream.run (fun _ ->
    Dream.html "Good morning, world!")

Middlewares are functions that take a handler, and run some code before or after — producing a “bigger” handler. Example 2-middleware inserts the Dream.logger middleware into a Web app:

let () =
  Dream.run
  @@ Dream.logger
  @@ fun _ -> Dream.html "Good morning, world!"

Examples 4-counter and 5-promise show user-defined middlewares:

let count_requests inner_handler request =
  count := !count + 1;
  inner_handler request

Routes tell Dream.router which handler to select for each request. See Routing and example 3-router. Routes are created by helpers such as Dream.get and Dream.scope:

Dream.router [
  Dream.scope "/admin" [Dream.memory_sessions] [
    Dream.get "/" admin_handler;
    Dream.get "/logout" admin_logout_handler;
  ];
]

The three handler-related types have a vaguely algebraic interpretation:

• Literal handlers are atoms.
• middleware is for sequential composition (product-like).
• route is for alternative composition (sum-like).

Dream.scope implements a distributive law.

'a message, pronounced “any message,” allows some functions to take either request or response as arguments, because both are defined in terms of 'a message. For example, in Headers:

val Dream.header : string -> 'a message -> string option

Type parameters for message for request and response, respectively. These are “phantom” types. They have no meaning other than they are different from each other. Dream only ever creates incoming message and outgoing message. incoming and outgoing are never mentioned again in the docs.

Dream uses Lwt for promises and asynchronous I/O. See example 5-promise.

HTTP request methods. See RFC 7231 §4.2, RFC 5789 §2, and MDN.

Evaluates to a string representation of the given method. For example, `GET is converted to "GET".

Evaluates to the method_ corresponding to the given method string.

Compares two methods, such that equal methods are detected even if one is represented as a string. For example,

Dream.methods_equal `GET (`Method "GET") = true

Converts methods represented as strings to variants. Methods generated by Dream are always normalized.

Dream.normalize_method (`Method "GET") = `GET

Informational (1xx) status codes. See RFC 7231 §6.2 and MDN. 101 Switching Protocols is generated internally by Dream.websocket. It is usually not necessary to use it directly.

Successful (2xx) status codes. See RFC 7231 §6.3, RFC 7233 §4.1 and MDN. The most common is 200 OK.

Redirection (3xx) status codes. See RFC 7231 §6.4 and RFC 7538 §3, and MDN. Use 303 See Other to direct clients to follow up with a GET request, especially after a form submission. Use 301 Moved Permanently for permanent redirections.

Client error (4xx) status codes. The most common are 400 Bad Request, 401 Unauthorized, 403 Forbidden, and, of course, 404 Not Found.

See MDN, and

• RFC 7231 §6.5 for most client error status codes.
• RFC 7233 §4.4 for 416 Range Not Satisfiable.
• RFC 7540 §9.1.2 for 421 Misdirected Request.
• RFC 8470 §5.2 for 425 Too Early.
• RFC 6585 for 428 Precondition Required, 429 Too Many Requests, and 431 Request Headers Too Large.
• RFC 7725 for 451 Unavailable For Legal Reasons.

Server error (5xx) status codes. See RFC 7231 §6.6 and MDN. The most common of these is 500 Internal Server Error.

Sum of all the status codes declared above.

Status codes, including codes directly represented as integers. See the types above for the full list and references.

Evaluates to a string representation of the given status. For example, `Not_Found and `Status 404 are both converted to "Not Found". Numbers are used for unknown status codes. For example, `Status 567 is converted to "567".

Converts known status codes to their string representations. Evaluates to None for unknown status codes.

Evaluates to the numeric value of the given status code.

Evaluates to the symbolic representation of the status code with the given number.

Evaluates to true if the given status is either from type Dream.informational, or is in the range `Status 100 — `Status 199.

Like Dream.is_informational, but for type Dream.successful and numeric codes 2xx.

Like Dream.is_informational, but for type Dream.redirection and numeric codes 3xx.

Like Dream.is_informational, but for type Dream.client_error and numeric codes 4xx.

Like Dream.is_informational, but for type Dream.server_error and numeric codes 5xx.

Compares two status codes, such that equal codes are detected even if one is represented as a number. For example,

Dream.status_codes_equal `Not_Found (`Status 404) = true

Converts status codes represented as numbers to variants. Status codes generated by Dream are always normalized.

Dream.normalize_status (`Status 404) = `Not_Found

Client sending the request. For example, "127.0.0.1:56001".

Whether the request was sent over HTTPS.

Request method. For example, `GET.

Request target. For example, "/foo/bar". See Dream.path.

Parsed request path. For example, "foo"; "bar".

Protocol version. (1, 1) for HTTP/1.1 and (2, 0) for HTTP/2.

Replaces the client. See Dream.client.

Replaces the method. See Dream.method_.

Replaces the path. See Dream.path.

Replaces the version. See Dream.version.

First query parameter with the given name. See RFC 3986 §3.4 and example w-query.

All query parameters with the given name.

Entire query string as a name-value list.

Creates a new response with the given string as body. ~code and ~status are two ways to specify the status code, which is 200 OK by default. The headers are empty by default.

Note that browsers may interpret lack of a Content-Type: header as if its value were application/octet-stream or text/html; charset=us-ascii, which will prevent correct interpretation of UTF-8 strings. Either add a Content-Type: header using ~headers or Dream.add_header, or use a wrapper like Dream.html. The modern Content-Type: for HTML is text/html; charset=utf-8. See Dream.text_html.

Same as Dream.response, but the new response is wrapped in a promise.

Same as Dream.respond, but adds Content-Type: text/html; charset=utf-8. See Dream.text_html.

Same as Dream.respond, but adds Content-Type: application/json. See Dream.application_json.

Creates a new response. Adds a Location: header with the given string. The default status code is 303 See Other, for a temporary redirection. Use ~status:`Moved_Permanently or ~code:301 for a permanent redirection.

Same as Dream.response with the empty string for a body.

Same as Dream.respond, but calls Dream.with_stream internally to prepare the response for stream writing, and then runs the callback asynchronously to do it. See example j-stream.

fun request ->
  Dream.stream (fun response ->
    let%lwt () = Dream.write "foo" response in
    Dream.close_stream response)

Response status. For example, `OK.

First header with the given name. Header names are case-insensitive. See RFC 7230 §3.2 and MDN.

All headers with the given name.

Entire header set as name-value list.

Whether the message has a header with the given name.

Appends a header with the given name and value. Does not remove any existing headers with the same name.

Removes all headers with the given name.

Equivalent to Dream.drop_header followed by Dream.add_header.

Appends a Set-Cookie: header to the response. Infers the most secure defaults from the request.

Dream.set_cookie "my.cookie" "value" request response

Specify Dream.run argument ~secret, or the Web app will not be able to decrypt cookies from prior starts.

See example c-cookie.

Most of the optional arguments are for overriding inferred defaults. ~expires and ~max_age are independently useful. In particular, to delete a cookie, use ~expires:0.

• ~prefix sets __Host-, __Secure-, or no prefix, from most secure to least. A conforming client will refuse to accept the cookie if ~domain, ~path, and ~secure don't match the constraints implied by the prefix. By default, Dream.set_cookie chooses the most restrictive prefix based on the other settings and the request. See RFC 6265bis §4.1.3 and MDN.
• ~encrypt:false disables cookie encryption. In that case, you must make sure that the cookie value does not contain =, ;, or newlines. The easiest way to do so is to pass the value through an encoder like Dream.to_base64url. See Dream.run argument ~secret.
• ~expires sets the Expires= attribute. The value is compatible with Unix.gettimeofday. See RFC 6265bis §4.1.2.1 and MDN.
• ~max_age sets the Max-Age= attribute. See RFC 6265bis §4.1.2.2 and MDN.
• ~domain sets the Domain= attribute. See RFC 6265bis §4.1.2.3 and MDN.
• ~path sets the Path= attribute. By default, Path= set to the site prefix in the request, which is usually /. See RFC 6265bis §4.1.2.4 and MDN.
• ~secure sets the Secure attribute. By default, Secure is set if Dream.https is true for the request. See RFC 6265bis §4.1.2.5 and MDN.
• ~http_only sets the HttpOnly attribute. HttpOnly is set by default. See RFC 6265bis §4.1.2.6 and MDN.
• ~same_site sets the SameSite= attribute. SameSite is set to Strict by default. See RFC 6265bis §4.1.2.7 and MDN.

Dream.to_set_cookie is a “raw” version of this function that does not do any inference.

First cookie with the given name. See example c-cookie.

Dream.cookie "my.cookie" request

Pass the same optional arguments as to Dream.set_cookie for the same cookie. This will allow Dream.cookie to infer the cookie name prefix, implementing a transparent cookie round trip with the most secure attributes applicable.

All cookies, with raw names and values.

Retrieves the entire body. Stores a reference, so Dream.body can be used many times. See example 6-echo.

Replaces the body.

Retrieves a body chunk. The chunk is not buffered, thus it can only be read once. See example j-stream.

Makes the response ready for stream writing with Dream.write. You should return it from your handler soon after — only one call to Dream.write will be accepted before then. See Dream.stream for a more convenient wrapper.

Streams out the string. The promise is fulfilled when the response can accept more writes.

Flushes write buffers. Data is sent to the client.

Finishes the response stream.

Byte arrays in the C heap. See Bigarray.Array1. This type is also found in several libraries installed by Dream, so their functions can be used with Dream.bigstring:

• Bigstringaf.t in bigstringaf.
• Lwt_bytes.t in Lwt.
• Cstruct.buffer in Cstruct.

Waits for the next stream event, and calls:

• ~bigstring with an offset and length, if a bigstring is written,
• ~close if close is requested, and
• ~exn to report an exception.

Streams out the bigstring slice.

CSRF protection for AJAX requests. Either the method must be `GET or `HEAD, or:

• Origin: or Referer: must be present, and
• their value must match Host:

Responds with 400 Bad Request if the check fails. See example e-json.

Implements the OWASP Verifying Origin With Standard Headers CSRF defense-in-depth technique, which is good enough for basic usage. Do not allow `GET or `HEAD requests to trigger important side effects if relying only on Dream.origin_referer_check.

Future extensions to this function may use X-Forwarded-Host or host whitelists.

For more thorough protection, generate CSRF tokens with Dream.csrf_token, send them to the client (for instance, in <meta> tags of a single-page application), and require their presence in an X-CSRF-Token: header.

Form CSRF checking results, in order from least to most severe. See Dream.form and example d-form.

The first three constructors, `Ok, `Expired, and `Wrong_session can occur in regular usage.

The remaining constructors, `Invalid_token, `Missing_token, `Many_tokens, `Wrong_content_type correspond to bugs, suspicious activity, or tokens so old that decryption keys have since been rotated on the server.

Parses the request body as a form. Performs CSRF checks. Use Dream.form_tag in a template to transparently generate forms that will pass these checks. See Templates and example d-form.

• Content-Type: must be application/x-www-form-urlencoded.
• The form must have a field named dream.csrf. Dream.form_tag adds such a field.
• Dream.form calls Dream.verify_csrf_token to check the token in dream.csrf.

The call must be done under a session middleware, since each CSRF token is scoped to a session. See Sessions.

Form fields are sorted for easy pattern matching:

match%lwt Dream.form request with
| `Ok ["email", email; "name", name] -> (* ... *)
| _ -> Dream.empty `Bad_Request

To recover from conditions like expired forms, add extra cases:

match%lwt Dream.form request with
| `Ok      ["email", email; "name", name] -> (* ... *)
| `Expired ["email", email; "name", name] -> (* ... *)
| _ -> Dream.empty `Bad_Request

It is recommended not to mutate state or send back sensitive data in the `Expired and `Wrong_session cases, as they may indicate an attack against a client.

The remaining cases, including unexpected field sets and the remaining constructors of Dream.form_result, usually indicate either bugs or attacks. It's usually fine to respond to all of them with 400 Bad Request.

Field values of an upload form, <form enctype="multipart/form-data">. See Dream.multipart and example g-upload.

• `Files is a list of filename-content pairs.
• `Value is the value of an ordinary form field.

Parts are then paired with field names by Dream.multipart, making a (string * part) list.

For example, if the form has <input name="foo" type="file" multiple>, and the user selects multiple files, the received field name and part will be

("foo", `Files [
  ("file1", "data1");
  ("file2", "data2");
])

Like Dream.form, but also reads files, and Content-Type: must be multipart/form-data. The <form> tag and CSRF token can be generated in a template with

<%s! Dream.form_tag ~action:"/"
       ~enctype:`Multipart_form_data request %>

See Dream.form_tag, section Templates, and example g-upload.

Dream.multipart reads entire files into memory, so it is only suitable for prototyping, or with yet-to-be-added file size and count limits. See Dream.upload below for a streaming version.

Upload stream events.

• `File (field_name, filename) begins a file in the stream. The Web app should call Dream.upload_file until None, then call Dream.upload again.
• `Field (field_name, value) is a complete field. The Web app should call Dream.upload next.
• `Done ends the stream.
• `Wrong_content_type occurs on the first call to Dream.upload if Content-Type: is not multipart/form-data.

Retrieves the next upload stream event.

Does not verify a CSRF token. There are several ways to add CSRF protection for an upload stream, including:

• Generate the form with Dream.form_tag. Check for `Field ("dream.csrf", token) during upload and call Dream.verify_csrf_token.
• Use FormData in the client to submit multipart/form-data by AJAX, and include a custom header.

Retrieves a file chunk.

CSRF token verification outcomes.

`Expired and `Wrong_session can occur in normal usage, when a user's form or session expire, respectively. However, they can also indicate attacks, including stolen tokens, stolen tokens from other sessions, or attempts to use a token from an invalidated pre-session after login.

`Invalid indicates a token with a bad signature, a payload that was not generated by Dream, or other serious errors that cannot usually be triggered by normal users. `Invalid usually corresponds to bugs or attacks. `Invalid can also occur for very old tokens after old keys are no longer in use on the server.

Returns a fresh CSRF token bound to the given request's and signed with the ~secret given to Dream.run. ~valid_for is the token's lifetime, in seconds. The default value is one hour (3600.). Dream uses signed tokens that are not stored server-side.

Checks that the CSRF token is valid for the request's session.

Generates a <form> tag and an <input> tag with a CSRF token, suitable for use with Dream.form and Dream.multipart. For example, in a template,

<%s! Dream.form_tag ~action:"/" request %>
  <input name="my.field">
</form>

expands to

<form method="POST" action="/">
  <input name="dream.csrf" type="hidden" value="a-token">
  <input name="my.field">
</form>

Pass ~enctype:`Multipart_form_data for a file upload form.

Does nothing but call its inner handler.

Combines a sequence of middlewares into one, such that these two lines are equivalent:

Dream.pipeline [middleware_1; middleware_2] @@ handler

               middleware_1 @@ middleware_2 @@ handler

Creates a router. Besides interpreting routes, a router is a middleware which calls its next handler if none of its routes match the request. Route components starting with : are parameters, which can be retrieved with Dream.param. See example 3-router.

let () =
  Dream.run
  @@ Dream.router [
    Dream.get "/echo/:word" @@ fun request ->
      Dream.html (Dream.param "word" request);
  ]
  @@ Dream.not_found

Dream.scope is the main form of site composition. However, Dream also supports full subsites with **:

let () =
  Dream.run
  @@ Dream.router [
    Dream.get "/static/**" @@ Dream.static "www/static";
  ]
  @@ Dream.not_found

** causes the request's path to be trimmed by the route prefix, and the request's prefix to be extended by it. It is mainly useful for “mounting” Dream.static as a subsite.

It can also be used as an escape hatch to convert a handler, which may include its own router, into a subsite. However, it is better to compose sites with routes and Dream.scope rather than opaque handlers and **, because, in the future, it may be possible to query routes for site structure metadata.

Retrieves the path parameter. If it is missing, Dream.param raises an exception — the program is buggy.

Groups routes under a common path prefix and middlewares. Middlewares are run only if a route matches.

Dream.scope "/api" [Dream.origin_referer_check] [
  Dream.get  "/widget" get_widget_handler;
  Dream.post "/widget" set_widget_handler;
]

To prefix routes without applying any more middleware, use the empty list:

Dream.scope "/api" [] [
  (* ...routes... *)
]

To apply middleware without prefixing the routes, use "/":

Dream.scope "/" [Dream.origin_referer_check] [
  (* ...routes... *)
]

Scopes can be nested.

Forwards `GET requests for the given path to the handler.

Dream.get "/home" home_template

Like Dream.get, but for each of the other methods.

Like Dream.get, but does not check the method.

Always responds with 404 Not Found.

Serves static files from the given local path. See example f-static.

let () =
  Dream.run
  @@ Dream.router {
    Dream.get "/static/**" @@ Dream.static "www/static";
  }
  @@ Dream.not_found

Dream.static local_path checks that the request path is relative and contains no parent directory references. It then calls ~loader local_root path request. The default loader responds with a file at local_root/path in the file system, or 404 Not Found if the file does not exist. It uses magic-mime to set the Content-Type:

Pass ~loader to implement any other behavior, including serving files from memory. See example w-one-binary. ~loader can set headers on its response, including ETag:

If checks on path fail, Dream.static responds with 404 Not Found.

Value from the request's session.

Mutates a value in the request's session. The back end may commit the value to storage immediately, so this function returns a promise.

Full session dictionary.

Invalidates the request's session, replacing it with a fresh, empty pre-session.

Stores sessions in server memory. Passes session IDs to clients in cookies. Session data is lost when the server process exits.

Stores sessions in encrypted cookies. Pass Dream.run ~secret to be able to decrypt cookies from previous server runs.

Stores sessions in an SQL database. Passes session IDs to clients in cookies. Must be used under Dream.sql_pool. Expects a table

CREATE TABLE dream_session (
  id TEXT PRIMARY KEY,
  label TEXT NOT NULL,
  expires_at REAL NOT NULL,
  payload TEXT NOT NULL
)

Secret value used to identify a client.

Tracing label suitable for printing to logs.

Time at which the session will expire.

A WebSocket connection. See RFC 6455 and MDN.

Creates a fresh 101 Switching Protocols response. Once this response is returned to Dream's HTTP layer, the callback is passed a new websocket, and the application can begin using it. See example k-websocket.

let my_handler = fun request ->
  Dream.websocket (fun websocket ->
    let%lwt () = Dream.send "Hello, world!" websocket in
    Dream.close_websocket websocket);

Sends a single message. The WebSocket is ready another message when the promise resolves.

With ~kind:`Text, the default, the message is interpreted as a UTF-8 string. The client will receive it transcoded to JavaScript's UTF-16 representation.

With ~kind:`Binary, the message will be received unmodified, as either a Blob or an ArrayBuffer. See MDN, WebSocket.binaryType.

Retrieves a message. If the WebSocket is closed before a complete message arrives, the result is None.

Closes the WebSocket. ~code is usually not necessary, but is needed for some protocols based on WebSockets. See RFC 6455 §7.4.

Dream.graphql make_context schema serves the GraphQL schema. Integrates ocaml-graphql-server. See examples i-graphql and w-graphql-subscription.

let () =
  Dream.run
  @@ Dream.router [
    Dream.post "/graphql"  (Dream.graphql Lwt.return schema);
    Dream.get  "/graphiql" (Dream.graphiql "/graphql");
  ]
  @@ Dream.not_found

make_context is called by Dream.graphql on every request to create the context, a value that is passed to each resolver from the schema. Passing Lwt.return, the same as

fun request -> Lwt.return request

causes the request itself to be used as the context:

field "name"
  ~doc:"User name"
  ~typ:(non_null string)
  ~args:Arg.[]
  ~resolve:(fun info user ->
    (* The context is in info.ctx *)
    user.name);

Serves GraphiQL, a GraphQL query editor. The string gives the GraphQL endpoint that the editor will work with.

Makes an SQL connection pool available to its inner handler.

Runs the callback with a connection from the SQL pool. See example h-sql.

let () =
  Dream.run
  @@ Dream.sql_pool "sqlite3://db.sqlite"
  @@ fun request ->
    request |> Dream.sql (fun db ->
      (* ... *))

Logs and times requests. Time spent logging is included. See example 2-middleware.

Formats a message and logs it. Disregard the obfuscated type: the first argument is a format string as described in the standard library modules Printf and Format. The rest of the arguments are determined by the format string. See example a-log.

Dream.log "Counter is now: %i" counter;
Dream.log "Client: %s" (Dream.client request);

Loggers. This type is difficult to read — instead, see Dream.error for usage.

Log levels, in order from most urgent to least.

Formats a message and writes it to the log at level `Error. The inner formatting function is called only if the current log level is `Error or higher. See example a-log.

Dream.error (fun log ->
  log ~request "My message, details: %s" details);

Pass the optional argument ~request to Dream.error to associate the message with a specific request. If not passed, Dream.error will try to guess the request. This usually works, but not always.

Like Dream.error, but for each of the other log levels.

Sub-logs. See Dream.sub_log right below.

Creates a new sub-log with the given name. For example,

let log = Dream.sub_log "myapp.ajax"

...creates a logger that can be used like Dream.error and the other default loggers, but prefixes "myapp.ajax" to each log message.

log.error (fun log -> log ~request "Validation failed")

See README of example a-log.

Initializes Dream's log with the given settings.

Dream initializes its logging back end lazily. This is so that if a Dream Web app is linked into a larger binary, it does not affect that binary's runtime unless the Web app runs.

This also allows the Web app to give logging settings explicitly by calling Dream.initialize_log early in program execution.

• ~backtraces:true, the default, causes Dream to call Printexc.record_backtrace, which makes exception backtraces available.

• ~async_exception_hook:true, the default, causes Dream to set Lwt.async_exception_hook so as to forward all asynchronous exceptions to the logger, and not terminate the process.

• ~level sets the log level threshould for the entire binary. The default is `Info.

• ~enable:false disables Dream logging completely. This can help sanitize output during testing.

Detailed errors. Ignore this type if only using Dream.error_template.

• condition describes the error itself.

  • `Response is a 4xx or 5xx response.
  • `Exn is a caught exception.
  • `String is an error that has only an English-language description.

  The default error handler logs `Exn and `Strings, but not `Response. `Response is assumed to be deliberate, and already logged by Dream.logger.

• layer is which part of the Dream stack detected the error.

  • `App is for application exceptions, rejections, and 4xx, 5xx responses.
  • `HTTP and `HTTP2 are for low-level HTTP protocol errors.
  • `TLS is for low-level TLS errors.
  • `WebSocket is for WebSocket errors.

  The default error handler uses this to just prepend a prefix to its log messages.

• caused_by is the party likely to have caused the error.

  • `Server errors suggest bugs, and correspond to 5xx responses.
  • `Client errors suggest user errors, network failure, buggy clients, and sometimes attacks. They correspond to 4xx responses.

• request is a request associated with the error, if there is one.

  As examples, a request might not be available if the error is a failure to parse an HTTP/1.1 request at all, or failure to perform a TLS handshake.

  In case of a `WebSocket error, the request is the client's original request to establish the WebSocket connection.

• response is a response that was either generated by the application, or suggested by the error context.

  In case of a `WebSocket error, the response is the application's original connection agreement response created by Dream.websocket.

  See Dream.error_template.

• client is the client's address, if available. For example, 127.0.0.1:56001.
• Suggested log level for the error. Usually `Error for `Server errors and `Warning for client errors.

• debug is true if Dream.run was called with ~debug.

  If so, the default error handler gathers various fields from any available request, formats the error condition, and passes the resulting string to the template.

  The default template shows this string in its repsonse, instead of returning a response with no body.

• will_send_response is true in error contexts where Dream will still send a response.

  The default handler calls the error template only if will_send_response is true.

Error handlers log errors and convert them into responses. Ignore if using Dream.error_template.

If the error has will_send_response = true, the error handler must return a response. Otherwise, it should return None.

If an error handler raises an exception or rejects, Dream logs this secondary failure. If the error context needs a response, Dream responds with an empty 500 Internal Server Error.

The behavior of Dream's default error handler is described at Dream.error.

Builds an error_handler from a template. See example 9-error.

let my_error_handler =
  Dream.error_template (fun ~debug_dump response ->
    let body =
      match debug_dump with
      | Some string -> Dream.html_escape string
      | None -> Dream.status_to_string (Dream.status response)
    in

    response
    |> Dream.with_body body
    |> Lwt.return)

The error's context suggests response. Usually, it's only valid field is Dream.status.

• If the error is an exception or rejection from the application, the status is usually 500 Internal Server Error.
• In case of a 4xx or 5xx response from the application, that response itself is passed to the template.
• For low-level errors, the status is typically either 400 Bad Request if the error was likely caused by the client, and 500 Internal Server Error if likely caused by the server.

If ~debug was passed to Dream.run, ~debug_dump will be Some info, where info is a multi-line string containing an error description, stack trace, request state, and other information.

When an error occurs in a context where a response is not possible, the template is not called. In some contexts where the template is called, the status code is hardcoded, but the headers and body from the template's response will still be used.

If the template itself raises an exception or rejects, an empty 500 Internal Server Error will be sent in contexts that require a response.

Runs the Web application represented by the handler, by default at http://localhost:8080.

This function calls Lwt_main.run internally, so it is intended to be the main loop of a program. Dream.serve is a version that does not call Lwt_main.run.

• ~interface is the network interface to listen on. Defaults to "localhost". Use "0.0.0.0" to listen on all interfaces.
• ~port is the port to listen on. Defaults to 8080.
• ~stop is a promise that causes the server to stop accepting new requests, and Dream.run to return. Requests that have already entered the Web application continue to be processed. The default value is a promise that never resolves. However, see also ~stop_on_input.
• ~debug:true enables debug information in error templates. See Dream.error_template. The default is false, to prevent accidental deployment with debug output turned on. See example 8-debug.
• ~error_handler handles all errors, both from the application, and low-level errors. See Errors and example 9-error.

• ~secret is a key to be used for cryptographic operations, such as signing CSRF tokens. By default, a random secret is generated on each call to Dream.run. Generate a 256-bit key for production with

  Dream.to_base64url (Dream.random 32)

  and load it from file or an environment variable.

• ~old_secrets is a list of previous secrets that can still be used for decryption, but not for encryption. This is intended for key rotation.
• ~prefix is a site prefix for applications that are not running at the root (/) of their domain. The default is "/", for no prefix.
• ~https:true enables HTTPS. You should also specify ~certificate_file and ~key_file. However, for development, Dream includes an insecure compiled-in localhost certificate. Enabling HTTPS also enables transparent upgrading of connections to HTTP/2. See example l-https.
• ~certificate_file and ~key_file specify the certificate and key file, respectively, when using ~https. They are not required for development, but are required for production. Dream will write a warning to the log if you are using ~https, don't provide ~certificate_file and ~key_file, and ~interface is not "localhost".
• ~builtins:false disables Built-in middleware.

The remaining arguments, can be used to gradually disable convenience features of Dream.run. Once all are disabled, you may want to switch to using Dream.serve.

• ~greeting:false disables the start-up log message that prints a link to the Web application.
• ~stop_on_input:false disables stopping the server on input on STDIN.
• ~graceful_stop:false disables waiting for one second after stop, before exiting from Dream.run.
• ~adjust_terminal:false disables adjusting the terminal to disable echo and line wrapping.

Like Dream.run, but returns a promise that does not resolve until the server stops listening, instead of calling Lwt_main.run.

This function is meant for integrating Dream applications into larger programs that have their own procedures for starting and stopping the Web server.

All arguments have the same meanings as they have in Dream.run.

Lowercases response headers for HTTP/2 requests.

If the request has Dream.version (1, _), then...

• if the response does not have Content-Length: and the body is a string, sets Content-Length: to the string's length, or
• if the response does not have Transfer-Encoding: and the body is a stream, sets Transfer-Encoding: chunked.

This is built in because an application cannot be expected to decide including these headers in the face of transparent HTTP/2 upgrades. The headers are necessary in HTTP/1, and forbidden or redundant and difficult to use in HTTP/2.

Forwards exceptions, rejections, and 4xx, 5xx responses from the application to the error handler. See Errors.

Assigns an id to each request.

Removes Dream.run ~prefix from the path in each request, and adds it to the request prefix. Responds with 502 Bad Gateway if the path does not have the expected prefix.

Escapes a string so that it is suitable for use as text inside HTML elements and quoted attribute values. Implements OWASP Cross Site Scripting Prevention Cheat Sheet RULE #1.

This function is not suitable for use with unquoted attributes, inline scripts, or inline CSS. See Security in example 7-template.

Converts the given string its base64url encoding, as specified in RFC 4648 §5, using a Web-safe alphabet and no padding. The resulting string can be used without escaping in URLs, form data, cookies, HTML content, attributes, and JavaScript code. For more options, see the Base64 library.

Inverse of Dream.to_base64url.

Percent-encodes a string for use inside a URL.

~international is true by default, and causes non-ASCII bytes to be preserved. This is suitable for display to users, including in <a href=""> attributes, which are displayed in browser status lines. See RFC 3987.

Use ~international:false for compatibility with legacy systems, or when constructing URL fragments from untrusted input that may not match the interface language(s) the user expects. In the latter case, similar letters from different writing scripts can be used to mislead users about the targets of links.

Inverse of Dream.to_percent_encoded.

Inverse of Dream.from_form_urlencoded. Percent-encodes names and values.

Converts form data or a query string from application/x-www-form-urlencoded format to a list of name-value pairs. See RFC 1866 §8.2.1. Reverses the percent-encoding of names and values.

Converts a Cookie: header value to key-value pairs. See RFC 6265bis §4.2.1. Does not apply any decoding to names and values.

Dream.to_set_cookie name value formats a Set-Cookie: header value. The optional arguments correspond to the attributes specified in RFC 6265bis §5.3, and are documented at Dream.set_cookie.

Does not apply any encoding to names and values. Be sure to encode so that names and values cannot contain `=`, `;`, or newline characters.

Splits a request target into a path and a query string.

Splits the string into components on / and percent-decodes each component. Empty components are dropped, except for the last. This function does not distinguish between absolute and relative paths, and is only meant for routes and request targets. So,

• Dream.from_path "" becomes [].
• Dream.from_path "/" becomes [""].
• Dream.from_path "abc" becomes ["abc"].
• Dream.from_path "/abc" becomes ["abc"].
• Dream.from_path "abc/" becomes ["abc"; ""].
• Dream.from_path "a%2Fb" becomes ["a/b"].
• Dream.from_path "a//b" becomes ["a"; "b"].

This function is not for use on targets, because it does not treat ? specially. See Dream.from_target if the argument string is actually a target, and may include a query string.

Changes the representation of path abc/ to the representation of abc by checking if the last element in the list is "", and, if it is, dropping it.

The string "text/html; charset=utf-8" for Content-Type: headers.

The string "application/json" for Content-Type: headers.

Generates the requested number of bytes using a cryptographically secure random number generator.

Signs and encrypts the string using the ~secret in the request. See Dream.run for setting ~secret.

~associated_data is included when computing the signature, but not included in the ciphertext. It can be used like a “salt,” to force ciphertexts from different contexts to be distinct, and dependent on the context.

For example, when Dream.set_cookie encrypts cookie values, it internally passes the cookie names in the associated data. This makes it impossible (or impractical) to use the ciphertext from one cookie as the value of another. The associated data will not match, and the value will be recognized as invalid.

Reverses Dream.encrypt.

To support secret rotation, the decryption secrets with which decryption is attempted are are (~secret)::(~old_secrets). See the descriptions of ~secret and ~old_secrets in Dream.run.

Per-message variable.

Per-server variable.

Declares a variable of type 'a in all messages. The variable is initially unset in each message. The optional ~name and ~show_value are used by Dream.run ~debug to show the variable in debug dumps.

Retrieves the value of the per-message variable.

Sets the per-message variable to the value.

Declares a variable of type 'a in all servers. The first time the variable is accessed, the given initializer function is called to get its value. Global variables cannot be changed. So, they are typically refs or other mutable data structures, such as hash tables.

Retrieves the value of the per-server variable.

Dream.request body creates a fresh request with the given body for testing. The optional arguments set the corresponding request fields.

Dream.test handler runs a handler the same way the HTTP server (Dream.run) would — assigning it a request id and noting the site root prefix, which is used by routers. Dream.test calls Lwt_main.run internally to await the response, which is why the response returned from the test is not wrapped in a promise. If you don't need these facilities, you can test handler by calling it directly with a request.

Dream.first message evaluates to the original request or response that message is immutably derived from. This is useful for getting the original state of requests especially, when they were first created inside the HTTP server (Dream.run).

Dream.last message evaluates to the latest request or response that was derived from message. This is most useful for obtaining the state of requests at the time an exception was raised, without having to instrument the latest version of the request before the exception.

Sorts headers by name. Headers with the same name are not sorted by value or otherwise reordered, because order is significant for some headers. See RFC 7230 §3.2.2 on header order. This function can help sanitize output before comparison.

Responds with the request body.