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 a canonical statement name from the query text and parameter types.
41/// Identical queries produce the same canonical name, enabling deduplication
42/// across clients.
43fn canonical_name(query: &str, param_types: &[u32]) -> String {
44    let mut hasher = Sha256::new();
45    hasher.update(query.as_bytes());
46    for &oid in param_types {
47        hasher.update(oid.to_le_bytes());
48    }
49    let hash = hasher.finalize();
50    format!(
51        "_hp_{:016x}",
52        u64::from_le_bytes(
53            hash[..8]
54                .try_into()
55                .expect("SHA-256 produces at least 8 bytes"),
56        )
57    )
58}
59
60// ---------------------------------------------------------------------------
61// Per-client state
62// ---------------------------------------------------------------------------
63
64/// Tracks the client-side → canonical name mapping for a single client session.
65#[derive(Default)]
66pub struct ClientPrepared {
67    /// client statement name → canonical name
68    names: HashMap<String, String>,
69}
70
71impl ClientPrepared {
72    pub fn new() -> Self {
73        Self::default()
74    }
75
76    /// Register a client-side name for a Parse, returning the canonical name.
77    pub fn register(&mut self, parse: &Parse, store: &mut StatementStore) -> String {
78        let canon = canonical_name(&parse.query, &parse.param_types);
79        store.add_ref(canon.clone(), parse.clone());
80        if !parse.name.is_empty()
81            && let Some(old_canon) = self.names.insert(parse.name.clone(), canon.clone())
82            && old_canon != canon
83        {
84            store.release(&old_canon);
85        }
86        canon
87    }
88
89    /// Look up the canonical name for a client-side statement name. Returns
90    /// `None` for unnamed statements (the empty string), which are always
91    /// forwarded as-is.
92    pub fn resolve(&self, client_name: &str) -> Option<&str> {
93        if client_name.is_empty() {
94            return None;
95        }
96        self.names.get(client_name).map(String::as_str)
97    }
98
99    /// Remove a client-side name mapping (client sent Close for this statement).
100    pub fn remove(&mut self, client_name: &str, store: &mut StatementStore) {
101        if let Some(canon) = self.names.remove(client_name) {
102            store.release(&canon);
103        }
104    }
105
106    /// Release all references held by this client. Call when the client
107    /// disconnects to allow the global store to reclaim memory.
108    pub fn release_all(&mut self, store: &mut StatementStore) {
109        for canon in self.names.values() {
110            store.release(canon);
111        }
112        self.names.clear();
113    }
114}
115
116// ---------------------------------------------------------------------------
117// Outbound rewriting + server-side preparation
118// ---------------------------------------------------------------------------
119
120/// Rewrite outbound (client → server) messages to use canonical prepared
121/// statement names. If the server doesn't have a needed statement, prepare it
122/// first (including LRU eviction if necessary).
123/// Returns `Some(msg)` to forward to server, or `None` if the message was
124/// consumed (synthetic response already sent to client).
125pub(super) async fn rewrite_outbound(
126    msg: proto::frontend::FrontendMessage,
127    client_prepared: &mut ClientPrepared,
128    server: &mut ServerConn,
129    pools: &Arc<PoolManager>,
130    client: &mut Framed<TcpStream, proto::codec::FrontendCodec>,
131) -> anyhow::Result<Option<proto::frontend::FrontendMessage>> {
132    match msg {
133        proto::frontend::FrontendMessage::Parse(parse) => {
134            if parse.name.is_empty() {
135                // Unnamed (anonymous) prepared statements are not cached — forward as-is.
136                return Ok(Some(proto::frontend::FrontendMessage::Parse(parse)));
137            }
138
139            let canon = {
140                let mut store = pools.stmt_store.lock();
141                client_prepared.register(&parse, &mut store)
142            };
143
144            // Ensure the server has this statement. If it was already there or
145            // was just prepared, do NOT forward the Parse again — PostgreSQL
146            // rejects duplicate named statements. Send a synthetic ParseComplete
147            // to the client instead.
148            ensure_prepared(&canon, server, pools).await?;
149            client
150                .send(proto::backend::BackendMessage::ParseComplete)
151                .await?;
152            Ok(None)
153        }
154
155        proto::frontend::FrontendMessage::Bind(mut bind) => {
156            if let Some(canon) = client_prepared.resolve(&bind.statement) {
157                ensure_prepared(canon, server, pools).await?;
158                bind.statement = canon.to_owned();
159            }
160            Ok(Some(proto::frontend::FrontendMessage::Bind(bind)))
161        }
162
163        proto::frontend::FrontendMessage::Describe(mut desc) => {
164            if desc.kind == proto::frontend::TargetKind::Statement
165                && let Some(canon) = client_prepared.resolve(&desc.name)
166            {
167                ensure_prepared(canon, server, pools).await?;
168                desc.name = canon.to_owned();
169            }
170            Ok(Some(proto::frontend::FrontendMessage::Describe(desc)))
171        }
172
173        // Close for named statements is handled by handle_close_intercept
174        // before reaching here. If one slips through (for portals or unnamed),
175        // forward as-is.
176        other => Ok(Some(other)),
177    }
178}
179
180/// Ensure a canonical statement is prepared on the server connection. If the
181/// server doesn't have it, send the stored Parse and consume the ParseComplete.
182async fn ensure_prepared(
183    canon: &str,
184    server: &mut ServerConn,
185    pools: &Arc<PoolManager>,
186) -> anyhow::Result<()> {
187    if server.prepared.contains(canon) {
188        server.prepared.touch(canon);
189        return Ok(());
190    }
191
192    // Look up the stored Parse first — bail if missing.
193    let stored_parse = {
194        let store = pools.stmt_store.lock();
195        store.get(canon).cloned()
196    };
197    let Some(mut parse) = stored_parse else {
198        anyhow::bail!("no stored Parse for canonical statement {canon}");
199    };
200
201    // Evict if necessary, then prepare.
202    if let Some(evicted) = server.prepared.insert(canon.to_owned()) {
203        server
204            .framed
205            .send(proto::frontend::FrontendMessage::Close(
206                proto::frontend::Close {
207                    kind: proto::frontend::TargetKind::Statement,
208                    name: evicted,
209                },
210            ))
211            .await?;
212        server
213            .framed
214            .send(proto::frontend::FrontendMessage::Sync)
215            .await?;
216        drain_until_ready(&mut server.framed).await?;
217    }
218
219    parse.name = canon.to_owned();
220    server
221        .framed
222        .send(proto::frontend::FrontendMessage::Parse(parse))
223        .await?;
224    server
225        .framed
226        .send(proto::frontend::FrontendMessage::Sync)
227        .await?;
228    drain_until_ready(&mut server.framed).await?;
229
230    Ok(())
231}
232
233/// Drain server responses until ReadyForQuery, discarding everything except
234/// errors (which are propagated).
235async fn drain_until_ready(
236    framed: &mut Framed<TcpStream, proto::codec::BackendCodec>,
237) -> anyhow::Result<()> {
238    loop {
239        match framed.next().await.transpose()? {
240            Some(proto::backend::BackendMessage::ReadyForQuery(_)) => return Ok(()),
241            Some(proto::backend::BackendMessage::ErrorResponse(err)) => {
242                anyhow::bail!(
243                    "server error during prepared statement management: {}",
244                    err.message().unwrap_or("unknown")
245                );
246            }
247            Some(_) => {} // ParseComplete, CloseComplete, etc.
248            None => anyhow::bail!("upstream closed during prepared statement management"),
249        }
250    }
251}
252
253// ---------------------------------------------------------------------------
254// Tests
255// ---------------------------------------------------------------------------
256
257#[cfg(test)]
258mod tests {
259    use super::*;
260
261    #[test]
262    fn canonical_name_deterministic() {
263        let a = canonical_name("SELECT 1", &[]);
264        let b = canonical_name("SELECT 1", &[]);
265        assert_eq!(a, b);
266        assert!(a.starts_with("_hp_"));
267    }
268
269    #[test]
270    fn canonical_name_differs_by_query() {
271        let a = canonical_name("SELECT 1", &[]);
272        let b = canonical_name("SELECT 2", &[]);
273        assert_ne!(a, b);
274    }
275
276    #[test]
277    fn canonical_name_differs_by_params() {
278        let a = canonical_name("SELECT $1", &[23]); // int4
279        let b = canonical_name("SELECT $1", &[25]); // text
280        assert_ne!(a, b);
281    }
282
283    #[test]
284    fn client_register_and_resolve() {
285        let mut store = StatementStore::new();
286        let mut client = ClientPrepared::new();
287
288        let parse = Parse {
289            name: "my_stmt".into(),
290            query: "SELECT 1".into(),
291            param_types: vec![],
292        };
293
294        let canon = client.register(&parse, &mut store);
295        assert_eq!(client.resolve("my_stmt"), Some(canon.as_str()));
296        assert!(store.get(&canon).is_some());
297    }
298
299    #[test]
300    fn client_unnamed_not_tracked() {
301        let mut store = StatementStore::new();
302        let mut client = ClientPrepared::new();
303
304        let parse = Parse {
305            name: String::new(),
306            query: "SELECT 1".into(),
307            param_types: vec![],
308        };
309
310        client.register(&parse, &mut store);
311        assert_eq!(client.resolve(""), None);
312    }
313
314    #[test]
315    fn client_remove() {
316        let mut store = StatementStore::new();
317        let mut client = ClientPrepared::new();
318
319        let parse = Parse {
320            name: "s1".into(),
321            query: "SELECT 1".into(),
322            param_types: vec![],
323        };
324
325        client.register(&parse, &mut store);
326        assert!(client.resolve("s1").is_some());
327        client.remove("s1", &mut store);
328        assert!(client.resolve("s1").is_none());
329    }
330
331    #[test]
332    fn deduplication_across_clients() {
333        let mut store = StatementStore::new();
334        let mut client_a = ClientPrepared::new();
335        let mut client_b = ClientPrepared::new();
336
337        let parse_a = Parse {
338            name: "s1".into(),
339            query: "SELECT 1".into(),
340            param_types: vec![],
341        };
342        let parse_b = Parse {
343            name: "s1".into(),
344            query: "SELECT 1".into(),
345            param_types: vec![],
346        };
347
348        let canon_a = client_a.register(&parse_a, &mut store);
349        let canon_b = client_b.register(&parse_b, &mut store);
350
351        // Same query text → same canonical name.
352        assert_eq!(canon_a, canon_b);
353    }
354
355    #[test]
356    fn no_collision_different_queries_same_client_name() {
357        let mut store = StatementStore::new();
358        let mut client_a = ClientPrepared::new();
359        let mut client_b = ClientPrepared::new();
360
361        let parse_a = Parse {
362            name: "s1".into(),
363            query: "SELECT 1".into(),
364            param_types: vec![],
365        };
366        let parse_b = Parse {
367            name: "s1".into(),
368            query: "SELECT 2".into(),
369            param_types: vec![],
370        };
371
372        let canon_a = client_a.register(&parse_a, &mut store);
373        let canon_b = client_b.register(&parse_b, &mut store);
374
375        // Same client name, different queries → different canonical names.
376        assert_ne!(canon_a, canon_b);
377    }
378
379    #[test]
380    fn store_refcount_cleanup() {
381        let mut store = StatementStore::new();
382        let mut client_a = ClientPrepared::new();
383        let mut client_b = ClientPrepared::new();
384
385        let parse = Parse {
386            name: "s1".into(),
387            query: "SELECT 1".into(),
388            param_types: vec![],
389        };
390
391        let canon = client_a.register(&parse, &mut store);
392        client_b.register(&parse, &mut store);
393
394        // Both clients reference it — store has the entry.
395        assert!(store.get(&canon).is_some());
396
397        // Release client A — refcount drops to 1, still in store.
398        client_a.release_all(&mut store);
399        assert!(store.get(&canon).is_some());
400
401        // Release client B — refcount drops to 0, removed from store.
402        client_b.release_all(&mut store);
403        assert!(store.get(&canon).is_none());
404    }
405
406    #[test]
407    fn remove_decrements_refcount() {
408        let mut store = StatementStore::new();
409        let mut client = ClientPrepared::new();
410
411        let parse = Parse {
412            name: "s1".into(),
413            query: "SELECT 1".into(),
414            param_types: vec![],
415        };
416
417        let canon = client.register(&parse, &mut store);
418        assert!(store.get(&canon).is_some());
419
420        client.remove("s1", &mut store);
421        // Single reference removed — gone from store.
422        assert!(store.get(&canon).is_none());
423    }
424}