sihl 0.4.0 · OCaml Package

val csrf : 
  ?not_allowed_handler:(Rock.Request.t -> Rock.Response.t Lwt.t) ->
  ?cookie_key:string ->
  ?input_name:string ->
  ?secret:string ->
  unit ->
  Rock.Middleware.t

csrf ?not_allowed_handler ?cookie_key ?input_name ?secret () returns a middleware that enables CSRF protection for unsafe HTTP requests.

not_allowed_handler is used if an unsafe request does not pass the CSRF protection check. By default, not_allowed_handler returns an empty response with status 403.

cookie_key is the key in the cookie under which a CSRF token will be stored. By default, cookie_key has a __Host prefix to increase cookie security. One important consequence of this prefix is, that the cookie cannot be sent across unencrypted (HTTP) connections. You should only set this argument if you know what you are doing and aware of the consequences.

input_name is the name of the input element that is used to send the CSRF token. By default, the value is _csrf. It is recommended to use a <hidden> field in a <form>.

secret is the secret used to hash the CSRF cookie value with. By default, SIHL_SECRET is used.

Internally, the CSRF protection is implemented as the Double Submit Cookie approach.

val error : 
  ?email_config:(string * string * (Sihl__.Contract_email.t -> unit Lwt.t)) ->
  ?reporter:(Opium.Request.t -> string -> unit Lwt.t) ->
  ?error_handler:(Rock.Request.t -> Rock.Response.t Lwt.t) ->
  unit ->
  Rock.Middleware.t

error ?email_config ?reporter ?handler () returns a middleware that catches all exceptions and shows them.

By default, it logs the exception with the request details. The response is either `text/html` or `application/json`, depending on the `Content-Type` header of the request. If SIHL_ENV is `development`, a more detailed debugging page is shown which makes development easier. You can override the error page/JSON that is shown by providing a custom error handler error_handler.

Optional email configuration email_config can be specified, which is a tuple (sender, recipient, send_function). Exceptions that are caught will be sent per email to recipient where sender is the sender of the email. Pass in the send function of the Sihl email service or provide your own send_function.

An optional custom reporter reporter can be defined. The middleware passes the request and the stringified exception to the reporter callback. Use the reporter to implement custom error reporting.

val flash : ?cookie_key:string -> unit -> Rock.Middleware.t

flash ?cookie_key () returns a middleware that is used to read and store flash data. Flash data is session data that is valid between two requests. A typical use case is displaying error messages after submitting forms.

cookie_key is the cookie name. By default, the value is _flash.

The flash data is stored in a separate flash cookie. The usual limitations apply such as a maximum of 4KB. Note that the cookie is not signed, don't put any data into the flash cookie that you have to trust.

val id : unit -> Rock.Middleware.t

id () returns a middleware that reads the X-Request-ID headers and assigns it to the request.

If no X-Request-ID is present, a random id is generated which is assigned to the request. The random id is a 64 byte long base64 encoded string. There is no uniqueness guarantee among ids of pending requests. However, generating two identical ids in a short period of time is highly unlikely.

val static_file : unit -> Rock.Middleware.t

static_file () returns a middleware that serves static files.

The directory that is served can be configured with PUBLIC_DIR. By default, the value is ./public.

The path under which the file are accessible can be configured with PUBLIC_URI_PREFIX. By default, the value is /assets.

package sihl