TCP/TLS connection pooling for Eio
anil.recoil.org
1(*---------------------------------------------------------------------------
2 Copyright (c) 2025 Anil Madhavapeddy <anil@recoil.org>. All rights reserved.
3 SPDX-License-Identifier: ISC
4 ---------------------------------------------------------------------------*)
5
6(** Configuration for connection pools *)
7
8(** {1 Logging} *)
9
10val src : Logs.Src.t
11(** Logs source for configuration operations. Configure logging with:
12 {[
13 Logs.Src.set_level Conpool.Config.src (Some Logs.Debug)
14 ]} *)
15
16(** {1 Type} *)
17
18type t
19(** Pool configuration *)
20
21(** {1 Construction} *)
22
23val make :
24 ?max_connections_per_endpoint:int ->
25 ?max_idle_time:float ->
26 ?max_connection_lifetime:float ->
27 ?max_connection_uses:int ->
28 ?health_check:([Eio.Resource.close_ty | Eio.Flow.two_way_ty] Eio.Resource.t -> bool) ->
29 ?connect_timeout:float ->
30 ?connect_retry_count:int ->
31 ?connect_retry_delay:float ->
32 ?on_connection_created:(Endpoint.t -> unit) ->
33 ?on_connection_closed:(Endpoint.t -> unit) ->
34 ?on_connection_reused:(Endpoint.t -> unit) ->
35 unit ->
36 t
37(** Create pool configuration with optional parameters.
38
39 @param max_connections_per_endpoint
40 Maximum concurrent connections per endpoint (default: 10)
41 @param max_idle_time
42 Maximum time a connection can sit idle in seconds (default: 60.0)
43 @param max_connection_lifetime
44 Maximum connection age in seconds (default: 300.0)
45 @param max_connection_uses
46 Maximum times a connection can be reused (default: unlimited)
47 @param health_check Custom health check function (default: none)
48 @param connect_timeout Connection timeout in seconds (default: 10.0)
49 @param connect_retry_count Number of connection retry attempts (default: 3)
50 @param connect_retry_delay
51 Initial retry delay in seconds, with exponential backoff (default: 0.1)
52 @param on_connection_created Hook called when a connection is created
53 @param on_connection_closed Hook called when a connection is closed
54 @param on_connection_reused Hook called when a connection is reused *)
55
56val default : t
57(** Sensible defaults for most use cases:
58 - max_connections_per_endpoint: 10
59 - max_idle_time: 60.0s
60 - max_connection_lifetime: 300.0s
61 - max_connection_uses: unlimited
62 - health_check: none
63 - connect_timeout: 10.0s
64 - connect_retry_count: 3
65 - connect_retry_delay: 0.1s
66 - hooks: none *)
67
68(** {1 Accessors} *)
69
70val max_connections_per_endpoint : t -> int
71(** Get maximum connections per endpoint. *)
72
73val max_idle_time : t -> float
74(** Get maximum idle time in seconds. *)
75
76val max_connection_lifetime : t -> float
77(** Get maximum connection lifetime in seconds. *)
78
79val max_connection_uses : t -> int option
80(** Get maximum connection uses, if any. *)
81
82val health_check :
83 t -> ([Eio.Resource.close_ty | Eio.Flow.two_way_ty] Eio.Resource.t -> bool) option
84(** Get custom health check function, if any. *)
85
86val connect_timeout : t -> float option
87(** Get connection timeout in seconds, if any. *)
88
89val connect_retry_count : t -> int
90(** Get number of connection retry attempts. *)
91
92val connect_retry_delay : t -> float
93(** Get initial retry delay in seconds. *)
94
95val on_connection_created : t -> (Endpoint.t -> unit) option
96(** Get connection created hook, if any. *)
97
98val on_connection_closed : t -> (Endpoint.t -> unit) option
99(** Get connection closed hook, if any. *)
100
101val on_connection_reused : t -> (Endpoint.t -> unit) option
102(** Get connection reused hook, if any. *)
103
104(** {1 Pretty-printing} *)
105
106val pp : t Fmt.t
107(** Pretty-printer for configuration. *)