Skip to main content

halephant_core/connections/
server.rs

1//! Upstream PostgreSQL connection establishment.
2//!
3//! Owns the TCP dial + startup handshake that produces a fully
4//! authenticated [`ServerConn`]. Used by every path that opens a
5//! connection to an upstream PostgreSQL node — pool checkout, pool
6//! refill, topology probing, LISTEN/NOTIFY multiplex.
7//!
8//! The [`ServerConn`] data type and its per-connection prepared
9//! statement tracker [`ServerPrepared`] live here because they're
10//! "what `connect_server` returns" and travel together through
11//! every subsystem that holds an upstream connection.
12
13use std::collections::{HashSet, VecDeque};
14use std::time::{Duration, Instant};
15
16use anyhow::Context;
17use futures_util::{SinkExt, StreamExt};
18use tokio::net::TcpStream;
19use tokio_util::codec::Framed;
20
21use crate::auth;
22use crate::config::cluster::pool::user::UserParameters;
23use crate::o11y;
24use crate::proto::backend::BackendMessage;
25use crate::proto::codec::BackendCodec;
26use crate::proto::frontend::{FrontendMessage, ProtocolVersion, Startup};
27
28use super::options::escape;
29
30// ---------------------------------------------------------------------------
31// ServerConn — a fully initialized upstream connection
32// ---------------------------------------------------------------------------
33
34/// A server connection that has completed the PostgreSQL startup sequence and
35/// is ready for query forwarding.
36pub struct ServerConn {
37    pub framed: Framed<TcpStream, BackendCodec>,
38    pub params: Vec<(String, String)>,
39    pub backend_key: (i32, i32),
40    pub created_at: Instant,
41    /// Tracks which prepared statements are cached on this server connection.
42    pub prepared: ServerPrepared,
43    /// GUC variables SET by the client during this session. Only these are
44    /// RESET during connection reset, preserving startup parameters.
45    pub dirty_vars: HashSet<String>,
46}
47
48// ---------------------------------------------------------------------------
49// ServerPrepared — per-connection prepared-statement LRU cache
50// ---------------------------------------------------------------------------
51
52/// Tracks which canonical prepared statements exist on a specific
53/// server connection, with LRU eviction when the configured limit is
54/// reached.
55///
56/// Lives next to [`ServerConn`] because it's "state that follows a
57/// connection through its lifetime" — created at `connect_server`
58/// time, travels with the connection through checkout and checkin,
59/// consulted by the transaction forwarder's
60/// prepared-statement-rewriting path.
61pub struct ServerPrepared {
62    /// Set of canonical names currently prepared on this server.
63    prepared: HashSet<String>,
64    /// LRU order: front = oldest, back = most recently used.
65    lru: VecDeque<String>,
66    /// Maximum statements to keep prepared per server connection.
67    max: u32,
68}
69
70impl ServerPrepared {
71    pub fn new(max: u32) -> Self {
72        Self {
73            prepared: HashSet::new(),
74            lru: VecDeque::new(),
75            max,
76        }
77    }
78
79    /// Check whether the canonical statement is already prepared on this server.
80    pub fn contains(&self, canon: &str) -> bool {
81        self.prepared.contains(canon)
82    }
83
84    /// Mark a canonical statement as prepared on this server. Returns the name
85    /// of an evicted statement if the cache is full, which the caller must send
86    /// a `Close` for before preparing the new one.
87    pub fn insert(&mut self, canon: String) -> Option<String> {
88        if self.prepared.contains(&canon) {
89            // Move to back of LRU.
90            self.lru.retain(|n| n != &canon);
91            self.lru.push_back(canon);
92            return None;
93        }
94
95        let evicted = if self.max > 0 && self.prepared.len() as u32 >= self.max {
96            self.evict()
97        } else {
98            None
99        };
100
101        self.prepared.insert(canon.clone());
102        self.lru.push_back(canon);
103        evicted
104    }
105
106    /// Touch a statement in the LRU (it was used).
107    pub fn touch(&mut self, canon: &str) {
108        self.lru.retain(|n| n != canon);
109        self.lru.push_back(canon.to_owned());
110    }
111
112    /// Evict the least recently used statement. Returns the canonical name of
113    /// the evicted statement.
114    fn evict(&mut self) -> Option<String> {
115        let name = self.lru.pop_front()?;
116        self.prepared.remove(&name);
117        Some(name)
118    }
119
120    /// Clear all tracked statements (called after DISCARD ALL).
121    pub fn clear(&mut self) {
122        self.prepared.clear();
123        self.lru.clear();
124    }
125}
126
127// ---------------------------------------------------------------------------
128// TCP + startup handshake
129// ---------------------------------------------------------------------------
130
131/// Connect to a TCP address with a timeout, TCP_NODELAY, and TCP keepalive.
132/// Used for all upstream connections (pooled, listener, auth).
133pub(crate) async fn connect_tcp(addr: &str, timeout: Duration) -> anyhow::Result<TcpStream> {
134    let stream = tokio::time::timeout(timeout, TcpStream::connect(addr))
135        .await
136        .with_context(|| format!("connection to {addr} timed out"))?
137        .with_context(|| format!("failed to connect to {addr}"))?;
138    stream.set_nodelay(true)?;
139    let sock = socket2::SockRef::from(&stream);
140    let keepalive = socket2::TcpKeepalive::new()
141        .with_time(Duration::from_secs(30))
142        .with_interval(Duration::from_secs(10));
143    if let Err(e) = sock.set_tcp_keepalive(&keepalive) {
144        tracing::debug!(%e, "failed to set TCP keepalive (dead-peer detection degraded)");
145    }
146    Ok(stream)
147}
148
149/// Open a new TCP connection to `upstream_addr` and complete the PostgreSQL
150/// startup handshake, including password authentication if the server requests
151/// it.
152#[tracing::instrument(name = "pool.connect", skip_all, err(Display), fields(
153    otel.kind = "client",
154    db.system.name = "postgresql",
155    db.namespace = %database,
156    server.address = %upstream_addr,
157    user = %user,
158    otel.status_code,
159    otel.status_description,
160))]
161pub(crate) async fn connect_server(
162    upstream_addr: &str,
163    database: &str,
164    user: &str,
165    password: Option<&str>,
166    params: &UserParameters,
167    max_prepared: u32,
168    connect_timeout: Duration,
169) -> anyhow::Result<ServerConn> {
170    let connect_start = Instant::now();
171    async {
172        let stream = connect_tcp(upstream_addr, connect_timeout).await?;
173        let mut framed = Framed::new(stream, BackendCodec::new());
174
175        // Build startup parameters: user and database are required, then append
176        // application_name and GUC options from the config.
177        let mut startup_params = vec![
178            ("user".into(), user.into()),
179            ("database".into(), database.into()),
180        ];
181        if let Some(ref app_name) = params.application_name {
182            startup_params.push(("application_name".into(), app_name.clone()));
183        }
184        if !params.options.is_empty() {
185            let options: String = params
186                .options
187                .iter()
188                .map(|(k, v)| format!("-c {}={}", escape(k), escape(v)))
189                .collect::<Vec<_>>()
190                .join(" ");
191            startup_params.push(("options".into(), options));
192        }
193
194        // Send startup message.
195        framed
196            .send(FrontendMessage::Startup(Startup {
197                version: ProtocolVersion { major: 3, minor: 0 },
198                parameters: startup_params,
199            }))
200            .await?;
201
202        // Collect startup responses. Named `server_params` to avoid
203        // shadowing the `params: &UserParameters` function argument
204        // — these are the `ParameterStatus` values the server reports
205        // back, not the GUC settings the client sent in the startup
206        // message.
207        let mut server_params = Vec::new();
208        let mut backend_key = (0, 0);
209
210        loop {
211            match framed
212                .next()
213                .await
214                .transpose()
215                .context("reading startup response")?
216            {
217                Some(BackendMessage::AuthenticationOk) => {}
218                Some(BackendMessage::AuthenticationCleartextPassword) => {
219                    let pw = password.context(
220                        "upstream requires password auth but no password found in .pgpass",
221                    )?;
222                    framed
223                        .send(FrontendMessage::PasswordMessage(pw.as_bytes().to_vec()))
224                        .await?;
225                }
226                Some(BackendMessage::AuthenticationMd5Password { .. }) => {
227                    anyhow::bail!(
228                        "upstream {upstream_addr} requested MD5 auth — \
229                         use SCRAM-SHA-256 or trust instead"
230                    );
231                }
232                Some(BackendMessage::AuthenticationSasl { mechanisms }) => {
233                    if !mechanisms.iter().any(|m| m == "SCRAM-SHA-256") {
234                        anyhow::bail!(
235                            "upstream {upstream_addr} requires unsupported SASL mechanism: {mechanisms:?}"
236                        );
237                    }
238                    let pw = password.context(
239                        "upstream requires SCRAM auth but no password found in .pgpass",
240                    )?;
241                    auth::scram::client::authenticate(&mut framed, pw)
242                        .await
243                        .map_err(|e| anyhow::anyhow!("{e}"))?;
244                }
245                Some(BackendMessage::ParameterStatus { name, value }) => {
246                    server_params.push((name, value));
247                }
248                Some(BackendMessage::BackendKeyData {
249                    process_id,
250                    secret_key,
251                }) => {
252                    backend_key = (process_id, secret_key);
253                }
254                Some(BackendMessage::ReadyForQuery(_)) => break,
255                Some(BackendMessage::ErrorResponse(err)) => {
256                    anyhow::bail!(
257                        "upstream startup error: {}",
258                        err.message().unwrap_or("unknown")
259                    );
260                }
261                Some(other) => {
262                    anyhow::bail!("unexpected message during upstream startup: {other:?}");
263                }
264                None => anyhow::bail!("upstream closed during startup"),
265            }
266        }
267
268        Ok(ServerConn {
269            framed,
270            params: server_params,
271            backend_key,
272            created_at: Instant::now(),
273            prepared: ServerPrepared::new(max_prepared),
274            dirty_vars: HashSet::new(),
275        })
276    }
277    .await
278    .inspect(|_| {
279        o11y::metrics::record_connect(connect_start, upstream_addr, database);
280        tracing::Span::current().record("otel.status_code", "OK");
281    })
282    .inspect_err(|_| {
283        o11y::metrics::record_error("connect_failed", upstream_addr);
284        let span = tracing::Span::current();
285        span.record("otel.status_code", "ERROR");
286        span.record("otel.status_description", "connect failed");
287    })
288}
289
290// ---------------------------------------------------------------------------
291// Tests — ServerPrepared LRU behaviour
292// ---------------------------------------------------------------------------
293
294#[cfg(test)]
295mod tests {
296    use super::*;
297
298    #[test]
299    fn server_insert_and_contains() {
300        let mut server = ServerPrepared::new(10);
301        assert!(!server.contains("stmt_a"));
302        server.insert("stmt_a".into());
303        assert!(server.contains("stmt_a"));
304    }
305
306    #[test]
307    fn server_lru_eviction() {
308        let mut server = ServerPrepared::new(2);
309        server.insert("a".into());
310        server.insert("b".into());
311
312        // Cache is full, inserting c should evict a (oldest).
313        let evicted = server.insert("c".into());
314        assert_eq!(evicted, Some("a".into()));
315        assert!(!server.contains("a"));
316        assert!(server.contains("b"));
317        assert!(server.contains("c"));
318    }
319
320    #[test]
321    fn server_lru_touch_prevents_eviction() {
322        let mut server = ServerPrepared::new(2);
323        server.insert("a".into());
324        server.insert("b".into());
325
326        // Touch a — now b is the oldest.
327        server.touch("a");
328
329        let evicted = server.insert("c".into());
330        assert_eq!(evicted, Some("b".into()));
331        assert!(server.contains("a"));
332        assert!(server.contains("c"));
333    }
334
335    #[test]
336    fn server_insert_existing_moves_to_back() {
337        let mut server = ServerPrepared::new(2);
338        server.insert("a".into());
339        server.insert("b".into());
340
341        // Re-insert a — should not evict, just move to back.
342        let evicted = server.insert("a".into());
343        assert!(evicted.is_none());
344
345        // Now b is oldest — inserting c evicts b.
346        let evicted = server.insert("c".into());
347        assert_eq!(evicted, Some("b".into()));
348    }
349
350    #[test]
351    fn server_clear() {
352        let mut server = ServerPrepared::new(10);
353        server.insert("a".into());
354        server.insert("b".into());
355        server.clear();
356        assert!(!server.contains("a"));
357        assert!(!server.contains("b"));
358    }
359}