Skip to main content

halephant_core/auth/
query.rs

1use std::sync::Arc;
2use std::time::{Duration, Instant};
3
4use futures_util::{SinkExt, StreamExt};
5use moka::Expiry;
6use moka::future::Cache;
7use tokio::net::TcpStream;
8use tokio_util::codec::Framed;
9use tracing::debug;
10
11use crate::auth::scram;
12use crate::connections::server::connect_tcp;
13use crate::errors;
14use crate::proto;
15
16// ---------------------------------------------------------------------------
17// Verifier cache
18// ---------------------------------------------------------------------------
19
20type CacheKey = (String, String);
21
22/// Upper bound on cached verifier entries. Each entry is ~100 bytes of
23/// verifier material plus the key strings, so 10k entries is roughly
24/// 1–2 MB — comfortably more than any realistic halephant deployment
25/// needs (bounded by `users × clusters`), while small enough that
26/// hitting the cap indicates configuration drift rather than normal
27/// operation. Moka evicts entries via its Window TinyLFU policy when
28/// the cap is reached.
29const MAX_CACHED_VERIFIERS: u64 = 10_000;
30
31/// Caches SCRAM verifiers fetched via `auth_query`, keyed by
32/// (upstream_addr, username).
33///
34/// Backed by [`moka::future::Cache`], which provides:
35///
36/// - **Bounded capacity** via LRU-ish W-TinyLFU eviction, so entries
37///   for decommissioned users or upstreams don't linger forever.
38/// - **Per-entry TTL** via a custom [`Expiry`] impl, so each cluster's
39///   configured `auth.cache_ttl` is honoured independently — a setup
40///   with one short-lived and one long-lived cluster gets the exact
41///   behaviour each configured.
42/// - **Concurrent miss coalescing** via `try_get_with`: multiple
43///   concurrent callers for the same key share a single upstream
44///   fetch, avoiding a thundering herd of auth queries when the first
45///   authentication request arrives for a fresh entry.
46pub struct VerifierCache {
47    entries: Cache<CacheKey, CachedEntry>,
48}
49
50/// Value stored in the cache. The TTL travels alongside the verifier
51/// so the [`Expiry`] impl can read it at insert time — this is how
52/// moka supports per-entry expiry while still using a single `Cache`
53/// instance shared across every cluster.
54#[derive(Clone)]
55struct CachedEntry {
56    verifier: scram::ScramVerifier,
57    ttl: Duration,
58}
59
60/// Reads the per-entry TTL from the stored value. Only
61/// `expire_after_create` is overridden — `expire_after_read` and
62/// `expire_after_update` default to `None`, meaning "keep the
63/// previously-computed expiration." Reads do not extend the lifetime.
64struct CachedEntryExpiry;
65
66impl Expiry<CacheKey, CachedEntry> for CachedEntryExpiry {
67    fn expire_after_create(
68        &self,
69        _key: &CacheKey,
70        value: &CachedEntry,
71        _created_at: Instant,
72    ) -> Option<Duration> {
73        Some(value.ttl)
74    }
75}
76
77impl Default for VerifierCache {
78    fn default() -> Self {
79        Self::new()
80    }
81}
82
83impl VerifierCache {
84    pub fn new() -> Self {
85        let expiry: Arc<dyn Expiry<CacheKey, CachedEntry> + Send + Sync + 'static> =
86            Arc::new(CachedEntryExpiry);
87        Self {
88            entries: Cache::builder()
89                .max_capacity(MAX_CACHED_VERIFIERS)
90                .expire_after(expiry)
91                .build(),
92        }
93    }
94
95    /// Look up a verifier from cache, or fetch it via `auth_query` if
96    /// missing or expired. Concurrent callers for the same key share
97    /// a single upstream fetch via `moka::future::Cache::try_get_with`.
98    pub(crate) async fn get(
99        &self,
100        user: &str,
101        admin: &crate::auth::AdminConn<'_>,
102    ) -> Result<scram::ScramVerifier, errors::AuthError> {
103        let cache_key: CacheKey = (admin.addr.to_owned(), user.to_owned());
104
105        // Every concurrent caller for `cache_key` that arrives while
106        // the future below is still pending shares this single fetch.
107        // The owned clones exist because the future must be 'static —
108        // moka stores it internally and polls it from a background
109        // task. `try_get_with` returns `Arc<E>` on error so the error
110        // can be shared among the coalesced waiters; we stringify
111        // through `VerifierFetch` rather than cloning because
112        // `AuthError` is not `Clone` (it carries `std::io::Error`).
113        let admin_user = admin.admin_user.to_owned();
114        let admin_database = admin.admin_database.to_owned();
115        let admin_pw = admin.password.map(str::to_owned);
116        let auth_query = admin.auth_query.to_owned();
117        let upstream_addr_owned = admin.addr.to_owned();
118        let user_owned = user.to_owned();
119        let cache_ttl = admin.cache_ttl;
120        let connect_timeout = admin.connect_timeout;
121
122        let entry = self
123            .entries
124            .try_get_with(cache_key, async move {
125                debug!(
126                    user = %user_owned,
127                    upstream = %upstream_addr_owned,
128                    admin_database = %admin_database,
129                    "fetching verifier via auth_query",
130                );
131                let verifier = fetch_verifier(
132                    &upstream_addr_owned,
133                    &admin_user,
134                    &admin_database,
135                    admin_pw.as_deref(),
136                    &auth_query,
137                    &user_owned,
138                    connect_timeout,
139                )
140                .await?;
141                Ok::<_, errors::AuthError>(CachedEntry {
142                    verifier,
143                    ttl: cache_ttl,
144                })
145            })
146            .await
147            .map_err(|e: Arc<errors::AuthError>| errors::AuthError::VerifierFetch(e.to_string()))?;
148
149        Ok(entry.verifier)
150    }
151}
152
153// ---------------------------------------------------------------------------
154// auth_query execution
155// ---------------------------------------------------------------------------
156
157/// Connect to `upstream_addr` as `admin_user`, authenticate (via SCRAM if
158/// required), run the `auth_query` for `target_user`, and parse the returned
159/// SCRAM verifier. The startup message selects `admin_database` — `"postgres"`
160/// by default, but operators can override when `auth_query` references
161/// database-local objects.
162///
163/// Routes through [`connect_tcp`] so the verifier fetch shares the
164/// same connect budget, `TCP_NODELAY`, and keepalive settings as
165/// every other upstream connection path.
166#[allow(clippy::too_many_arguments)]
167async fn fetch_verifier(
168    upstream_addr: &str,
169    admin_user: &str,
170    admin_database: &str,
171    admin_password: Option<&str>,
172    auth_query_template: &str,
173    target_user: &str,
174    connect_timeout: Duration,
175) -> Result<scram::ScramVerifier, errors::AuthError> {
176    let stream = connect_tcp(upstream_addr, connect_timeout)
177        .await
178        .map_err(|e| {
179            errors::AuthError::VerifierFetch(format!("connect to {upstream_addr}: {e}"))
180        })?;
181    let mut conn = Framed::new(stream, proto::codec::BackendCodec::new());
182
183    let result = run_auth_query(
184        &mut conn,
185        admin_user,
186        admin_database,
187        admin_password,
188        auth_query_template,
189        target_user,
190    )
191    .await;
192
193    // Always send Terminate to cleanly close the admin connection,
194    // regardless of whether the query succeeded or failed.
195    let _ = conn.send(proto::frontend::FrontendMessage::Terminate).await;
196
197    result
198}
199
200/// Run the startup handshake and auth query on an established connection.
201async fn run_auth_query(
202    conn: &mut Framed<TcpStream, proto::codec::BackendCodec>,
203    admin_user: &str,
204    admin_database: &str,
205    admin_password: Option<&str>,
206    auth_query_template: &str,
207    target_user: &str,
208) -> Result<scram::ScramVerifier, errors::AuthError> {
209    conn.send(proto::frontend::FrontendMessage::Startup(
210        proto::frontend::Startup {
211            version: proto::frontend::ProtocolVersion { major: 3, minor: 0 },
212            parameters: vec![
213                ("user".into(), admin_user.into()),
214                ("database".into(), admin_database.into()),
215            ],
216        },
217    ))
218    .await
219    .map_err(|e| errors::AuthError::VerifierFetch(format!("send startup: {e}")))?;
220
221    // Consume startup responses until ReadyForQuery.
222    loop {
223        match conn
224            .next()
225            .await
226            .transpose()
227            .map_err(|e| errors::AuthError::VerifierFetch(format!("admin startup: {e}")))?
228        {
229            Some(
230                proto::backend::BackendMessage::AuthenticationOk
231                | proto::backend::BackendMessage::ParameterStatus { .. }
232                | proto::backend::BackendMessage::BackendKeyData { .. },
233            ) => {}
234            Some(proto::backend::BackendMessage::AuthenticationSasl { mechanisms }) => {
235                if !mechanisms.iter().any(|m| m == "SCRAM-SHA-256") {
236                    return Err(errors::AuthError::VerifierFetch(format!(
237                        "admin connection requires unsupported SASL mechanism: {mechanisms:?}"
238                    )));
239                }
240                let pw = admin_password.ok_or_else(|| {
241                    errors::AuthError::VerifierFetch(
242                        "admin connection requires SCRAM auth but no password in .pgpass".into(),
243                    )
244                })?;
245                scram::client::authenticate(conn, pw).await?;
246            }
247            Some(proto::backend::BackendMessage::AuthenticationCleartextPassword) => {
248                let pw = admin_password.ok_or_else(|| {
249                    errors::AuthError::VerifierFetch(
250                        "admin connection requires password but none in .pgpass".into(),
251                    )
252                })?;
253                conn.send(proto::frontend::FrontendMessage::PasswordMessage(
254                    pw.as_bytes().to_vec(),
255                ))
256                .await
257                .map_err(|e| errors::AuthError::VerifierFetch(format!("send password: {e}")))?;
258            }
259            Some(proto::backend::BackendMessage::ReadyForQuery(_)) => break,
260            Some(proto::backend::BackendMessage::ErrorResponse(err)) => {
261                return Err(errors::AuthError::VerifierFetch(format!(
262                    "admin startup error: {}",
263                    err.message().unwrap_or("unknown")
264                )));
265            }
266            Some(other) => {
267                return Err(errors::AuthError::VerifierFetch(format!(
268                    "unexpected during admin startup: {other:?}"
269                )));
270            }
271            None => {
272                return Err(errors::AuthError::VerifierFetch(
273                    "upstream closed during admin startup".into(),
274                ));
275            }
276        }
277    }
278
279    // Execute the auth_query using the extended query protocol so the username
280    // is sent as a typed parameter, avoiding any string-escaping issues.
281    conn.feed(proto::frontend::FrontendMessage::Parse(
282        proto::frontend::Parse {
283            name: String::new(),
284            query: auth_query_template.to_owned(),
285            param_types: vec![],
286        },
287    ))
288    .await
289    .map_err(|e| errors::AuthError::VerifierFetch(format!("send parse: {e}")))?;
290    conn.feed(proto::frontend::FrontendMessage::Bind(
291        proto::frontend::Bind {
292            portal: String::new(),
293            statement: String::new(),
294            param_formats: vec![],
295            params: vec![Some(target_user.as_bytes().to_vec())],
296            result_formats: vec![],
297        },
298    ))
299    .await
300    .map_err(|e| errors::AuthError::VerifierFetch(format!("send bind: {e}")))?;
301    conn.feed(proto::frontend::FrontendMessage::Execute(
302        proto::frontend::Execute {
303            portal: String::new(),
304            max_rows: 0,
305        },
306    ))
307    .await
308    .map_err(|e| errors::AuthError::VerifierFetch(format!("send execute: {e}")))?;
309    conn.send(proto::frontend::FrontendMessage::Sync)
310        .await
311        .map_err(|e| errors::AuthError::VerifierFetch(format!("send sync: {e}")))?;
312
313    // Read the result.
314    let mut verifier_str: Option<String> = None;
315
316    loop {
317        match conn
318            .next()
319            .await
320            .transpose()
321            .map_err(|e| errors::AuthError::VerifierFetch(format!("auth_query: {e}")))?
322        {
323            Some(proto::backend::BackendMessage::DataRow(cols)) => {
324                if cols.len() >= 2
325                    && let Some(ref data) = cols[1]
326                {
327                    verifier_str = Some(String::from_utf8_lossy(data).into_owned());
328                }
329            }
330            Some(proto::backend::BackendMessage::ReadyForQuery(_)) => break,
331            Some(proto::backend::BackendMessage::ErrorResponse(err)) => {
332                return Err(errors::AuthError::VerifierFetch(format!(
333                    "auth_query error: {}",
334                    err.message().unwrap_or("unknown")
335                )));
336            }
337            None => {
338                return Err(errors::AuthError::VerifierFetch(
339                    "upstream closed during auth_query".into(),
340                ));
341            }
342            // ParseComplete, BindComplete, RowDescription, CommandComplete, notices, etc.
343            Some(_) => {}
344        }
345    }
346
347    let raw = verifier_str.ok_or_else(|| {
348        errors::AuthError::VerifierFetch(format!("no password found for user {target_user:?}"))
349    })?;
350
351    scram::ScramVerifier::parse(&raw)
352}