sihl 3.0.1 · OCaml Package

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

csrf ?not_allowed_handler ?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.

key is the key in the session cookie under which a CSRF token will be stored.

Internally, the CSRF protection is implemented as a Double Submit Cookie approach. session_key is the name of the session cookie the CSRF token should be stored in. By default, the value is _session. If you want the CSRF cookie to use a __Host prefix, you have to adjust the session cookie key.

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 encrypt the CSRF cookie value with. By default, SIHL_SECRET is used.

For security purposes, AES is used for encryption.

val error : 
  ?email_config:(string * string * (Sihl__.Contract_email.t -> unit Lwt.t)) ->
  ?reporter:(Request.t -> string -> unit Lwt.t) ->
  ?error_handler:(Request.t -> 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 migration : (unit -> (string * int) list Lwt.t) -> Rock.Middleware.t

migration fetch_pending_migrations returns a middleware that shows a warning page in case there are pending migrations. The middleware shows a generic internal error page if SIHL_ENV is production to not leak information.

fetch_pending_migrations is a function that returns a list of pending migrations. Use the pending_migration function of the migration service. If the returned list is empty, there are no pending migrations.

val trailing_slash : unit -> Rock.Middleware.t

trailing_slash () returns a middleware that removes all trailing slashes / from the request URI path. Apply it globally (before the router) to make sure that a path /foo/bar/ matches the route /foo/bar.

Multiple trailing slashes are removed.

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