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}