package paf

  1. Overview
  2. Docs
HTTP/AF and MirageOS

Install 

dune-project
 Dependency

github.com Readme Changelog MIT License Edit opam file Versions (5)

Authors

  1. R
    Romain Calascibetta <romain.calascibetta@gmail.com>

Maintainers

  1. R
    Romain Calascibetta <romain.calascibetta@gmail.com>

Sources

paf-0.5.0.tbz
sha256=a1646fc1bf0386d17796d59a67a9a82a681a74552782bba8d54388686355fe83
sha512=616f5b7c7090b5f9bba70969fce56ffc909ec31a6a9045d8093e4494e76607b4ebb957cc1b2318364d50f30e5414d058af46a23bf8ea0a0ee421dc94378b9c31

doc/paf.mirage/Paf_mirage/Make/index.html

Module Paf_mirage.MakeSource

Parameters

Signature

Sourcetype stack = Stack.t

The type of the TCP/IP stack.

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

Sourcemodule TCP : sig ... end
Sourcemodule TLS : sig ... end
Sourceval tcp_protocol : (stack * ipaddr * int, TCP.flow) Mimic.protocol
Sourceval tcp_edn : (stack * ipaddr * int) Mimic.value
Sourceval tls_edn : ([ `host ] Domain_name.t option * Tls.Config.client * stack * ipaddr * int) Mimic.value
Sourceval tls_protocol : ([ `host ] Domain_name.t option * Tls.Config.client * stack * ipaddr * int, TLS.flow) Mimic.protocol

Server implementation.

Sourcetype t

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

Sourcetype dst = ipaddr * int
Sourceval init : port:int -> stack -> t Lwt.t

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

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

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

Sourceval 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
Sourceval 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).

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

Sourceval 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).

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