Skip to main content

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}