TCP/TLS connection pooling for Eio
anil.recoil.org
1# Conpool - Protocol-agnostic Connection Pooling for Eio
2
3Conpool 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.
4
5## Key Features
6
7- **Protocol-agnostic**: Works with HTTP, Redis, PostgreSQL, or any TCP-based protocol
8- **Health validation**: Automatically validates connections before reuse
9- **Per-endpoint limits**: Independent connection limits and pooling for each endpoint
10- **TLS support**: Optional TLS configuration for secure connections
11- **Statistics & monitoring**: Track connection usage, hits/misses, and health status
12- **Built on Eio**: Leverages Eio's structured concurrency and resource management
13
14## Usage
15
16Basic example establishing a connection pool:
17
18```ocaml
19open Eio.Std
20
21let run env =
22 Switch.run (fun sw ->
23 (* Create a connection pool *)
24 let pool = Conpool.create
25 ~sw
26 ~net:(Eio.Stdenv.net env)
27 ~clock:(Eio.Stdenv.clock env)
28 ()
29 in
30
31 (* Define an endpoint *)
32 let endpoint = Conpool.Endpoint.make ~host:"example.com" ~port:80 in
33
34 (* Use a connection from the pool *)
35 Conpool.with_connection pool endpoint (fun conn ->
36 Eio.Flow.copy_string "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n" conn;
37 let buf = Eio.Buf_read.of_flow conn ~max_size:4096 in
38 Eio.Buf_read.take_all buf
39 )
40 )
41```
42
43With TLS configuration:
44
45```ocaml
46let run env =
47 Switch.run (fun sw ->
48 (* Create TLS configuration - SNI servername is automatically set to the endpoint's hostname *)
49 let tls_config = Tls.Config.client ~authenticator:(Ca_certs.authenticator ()) () in
50
51 (* Create pool with TLS *)
52 let pool = Conpool.create
53 ~sw
54 ~net:(Eio.Stdenv.net env)
55 ~clock:(Eio.Stdenv.clock env)
56 ~tls:tls_config
57 ()
58 in
59
60 let endpoint = Conpool.Endpoint.make ~host:"example.com" ~port:443 in
61 Conpool.with_connection pool endpoint (fun conn ->
62 (* Use TLS-encrypted connection *)
63 ...
64 )
65 )
66```
67
68Custom pool configuration:
69
70```ocaml
71let config = Conpool.Config.make
72 ~max_connections_per_endpoint:20
73 ~max_idle_per_endpoint:5
74 ~connection_timeout:10.0
75 ~validation_interval:300.0
76 ()
77in
78
79let pool = Conpool.create ~sw ~net ~clock ~config ()
80```
81
82Monitor pool statistics:
83
84```ocaml
85let stats = Conpool.stats pool endpoint in
86Printf.printf "Active: %d, Idle: %d, Hits: %d, Misses: %d\n"
87 (Conpool.Stats.active_connections stats)
88 (Conpool.Stats.idle_connections stats)
89 (Conpool.Stats.cache_hits stats)
90 (Conpool.Stats.cache_misses stats)
91```
92
93## Installation
94
95```
96opam install conpool
97```
98
99## Documentation
100
101API documentation is available at https://tangled.org/@anil.recoil.org/ocaml-conpool or via:
102
103```
104opam install conpool
105odig doc conpool
106```
107
108## License
109
110ISC