Skip to main content

objectiveai_db_proxy/
conduit.rs

1//! The multiplexer: many Postgres connections over one host socket.
2//!
3//! CONCURRENCY IS THE WHOLE JOB. A connection pool opens several
4//! sockets at once and expects them to make progress in parallel,
5//! which they must do while sharing a single WebSocket. Three rules
6//! keep them from serializing behind each other:
7//!
8//! - every hand-off is an UNBOUNDED channel send, so no stream ever
9//!   waits on another stream's reader;
10//! - routing NEVER awaits I/O, so one slow client cannot stall the
11//!   socket every other client shares;
12//! - exactly ONE writer task owns the WebSocket sink, so frames
13//!   interleave at chunk granularity instead of queueing behind
14//!   whichever stream reached the sink first.
15//!
16//! The remaining coupling is bandwidth: one socket carries everything,
17//! so a large result set shares it rather than blocking its siblings.
18
19use std::sync::Arc;
20use std::sync::atomic::{AtomicU32, AtomicU64, Ordering};
21
22use axum::body::Bytes;
23use axum::extract::ws::Message;
24use dashmap::DashMap;
25use tokio::sync::{mpsc, watch};
26
27use crate::frame::Frame;
28
29/// The attached host relay: where to put frames bound for the
30/// database, and the epoch identifying which relay that is.
31#[derive(Clone)]
32pub struct Host {
33    pub epoch: u64,
34    pub tx: mpsc::UnboundedSender<Message>,
35}
36
37struct Stream {
38    /// The relay this stream was opened over. A stream cannot outlive
39    /// it: when that socket dies, so does the far-end Postgres
40    /// connection this stream is one half of.
41    epoch: u64,
42    /// The client connection's inbound pump.
43    tx: mpsc::UnboundedSender<Bytes>,
44}
45
46pub struct Conduit {
47    next_id: AtomicU32,
48    next_epoch: AtomicU64,
49    streams: DashMap<u32, Stream>,
50    /// The current relay, or `None` while no host is attached. A
51    /// `watch` rather than a notification so a client arriving AFTER
52    /// the host attached reads the value instead of waiting forever on
53    /// a signal it missed.
54    host: watch::Sender<Option<Host>>,
55}
56
57impl Conduit {
58    pub fn new() -> Arc<Self> {
59        Arc::new(Self {
60            // Ids start at 1 so that 0 never names a live stream.
61            next_id: AtomicU32::new(1),
62            next_epoch: AtomicU64::new(1),
63            streams: DashMap::new(),
64            // Sender only — readers subscribe on demand, so there are
65            // usually NO receivers, which is why every write to this
66            // cell has to be one that stores unconditionally. See
67            // [`attach`](Self::attach).
68            host: watch::channel(None).0,
69        })
70    }
71
72    /// Wait for a relay to be attached, returning it as soon as one is.
73    ///
74    /// A plugin can — and on a cold start will — connect before the
75    /// host has dialed in. Holding here rather than buffering is
76    /// deliberate: the client's bytes stay in the kernel receive
77    /// buffer, so backpressure is the TCP window and this process
78    /// never grows a queue of its own.
79    ///
80    /// `None` only once the [`Conduit`] itself is gone, which means the
81    /// process is shutting down and there is nothing left to wait for.
82    pub async fn host(&self) -> Option<Host> {
83        let mut rx = self.host.subscribe();
84        loop {
85            if let Some(host) = rx.borrow_and_update().clone() {
86                return Some(host);
87            }
88            rx.changed().await.ok()?;
89        }
90    }
91
92    /// Resolve once `epoch` is no longer the attached relay — because it
93    /// detached, or because a newer one superseded it.
94    ///
95    /// This is what a client connection watches, and it is load-bearing
96    /// rather than belt-and-braces. [`detach`](Self::detach) sweeps the
97    /// streams it knows about, but a client that read the relay just
98    /// before it detached can register just after, leaving a stream no
99    /// sweep will ever see. Such a client is typically mid-round-trip —
100    /// blocked on a response that is never coming — and on a loopback
101    /// socket with no keepalive it would block forever. Watching the
102    /// cell makes the *value* authoritative instead of the sweep, so the
103    /// race resolves itself no matter which order the two happen in.
104    pub async fn detached(&self, epoch: u64) {
105        let mut rx = self.host.subscribe();
106        while rx
107            .borrow_and_update()
108            .as_ref()
109            .is_some_and(|host| host.epoch == epoch)
110        {
111            if rx.changed().await.is_err() {
112                return;
113            }
114        }
115    }
116
117    /// Attach a relay, returning its epoch. Newest wins: a host that
118    /// redials after a blip supersedes whatever was here.
119    ///
120    /// `send_replace`, NOT `send`, and that is the whole correctness of
121    /// this function. `send` reports "no receivers" as an error AND
122    /// DISCARDS THE VALUE — and no receiver exists at the moment that
123    /// matters most, because [`Conduit::new`] keeps only the sender and
124    /// every reader subscribes on demand. The normal cold start is
125    /// exactly that case: the host dials in and attaches before any
126    /// Postgres client has arrived to subscribe, so with `send` the
127    /// relay was stored nowhere, [`host`](Self::host) then saw `None`
128    /// forever, and every client parked until its pool timed out. A
129    /// relay that has attached must be visible to clients that arrive
130    /// afterwards, so the write cannot be conditional on someone
131    /// already watching.
132    pub fn attach(&self, tx: mpsc::UnboundedSender<Message>) -> u64 {
133        let epoch = self.next_epoch.fetch_add(1, Ordering::Relaxed);
134        self.host.send_replace(Some(Host { epoch, tx }));
135        epoch
136    }
137
138    /// A relay ended.
139    pub fn detach(&self, epoch: u64) {
140        // Clear the cell only if this relay still occupies it — a
141        // newer socket that already superseded us stays attached.
142        // `send_if_modified` writes through whether or not anyone is
143        // watching (unlike `send` — see [`attach`](Self::attach)), so a
144        // detach with no clients around still clears the cell.
145        self.host.send_if_modified(|slot| {
146            if slot.as_ref().is_some_and(|host| host.epoch == epoch) {
147                *slot = None;
148                true
149            } else {
150                false
151            }
152        });
153        // Every stream opened over this relay is now orphaned. Dropping
154        // its sender ends the client's inbound pump, which shuts that
155        // client's socket — which is precisely what makes a pool
156        // reconnect instead of waiting on a backend that is never
157        // going to answer.
158        self.streams.retain(|_, stream| stream.epoch != epoch);
159    }
160
161    /// Register a client connection and mint its id.
162    ///
163    /// Ids are monotonic and never reused within a container's life:
164    /// four billion connections is not a number a plugin container
165    /// reaches, so there is no wraparound to reason about.
166    pub fn open(&self, epoch: u64, tx: mpsc::UnboundedSender<Bytes>) -> u32 {
167        let id = self.next_id.fetch_add(1, Ordering::Relaxed);
168        self.streams.insert(id, Stream { epoch, tx });
169        id
170    }
171
172    pub fn close(&self, id: u32) {
173        self.streams.remove(&id);
174    }
175
176    /// Route one frame that arrived from the host. Never awaits.
177    pub fn route(&self, frame: Frame) {
178        match frame {
179            Frame::Data { id, payload } => {
180                // The guard must be released before `remove`, or
181                // dashmap deadlocks on its own shard lock. It is: the
182                // scrutinee temporary lives to the end of the `match`
183                // statement, and the `remove` is after it.
184                let gone = match self.streams.get(&id) {
185                    Some(stream) => stream.tx.send(payload).is_err(),
186                    // A frame for a stream that already closed. The
187                    // host has not seen our `Close` yet; nothing to do.
188                    None => false,
189                };
190                if gone {
191                    self.streams.remove(&id);
192                }
193            }
194            Frame::Close { id } => {
195                self.streams.remove(&id);
196            }
197            // `Open` is minted here and only ever travels proxy→host.
198            // One arriving inbound is a peer that does not understand
199            // the protocol, and names no stream we could route to.
200            Frame::Open { .. } => {}
201        }
202    }
203}