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}