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