Skip to main content

halephant_core/pool/
mod.rs

1#![cfg_attr(test, allow(clippy::unwrap_used))]
2mod candidates;
3mod checkout;
4pub mod prepared;
5mod refill;
6pub mod types;
7mod wait;
8
9pub use types::{ConnGuard, Routing};
10
11use std::collections::HashMap;
12use std::sync::Arc;
13use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
14use std::time::Instant;
15
16use arc_swap::ArcSwap;
17use parking_lot::Mutex;
18use tracing::debug;
19
20use crate::auth::pgpass::Pgpass;
21use crate::config::Config;
22use crate::errors::ResolveError;
23use crate::o11y;
24use crate::topology;
25
26// ---------------------------------------------------------------------------
27// Public types
28// ---------------------------------------------------------------------------
29
30/// Manages connection pools keyed by (node, database, user). Each upstream
31/// node gets its own pool, enabling per-node failover and separate
32/// primary/replica connection limits.
33pub struct PoolManager {
34    pub(in crate::pool) inner: Mutex<types::Inner>,
35    /// Hot-reloadable configuration handle. Operations that span
36    /// multiple reads snapshot via `self.config.load_full()` at the
37    /// start for intra-operation consistency; transient reads (e.g.,
38    /// from background tasks like `reset_and_return`) can load fresh
39    /// on each access to pick up the latest config.
40    pub(in crate::pool) config: Arc<ArcSwap<Config>>,
41    pub(in crate::pool) topology: Arc<topology::TopologyManager>,
42    pub(in crate::pool) pgpass: Arc<Pgpass>,
43    /// Round-robin counter for replica selection across clusters.
44    pub(in crate::pool) replica_rr: AtomicUsize,
45    /// Global prepared statement store shared across all clients.
46    pub(crate) stmt_store: Mutex<prepared::StatementStore>,
47    /// Set by [`PoolManager::shutdown`] to signal queued waiters to
48    /// abort. Sits on a dedicated atomic so the wait loop can check it
49    /// without reacquiring the inner lock.
50    pub(in crate::pool) shutting_down: AtomicBool,
51}
52
53// ---------------------------------------------------------------------------
54// PoolManager — construction and public API
55// ---------------------------------------------------------------------------
56
57impl PoolManager {
58    pub fn new(
59        config: Arc<ArcSwap<Config>>,
60        topology: Arc<topology::TopologyManager>,
61        pgpass: Arc<Pgpass>,
62    ) -> Self {
63        Self {
64            inner: Mutex::new(types::Inner {
65                pools: HashMap::new(),
66                waits: HashMap::new(),
67            }),
68            config,
69            topology,
70            pgpass,
71            replica_rr: AtomicUsize::new(0),
72            stmt_store: Mutex::new(prepared::StatementStore::new()),
73            shutting_down: AtomicBool::new(false),
74        }
75    }
76
77    /// Access the shared config handle. Used by the reload path to
78    /// atomically swap in a new `Config` via `store`; callers that just
79    /// want to read the current config should use `load_full()` on the
80    /// returned handle for intra-operation consistency.
81    pub fn config(&self) -> &Arc<ArcSwap<Config>> {
82        &self.config
83    }
84
85    /// Access the pgpass store.
86    pub fn pgpass(&self) -> &Pgpass {
87        &self.pgpass
88    }
89
90    /// Signal that halephant is shutting down: set the shutdown flag
91    /// and wake every queued waiter so they return a classified error
92    /// immediately instead of sitting on the queue until `checkout_timeout`
93    /// expires or they get force-aborted.
94    ///
95    /// Called from the graceful shutdown path in `main` right after the
96    /// accept loop exits, before draining client tasks.
97    pub fn shutdown(&self) {
98        self.shutting_down.store(true, Ordering::Release);
99        self.wake_all_waiters();
100    }
101
102    /// Resolve a routing target for a database. Returns the upstream
103    /// address as an owned string.
104    ///
105    /// Returns a specific [`ResolveError`] if the database is unknown, the
106    /// primary has not been discovered, or no healthy replica is available.
107    pub fn resolve(&self, database: &str, routing: Routing) -> Result<String, ResolveError> {
108        let cfg = self.config.load_full();
109        let (cluster_name, _, _) =
110            cfg.find_pool(database)
111                .ok_or_else(|| ResolveError::UnknownDatabase {
112                    database: database.to_owned(),
113                })?;
114
115        match routing {
116            Routing::Primary => {
117                self.topology
118                    .primary(cluster_name)
119                    .ok_or_else(|| ResolveError::NoPrimary {
120                        cluster: cluster_name.to_owned(),
121                    })
122            }
123            Routing::Replica => {
124                let replicas = self.topology.replicas(cluster_name);
125                if replicas.is_empty() {
126                    return Err(ResolveError::NoReplica {
127                        cluster: cluster_name.to_owned(),
128                    });
129                }
130                // `resolve` is a read-only lookup used by admin/metrics
131                // callers that want _an_ address, not a reservation.
132                // Snapshot the RR counter with `load` instead of
133                // `fetch_add` so these calls don't steal a rotation
134                // slot from the checkout path and skew replica
135                // distribution.
136                let idx = self.replica_rr.load(Ordering::Relaxed) % replicas.len();
137                Ok(replicas[idx].clone())
138            }
139        }
140    }
141
142    /// Look up the upstream password from the `.pgpass` file for the given
143    /// connection parameters. Returns `None` if no matching entry exists.
144    pub(in crate::pool) fn lookup_password(
145        &self,
146        addr: &str,
147        database: &str,
148        user: &str,
149    ) -> Option<String> {
150        self.pgpass
151            .lookup_addr(addr, database, user)
152            .map(str::to_owned)
153    }
154
155    /// Drain idle connections for a specific node across all databases/users.
156    /// Called when topology detects a node role change or unreachability.
157    pub fn drain_node(&self, node: &str) {
158        let drained = {
159            let mut inner = self.inner.lock();
160            let mut drained = 0u32;
161            for (key, pool) in &mut inner.pools {
162                if key.node == node {
163                    drained += pool.idle.len() as u32;
164                    pool.idle.clear();
165                }
166            }
167            drained
168        };
169        if drained > 0 {
170            debug!(node, drained, "drained idle connections for node");
171        }
172        // Topology has changed for this node (likely a role flip) —
173        // wake every waiter so they re-run `candidate_nodes` against
174        // the fresh topology. The waiter that was blocked on the old
175        // role's queue may now belong on the other queue entirely.
176        self.wake_all_waiters();
177    }
178
179    /// Close all idle connections across all pools. Called during shutdown.
180    pub fn drain_all(&self) {
181        let mut inner = self.inner.lock();
182        let mut drained = 0u32;
183        for pool in inner.pools.values_mut() {
184            drained += pool.idle.len() as u32;
185            pool.idle.clear();
186        }
187        if drained > 0 {
188            debug!(drained, "drained all idle connections for shutdown");
189        }
190    }
191
192    /// Returns a snapshot of all pool states for metrics reporting.
193    pub fn pool_stats(&self) -> Vec<(o11y::metrics::PoolKeyInfo, o11y::metrics::PoolStats)> {
194        let inner = self.inner.lock();
195        inner
196            .pools
197            .iter()
198            .map(|(key, pool)| {
199                (
200                    o11y::metrics::PoolKeyInfo {
201                        node: key.node.clone(),
202                        database: key.database.clone(),
203                        user: key.user.clone(),
204                    },
205                    o11y::metrics::PoolStats {
206                        active: pool.active,
207                        idle: pool.idle.len() as u32,
208                        resetting: pool.resetting,
209                    },
210                )
211            })
212            .collect()
213    }
214
215    /// Returns a snapshot of every non-empty wait queue.
216    #[must_use]
217    pub fn queue_stats(&self) -> Vec<o11y::metrics::QueueInfo> {
218        let now = Instant::now();
219        let inner = self.inner.lock();
220        inner
221            .waits
222            .iter()
223            .filter_map(|(key, queue)| {
224                let depth = queue.waiters.len();
225                if depth == 0 {
226                    return None;
227                }
228                let oldest = queue.waiters.front().map_or(0.0, |(enqueued_at, _)| {
229                    now.saturating_duration_since(*enqueued_at).as_secs_f64()
230                });
231                Some(o11y::metrics::QueueInfo {
232                    database: key.database.clone(),
233                    user: key.user.clone(),
234                    role: key.role,
235                    depth: depth as u32,
236                    oldest_wait_secs: oldest,
237                })
238            })
239            .collect()
240    }
241
242    /// Returns the configured connection limits for each pool.
243    pub fn pool_limits(&self) -> Vec<o11y::metrics::PoolLimits> {
244        let cfg = self.config.load_full();
245        cfg.cluster
246            .values()
247            .flat_map(|cluster| {
248                cluster
249                    .pool
250                    .iter()
251                    .map(|(db_name, pool)| o11y::metrics::PoolLimits {
252                        database: pool.database_name(db_name).to_owned(),
253                        max_primary: pool.max_connections.primary,
254                        max_replica: pool.max_connections.replica,
255                    })
256            })
257            .collect()
258    }
259}