Skip to main content

halephant_core/pool/
checkout.rs

1//! Connection checkout — the hot path through the pool.
2
3use std::sync::Arc;
4use std::sync::atomic::Ordering;
5use std::time::{Duration, Instant};
6
7use tokio::sync::oneshot;
8use tracing::debug;
9
10use crate::clients;
11use crate::errors::ResolveError;
12use crate::o11y;
13use crate::pool::PoolManager;
14use crate::pool::candidates::ConnectSpec;
15use crate::pool::types::{
16    CandidateResult, CheckoutError, ConnGuard, ConnId, PoolKey, Routing, WaitKey, Waiter,
17    classify_checkout_error,
18};
19
20impl PoolManager {
21    #[tracing::instrument(name = "pool.checkout", skip_all, err(Display), fields(
22        db.namespace = %database,
23        user = %user,
24        halephant.client.id = client.id().as_u64(),
25        read_only,
26        pool.reused,
27        pool.waited,
28        otel.status_code,
29        otel.status_description,
30    ))]
31    pub async fn checkout(
32        self: &Arc<Self>,
33        client: &clients::ClientGuard,
34        database: &str,
35        user: &str,
36        read_only: bool,
37    ) -> anyhow::Result<ConnGuard> {
38        let routing = if read_only {
39            Routing::Replica
40        } else {
41            Routing::Primary
42        };
43        let wait_key = WaitKey {
44            database: database.to_owned(),
45            role: routing,
46        };
47
48        let cfg = self.config.load_full();
49        let checkout_start = Instant::now();
50        let mut queue_start: Option<Instant> = None;
51
52        async {
53            let (cluster_name, idle_timeout, max_lifetime, checkout_timeout) = {
54                let Some((name, _, pool_config)) = cfg.find_pool(database) else {
55                    return Err(ResolveError::UnknownDatabase {
56                        database: database.to_owned(),
57                    }
58                    .into());
59                };
60                (
61                    name.to_owned(),
62                    pool_config.idle_timeout,
63                    pool_config.max_lifetime,
64                    pool_config
65                        .checkout_timeout
66                        .unwrap_or(cfg.server.checkout_timeout),
67                )
68            };
69
70            // One resolver owns the upstream connect identity, shared
71            // with refill. An unconfigured user is refused here —
72            // matching the frontend's `is_user_allowed` gate — never
73            // silently mapped to the client-facing name.
74            let spec = ConnectSpec::resolve(&cfg, database, user)?;
75
76            loop {
77                // Build candidate lists: primary target first, then
78                // primary as fallback for read-only traffic.
79                let candidates = self.resolve_candidates(&cfg, database, user, routing);
80                let fallback = if routing == Routing::Replica {
81                    self.resolve_candidates(&cfg, database, user, Routing::Primary)
82                } else {
83                    Vec::new()
84                };
85                if candidates.is_empty() && fallback.is_empty() {
86                    return Err(match routing {
87                        Routing::Primary => ResolveError::NoPrimary {
88                            cluster: cluster_name.clone(),
89                        },
90                        Routing::Replica => ResolveError::NoReplica {
91                            cluster: cluster_name.clone(),
92                        },
93                    }
94                    .into());
95                }
96
97                // Try preferred candidates, then fallback.
98                let mut got = CandidateResult::AllFull;
99                for batch in [&candidates, &fallback] {
100                    if batch.is_empty() {
101                        continue;
102                    }
103                    got = self.try_candidates(&cfg, batch, idle_timeout, max_lifetime);
104                    if !matches!(got, CandidateResult::AllFull) {
105                        break;
106                    }
107                }
108
109                match got {
110                    CandidateResult::GotIdle { key, conn } => {
111                        record_checkout_success(
112                            &key,
113                            checkout_start,
114                            queue_start,
115                            database,
116                            user,
117                            routing,
118                            true,
119                        );
120                        return Ok(ConnGuard {
121                            pools: Arc::clone(self),
122                            key,
123                            id: conn.id,
124                            conn: Some(conn.conn),
125                        });
126                    }
127                    CandidateResult::Claimed { key, id } => {
128                        match self.connect_with_spec(&key.node, &spec).await {
129                            Ok(conn) => {
130                                record_checkout_success(
131                                    &key,
132                                    checkout_start,
133                                    queue_start,
134                                    database,
135                                    user,
136                                    routing,
137                                    false,
138                                );
139                                return Ok(ConnGuard {
140                                    pools: Arc::clone(self),
141                                    key,
142                                    id,
143                                    conn: Some(conn),
144                                });
145                            }
146                            Err(e) => {
147                                self.discard_internal(&key, id);
148                                let total = candidates.len() + fallback.len();
149                                if total == 1 {
150                                    return Err(e);
151                                }
152                            }
153                        }
154                    }
155                    CandidateResult::AllFull => {}
156                }
157
158                let rx = {
159                    let (tx, rx) = oneshot::channel();
160                    let mut inner = self.inner.lock();
161                    inner
162                        .waits
163                        .entry(wait_key.clone())
164                        .or_default()
165                        .waiters
166                        .push_back(Waiter {
167                            enqueued_at: Instant::now(),
168                            user: user.to_owned(),
169                            tx,
170                        });
171                    rx
172                };
173                client.set_waiting_for(Some(clients::WaitTarget {
174                    database: database.to_owned(),
175                    user: user.to_owned(),
176                    role: match routing {
177                        Routing::Primary => clients::WaitRole::Primary,
178                        Routing::Replica => clients::WaitRole::Replica,
179                    },
180                }));
181                client.set_state(clients::ClientState::Waiting);
182                queue_start.get_or_insert_with(Instant::now);
183
184                let timeout_error = || CheckoutError::Timeout {
185                    timeout: checkout_timeout,
186                    database: database.to_owned(),
187                    user: user.to_owned(),
188                };
189                let remaining = checkout_timeout.saturating_sub(checkout_start.elapsed());
190                if remaining.is_zero() {
191                    client.set_waiting_for(None);
192                    client.set_state(clients::ClientState::Idle);
193                    return Err(timeout_error().into());
194                }
195                let wake = tokio::time::timeout(remaining, rx).await;
196                client.set_waiting_for(None);
197                client.set_state(clients::ClientState::Idle);
198
199                if wake.is_err() {
200                    return Err(timeout_error().into());
201                }
202                if self.shutting_down.load(Ordering::Acquire) {
203                    return Err(CheckoutError::ShuttingDown.into());
204                }
205            }
206        }
207        .await
208        .inspect(|_| {
209            tracing::Span::current().record("otel.status_code", "OK");
210        })
211        .inspect_err(|e| {
212            o11y::metrics::record_checkout_error(database, user, classify_checkout_error(e));
213            let span = tracing::Span::current();
214            span.record("otel.status_code", "ERROR");
215            span.record("otel.status_description", "checkout failed");
216        })
217    }
218
219    // -----------------------------------------------------------------------
220    // Internals
221    // -----------------------------------------------------------------------
222
223    fn resolve_candidates(
224        &self,
225        cfg: &crate::config::Config,
226        database: &str,
227        user: &str,
228        routing: Routing,
229    ) -> Vec<PoolKey> {
230        let Some((cluster_name, _, _)) = cfg.find_pool(database) else {
231            return Vec::new();
232        };
233        match routing {
234            Routing::Primary => {
235                let Some(primary) = self.topology.primary(cluster_name) else {
236                    return Vec::new();
237                };
238                vec![PoolKey {
239                    node: primary,
240                    database: database.to_owned(),
241                    user: user.to_owned(),
242                }]
243            }
244            Routing::Replica => self
245                .topology
246                .replicas(cluster_name)
247                .iter()
248                .map(|addr| PoolKey {
249                    node: addr.clone(),
250                    database: database.to_owned(),
251                    user: user.to_owned(),
252                })
253                .collect(),
254        }
255    }
256
257    fn try_candidates(
258        &self,
259        cfg: &crate::config::Config,
260        candidates: &[PoolKey],
261        idle_timeout: Duration,
262        max_lifetime: Duration,
263    ) -> CandidateResult {
264        let mut inner = self.inner.lock();
265
266        // Rank by active count (least-connections). Rotate for tie-break.
267        let mut ranked: Vec<&PoolKey> = candidates.iter().collect();
268        if ranked.len() > 1 {
269            let start = self.replica_rr.fetch_add(1, Ordering::Relaxed) % ranked.len();
270            ranked.rotate_left(start);
271            ranked.sort_by_key(|k| inner.pools.get(*k).map_or(0, |p| p.active.len()));
272        }
273
274        for key in ranked {
275            let limits = self.resolve_limits(cfg, key);
276
277            // Try to reuse an idle connection. Scoped so the mutable
278            // pool borrow drops before the node_total scan.
279            let idle = {
280                let pool = inner.pools.entry(key.clone()).or_default();
281                let idle = pool.pop_idle(idle_timeout, max_lifetime);
282                if let Some(ref c) = idle {
283                    pool.active.insert(c.id);
284                }
285                idle
286            };
287            if let Some(idle) = idle {
288                return CandidateResult::GotIdle {
289                    key: key.clone(),
290                    conn: Box::new(idle),
291                };
292            }
293
294            let user_total = inner.pools.get(key).map_or(0, super::types::Pool::total);
295            if !limits.user_has_capacity(user_total) {
296                continue;
297            }
298
299            let node_total = inner.node_total(&key.node, &key.database);
300            if !limits.pool_has_capacity(node_total) && !Self::evict_idle_for_node(&mut inner, key)
301            {
302                continue;
303            }
304
305            let id = ConnId::next();
306            inner
307                .pools
308                .entry(key.clone())
309                .or_default()
310                .active
311                .insert(id);
312            return CandidateResult::Claimed {
313                key: key.clone(),
314                id,
315            };
316        }
317
318        CandidateResult::AllFull
319    }
320
321    fn evict_idle_for_node(inner: &mut super::types::Inner, key: &PoolKey) -> bool {
322        let victim = inner
323            .pools
324            .iter()
325            .filter(|(k, p)| k.node == key.node && k.database == key.database && !p.idle.is_empty())
326            .min_by_key(|(_, p)| p.idle.front().map_or(Instant::now(), |i| i.idle_since))
327            .map(|(k, _)| k.clone());
328        if let Some(ref vk) = victim
329            && let Some(pool) = inner.pools.get_mut(vk)
330        {
331            pool.idle.pop_front();
332        }
333        victim.is_some()
334    }
335
336    pub(in crate::pool) fn discard_internal(&self, key: &PoolKey, id: ConnId) {
337        {
338            let mut inner = self.inner.lock();
339            if let Some(pool) = inner.pools.get_mut(key) {
340                pool.active.remove(&id);
341            }
342        }
343        self.wake_one_for_node(key);
344    }
345}
346
347fn record_checkout_success(
348    key: &PoolKey,
349    checkout_start: Instant,
350    queue_start: Option<Instant>,
351    database: &str,
352    user: &str,
353    routing: Routing,
354    reused: bool,
355) {
356    if let Some(queued_at) = queue_start {
357        o11y::metrics::record_wait_duration(queued_at.elapsed(), database, user, routing);
358    }
359    o11y::metrics::record_checkout(checkout_start, database, user, &key.node);
360    let span = tracing::Span::current();
361    span.record("pool.reused", reused);
362    span.record("pool.waited", queue_start.is_some());
363    debug!(database, user, node = %key.node, reused, "checkout complete");
364}