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}