mehari-mirage 0.1 · OCaml Package

A functor building an IO module from Mirage components.

Parameters

module Clock : Mirage_clock.PCLOCK

module Stack : Tcpip.Stack.V4V6

module Time : Mirage_time.S

Signature

module IO = Lwt

type stack = Stack.t

Tcpip stack.

Net

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

type addr = Ipaddr.t

Type for IP address.

type handler = addr Mehari.request -> Mehari.response IO.t

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

type route

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

type rate_limiter

Rate limiter. See Rate limit.

type middleware = handler -> handler

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

Middleware

val 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

val 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

val router : route list -> handler

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

val 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.

val 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.

val 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

val 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

val 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

val set_log_lvl : Logs.level -> unit

Set Mehari's logger to the given log level.

val logger : handler -> handler

Logs and times requests. Time spent logging is included.

val debug : 'a Logs.log

val info : 'a Logs.log

val warning : 'a Logs.log

val error : 'a Logs.log

Response

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

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

val 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.

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

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

val 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.

val 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

val 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.

raises Invalid_argument
if certchains is empty.

package mehari-mirage