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    /// Check whether a canonical statement exists in the global store.
86    #[doc(hidden)]
87    pub fn has_prepared(&self, canon: &str) -> bool {
88        self.stmt_store.lock().get(canon).is_some()
89    }
90
91    /// Access the pgpass store.
92    pub fn pgpass(&self) -> &Pgpass {
93        &self.pgpass
94    }
95
96    /// Signal that halephant is shutting down: set the shutdown flag
97    /// and wake every queued waiter so they return a classified error
98    /// immediately instead of sitting on the queue until `checkout_timeout`
99    /// expires or they get force-aborted.
100    ///
101    /// Called from the graceful shutdown path in `main` right after the
102    /// accept loop exits, before draining client tasks.
103    pub fn shutdown(&self) {
104        self.shutting_down.store(true, Ordering::Release);
105        self.wake_all_waiters();
106    }
107
108    /// Resolve a routing target for a database. Returns the upstream
109    /// address as an owned string.
110    ///
111    /// Returns a specific [`ResolveError`] if the database is unknown, the
112    /// primary has not been discovered, or no healthy replica is available.
113    pub fn resolve(&self, database: &str, routing: Routing) -> Result<String, ResolveError> {
114        let cfg = self.config.load_full();
115        let (cluster_name, _, _) =
116            cfg.find_pool(database)
117                .ok_or_else(|| ResolveError::UnknownDatabase {
118                    database: database.to_owned(),
119                })?;
120
121        match routing {
122            Routing::Primary => {
123                self.topology
124                    .primary(cluster_name)
125                    .ok_or_else(|| ResolveError::NoPrimary {
126                        cluster: cluster_name.to_owned(),
127                    })
128            }
129            Routing::Replica => {
130                let replicas = self.topology.replicas(cluster_name);
131                if replicas.is_empty() {
132                    return Err(ResolveError::NoReplica {
133                        cluster: cluster_name.to_owned(),
134                    });
135                }
136                // `resolve` is a read-only lookup used by admin/metrics
137                // callers that want _an_ address, not a reservation.
138                // Snapshot the RR counter with `load` instead of
139                // `fetch_add` so these calls don't steal a rotation
140                // slot from the checkout path and skew replica
141                // distribution.
142                let idx = self.replica_rr.load(Ordering::Relaxed) % replicas.len();
143                Ok(replicas[idx].clone())
144            }
145        }
146    }
147
148    /// Look up the upstream password from the `.pgpass` file for the given
149    /// connection parameters. Returns `None` if no matching entry exists.
150    pub(in crate::pool) fn lookup_password(
151        &self,
152        addr: &str,
153        database: &str,
154        user: &str,
155    ) -> Option<String> {
156        self.pgpass
157            .lookup_addr(addr, database, user)
158            .map(str::to_owned)
159    }
160
161    /// Drain idle connections for a specific node across all databases/users.
162    /// Called when topology detects a node role change or unreachability.
163    pub fn drain_node(&self, node: &str) {
164        let drained = {
165            let mut inner = self.inner.lock();
166            let mut drained = 0u32;
167            for (key, pool) in &mut inner.pools {
168                if key.node == node {
169                    drained += pool.idle.len() as u32;
170                    pool.idle.clear();
171                }
172            }
173            drained
174        };
175        if drained > 0 {
176            debug!(node, drained, "drained idle connections for node");
177        }
178        // Topology has changed for this node (likely a role flip) —
179        // wake every waiter so they re-run `candidate_nodes` against
180        // the fresh topology. The waiter that was blocked on the old
181        // role's queue may now belong on the other queue entirely.
182        self.wake_all_waiters();
183    }
184
185    /// Close all idle connections across all pools. Called during shutdown.
186    pub fn drain_all(&self) {
187        let mut inner = self.inner.lock();
188        let mut drained = 0u32;
189        for pool in inner.pools.values_mut() {
190            drained += pool.idle.len() as u32;
191            pool.idle.clear();
192        }
193        if drained > 0 {
194            debug!(drained, "drained all idle connections for shutdown");
195        }
196    }
197
198    /// Returns a snapshot of all pool states for metrics reporting.
199    pub fn pool_stats(&self) -> Vec<(o11y::metrics::PoolKeyInfo, o11y::metrics::PoolStats)> {
200        let inner = self.inner.lock();
201        inner
202            .pools
203            .iter()
204            .map(|(key, pool)| {
205                (
206                    o11y::metrics::PoolKeyInfo {
207                        node: key.node.clone(),
208                        database: key.database.clone(),
209                        user: key.user.clone(),
210                    },
211                    o11y::metrics::PoolStats {
212                        active: pool.active,
213                        idle: pool.idle.len() as u32,
214                        resetting: pool.resetting,
215                    },
216                )
217            })
218            .collect()
219    }
220
221    /// Returns a snapshot of every non-empty wait queue.
222    #[must_use]
223    pub fn queue_stats(&self) -> Vec<o11y::metrics::QueueInfo> {
224        let now = Instant::now();
225        let inner = self.inner.lock();
226        inner
227            .waits
228            .iter()
229            .filter_map(|(key, queue)| {
230                let depth = queue.waiters.len();
231                if depth == 0 {
232                    return None;
233                }
234                let oldest = queue.waiters.front().map_or(0.0, |(enqueued_at, _)| {
235                    now.saturating_duration_since(*enqueued_at).as_secs_f64()
236                });
237                Some(o11y::metrics::QueueInfo {
238                    database: key.database.clone(),
239                    user: key.user.clone(),
240                    role: key.role,
241                    depth: depth as u32,
242                    oldest_wait_secs: oldest,
243                })
244            })
245            .collect()
246    }
247
248    /// Returns the configured connection limits for each pool.
249    pub fn pool_limits(&self) -> Vec<o11y::metrics::PoolLimits> {
250        let cfg = self.config.load_full();
251        cfg.cluster
252            .values()
253            .flat_map(|cluster| {
254                cluster
255                    .pool
256                    .iter()
257                    .map(|(db_name, pool)| o11y::metrics::PoolLimits {
258                        database: pool.database_name(db_name).to_owned(),
259                        max_primary: pool.max_connections.primary,
260                        max_replica: pool.max_connections.replica,
261                    })
262            })
263            .collect()
264    }
265}