objectiveai_db_proxy/run.rs
1//! The two listeners.
2//!
3//! There are two sockets, and which way each one faces is the point:
4//!
5//! | role | bind | protocol |
6//! |------------------|----------------------|-----------|
7//! | Postgres clients | `127.0.0.1:14979` | raw TCP |
8//! | laboratory host | `0.0.0.0:14980` | WebSocket |
9//!
10//! ALL FOUR VALUES ARE HARDCODED, and there is no configuration of any
11//! kind — no env, no arguments, no `.env`. That is a deliberate
12//! narrowing, not laziness.
13//!
14//! This binary is copied into a container somebody else built and
15//! started with `podman exec`, which inherits that image's environment.
16//! While these were read from env under generic names, an image
17//! declaring `ENV ADDRESS=127.0.0.1` or `ENV PORT=8080` for its OWN
18//! server — an entirely ordinary thing to do — silently reconfigured
19//! the proxy, and binding the conduit port to loopback makes it
20//! unreachable through a published port, so the plugin's database hung
21//! with nothing to say why. Hardcoding removes that whole class of
22//! failure instead of defending against it: there is nothing for an
23//! image to collide with, and nothing the launcher has to remember to
24//! pass.
25//!
26//! The Postgres side is loopback because nothing outside the container
27//! has any business reaching it, and fixed because that is what lets a
28//! connection string be stamped into container env before this process
29//! exists — the whole reason a plugin can stay ignorant of the
30//! mechanism. Inside a container's own network namespace there is no
31//! contention to randomize away from.
32//!
33//! The host side binds `0.0.0.0` because a published container port does
34//! not reach a loopback-bound listener.
35//!
36//! Neither port collides with anything already in these containers:
37//! `14978` is the laboratory MCP server's. The laboratory host declares
38//! the same two numbers independently, exactly as it declares the frame
39//! format — the two halves agree by contract, not by configuration.
40
41use std::sync::Arc;
42
43use tokio::io::{AsyncReadExt as _, AsyncWriteExt as _};
44use tokio::sync::mpsc;
45
46use crate::conduit::Conduit;
47use crate::frame::{self, Frame};
48
49/// Where Postgres clients connect. Loopback: in-container only.
50pub const POSTGRES_ADDRESS: &str = "127.0.0.1";
51
52/// The port Postgres clients connect to — what the launcher names in
53/// `OBJECTIVEAI_POSTGRES_URL`.
54pub const POSTGRES_PORT: u16 = 14979;
55
56/// Where the laboratory host dials in. `0.0.0.0`, because a published
57/// container port does not reach a loopback-bound listener.
58pub const HOST_ADDRESS: &str = "0.0.0.0";
59
60/// The port the laboratory host dials, published out of the container.
61pub const HOST_PORT: u16 = 14980;
62
63/// How much is read from a client socket at a time.
64///
65/// A read size, NOT a protocol limit: a Postgres message larger than
66/// this simply spans several frames, because both ends of the conduit
67/// reassemble from a byte stream exactly as they would from a socket.
68const READ_CHUNK: usize = 16 * 1024;
69
70pub struct Servers {
71 pub conduit: Arc<Conduit>,
72 pub postgres: tokio::net::TcpListener,
73 pub host: tokio::net::TcpListener,
74 pub router: axum::Router,
75}
76
77pub async fn setup() -> std::io::Result<Servers> {
78 let conduit = Conduit::new();
79
80 // A single route at the root: the port is dedicated to this and
81 // nothing else, so a path would only be a second name for the same
82 // thing that both ends have to agree on.
83 let router = axum::Router::new()
84 .route("/", axum::routing::any(upgrade))
85 .with_state(Arc::clone(&conduit));
86
87 // Two independent binds, so they go together rather than one after
88 // the other. `try_join!` also gives the failure semantics this wants:
89 // half a conduit is useless, so the first bind to fail is the whole
90 // setup's error.
91 let (postgres, host) = tokio::try_join!(
92 tokio::net::TcpListener::bind((POSTGRES_ADDRESS, POSTGRES_PORT)),
93 tokio::net::TcpListener::bind((HOST_ADDRESS, HOST_PORT)),
94 )?;
95
96 Ok(Servers {
97 conduit,
98 postgres,
99 host,
100 router,
101 })
102}
103
104pub async fn serve(servers: Servers) -> std::io::Result<()> {
105 let Servers {
106 conduit,
107 postgres,
108 host,
109 router,
110 } = servers;
111
112 // TCP keepalive on the host socket: the relay is idle whenever the
113 // plugin is, so a peer that died silently has to surface as a
114 // socket error rather than an eternally quiet stream. The Postgres
115 // listener needs none — its clients are in this same network
116 // namespace, and their death is never silent.
117 use axum::serve::ListenerExt;
118 let host = host.tap_io(|io| objectiveai_sdk::net::set_tcp_keepalive(io));
119
120 // Either listener failing takes the process down: half a conduit is
121 // not a conduit.
122 tokio::select! {
123 result = accept_postgres(postgres, conduit) => result,
124 result = axum::serve(host, router) => result,
125 }
126}
127
128pub async fn run() -> std::io::Result<()> {
129 let servers = setup().await?;
130 tracing::info!(
131 postgres = %servers.postgres.local_addr()?,
132 host = %servers.host.local_addr()?,
133 "listening",
134 );
135 serve(servers).await
136}
137
138/// Accept Postgres clients forever.
139async fn accept_postgres(
140 listener: tokio::net::TcpListener,
141 conduit: Arc<Conduit>,
142) -> std::io::Result<()> {
143 loop {
144 match listener.accept().await {
145 Ok((stream, _)) => {
146 tokio::spawn(client(stream, Arc::clone(&conduit)));
147 }
148 // Accept errors are per-connection (a descriptor limit, a
149 // client that vanished during the handshake), not a broken
150 // listener — dying here would take down a database that is
151 // otherwise working. The pause is what keeps a persistent
152 // error from becoming a hot spin.
153 Err(error) => {
154 tracing::warn!(%error, "accept failed");
155 tokio::time::sleep(std::time::Duration::from_millis(100)).await;
156 }
157 }
158 }
159}
160
161/// One Postgres client, from accept to close.
162async fn client(stream: tokio::net::TcpStream, conduit: Arc<Conduit>) {
163 // pgwire is a request/response conversation; Nagle would charge it
164 // coalescing delay on every round trip.
165 let _ = stream.set_nodelay(true);
166
167 let Some(host) = conduit.host().await else {
168 return;
169 };
170
171 let (mut read, mut write) = stream.into_split();
172 let (tx, mut rx) = mpsc::unbounded_channel();
173 let id = conduit.open(host.epoch, tx);
174
175 if host
176 .tx
177 .send(axum::extract::ws::Message::Binary(frame::encode_open(id)))
178 .is_err()
179 {
180 conduit.close(id);
181 return;
182 }
183
184 // The inbound pump. It ends when its sender is dropped — client
185 // gone, host `Close`, or the relay detaching — and the FIN it
186 // leaves behind is what tells the client its server went away.
187 let writer = tokio::spawn(async move {
188 while let Some(payload) = rx.recv().await {
189 if write.write_all(&payload).await.is_err() {
190 break;
191 }
192 }
193 let _ = write.shutdown().await;
194 });
195
196 let mut buf = vec![0u8; READ_CHUNK];
197 loop {
198 // Watching the relay alongside the client is what keeps this
199 // connection from outliving the socket its far end depends on.
200 // A client sitting on a half-finished round trip has nothing to
201 // read and nothing to write, so without this it would wait on a
202 // response no longer coming — and on loopback, with no keepalive
203 // to notice, it would wait forever.
204 let result = tokio::select! {
205 _ = conduit.detached(host.epoch) => break,
206 result = read.read(&mut buf) => result,
207 };
208 let filled = match result {
209 Ok(0) | Err(_) => break,
210 Ok(filled) => filled,
211 };
212 if host
213 .tx
214 .send(axum::extract::ws::Message::Binary(frame::encode_data(
215 id,
216 &buf[..filled],
217 )))
218 .is_err()
219 {
220 break;
221 }
222 }
223
224 // Deregistering drops the pump's sender, which shuts the client
225 // socket; the `Close` lets the host release the real connection
226 // instead of leaving it attached to a stream nothing will ever read.
227 conduit.close(id);
228 let _ = host
229 .tx
230 .send(axum::extract::ws::Message::Binary(frame::encode_close(id)));
231 // NOT awaited, deliberately. The pump has everything it needs to
232 // finish on its own — drain, then shut the socket down — and waiting
233 // would mean blocking on a client that has stopped reading, since a
234 // full receive window parks `write_all` indefinitely. Nothing here
235 // depends on that teardown having happened, and the stream is already
236 // deregistered, so nothing can route to it either.
237 drop(writer);
238}
239
240async fn upgrade(
241 ws: axum::extract::WebSocketUpgrade,
242 axum::extract::State(conduit): axum::extract::State<Arc<Conduit>>,
243) -> axum::response::Response {
244 ws.on_upgrade(move |socket| relay(socket, conduit))
245}
246
247/// Relay one host socket until it breaks.
248async fn relay(socket: axum::extract::ws::WebSocket, conduit: Arc<Conduit>) {
249 use axum::extract::ws::Message;
250 use futures::{SinkExt as _, StreamExt as _};
251
252 let (mut sink, mut stream) = socket.split();
253
254 // ONE writer owns the sink. Every client's frames go through this
255 // channel, so they interleave instead of queueing behind whichever
256 // client got there first.
257 let (tx, mut rx) = mpsc::unbounded_channel::<Message>();
258 let writer = tokio::spawn(async move {
259 while let Some(message) = rx.recv().await {
260 if sink.send(message).await.is_err() {
261 break;
262 }
263 }
264 });
265
266 let epoch = conduit.attach(tx);
267
268 while let Some(Ok(message)) = stream.next().await {
269 match message {
270 Message::Binary(bytes) => {
271 if let Some(frame) = Frame::decode(bytes) {
272 conduit.route(frame);
273 }
274 }
275 Message::Close(_) => break,
276 // Text is not part of the format, and axum answers
277 // ping/pong itself.
278 _ => {}
279 }
280 }
281
282 conduit.detach(epoch);
283 writer.abort();
284}