sihl 0.3.0 · OCaml Package

val authorization_user : login_path_f:(unit -> string) -> Rock.Middleware.t

deprecated authorization_user will be moved to a dedicated authorization package sihl-authorization in the future.

val authorization_admin : 
  login_path_f:(unit -> string) ->
  (Sihl__.Contract_user.t -> bool) ->
  Rock.Middleware.t

deprecated authorization_admin will be moved to a dedicated authorization package sihl-authorization in the future.

val bearer_token : Rock.Middleware.t

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

form_data_name is the name of the input element that is used to send the CSRF token. The default is csrf. It is recommended to use a <hidden> field in a <form>.

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.

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 csrf : 
  ?not_allowed_handler:(Rock.Request.t -> Rock.Response.t Lwt.t) ->
  ?cookie_key:string ->
  ?form_data_name:string ->
  ?secret:string ->
  unit ->
  Rock.Middleware.t

val error : 
  ?email_config:(string * string * (Sihl__.Contract_email.t -> unit Lwt.t)) ->
  ?reporter:(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 email will only be sent if SIHL_ENV is `production`.

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

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

val form : Rock.Middleware.t

val htmx : Rock.Middleware.t

val id : Rock.Middleware.t

val json : Rock.Middleware.t

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

session ?cookie_key ?secret () returns a middleware that reads and stores session values. The actual session values are stored in a signed cookie. Be aware of the limitations of this technique. Firstly, make sure that the session value does not exceed 4KB. Secondly, the client is able to read the session values. If you need to store a large amount of data, use the sihl-cache package and store the key in the session cookie.

cookie_key is the key of the session cookie. By default, the value is _session.

secret is a secret string that is used to sign cookies. By default SIHL_SECRET is used.

val static_file : unit -> Rock.Middleware.t

val user : 
  ?key:string ->
  (string -> Sihl__.Contract_user.t option Lwt.t) ->
  Rock.Middleware.t

user ?key find_user returns a middleware that sets the user based on the session cookie that was sent by the browser.

key is the user id that has been used to store a user id in the session. Be default, the value is user_id.

find_user is a function that returns a user given a user id.

package sihl