Module Opium.Middleware
Collection of middlewares commonly used to build Opium applications.
router
val router : Rock.Handler.t Router.t -> Rock.Middleware.t
router router
creates a middleware that route the request to an handler depending on the URI of the request.The middleware
router
takes a instance ofRouter.t
. It will call the handler if a match is found in the given list of endpoint, and will fallback to the default handler otherwise.The routes can use pattern patching to match multiple endpoints.
A URI segment preceded with a colon ":" will match any string and will insert the value of the segment in the environment of the request.
For instance, the middleware defined with:
let router = Router.add Router.empty ~action:Handler.hello_world ~meth:`GET ~route:"/hello/:name" ;; let middleware = Middleware.router router
will match any URI that matches "/hello/" followed by a string. This value of the last segment will be inserted in the request environment with the key "name", and the request will be handled by handler defined in
Handler.hello_world
.Another way to use pattern matching is to use the wildchar "*" character. The URI segment using "*" will match any URI segment, but will not insert the value of the segment in the request enviroment.
For instance, the middleware defined with:
let router = Router.add Router.empty ~action:Handler.hello_world ~meth:`GET ~route:"/*/hello" ;; let middleware = Middleware.router router
will redirect any URI containing two segments with the last segment containing "hello" to the handler defined in
Handler.hello_world
.
debugger
val debugger : Rock.Middleware.t
debugger
creates a middleware that that catches any error that occurs when processing the request and pretty prints the error in an an HTML page.It should only be used during development: you probably don't want to serve a detail of the error to your users in production.
logger
val logger : Rock.Middleware.t
logger
creates a middleware that logs the requests and their response.The request's target URL and the HTTP method are logged with the "info" verbosity. Once the request has been processed successfully, the response's HTTP code is logged with the "info" verbosity.
If the body of the request or the response are a string (as opposed to a stream), their content is logged with the "debug" verbosity.
If an error occurs while processing the request, the error is logged with an "error" verbosity.
Note that this middleware is best used as the first middleware of the pipeline because any previous middleware might change the request / response after
Logger
has been applied.
allow_cors
val allow_cors : ?origins:string list -> ?credentials:bool -> ?max_age:int -> ?headers:string list -> ?expose:string list -> ?methods:Method.t list -> ?send_preflight_response:bool -> unit -> Rock.Middleware.t
allow_cors ?origins ?credentials ?max_age ?headers ?expose ?methods ?send_preflight_response ()
creates a middleware that adds Cross-Origin Resource Sharing (CORS) header to the responses.
static
val static : read:(string -> (Body.t, [ Status.client_error | Status.server_error ]) Lwt_result.t) -> ?uri_prefix:string -> ?headers:Headers.t -> ?etag_of_fname:(string -> string option) -> unit -> Rock.Middleware.t
static ~read ?uri_prefix ?headers ?etag_of_fname ()
creates a middleware that is used to serve static content.It is Unix-independent, you can provide your own read function that could read from in-memory content, or read a Unix filesystem, or even connect to a third party service such as S3.
The responses will contain a
Content-type
header that is auto-detected based on the file extension using theMagic_mime
.lookup function. Additional headers can be provided throughheaders
.It supports the HTTP entity tag (ETag) protocol to provide web cache validation. If
etag_of_fname
is provided, the response will contain anETag
header. If the request contains anIf-None-Match
header with anETag
equal to that generated byetag_of_fname
, this middleware will respond with304 Not Modified
.
static_unix
val static_unix : local_path:string -> ?uri_prefix:string -> ?headers:Headers.t -> ?etag_of_fname:(string -> string option) -> unit -> Rock.Middleware.t
static_unix ~local_path ?uri_prefix ?headers ?etag_of_fname ()
creates a middleware that is used to serve static content from a local filesystem.The behaviour of the middleware is the same as
static
, since the latter is used with aread
function that reads from the local filesystem.
content_length
val content_length : Rock.Middleware.t
content_length
is middleware that overrides the request'sPOST
method with the method defined in the_method
request parameter.The
POST
method can be overridden by the following HTTP methods:PUT
PATCH
DELETE
method_override
val method_override : Rock.Middleware.t
method_override
is a middleware that replaces the HTTP method with the one found in the_method
field ofapplication/x-www-form-urlencoded
encodedPOST
requests.Requests that are not
application/x-www-form-urlencoded
encoded or with method different thanPOST
remain untouched.This is especially useful when sending requests from HTML form, because they only support the
GET
andPOST
method.
method_required
val method_required : ?allowed_methods:Method.t list -> unit -> Rock.Middleware.t
method_required
creates a middleware that filters the requests by method and respond with a`Method_not_allowed
status (HTTP 405
) if the method is not allowed.
etag
val etag : Rock.Middleware.t
etag
is a middleware that adds an ETag header to responses and respond with the HTTP code304
when the computed ETag matches the one specified in the request.
head
val head : Rock.Middleware.t
head
is a middleware that add supports forHEAD
request for handlers that receiveGET
requests.It works by replacing the
HEAD
method by theGET
method before sending the request to the handler, and removes the body of the response before sending it to the client.