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 connection pool *)
    let pool = Conpool.create
      ~sw
      ~net:(Eio.Stdenv.net env)
      ~clock:(Eio.Stdenv.clock env)
      ()
    in

    (* Define an endpoint *)
    let endpoint = Conpool.Endpoint.make ~host:"example.com" ~port:80 in

    (* Use a connection from the pool *)
    Conpool.with_connection pool endpoint (fun conn ->
      Eio.Flow.copy_string "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n" conn;
      let buf = Eio.Buf_read.of_flow conn ~max_size:4096 in
      Eio.Buf_read.take_all buf
    )
  )

With TLS configuration:

let run env =
  Switch.run (fun sw ->
    (* Create TLS configuration *)
    let tls = Conpool.Tls_config.make
      ~authenticator:(Ca_certs.authenticator ())
      ()
    in

    (* Create pool with TLS *)
    let pool = Conpool.create
      ~sw
      ~net:(Eio.Stdenv.net env)
      ~clock:(Eio.Stdenv.clock env)
      ~tls
      ()
    in

    let endpoint = Conpool.Endpoint.make ~host:"example.com" ~port:443 in
    Conpool.with_connection pool endpoint (fun conn ->
      (* Use TLS-encrypted connection *)
      ...
    )
  )

Custom pool configuration:

let config = Conpool.Config.make
  ~max_connections_per_endpoint:20
  ~max_idle_per_endpoint:5
  ~connection_timeout:10.0
  ~validation_interval:300.0
  ()
in

let pool = Conpool.create ~sw ~net ~clock ~config ()

Monitor pool statistics:

let stats = Conpool.stats pool endpoint in
Printf.printf "Active: %d, Idle: %d, Hits: %d, Misses: %d\n"
  (Conpool.Stats.active_connections stats)
  (Conpool.Stats.idle_connections stats)
  (Conpool.Stats.cache_hits stats)
  (Conpool.Stats.cache_misses stats)

Installation#

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

License#

ISC

Clone this repository