package mehari-mirage

  1. Overview
  2. Docs

Module Mehari_mirage.MakeSource

A functor building an IO module from Mirage components.

Parameters

module Clock : Mirage_clock.PCLOCK

Signature

Sourcemodule IO = Lwt
Sourcetype stack = Stack.t

Tcpip stack.

Net

include Mehari.NET with module IO := IO and type addr = Ipaddr.t
Sourcetype addr = Ipaddr.t

Type for IP address.

Handlers are asynchronous functions from Mehari.request to Mehari.response.

Sourcetype route

Routes tell router which handler to select for each request. See Routing.

Sourcetype rate_limiter

Rate limiter. See Rate limit.

Sourcetype middleware = handler -> handler

Middlewares take a handler, and run some code before or after — producing a “bigger” handler. See Middleware.

Middleware

Sourceval no_middleware : middleware

Does nothing but call its inner handler. Useful for disabling middleware conditionally during application startup:

if development then
  my_middleware
else
  Mehari.no_middleware
Sourceval pipeline : middleware list -> middleware

Combines a list of middlewares into one, such that these two lines are equivalent: Mehari.pipeline [ mw1 ; mw2 ] @@ handler mw1 @@ mw2 @@ handler.

Routing

Sourceval router : route list -> handler

Creates a router. If none of the routes match the Mehari.request, the router returns Mehari.not_found.

Sourceval route : ?rate_limit:rate_limiter -> ?mw:middleware -> ?typ:[ `Raw | `Regex ] -> string -> handler -> route

route ~rate_limit ~mw ~typ path handler forwards requests for path to handler. path can be a string literal or a regex in Perl style depending of typ. If rate limit is in effect, handler is not executed and a respond with Mehari.status Mehari.slow_down is sended.

Sourceval scope : ?rate_limit:rate_limiter -> ?mw:middleware -> string -> route list -> route

scope ~rate_limit ~mw prefix routes groups routes under the path prefix, rate_limit and mw.

Sourceval no_route : route

A dummy value of type route that is completely ignored by the router. Useful for disabling routes conditionally during application start.

Rate limit

Sourceval make_rate_limit : ?period:int -> int -> [ `Second | `Minute | `Hour | `Day ] -> rate_limiter

make_rate_limit ~period n unit creates a rate_limiter which limits client to n request per period * unit. For example,

make_rate_limit ~period:2 5 `Hour

limits client to 5 requests every 2 hours.

Virtual hosting

Sourceval virtual_hosts : ?meth:[ `ByURL | `SNI ] -> (string * handler) list -> handler

virtual_hosts ?meth [(domain, handler); ...] produces a handler which enables virtual hosting at the TLS-layer using SNI.

  • meth can be used to choose which source to match the hostnames against. Defaults to `SNI.

Logging

Sourceval set_log_lvl : Logs.level -> unit

Set Mehari's logger to the given log level.

Sourceval logger : handler -> handler

Logs and times requests. Time spent logging is included.

Sourceval debug : 'a Logs.log
Sourceval info : 'a Logs.log
Sourceval warning : 'a Logs.log
Sourceval error : 'a Logs.log

Response

Sourceval respond : 'a Mehari.status -> 'a -> Mehari.response IO.t

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

Sourceval respond_body : Mehari.body -> Mehari.mime -> Mehari.response IO.t

Same as respond but respond with given Mehari.body and use given Mehari.mime as mime type.

Sourceval respond_text : string -> Mehari.response IO.t

Same as respond but respond with given text and use text/plain as Mehari.mime type.

Sourceval respond_gemtext : ?charset:string -> ?lang:string list -> Mehari.Gemtext.t -> Mehari.response IO.t

Same as respond but respond with given Mehari.Gemtext.t and use text/gemini as Mehari.mime type.

Sourceval respond_raw : [ `Body of string | `Full of int * string * string ] -> Mehari.response IO.t

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

Entry point

Sourceval run : ?port:int -> ?timeout:float -> ?verify_url_host:bool -> ?config:Tls.Config.server -> ?certchains:(string * string) list -> stack -> handler -> unit IO.t

run ?port ?timeout ?verify_url_host ?config ?certchains stack handler runs the server using host.

  • port is the port to listen on. Defaults to 1965.
  • timeout is the maximum waiting time in seconds for the client to write a request after TLS handshake. Unset by default.
  • verify_url_host, if true (by default), will verify if the URL hostname corresponds to the server's certificate (chosen according to ocaml-tls sni.md).

  • config is the TLS server configuration. Defaults to

      Tls.Config.server ~certificates
      ~authenticator:(fun ?ip:_ ~host:_ _ -> Ok None)
      ()

    To support client certificates, specify the authenticator.

  • certchains is the list of form [(cert_path, private_key_path); ...], the last one is considered default.