Conpool is a connection pooling library built on Eio that manages TCP connection lifecycles, validates connection health, and provides per-endpoint resource limiting for any TCP-based protocol.

Key Features#

Protocol-agnostic: Works with HTTP, Redis, PostgreSQL, or any TCP-based protocol
Health validation: Automatically validates connections before reuse
Per-endpoint limits: Independent connection limits and pooling for each endpoint
TLS support: Optional TLS configuration for secure connections
Statistics & monitoring: Track connection usage, hits/misses, and health status
Built on Eio: Leverages Eio's structured concurrency and resource management

Usage#

Basic example establishing a connection pool:

open Eio.Std

let run env =
  Switch.run (fun sw ->
    (* Create a basic connection pool (no protocol state) *)
    let pool =
      Conpool.basic
      ~sw
      ~net:(Eio.Stdenv.net env)
      ~clock:(Eio.Stdenv.clock env)
      ()
    in

    (* Define an endpoint *)
    let endpoint = Conpool.Endpoint.v ~host:"example.com" ~port:80 in
    (* Use a connection from the pool *)
    Eio.Switch.run (fun conn_sw ->
      let conn = Conpool.connection ~sw:conn_sw pool endpoint in
      Eio.Flow.copy_string "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n"
        conn.flow;
      let buf = Eio.Buf_read.of_flow conn.flow ~max_size:4096 in
      Eio.Buf_read.take_all buf))

With TLS configuration:

open Eio.Std

let run env =
  Switch.run (fun sw ->
    (* Create TLS configuration - SNI servername is automatically set to the endpoint's hostname *)
    let authenticator = Result.get_ok (Ca_certs.authenticator ()) in
    let tls_config = Result.get_ok (Tls.Config.client ~authenticator ()) in
    (* Create pool with TLS *)
    let pool =
      Conpool.basic
      ~sw
      ~net:(Eio.Stdenv.net env)
      ~clock:(Eio.Stdenv.clock env)
      ~tls:tls_config
      ()
    in

    let endpoint = Conpool.Endpoint.v ~host:"example.com" ~port:443 in
    Eio.Switch.run (fun conn_sw ->
      let conn = Conpool.connection ~sw:conn_sw pool endpoint in
      (* Use TLS-encrypted conn.flow *)
      ignore conn.flow))

Custom pool configuration:

let make_pool ~sw ~net ~clock =
  let config =
    Conpool.Config.v
      ~max_connections_per_endpoint:20
      ~max_idle_time:60.0
      ~max_connection_lifetime:300.0
      ~connect_timeout:10.0
      ()
  in
  Conpool.basic ~sw ~net ~clock ~config ()

Monitor pool statistics:

let print_stats pool endpoint =
  let stats = Conpool.stats pool endpoint in
  Printf.printf "Active: %d, Idle: %d, Created: %d, Reused: %d\n"
    (Conpool.Stats.active stats)
    (Conpool.Stats.idle stats)
    (Conpool.Stats.total_created stats)
    (Conpool.Stats.total_reused stats)

Installation#

Install with opam:

$ opam install conpool

If opam cannot find the package, it may not yet be released in the public opam-repository. Add the overlay repository, then install it:

$ opam repo add samoht https://tangled.org/gazagnaire.org/opam-overlay.git
$ opam update
$ opam install conpool

Documentation#

API documentation is available at https://tangled.org/@anil.recoil.org/ocaml-conpool or via:

opam install conpool
odig doc conpool

Licence#

ISC

Configure Feed