(** Connection pooling for efficient JMAP client connection reuse.
    
    This module provides connection pooling functionality to reuse HTTP connections
    and reduce the overhead of establishing new connections for each JMAP request.
    It supports connection timeouts, health checks, and automatic cleanup.
    
    @see <https://www.rfc-editor.org/rfc/rfc8620.html#section-3.3> RFC 8620, Section 3.3
*)

(** Statistics for connection pool monitoring *)
type pool_stats = {
  total_connections : int;       (** Total connections in pool *)
  active_connections : int;      (** Currently active connections *)  
  idle_connections : int;        (** Currently idle connections *)
  total_requests : int;          (** Total requests processed *)
  cache_hits : int;             (** Requests served from cached connections *)
  cache_misses : int;           (** Requests requiring new connections *)
  connection_failures : int;     (** Failed connection attempts *)
}

(** TLS configuration options *)
type tls_config = {
  authenticator : X509.Authenticator.t option;  (** Custom TLS authenticator *)
  certificates : Tls.Config.own_cert list;       (** Client certificates for mutual TLS *)
  ciphers : Tls.Ciphersuite.ciphersuite list option; (** Allowed cipher suites *)
  version : (Tls.Core.tls_version * Tls.Core.tls_version) option; (** Min and max TLS versions *)
  alpn_protocols : string list option;           (** ALPN protocol list *)
}

(** Connection pool configuration *)
type pool_config = {
  max_connections : int;         (** Maximum total connections *)
  max_idle_connections : int;    (** Maximum idle connections to keep *)
  connection_timeout : float;    (** Connection establishment timeout (seconds) *)
  idle_timeout : float;          (** Time to keep idle connections (seconds) *)
  max_lifetime : float;          (** Maximum connection lifetime (seconds) *)
  health_check_interval : float; (** Health check interval (seconds) *)
  enable_keep_alive : bool;      (** Enable HTTP keep-alive *)
}

(** Connection pool type - opaque *)
type t

(** Create default pool configuration *)
val default_config : unit -> pool_config

(** Create a new connection pool.
    @param config Pool configuration options
    @param sw Eio switch for resource management
    @return New connection pool *)
val create : 
  ?config:pool_config -> 
  sw:Eio.Switch.t -> 
  unit -> 
  t

(** Perform HTTP request using pooled connection.
    @param pool The connection pool to use
    @param env Eio environment for network operations  
    @param method_ HTTP method to use
    @param uri Target URI for the request
    @param headers HTTP headers to send
    @param body Optional request body
    @param tls_config Optional TLS configuration
    @return HTTP response body or error *)
val http_request_with_pool : 
  t ->
  env:< net : 'a Eio.Net.t ; .. > ->
  method_:Http.Method.t ->
  uri:Uri.t ->
  headers:(string * string) list ->
  body:string option ->
  tls_config:tls_config option ->
  (string, Jmap.Error.error) result

(** Get pool statistics for monitoring.
    @param pool The connection pool
    @return Current pool statistics *)
val get_stats : t -> pool_stats

(** Close all connections and clean up pool.
    @param pool The connection pool to close *)
val close : t -> unit