Skip to main content

halephant_core/proxy/
prepared.rs

1//! Per-client prepared statement state and server-side rewriting.
2//!
3//! When a server connection is reassigned between clients in
4//! transaction-mode pooling, prepared statements from the previous
5//! client do not exist on the new server. This module solves the
6//! problem by:
7//!
8//! 1. Intercepting `Parse` messages and assigning canonical names
9//!    based on a hash of the query text and parameter types.
10//! 2. Maintaining a per-client mapping from client-side names to
11//!    canonical names.
12//! 3. Tracking which canonical statements each server connection has
13//!    prepared. (Per-connection state lives on
14//!    [`crate::connections::server::PreparedStatements`] so it can travel
15//!    with the [`crate::connections::server::ServerConn`] it belongs
16//!    to, and decides which backend replies to filter.)
17//! 4. Transparently re-preparing statements on cache miss.
18//!
19//! The global, reference-counted store of Parse messages lives in
20//! [`crate::pool::prepared::StatementStore`].
21
22use std::collections::HashMap;
23use std::sync::Arc;
24
25use futures_util::SinkExt;
26use sha2::{Digest, Sha256};
27use tokio::net::TcpStream;
28use tokio_util::codec::Framed;
29
30use crate::connections::server::{ClientParse, Reprepare, ServerConn};
31use crate::pool::PoolManager;
32use crate::pool::prepared::StatementStore;
33use crate::proto;
34use crate::proto::frontend::Parse;
35
36// ---------------------------------------------------------------------------
37// Canonical name generation
38// ---------------------------------------------------------------------------
39
40/// Compute the canonical name for a query. Exposed for integration
41/// tests that need to predict canonical names.
42#[doc(hidden)]
43pub fn canonical_for_test(query: &str, param_types: &[u32]) -> String {
44    canonical_name(query, param_types)
45}
46
47/// Compute a canonical statement name from the query text and parameter types.
48/// Identical queries produce the same canonical name, enabling deduplication
49/// across clients.
50fn canonical_name(query: &str, param_types: &[u32]) -> String {
51    let mut hasher = Sha256::new();
52    hasher.update(query.as_bytes());
53    for &oid in param_types {
54        hasher.update(oid.to_le_bytes());
55    }
56    let hash = hasher.finalize();
57    format!(
58        "_hp_{:016x}",
59        u64::from_le_bytes(
60            hash[..8]
61                .try_into()
62                .expect("SHA-256 produces at least 8 bytes"),
63        )
64    )
65}
66
67// ---------------------------------------------------------------------------
68// Per-client state
69// ---------------------------------------------------------------------------
70
71/// Tracks the client-side → canonical name mapping for a single client session.
72#[derive(Default)]
73pub struct ClientPrepared {
74    /// client statement name → canonical name (includes `""` for unnamed)
75    names: HashMap<String, String>,
76}
77
78impl ClientPrepared {
79    pub fn new() -> Self {
80        Self::default()
81    }
82
83    /// Register a client-side name for a Parse, returning the canonical name.
84    /// Works for both named and unnamed (`""`) statements — unnamed
85    /// entries are tracked the same way so `Bind("")` in a subsequent
86    /// transaction resolves to the canonical name and gets re-prepared
87    /// on a fresh server connection automatically.
88    pub fn register(&mut self, parse: &Parse, store: &mut StatementStore) -> String {
89        let canon = canonical_name(&parse.query, &parse.param_types);
90        match self.names.insert(parse.name.clone(), canon.clone()) {
91            Some(ref old_canon) if old_canon == &canon => {
92                // Same canonical — no ref-count change needed.
93            }
94            Some(old_canon) => {
95                store.add_ref(canon.clone(), parse.clone());
96                store.release(&old_canon);
97            }
98            None => {
99                store.add_ref(canon.clone(), parse.clone());
100            }
101        }
102        canon
103    }
104
105    /// Look up the canonical name for a client-side statement name.
106    /// Returns `None` if the name isn't tracked (first use, or the
107    /// client never sent a `Parse` for it).
108    pub fn resolve(&self, client_name: &str) -> Option<&str> {
109        self.names.get(client_name).map(String::as_str)
110    }
111
112    /// Remove a client-side name mapping (client sent Close for this statement).
113    pub fn remove(&mut self, client_name: &str, store: &mut StatementStore) {
114        if let Some(canon) = self.names.remove(client_name) {
115            store.release(&canon);
116        }
117    }
118
119    /// Release all references held by this client. Call when the client
120    /// disconnects to allow the global store to reclaim memory.
121    pub fn release_all(&mut self, store: &mut StatementStore) {
122        for canon in self.names.values() {
123            store.release(canon);
124        }
125        self.names.clear();
126    }
127}
128
129/// RAII holder for a session's [`ClientPrepared`] that releases every
130/// statement-store reference on drop — including when the client task is
131/// cancelled mid-`await`, where an explicit cleanup after the forward
132/// loop would never run. Shared by both pool modes.
133pub(super) struct PreparedGuard {
134    pub(super) inner: ClientPrepared,
135    pub(super) pools: Arc<PoolManager>,
136}
137
138impl Drop for PreparedGuard {
139    fn drop(&mut self) {
140        let mut store = self.pools.stmt_store.lock();
141        self.inner.release_all(&mut store);
142    }
143}
144
145// ---------------------------------------------------------------------------
146// Outbound rewriting + server-side preparation
147// ---------------------------------------------------------------------------
148
149/// Rewrite outbound (client → server) messages to use canonical prepared
150/// statement names. If the server doesn't have a needed statement, prepare it
151/// first (including LRU eviction if necessary).
152/// Returns `Some(msg)` to forward to server, or `None` if the message was
153/// consumed (synthetic response already sent to client).
154pub(super) async fn rewrite_outbound(
155    msg: proto::frontend::FrontendMessage,
156    client_prepared: &mut ClientPrepared,
157    server: &mut ServerConn,
158    pools: &Arc<PoolManager>,
159    client: &mut Framed<TcpStream, proto::codec::FrontendCodec>,
160) -> anyhow::Result<Option<proto::frontend::FrontendMessage>> {
161    match msg {
162        proto::frontend::FrontendMessage::Parse(parse) => {
163            let canon = {
164                let mut store = pools.stmt_store.lock();
165                client_prepared.register(&parse, &mut store)
166            };
167
168            match server.statements.note_client_parse(&canon) {
169                ClientParse::Synthesize => {
170                    // Already prepared on this backend — either the client
171                    // re-Parsed a query it already sent, or another client
172                    // prepared the same canonical first. Re-Parsing the
173                    // canonical name would draw "prepared statement already
174                    // exists", so skip the backend round-trip and answer
175                    // synthetically.
176                    client
177                        .send(proto::backend::BackendMessage::ParseComplete)
178                        .await?;
179                    Ok(None)
180                }
181                ClientParse::Forward { eviction } => {
182                    // Not on this backend yet. Forward the Parse under its
183                    // canonical name so the backend's own ParseComplete
184                    // flows back in order — no synthetic reply, no
185                    // out-of-band Sync. Evict first if the cache was full.
186                    send_eviction(eviction, server).await?;
187                    let mut parse = parse;
188                    parse.name = canon;
189                    Ok(Some(proto::frontend::FrontendMessage::Parse(parse)))
190                }
191            }
192        }
193
194        proto::frontend::FrontendMessage::Bind(mut bind) => {
195            if let Some(canon) = client_prepared.resolve(&bind.statement) {
196                ensure_prepared(canon, server, pools).await?;
197                bind.statement = canon.to_owned();
198            }
199            Ok(Some(proto::frontend::FrontendMessage::Bind(bind)))
200        }
201
202        proto::frontend::FrontendMessage::Describe(mut desc) => {
203            if desc.kind == proto::frontend::TargetKind::Statement
204                && let Some(canon) = client_prepared.resolve(&desc.name)
205            {
206                ensure_prepared(canon, server, pools).await?;
207                desc.name = canon.to_owned();
208            }
209            Ok(Some(proto::frontend::FrontendMessage::Describe(desc)))
210        }
211
212        proto::frontend::FrontendMessage::Close(close) => {
213            // Statement closes are absorbed by `handle_close_intercept`
214            // before reaching here, so this is a portal close. Forward it
215            // and record that its `CloseComplete` belongs to the client —
216            // this keeps the `CloseComplete` FIFO aligned with any
217            // interleaved eviction closes.
218            server.statements.note_portal_close();
219            Ok(Some(proto::frontend::FrontendMessage::Close(close)))
220        }
221
222        other => Ok(Some(other)),
223    }
224}
225
226/// Ensure a canonical statement is prepared on the server connection.
227///
228/// On a cache miss the stored `Parse` is injected into the normal
229/// outbound stream — **without** a `Sync` and without draining the
230/// backend — and [`PreparedStatements`] records the disposition so the
231/// proxy strips the matching `ParseComplete`/`CloseComplete` from the
232/// client-facing stream. (The previous implementation injected a `Sync`
233/// and drained to `ReadyForQuery`, which discarded responses the backend
234/// had buffered for the client's own pipelined messages — corrupting the
235/// stream for drivers that batch statements.)
236///
237/// Used for `Bind`/`Describe`-triggered re-preparation, where the client
238/// never sent a `Parse`, so the injected `ParseComplete` is suppressed.
239///
240/// [`PreparedStatements`]: crate::connections::server::PreparedStatements
241async fn ensure_prepared(
242    canon: &str,
243    server: &mut ServerConn,
244    pools: &Arc<PoolManager>,
245) -> anyhow::Result<()> {
246    match server.statements.note_reprepare(canon) {
247        Reprepare::AlreadyPrepared => Ok(()),
248        Reprepare::Prepare { eviction } => {
249            // Any canonical in `client_prepared` keeps its `Parse` in the
250            // store (the ref is held until release), so this lookup is
251            // effectively infallible. On the impossible miss we bail and
252            // the connection is discarded, so the optimistic insert
253            // `note_reprepare` just made never reaches the pool.
254            let stored_parse = {
255                let store = pools.stmt_store.lock();
256                store.get(canon).cloned()
257            };
258            let Some(mut parse) = stored_parse else {
259                anyhow::bail!("no stored Parse for canonical statement {canon}");
260            };
261            send_eviction(eviction, server).await?;
262            parse.name = canon.to_owned();
263            server
264                .framed
265                .send(proto::frontend::FrontendMessage::Parse(parse))
266                .await?;
267            Ok(())
268        }
269    }
270}
271
272/// Send a statement `Close` for an LRU-evicted canonical, if any. Its
273/// `CloseComplete` is already queued for suppression by the
274/// [`PreparedStatements`] call that returned `eviction`.
275///
276/// [`PreparedStatements`]: crate::connections::server::PreparedStatements
277async fn send_eviction(eviction: Option<String>, server: &mut ServerConn) -> anyhow::Result<()> {
278    if let Some(evicted) = eviction {
279        server
280            .framed
281            .send(proto::frontend::FrontendMessage::Close(
282                proto::frontend::Close {
283                    kind: proto::frontend::TargetKind::Statement,
284                    name: evicted,
285                },
286            ))
287            .await?;
288    }
289    Ok(())
290}
291
292// ---------------------------------------------------------------------------
293// Tests
294// ---------------------------------------------------------------------------
295
296#[cfg(test)]
297mod tests {
298    use super::*;
299
300    #[test]
301    fn canonical_name_deterministic() {
302        let a = canonical_name("SELECT 1", &[]);
303        let b = canonical_name("SELECT 1", &[]);
304        assert_eq!(a, b);
305        assert!(a.starts_with("_hp_"));
306    }
307
308    #[test]
309    fn canonical_name_differs_by_query() {
310        let a = canonical_name("SELECT 1", &[]);
311        let b = canonical_name("SELECT 2", &[]);
312        assert_ne!(a, b);
313    }
314
315    #[test]
316    fn canonical_name_differs_by_params() {
317        let a = canonical_name("SELECT $1", &[23]); // int4
318        let b = canonical_name("SELECT $1", &[25]); // text
319        assert_ne!(a, b);
320    }
321
322    #[test]
323    fn client_register_and_resolve() {
324        let mut store = StatementStore::new();
325        let mut client = ClientPrepared::new();
326
327        let parse = Parse {
328            name: "my_stmt".into(),
329            query: "SELECT 1".into(),
330            param_types: vec![],
331        };
332
333        let canon = client.register(&parse, &mut store);
334        assert_eq!(client.resolve("my_stmt"), Some(canon.as_str()));
335        assert!(store.get(&canon).is_some());
336    }
337
338    #[test]
339    fn client_unnamed_tracked() {
340        let mut store = StatementStore::new();
341        let mut client = ClientPrepared::new();
342
343        let parse = Parse {
344            name: String::new(),
345            query: "SELECT 1".into(),
346            param_types: vec![],
347        };
348
349        let canon = client.register(&parse, &mut store);
350        assert_eq!(client.resolve(""), Some(canon.as_str()));
351        assert!(store.get(&canon).is_some());
352    }
353
354    #[test]
355    fn client_unnamed_replaced_by_new_parse() {
356        let mut store = StatementStore::new();
357        let mut client = ClientPrepared::new();
358
359        let parse1 = Parse {
360            name: String::new(),
361            query: "SELECT 1".into(),
362            param_types: vec![],
363        };
364        let parse2 = Parse {
365            name: String::new(),
366            query: "SELECT 2".into(),
367            param_types: vec![],
368        };
369
370        let canon1 = client.register(&parse1, &mut store);
371        let canon2 = client.register(&parse2, &mut store);
372        assert_ne!(canon1, canon2);
373
374        // The unnamed slot now points to the second query.
375        assert_eq!(client.resolve(""), Some(canon2.as_str()));
376        // First query's refcount dropped to zero — removed from store.
377        assert!(store.get(&canon1).is_none());
378        assert!(store.get(&canon2).is_some());
379    }
380
381    #[test]
382    fn reparse_same_query_does_not_leak_refcount() {
383        let mut store = StatementStore::new();
384        let mut client = ClientPrepared::new();
385
386        let parse = Parse {
387            name: String::new(),
388            query: "SELECT 1".into(),
389            param_types: vec![],
390        };
391
392        let canon = client.register(&parse, &mut store);
393        // Re-register the exact same query — refcount must stay at 1.
394        client.register(&parse, &mut store);
395        client.register(&parse, &mut store);
396
397        // release_all releases one ref — should reach zero.
398        client.release_all(&mut store);
399        assert!(
400            store.get(&canon).is_none(),
401            "store entry should be gone after release_all, but refcount leaked"
402        );
403    }
404
405    #[test]
406    fn client_remove() {
407        let mut store = StatementStore::new();
408        let mut client = ClientPrepared::new();
409
410        let parse = Parse {
411            name: "s1".into(),
412            query: "SELECT 1".into(),
413            param_types: vec![],
414        };
415
416        client.register(&parse, &mut store);
417        assert!(client.resolve("s1").is_some());
418        client.remove("s1", &mut store);
419        assert!(client.resolve("s1").is_none());
420    }
421
422    #[test]
423    fn deduplication_across_clients() {
424        let mut store = StatementStore::new();
425        let mut client_a = ClientPrepared::new();
426        let mut client_b = ClientPrepared::new();
427
428        let parse_a = Parse {
429            name: "s1".into(),
430            query: "SELECT 1".into(),
431            param_types: vec![],
432        };
433        let parse_b = Parse {
434            name: "s1".into(),
435            query: "SELECT 1".into(),
436            param_types: vec![],
437        };
438
439        let canon_a = client_a.register(&parse_a, &mut store);
440        let canon_b = client_b.register(&parse_b, &mut store);
441
442        // Same query text → same canonical name.
443        assert_eq!(canon_a, canon_b);
444    }
445
446    #[test]
447    fn no_collision_different_queries_same_client_name() {
448        let mut store = StatementStore::new();
449        let mut client_a = ClientPrepared::new();
450        let mut client_b = ClientPrepared::new();
451
452        let parse_a = Parse {
453            name: "s1".into(),
454            query: "SELECT 1".into(),
455            param_types: vec![],
456        };
457        let parse_b = Parse {
458            name: "s1".into(),
459            query: "SELECT 2".into(),
460            param_types: vec![],
461        };
462
463        let canon_a = client_a.register(&parse_a, &mut store);
464        let canon_b = client_b.register(&parse_b, &mut store);
465
466        // Same client name, different queries → different canonical names.
467        assert_ne!(canon_a, canon_b);
468    }
469
470    #[test]
471    fn store_refcount_cleanup() {
472        let mut store = StatementStore::new();
473        let mut client_a = ClientPrepared::new();
474        let mut client_b = ClientPrepared::new();
475
476        let parse = Parse {
477            name: "s1".into(),
478            query: "SELECT 1".into(),
479            param_types: vec![],
480        };
481
482        let canon = client_a.register(&parse, &mut store);
483        client_b.register(&parse, &mut store);
484
485        // Both clients reference it — store has the entry.
486        assert!(store.get(&canon).is_some());
487
488        // Release client A — refcount drops to 1, still in store.
489        client_a.release_all(&mut store);
490        assert!(store.get(&canon).is_some());
491
492        // Release client B — refcount drops to 0, removed from store.
493        client_b.release_all(&mut store);
494        assert!(store.get(&canon).is_none());
495    }
496
497    #[test]
498    fn remove_decrements_refcount() {
499        let mut store = StatementStore::new();
500        let mut client = ClientPrepared::new();
501
502        let parse = Parse {
503            name: "s1".into(),
504            query: "SELECT 1".into(),
505            param_types: vec![],
506        };
507
508        let canon = client.register(&parse, &mut store);
509        assert!(store.get(&canon).is_some());
510
511        client.remove("s1", &mut store);
512        // Single reference removed — gone from store.
513        assert!(store.get(&canon).is_none());
514    }
515}