feat: experimental codex stdio-to-uds subcommand (#5350)

codex-rs/stdio-to-uds/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+edition = "2024"
+name = "codex-stdio-to-uds"
+version = { workspace = true }
+
+[[bin]]
+name = "codex-stdio-to-uds"
+path = "src/main.rs"
+
+[lib]
+name = "codex_stdio_to_uds"
+path = "src/lib.rs"
+
+[lints]
+workspace = true
+
+[dependencies]
+anyhow = { workspace = true }
+
+[target.'cfg(target_os = "windows")'.dependencies]
+uds_windows = { workspace = true }
+
+[dev-dependencies]
+assert_cmd = { workspace = true }
+pretty_assertions = { workspace = true }
+tempfile = { workspace = true }

codex-rs/stdio-to-uds/README.md

@@ -0,0 +1,20 @@
+# codex-stdio-to-uds
+
+Traditionally, there are two transport mechanisms for an MCP server: stdio and HTTP.
+
+This crate helps enable a third, which is UNIX domain socket, because it has the advantages that:
+
+- The UDS can be attached to long-running process, like an HTTP server.
+- The UDS can leverage UNIX file permissions to restrict access.
+
+To that end, this crate provides an adapter between a UDS and stdio. The idea is that someone could start an MCP server that communicates over `/tmp/mcp.sock`. Then the user could specify this on the fly like so:
+
+```
+codex --config mcp_servers.example={command="codex-stdio-to-uds",args=["/tmp/mcp.sock"]}
+```
+
+Unfortunately, the Rust standard library does not provide support for UNIX domain sockets on Windows today even though support was added in October 2018 in Windows 10:
+
+https://github.com/rust-lang/rust/issues/56533
+
+As a workaround, this crate leverages https://crates.io/crates/uds_windows as a dependency on Windows.

codex-rs/stdio-to-uds/src/lib.rs

@@ -0,0 +1,52 @@
+#![deny(clippy::print_stdout)]
+
+use std::io;
+use std::io::Write;
+use std::net::Shutdown;
+use std::path::Path;
+use std::thread;
+
+use anyhow::Context;
+use anyhow::anyhow;
+
+#[cfg(unix)]
+use std::os::unix::net::UnixStream;
+
+#[cfg(windows)]
+use uds_windows::UnixStream;
+
+/// Connects to the Unix Domain Socket at `socket_path` and relays data between
+/// standard input/output and the socket.
+pub fn run(socket_path: &Path) -> anyhow::Result<()> {
+    let mut stream = UnixStream::connect(socket_path)
+        .with_context(|| format!("failed to connect to socket at {}", socket_path.display()))?;
+
+    let mut reader = stream
+        .try_clone()
+        .context("failed to clone socket for reading")?;
+
+    let stdout_thread = thread::spawn(move || -> io::Result<()> {
+        let stdout = io::stdout();
+        let mut handle = stdout.lock();
+        io::copy(&mut reader, &mut handle)?;
+        handle.flush()?;
+        Ok(())
+    });
+
+    let stdin = io::stdin();
+    {
+        let mut handle = stdin.lock();
+        io::copy(&mut handle, &mut stream).context("failed to copy data from stdin to socket")?;
+    }
+
+    stream
+        .shutdown(Shutdown::Write)
+        .context("failed to shutdown socket writer")?;
+
+    let stdout_result = stdout_thread
+        .join()
+        .map_err(|_| anyhow!("thread panicked while copying socket data to stdout"))?;
+    stdout_result.context("failed to copy data from socket to stdout")?;
+
+    Ok(())
+}

codex-rs/stdio-to-uds/src/main.rs

@@ -0,0 +1,19 @@
+use std::env;
+use std::path::PathBuf;
+use std::process;
+
+fn main() -> anyhow::Result<()> {
+    let mut args = env::args_os().skip(1);
+    let Some(socket_path) = args.next() else {
+        eprintln!("Usage: codex-stdio-to-uds <socket-path>");
+        process::exit(1);
+    };
+
+    if args.next().is_some() {
+        eprintln!("Expected exactly one argument: <socket-path>");
+        process::exit(1);
+    }
+
+    let socket_path = PathBuf::from(socket_path);
+    codex_stdio_to_uds::run(&socket_path)
+}

codex-rs/stdio-to-uds/tests/stdio_to_uds.rs

@@ -0,0 +1,68 @@
+use std::io::ErrorKind;
+use std::io::Read;
+use std::io::Write;
+use std::sync::mpsc;
+use std::thread;
+use std::time::Duration;
+
+use anyhow::Context;
+use assert_cmd::Command;
+use pretty_assertions::assert_eq;
+
+#[cfg(unix)]
+use std::os::unix::net::UnixListener;
+
+#[cfg(windows)]
+use uds_windows::UnixListener;
+
+#[test]
+fn pipes_stdin_and_stdout_through_socket() -> anyhow::Result<()> {
+    let dir = tempfile::TempDir::new().context("failed to create temp dir")?;
+    let socket_path = dir.path().join("socket");
+    let listener = match UnixListener::bind(&socket_path) {
+        Ok(listener) => listener,
+        Err(err) if err.kind() == ErrorKind::PermissionDenied => {
+            eprintln!("skipping test: failed to bind unix socket: {err}");
+            return Ok(());
+        }
+        Err(err) => {
+            return Err(err).context("failed to bind test unix socket");
+        }
+    };
+
+    let (tx, rx) = mpsc::channel();
+    let server_thread = thread::spawn(move || -> anyhow::Result<()> {
+        let (mut connection, _) = listener
+            .accept()
+            .context("failed to accept test connection")?;
+        let mut received = Vec::new();
+        connection
+            .read_to_end(&mut received)
+            .context("failed to read data from client")?;
+        tx.send(received)
+            .map_err(|_| anyhow::anyhow!("failed to send received bytes to test thread"))?;
+        connection
+            .write_all(b"response")
+            .context("failed to write response to client")?;
+        Ok(())
+    });
+
+    Command::cargo_bin("codex-stdio-to-uds")?
+        .arg(&socket_path)
+        .write_stdin("request")
+        .assert()
+        .success()
+        .stdout("response");
+
+    let received = rx
+        .recv_timeout(Duration::from_secs(1))
+        .context("server did not receive data in time")?;
+    assert_eq!(received, b"request");
+
+    let server_result = server_thread
+        .join()
+        .map_err(|_| anyhow::anyhow!("server thread panicked"))?;
+    server_result.context("server failed")?;
+
+    Ok(())
+}