Module Conduit_lwt_unix

Connection establishment using the Lwt_unix library

Core types

type client_tls_config = [ `Hostname of string ] * [ `IP of Ipaddr.t ] * [ `Port of int ]

Configuration fragment for a TLS client connecting to a remote endpoint

val sexp_of_client_tls_config : client_tls_config -> Sexplib0.Sexp.t
val client_tls_config_of_sexp : Sexplib0.Sexp.t -> client_tls_config
type 'a io = 'a Lwt.t
type ic = Lwt_io.input_channel
val sexp_of_ic : ic -> Sexplib0.Sexp.t
val ic_of_sexp : Sexplib0.Sexp.t -> ic
type oc = Lwt_io.output_channel
val sexp_of_oc : oc -> Sexplib0.Sexp.t
val oc_of_sexp : Sexplib0.Sexp.t -> oc
type client = [
  1. | `TLS of client_tls_config
  2. | `TLS_tunnel of [ `Hostname of string ] * ic * oc
  3. | `TLS_native of client_tls_config
    (*

    Force use of native OCaml TLS stack to connect.

    *)
  4. | `OpenSSL of client_tls_config
    (*

    Force use of Lwt OpenSSL bindings to connect.

    *)
  5. | `TCP of [ `IP of Ipaddr.t ] * [ `Port of int ]
    (*

    Use TCP to connect to the given ip, port tuple.

    *)
  6. | `Unix_domain_socket of [ `File of string ]
    (*

    Use UNIX domain sockets to connect to a socket on the path.

    *)
  7. | `Vchan_direct of [ `Domid of int ] * [ `Port of string ]
    (*

    Connect to the remote VM on the domid, port tuple.

    *)
  8. | `Vchan_domain_socket of [ `Domain_name of string ] * [ `Port of string ]
    (*

    Use the Vchan name resolution to connect

    *)
]

Set of supported client connections that are supported by this module:

  • `TLS (`Hostname host, `IP ip, `Port port): Use OCaml-TLS or OpenSSL (depending on CONDUIT_TLS) to connect to the given host, ip, port tuple via TCP.
  • `TLS_native _: Force use of native OCaml TLS stack to connect.
  • `OpenSSL _: Force use of Lwt OpenSSL bindings to connect.
  • `TCP (`IP ip, `Port port): Use TCP to connect to the given ip, port tuple.
  • `Unix_domain_socket (`File path): Use UNIX domain sockets to connect to a socket on the path.
  • `Vchan_direct (`Domid domid, `Port port): Connect to the remote VM on the domid, port tuple.
  • `Vchan_domain_socket (`Domain_name domain, `Port port_name): Use the Vchan name resolution to connect.
val sexp_of_client : client -> Sexplib0.Sexp.t
val client_of_sexp : Sexplib0.Sexp.t -> client
val __client_of_sexp__ : Sexplib0.Sexp.t -> client
type server_tls_config = [ `Crt_file_path of string ] * [ `Key_file_path of string ] * [ `Password of bool -> string | `No_password ] * [ `Port of int ]

Configuration fragment for a listening TLS server

val sexp_of_server_tls_config : server_tls_config -> Sexplib0.Sexp.t
val server_tls_config_of_sexp : Sexplib0.Sexp.t -> server_tls_config
type tcp_config = [
  1. | `Port of int
  2. | `Socket of Lwt_unix.file_descr
]

Set of ways to create TCP servers

  • `Port port: Create a socket listening to provided port.
  • `Socket file_descr: Use the provided file descriptor to create a server.
val sexp_of_tcp_config : tcp_config -> Sexplib0.Sexp.t
val tcp_config_of_sexp : Sexplib0.Sexp.t -> tcp_config
val __tcp_config_of_sexp__ : Sexplib0.Sexp.t -> tcp_config
type server = [
  1. | `TLS of server_tls_config
  2. | `OpenSSL of server_tls_config
  3. | `TLS_native of server_tls_config
  4. | `TCP of tcp_config
  5. | `Unix_domain_socket of [ `File of string ]
  6. | `Vchan_direct of int * string
  7. | `Vchan_domain_socket of string * string
  8. | `Launchd of string
]

Set of supported listening mechanisms that are supported by this module.

  • `TLS server_tls_config: Use OCaml-TLS or OpenSSL (depending on CONDUIT_TLS) to connect to the given host, ip, port tuple via TCP.
  • `TLS_native _: Force use of native OCaml TLS stack to connect.
  • `OpenSSL _: Force use of Lwt OpenSSL bindings to connect.
  • `TCP (`Port port): Listen on the specified TCPv4 port.
  • `Unix_domain_socket (`File path): Use UNIX domain sockets to listen on the path.
  • `Vchan_direct (domid, port): Listen for the remote VM on the domid, port tuple.
  • `Vchan_domain_socket (domain, port_name): Use the Vchan name resolution to listen
  • `Listening_socket fd: Use the socket given, useful for inherited systemd sockets.
  • `Launchd name: uses MacOS X launchd to start the service, via the name of the Sockets element within the service description plist file. See the ocaml-launchd documentation for more.
val sexp_of_server : server -> Sexplib0.Sexp.t
val server_of_sexp : Sexplib0.Sexp.t -> server
val __server_of_sexp__ : Sexplib0.Sexp.t -> server
type tcp_flow = private {
  1. fd : Lwt_unix.file_descr;
  2. ip : Ipaddr.t;
  3. port : int;
}

tcp_flow contains the state of a single TCP connection.

val sexp_of_tcp_flow : tcp_flow -> Sexplib0.Sexp.t
type domain_flow = private {
  1. fd : Lwt_unix.file_descr;
  2. path : string;
}

domain_flow contains the state of a single Unix domain socket connection.

val sexp_of_domain_flow : domain_flow -> Sexplib0.Sexp.t
type vchan_flow = private {
  1. domid : int;
  2. port : string;
}

vchan_flow contains the state of a single Vchan shared memory connection.

val sexp_of_vchan_flow : vchan_flow -> Sexplib0.Sexp.t
type flow = private
  1. | TCP of tcp_flow
  2. | Tunnel of string * ic * oc
  3. | Domain_socket of domain_flow
  4. | Vchan of vchan_flow

A flow contains the state of a single connection, over a specific transport method.

val sexp_of_flow : flow -> Sexplib0.Sexp.t
type tls_own_key = [
  1. | `None
  2. | `TLS of [ `Crt_file_path of string ] * [ `Key_file_path of string ] * [ `Password of bool -> string | `No_password ]
]

Type describing where to locate a PEM key in the filesystem

val sexp_of_tls_own_key : tls_own_key -> Sexplib0.Sexp.t
val tls_own_key_of_sexp : Sexplib0.Sexp.t -> tls_own_key
val __tls_own_key_of_sexp__ : Sexplib0.Sexp.t -> tls_own_key
type ctx

State handler for an active conduit

val sexp_of_ctx : ctx -> Sexplib0.Sexp.t

Connection and listening

val default_ctx : ctx Stdlib.Lazy.t

Default context that listens on all source addresses with no TLS certificate associated with the Conduit

val init : ?src:string -> ?tls_own_key:tls_own_key -> ?tls_authenticator:Conduit_lwt_tls.X509.authenticator -> ?ssl_ctx:Conduit_lwt_unix_ssl.Client.context -> ?ssl_client_verify:Conduit_lwt_unix_ssl.Client.verify -> unit -> ctx io

init ?src ?tls_own_key ?tls_authenticator ?ssl_ctx () will initialize a Unix conduit that binds to the src interface if specified.

If TLS server connections are used, then tls_own_key must contain a valid certificate to be used to advertise a TLS connection. In TLS mode the certificate is validated using tls_authenticator. By default, the validation is using the OS trust anchors.

If SSL client connections are used, then tls_own_key may contain a valid certificate to be used to advertise a TLS connection. If it's not configured ssl_ctx will be used to configure OpenSSL.

val connect : ctx:ctx -> client -> (flow * ic * oc) io

connect ~ctx client establishes an outgoing connection via the ctx context to the endpoint described by client

val serve : ?backlog:int -> ?timeout:int -> ?stop:unit io -> on_exn:(exn -> unit) -> ctx:ctx -> mode:server -> (flow -> ic -> oc -> unit io) -> unit io

serve ?backlog ?timeout ?stop ~on_exn ~ctx ~mode fn establishes a listening connection of type mode, using the ctx context. The stop thread will terminate the server if it ever becomes determined. Every connection will be served in a new lightweight thread that is invoked via the fn callback. The fn callback is passed the flow representing the client connection and the associated input ic and output oc channels. If the callback raises an exception, it is passed to on_exn.

val set_max_active : int -> unit

set_max_active nconn sets the maximum number of active connections accepted. When the limit is hit accept blocks until another server connection is closed.

type endp = [
  1. | Conduit.endp
  2. | `TLS_tunnel of string * ic * oc
    (*

    Wrap in a TLS channel over an existing Lwt_io.channel connection, hostname,input_channel,output_channel

    *)
]
val sexp_of_endp : endp -> Sexplib0.Sexp.t
val endp_of_sexp : Sexplib0.Sexp.t -> endp
val __endp_of_sexp__ : Sexplib0.Sexp.t -> endp
val endp_of_flow : flow -> endp

endp_of_flow flow retrieves the original endp from the established flow

val endp_to_client : ctx:ctx -> [< endp ] -> client io

endp_to_client ~ctx endp converts an endp into a a concrete connection mechanism of type client

val endp_to_server : ctx:ctx -> Conduit.endp -> server io

endp_to_server ~ctx endp converts an endp into a a concrete connection mechanism of type server

TLS library selection

type tls_lib =
  1. | OpenSSL
    (*

    The Lwt_ssl bindings to the C OpenSSL library

    *)
  2. | Native
    (*

    A pure OCaml TLS implementation

    *)
  3. | No_tls
    (*

    No TLS implementation available, so any connections will fail

    *)

Currently selected method of using TLS for client and servers

val tls_library : tls_lib Stdlib.ref

The default selection is to select OpenSSL, Native and No_tls in decreasing order of priority. The native OCaml stack can be forced by setting the CONDUIT_TLS Unix environment variable to native.