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. (The per-connection LRU cache lives on
14//!    [`crate::connections::server::ServerPrepared`] so it can travel
15//!    with the [`crate::connections::server::ServerConn`] it belongs
16//!    to.)
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, StreamExt};
26use sha2::{Digest, Sha256};
27use tokio::net::TcpStream;
28use tokio_util::codec::Framed;
29
30use crate::connections::server::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// ---------------------------------------------------------------------------
130// Outbound rewriting + server-side preparation
131// ---------------------------------------------------------------------------
132
133/// Rewrite outbound (client → server) messages to use canonical prepared
134/// statement names. If the server doesn't have a needed statement, prepare it
135/// first (including LRU eviction if necessary).
136/// Returns `Some(msg)` to forward to server, or `None` if the message was
137/// consumed (synthetic response already sent to client).
138pub(super) async fn rewrite_outbound(
139    msg: proto::frontend::FrontendMessage,
140    client_prepared: &mut ClientPrepared,
141    server: &mut ServerConn,
142    pools: &Arc<PoolManager>,
143    client: &mut Framed<TcpStream, proto::codec::FrontendCodec>,
144) -> anyhow::Result<Option<proto::frontend::FrontendMessage>> {
145    match msg {
146        proto::frontend::FrontendMessage::Parse(parse) => {
147            let canon = {
148                let mut store = pools.stmt_store.lock();
149                client_prepared.register(&parse, &mut store)
150            };
151
152            ensure_prepared(&canon, server, pools).await?;
153            client
154                .send(proto::backend::BackendMessage::ParseComplete)
155                .await?;
156            Ok(None)
157        }
158
159        proto::frontend::FrontendMessage::Bind(mut bind) => {
160            if let Some(canon) = client_prepared.resolve(&bind.statement) {
161                ensure_prepared(canon, server, pools).await?;
162                bind.statement = canon.to_owned();
163            }
164            Ok(Some(proto::frontend::FrontendMessage::Bind(bind)))
165        }
166
167        proto::frontend::FrontendMessage::Describe(mut desc) => {
168            if desc.kind == proto::frontend::TargetKind::Statement
169                && let Some(canon) = client_prepared.resolve(&desc.name)
170            {
171                ensure_prepared(canon, server, pools).await?;
172                desc.name = canon.to_owned();
173            }
174            Ok(Some(proto::frontend::FrontendMessage::Describe(desc)))
175        }
176
177        // Statement Close is handled by handle_close_intercept before
178        // reaching here. Portal closes pass through as-is.
179        other => Ok(Some(other)),
180    }
181}
182
183/// Ensure a canonical statement is prepared on the server connection. If the
184/// server doesn't have it, send the stored Parse and consume the ParseComplete.
185async fn ensure_prepared(
186    canon: &str,
187    server: &mut ServerConn,
188    pools: &Arc<PoolManager>,
189) -> anyhow::Result<()> {
190    if server.prepared.contains(canon) {
191        server.prepared.touch(canon);
192        return Ok(());
193    }
194
195    // Look up the stored Parse first — bail if missing.
196    let stored_parse = {
197        let store = pools.stmt_store.lock();
198        store.get(canon).cloned()
199    };
200    let Some(mut parse) = stored_parse else {
201        anyhow::bail!("no stored Parse for canonical statement {canon}");
202    };
203
204    // Evict if necessary, then prepare.
205    if let Some(evicted) = server.prepared.insert(canon.to_owned()) {
206        server
207            .framed
208            .send(proto::frontend::FrontendMessage::Close(
209                proto::frontend::Close {
210                    kind: proto::frontend::TargetKind::Statement,
211                    name: evicted,
212                },
213            ))
214            .await?;
215        server
216            .framed
217            .send(proto::frontend::FrontendMessage::Sync)
218            .await?;
219        drain_until_ready(&mut server.framed).await?;
220    }
221
222    parse.name = canon.to_owned();
223    server
224        .framed
225        .send(proto::frontend::FrontendMessage::Parse(parse))
226        .await?;
227    server
228        .framed
229        .send(proto::frontend::FrontendMessage::Sync)
230        .await?;
231    drain_until_ready(&mut server.framed).await?;
232
233    Ok(())
234}
235
236/// Drain server responses until ReadyForQuery, discarding everything except
237/// errors (which are propagated).
238async fn drain_until_ready(
239    framed: &mut Framed<TcpStream, proto::codec::BackendCodec>,
240) -> anyhow::Result<()> {
241    loop {
242        match framed.next().await.transpose()? {
243            Some(proto::backend::BackendMessage::ReadyForQuery(_)) => return Ok(()),
244            Some(proto::backend::BackendMessage::ErrorResponse(err)) => {
245                anyhow::bail!(
246                    "server error during prepared statement management: {}",
247                    err.message().unwrap_or("unknown")
248                );
249            }
250            Some(_) => {} // ParseComplete, CloseComplete, etc.
251            None => anyhow::bail!("upstream closed during prepared statement management"),
252        }
253    }
254}
255
256// ---------------------------------------------------------------------------
257// Tests
258// ---------------------------------------------------------------------------
259
260#[cfg(test)]
261mod tests {
262    use super::*;
263
264    #[test]
265    fn canonical_name_deterministic() {
266        let a = canonical_name("SELECT 1", &[]);
267        let b = canonical_name("SELECT 1", &[]);
268        assert_eq!(a, b);
269        assert!(a.starts_with("_hp_"));
270    }
271
272    #[test]
273    fn canonical_name_differs_by_query() {
274        let a = canonical_name("SELECT 1", &[]);
275        let b = canonical_name("SELECT 2", &[]);
276        assert_ne!(a, b);
277    }
278
279    #[test]
280    fn canonical_name_differs_by_params() {
281        let a = canonical_name("SELECT $1", &[23]); // int4
282        let b = canonical_name("SELECT $1", &[25]); // text
283        assert_ne!(a, b);
284    }
285
286    #[test]
287    fn client_register_and_resolve() {
288        let mut store = StatementStore::new();
289        let mut client = ClientPrepared::new();
290
291        let parse = Parse {
292            name: "my_stmt".into(),
293            query: "SELECT 1".into(),
294            param_types: vec![],
295        };
296
297        let canon = client.register(&parse, &mut store);
298        assert_eq!(client.resolve("my_stmt"), Some(canon.as_str()));
299        assert!(store.get(&canon).is_some());
300    }
301
302    #[test]
303    fn client_unnamed_tracked() {
304        let mut store = StatementStore::new();
305        let mut client = ClientPrepared::new();
306
307        let parse = Parse {
308            name: String::new(),
309            query: "SELECT 1".into(),
310            param_types: vec![],
311        };
312
313        let canon = client.register(&parse, &mut store);
314        assert_eq!(client.resolve(""), Some(canon.as_str()));
315        assert!(store.get(&canon).is_some());
316    }
317
318    #[test]
319    fn client_unnamed_replaced_by_new_parse() {
320        let mut store = StatementStore::new();
321        let mut client = ClientPrepared::new();
322
323        let parse1 = Parse {
324            name: String::new(),
325            query: "SELECT 1".into(),
326            param_types: vec![],
327        };
328        let parse2 = Parse {
329            name: String::new(),
330            query: "SELECT 2".into(),
331            param_types: vec![],
332        };
333
334        let canon1 = client.register(&parse1, &mut store);
335        let canon2 = client.register(&parse2, &mut store);
336        assert_ne!(canon1, canon2);
337
338        // The unnamed slot now points to the second query.
339        assert_eq!(client.resolve(""), Some(canon2.as_str()));
340        // First query's refcount dropped to zero — removed from store.
341        assert!(store.get(&canon1).is_none());
342        assert!(store.get(&canon2).is_some());
343    }
344
345    #[test]
346    fn reparse_same_query_does_not_leak_refcount() {
347        let mut store = StatementStore::new();
348        let mut client = ClientPrepared::new();
349
350        let parse = Parse {
351            name: String::new(),
352            query: "SELECT 1".into(),
353            param_types: vec![],
354        };
355
356        let canon = client.register(&parse, &mut store);
357        // Re-register the exact same query — refcount must stay at 1.
358        client.register(&parse, &mut store);
359        client.register(&parse, &mut store);
360
361        // release_all releases one ref — should reach zero.
362        client.release_all(&mut store);
363        assert!(
364            store.get(&canon).is_none(),
365            "store entry should be gone after release_all, but refcount leaked"
366        );
367    }
368
369    #[test]
370    fn client_remove() {
371        let mut store = StatementStore::new();
372        let mut client = ClientPrepared::new();
373
374        let parse = Parse {
375            name: "s1".into(),
376            query: "SELECT 1".into(),
377            param_types: vec![],
378        };
379
380        client.register(&parse, &mut store);
381        assert!(client.resolve("s1").is_some());
382        client.remove("s1", &mut store);
383        assert!(client.resolve("s1").is_none());
384    }
385
386    #[test]
387    fn deduplication_across_clients() {
388        let mut store = StatementStore::new();
389        let mut client_a = ClientPrepared::new();
390        let mut client_b = ClientPrepared::new();
391
392        let parse_a = Parse {
393            name: "s1".into(),
394            query: "SELECT 1".into(),
395            param_types: vec![],
396        };
397        let parse_b = Parse {
398            name: "s1".into(),
399            query: "SELECT 1".into(),
400            param_types: vec![],
401        };
402
403        let canon_a = client_a.register(&parse_a, &mut store);
404        let canon_b = client_b.register(&parse_b, &mut store);
405
406        // Same query text → same canonical name.
407        assert_eq!(canon_a, canon_b);
408    }
409
410    #[test]
411    fn no_collision_different_queries_same_client_name() {
412        let mut store = StatementStore::new();
413        let mut client_a = ClientPrepared::new();
414        let mut client_b = ClientPrepared::new();
415
416        let parse_a = Parse {
417            name: "s1".into(),
418            query: "SELECT 1".into(),
419            param_types: vec![],
420        };
421        let parse_b = Parse {
422            name: "s1".into(),
423            query: "SELECT 2".into(),
424            param_types: vec![],
425        };
426
427        let canon_a = client_a.register(&parse_a, &mut store);
428        let canon_b = client_b.register(&parse_b, &mut store);
429
430        // Same client name, different queries → different canonical names.
431        assert_ne!(canon_a, canon_b);
432    }
433
434    #[test]
435    fn store_refcount_cleanup() {
436        let mut store = StatementStore::new();
437        let mut client_a = ClientPrepared::new();
438        let mut client_b = ClientPrepared::new();
439
440        let parse = Parse {
441            name: "s1".into(),
442            query: "SELECT 1".into(),
443            param_types: vec![],
444        };
445
446        let canon = client_a.register(&parse, &mut store);
447        client_b.register(&parse, &mut store);
448
449        // Both clients reference it — store has the entry.
450        assert!(store.get(&canon).is_some());
451
452        // Release client A — refcount drops to 1, still in store.
453        client_a.release_all(&mut store);
454        assert!(store.get(&canon).is_some());
455
456        // Release client B — refcount drops to 0, removed from store.
457        client_b.release_all(&mut store);
458        assert!(store.get(&canon).is_none());
459    }
460
461    #[test]
462    fn remove_decrements_refcount() {
463        let mut store = StatementStore::new();
464        let mut client = ClientPrepared::new();
465
466        let parse = Parse {
467            name: "s1".into(),
468            query: "SELECT 1".into(),
469            param_types: vec![],
470        };
471
472        let canon = client.register(&parse, &mut store);
473        assert!(store.get(&canon).is_some());
474
475        client.remove("s1", &mut store);
476        // Single reference removed — gone from store.
477        assert!(store.get(&canon).is_none());
478    }
479}