paf 0.6.0 · OCaml Package

Parameters

module Stack : Tcpip.Tcp.S

Signature

type stack = Stack.t

The type of the TCP/IP stack.

type ipaddr = Stack.ipaddr

The type of the IP address.

Protocols.

From the given stack, Paf_mirage constructs protocols needed for HTTP:

A simple TCP/IP protocol
A TCP/IP protocol wrapped into TLS via ocaml-tls

We expose these protocols in the sense of mimic. They are registered globally with mimic and are usable via mimic (see Mimic.resolve) as long as the given ctx contains tcp_edn and/or tls_edn. Such way to instance something which represents these protocols and usable as a Mirage_flow.S are useful for the client-side, see run.

We expose 2 new functions: no_close/to_close. In a specific context such as the proxy, the handler should notify us to fakely close the underlying connection. Indeed, Paf will try to close your connection as soon as the HTTP transmission is finished. However, in the case of a proxy, the connection must remains then. TCP.no_close sets the flow so that the next call to TCP.close is ignored. to_close resets the flow to the basic behavior - we will really close the given flow.

module TCP : sig ... end

module TLS : sig ... end

val tcp_protocol : (stack * ipaddr * int, TCP.flow) Mimic.protocol

val tcp_edn : (stack * ipaddr * int) Mimic.value

val tls_edn : 
  ([ `host ] Domain_name.t option * Tls.Config.client * stack * ipaddr * int)
    Mimic.value

val tls_protocol : 
  ([ `host ] Domain_name.t option * Tls.Config.client * stack * ipaddr * int,
    TLS.flow)
    Mimic.protocol

Server implementation.

type t

The type of the socket bound on a specific port (via init).

type dst = ipaddr * int

val init : port:int -> stack -> t Lwt.t

init ~port stack bounds the given stack to a specific port and return the main socket t.

val accept : t -> (TCP.flow, [> `Closed ]) Stdlib.result Lwt.t

accept t waits an incoming connection and return a socket connected to a peer.

val close : t -> unit Lwt.t

close t closes the main socket.

HTTP/1.1 servers.

The user is able to launch a simple HTTP/1.1 server with TLS or not. Below, you can see a simple example:

let run ~error_handler ~request_handler =
  Paf_mirage.init ~port:8080 stack >>= fun t ->
  Paf_mirage.http_service ~error_handler request_handler
  >>= fun service ->
  let (`Initialized th) = Paf_mirage.serve service t in
  th

val http_service : 
  ?config:Httpaf.Config.t ->
  error_handler:(dst -> Httpaf.Server_connection.error_handler) ->
  (TCP.flow -> dst -> Httpaf.Server_connection.request_handler) ->
  t Paf.service

http_service ~error_handler request_handler makes an HTTP/AF service where any HTTP/1.1 requests are handled by request_handler. The returned service is not yet launched (see serve).

val https_service : 
  tls:Tls.Config.server ->
  ?config:Httpaf.Config.t ->
  error_handler:(dst -> Httpaf.Server_connection.error_handler) ->
  (TLS.flow -> dst -> Httpaf.Server_connection.request_handler) ->
  t Paf.service

https_service ~tls ~error_handler request_handler makes an HTTP/AF service over TLS (from the given TLS configuration). Then, HTTP/1.1 requests are handled by request_handler. The returned service is not yet launched (see serve).

HTTP/1.1 & H2 over TLS server.

It's possible to make am ALPN server. It's an HTTP server which can handle

HTTP/1.1 requests
and H2 requests

The choice is made by the ALPN challenge on the TLS layer where the client can send which protocol he/she wants to use. Therefore, the server must handle these two cases.

val alpn_service : 
  tls:Tls.Config.server ->
  ?config:(Httpaf.Config.t * H2.Config.t) ->
  (TLS.flow, dst) Alpn.server_handler ->
  t Paf.service

alpn_service ~tls handler makes an H2/HTTP/AF service over TLS (from the given TLS configuration). An HTTP request (version 1.1 or 2) is handled then by handler. The returned service is not yet launched (see serve to launch it).

val serve : 
  ?stop:Lwt_switch.t ->
  't Paf.service ->
  't ->
  [ `Initialized of unit Lwt.t ]

serve ?stop service returns an initialized promise of the given service service. stop can be used to stop the service.