package conduit

  1. Overview
  2. Docs

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

include sig ... end
val client_tls_config_of_sexp : Sexplib.Sexp.t -> client_tls_config
val sexp_of_client_tls_config : client_tls_config -> Sexplib.Sexp.t
type client = [
  1. | `TLS of client_tls_config
  2. | `TLS_native of client_tls_config
    (*

    Force use of native OCaml TLS stack to connect.

    *)
  3. | `OpenSSL of client_tls_config
    (*

    Force use of Lwt OpenSSL bindings to connect.

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

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

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

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

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

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

    *)
  7. | `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.
include sig ... end
val client_of_sexp : Sexplib.Sexp.t -> client
val __client_of_sexp__ : Sexplib.Sexp.t -> client
val sexp_of_client : client -> Sexplib.Sexp.t
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

include sig ... end
val server_tls_config_of_sexp : Sexplib.Sexp.t -> server_tls_config
val sexp_of_server_tls_config : server_tls_config -> Sexplib.Sexp.t
type server = [
  1. | `TLS of server_tls_config
  2. | `OpenSSL of server_tls_config
  3. | `TLS_native of server_tls_config
  4. | `TCP of [ `Port of int ]
  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
  • `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.
include sig ... end
val server_of_sexp : Sexplib.Sexp.t -> server
val __server_of_sexp__ : Sexplib.Sexp.t -> server
val sexp_of_server : server -> Sexplib.Sexp.t
type 'a io = 'a Lwt.t
type tcp_flow = private {
  1. fd : Lwt_unix.file_descr Sexplib.Conv.sexp_opaque;
  2. ip : Ipaddr.t;
  3. port : int;
}

tcp_flow contains the state of a single TCP connection.

include sig ... end
val sexp_of_tcp_flow : tcp_flow -> Sexplib.Sexp.t
type domain_flow = private {
  1. fd : Lwt_unix.file_descr Sexplib.Conv.sexp_opaque;
  2. path : string;
}

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

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

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

include sig ... end
val sexp_of_vchan_flow : vchan_flow -> Sexplib.Sexp.t
type flow = private
  1. | TCP of tcp_flow
  2. | Domain_socket of domain_flow
  3. | Vchan of vchan_flow

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

include sig ... end
val sexp_of_flow : flow -> Sexplib.Sexp.t
type tls_server_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

include sig ... end
val tls_server_key_of_sexp : Sexplib.Sexp.t -> tls_server_key
val __tls_server_key_of_sexp__ : Sexplib.Sexp.t -> tls_server_key
val sexp_of_tls_server_key : tls_server_key -> Sexplib.Sexp.t
type ctx

State handler for an active conduit

include sig ... end
val sexp_of_ctx : ctx -> Sexplib.Sexp.t

Connection and listening

val default_ctx : ctx

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

val init : ?src:string -> ?tls_server_key:tls_server_key -> unit -> ctx io

init ?src ?tls_server_key () will initialize a Unix conduit that binds to the src interface if specified. If TLS server connections are used, then tls_server_key must contain a valid certificate to be used to advertise a TLS connection

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 : ?timeout:int -> ?stop:unit io -> ctx:ctx -> mode:server -> (flow -> ic -> oc -> unit io) -> unit io

serve ?timeout ?stop ~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 !Lwt.async_exception_hook.

val endp_of_flow : flow -> Conduit.endp

endp_of_flow flow retrieves the original Conduit.endp from the established flow

val endp_to_client : ctx:ctx -> Conduit.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 Pervasives.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.

OCaml

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct