Add exec-server stub server and protocol docs (#15089)

Stacked PR 1/3.

This is the initialize-only exec-server stub slice: binary/client
scaffolding and protocol docs, without exec/filesystem implementation.

---------

Co-authored-by: Codex <noreply@openai.com>

codex-rs/exec-server/src/server/handler.rs

@@ -0,0 +1,40 @@
+use std::sync::atomic::AtomicBool;
+use std::sync::atomic::Ordering;
+
+use codex_app_server_protocol::JSONRPCErrorError;
+
+use crate::protocol::InitializeResponse;
+use crate::server::jsonrpc::invalid_request;
+
+pub(crate) struct ExecServerHandler {
+    initialize_requested: AtomicBool,
+    initialized: AtomicBool,
+}
+
+impl ExecServerHandler {
+    pub(crate) fn new() -> Self {
+        Self {
+            initialize_requested: AtomicBool::new(false),
+            initialized: AtomicBool::new(false),
+        }
+    }
+
+    pub(crate) async fn shutdown(&self) {}
+
+    pub(crate) fn initialize(&self) -> Result<InitializeResponse, JSONRPCErrorError> {
+        if self.initialize_requested.swap(true, Ordering::SeqCst) {
+            return Err(invalid_request(
+                "initialize may only be sent once per connection".to_string(),
+            ));
+        }
+        Ok(InitializeResponse {})
+    }
+
+    pub(crate) fn initialized(&self) -> Result<(), String> {
+        if !self.initialize_requested.load(Ordering::SeqCst) {
+            return Err("received `initialized` notification before `initialize`".into());
+        }
+        self.initialized.store(true, Ordering::SeqCst);
+        Ok(())
+    }
+}

codex-rs/exec-server/src/server/jsonrpc.rs

@@ -0,0 +1,53 @@
+use codex_app_server_protocol::JSONRPCError;
+use codex_app_server_protocol::JSONRPCErrorError;
+use codex_app_server_protocol::JSONRPCMessage;
+use codex_app_server_protocol::JSONRPCResponse;
+use codex_app_server_protocol::RequestId;
+use serde_json::Value;
+
+pub(crate) fn invalid_request(message: String) -> JSONRPCErrorError {
+    JSONRPCErrorError {
+        code: -32600,
+        data: None,
+        message,
+    }
+}
+
+pub(crate) fn invalid_params(message: String) -> JSONRPCErrorError {
+    JSONRPCErrorError {
+        code: -32602,
+        data: None,
+        message,
+    }
+}
+
+pub(crate) fn method_not_found(message: String) -> JSONRPCErrorError {
+    JSONRPCErrorError {
+        code: -32601,
+        data: None,
+        message,
+    }
+}
+
+pub(crate) fn response_message(
+    request_id: RequestId,
+    result: Result<Value, JSONRPCErrorError>,
+) -> JSONRPCMessage {
+    match result {
+        Ok(result) => JSONRPCMessage::Response(JSONRPCResponse {
+            id: request_id,
+            result,
+        }),
+        Err(error) => JSONRPCMessage::Error(JSONRPCError {
+            id: request_id,
+            error,
+        }),
+    }
+}
+
+pub(crate) fn invalid_request_message(reason: String) -> JSONRPCMessage {
+    JSONRPCMessage::Error(JSONRPCError {
+        id: RequestId::Integer(-1),
+        error: invalid_request(reason),
+    })
+}

codex-rs/exec-server/src/server/processor.rs

@@ -0,0 +1,121 @@
+use codex_app_server_protocol::JSONRPCMessage;
+use codex_app_server_protocol::JSONRPCNotification;
+use codex_app_server_protocol::JSONRPCRequest;
+use tracing::debug;
+
+use crate::connection::JsonRpcConnection;
+use crate::connection::JsonRpcConnectionEvent;
+use crate::protocol::INITIALIZE_METHOD;
+use crate::protocol::INITIALIZED_METHOD;
+use crate::protocol::InitializeParams;
+use crate::server::ExecServerHandler;
+use crate::server::jsonrpc::invalid_params;
+use crate::server::jsonrpc::invalid_request_message;
+use crate::server::jsonrpc::method_not_found;
+use crate::server::jsonrpc::response_message;
+use tracing::warn;
+
+pub(crate) async fn run_connection(connection: JsonRpcConnection) {
+    let (json_outgoing_tx, mut incoming_rx, _connection_tasks) = connection.into_parts();
+    let handler = ExecServerHandler::new();
+
+    while let Some(event) = incoming_rx.recv().await {
+        match event {
+            JsonRpcConnectionEvent::Message(message) => {
+                let response = match handle_connection_message(&handler, message).await {
+                    Ok(response) => response,
+                    Err(err) => {
+                        tracing::warn!(
+                            "closing exec-server connection after protocol error: {err}"
+                        );
+                        break;
+                    }
+                };
+                let Some(response) = response else {
+                    continue;
+                };
+                if json_outgoing_tx.send(response).await.is_err() {
+                    break;
+                }
+            }
+            JsonRpcConnectionEvent::MalformedMessage { reason } => {
+                warn!("ignoring malformed exec-server message: {reason}");
+                if json_outgoing_tx
+                    .send(invalid_request_message(reason))
+                    .await
+                    .is_err()
+                {
+                    break;
+                }
+            }
+            JsonRpcConnectionEvent::Disconnected { reason } => {
+                if let Some(reason) = reason {
+                    debug!("exec-server connection disconnected: {reason}");
+                }
+                break;
+            }
+        }
+    }
+
+    handler.shutdown().await;
+}
+
+pub(crate) async fn handle_connection_message(
+    handler: &ExecServerHandler,
+    message: JSONRPCMessage,
+) -> Result<Option<JSONRPCMessage>, String> {
+    match message {
+        JSONRPCMessage::Request(request) => Ok(Some(dispatch_request(handler, request))),
+        JSONRPCMessage::Notification(notification) => {
+            handle_notification(handler, notification)?;
+            Ok(None)
+        }
+        JSONRPCMessage::Response(response) => Err(format!(
+            "unexpected client response for request id {:?}",
+            response.id
+        )),
+        JSONRPCMessage::Error(error) => Err(format!(
+            "unexpected client error for request id {:?}",
+            error.id
+        )),
+    }
+}
+
+fn dispatch_request(handler: &ExecServerHandler, request: JSONRPCRequest) -> JSONRPCMessage {
+    let JSONRPCRequest {
+        id,
+        method,
+        params,
+        trace: _,
+    } = request;
+
+    match method.as_str() {
+        INITIALIZE_METHOD => {
+            let result = serde_json::from_value::<InitializeParams>(
+                params.unwrap_or(serde_json::Value::Null),
+            )
+            .map_err(|err| invalid_params(err.to_string()))
+            .and_then(|_params| handler.initialize())
+            .and_then(|response| {
+                serde_json::to_value(response).map_err(|err| invalid_params(err.to_string()))
+            });
+            response_message(id, result)
+        }
+        other => response_message(
+            id,
+            Err(method_not_found(format!(
+                "exec-server stub does not implement `{other}` yet"
+            ))),
+        ),
+    }
+}
+
+fn handle_notification(
+    handler: &ExecServerHandler,
+    notification: JSONRPCNotification,
+) -> Result<(), String> {
+    match notification.method.as_str() {
+        INITIALIZED_METHOD => handler.initialized(),
+        other => Err(format!("unexpected notification method: {other}")),
+    }
+}

codex-rs/exec-server/src/server/transport.rs

@@ -0,0 +1,118 @@
+use std::net::SocketAddr;
+use std::str::FromStr;
+
+use tokio::net::TcpListener;
+use tokio_tungstenite::accept_async;
+use tracing::warn;
+
+use crate::connection::JsonRpcConnection;
+use crate::server::processor::run_connection;
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum ExecServerTransport {
+    Stdio,
+    WebSocket { bind_address: SocketAddr },
+}
+
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub enum ExecServerTransportParseError {
+    UnsupportedListenUrl(String),
+    InvalidWebSocketListenUrl(String),
+}
+
+impl std::fmt::Display for ExecServerTransportParseError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            ExecServerTransportParseError::UnsupportedListenUrl(listen_url) => write!(
+                f,
+                "unsupported --listen URL `{listen_url}`; expected `stdio://` or `ws://IP:PORT`"
+            ),
+            ExecServerTransportParseError::InvalidWebSocketListenUrl(listen_url) => write!(
+                f,
+                "invalid websocket --listen URL `{listen_url}`; expected `ws://IP:PORT`"
+            ),
+        }
+    }
+}
+
+impl std::error::Error for ExecServerTransportParseError {}
+
+impl ExecServerTransport {
+    pub const DEFAULT_LISTEN_URL: &str = "ws://127.0.0.1:0";
+
+    pub fn from_listen_url(listen_url: &str) -> Result<Self, ExecServerTransportParseError> {
+        if listen_url == "stdio://" {
+            return Ok(Self::Stdio);
+        }
+
+        if let Some(socket_addr) = listen_url.strip_prefix("ws://") {
+            let bind_address = socket_addr.parse::<SocketAddr>().map_err(|_| {
+                ExecServerTransportParseError::InvalidWebSocketListenUrl(listen_url.to_string())
+            })?;
+            return Ok(Self::WebSocket { bind_address });
+        }
+
+        Err(ExecServerTransportParseError::UnsupportedListenUrl(
+            listen_url.to_string(),
+        ))
+    }
+}
+
+impl FromStr for ExecServerTransport {
+    type Err = ExecServerTransportParseError;
+
+    fn from_str(s: &str) -> Result<Self, Self::Err> {
+        Self::from_listen_url(s)
+    }
+}
+
+pub(crate) async fn run_transport(
+    transport: ExecServerTransport,
+) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+    match transport {
+        ExecServerTransport::Stdio => {
+            run_connection(JsonRpcConnection::from_stdio(
+                tokio::io::stdin(),
+                tokio::io::stdout(),
+                "exec-server stdio".to_string(),
+            ))
+            .await;
+            Ok(())
+        }
+        ExecServerTransport::WebSocket { bind_address } => {
+            run_websocket_listener(bind_address).await
+        }
+    }
+}
+
+async fn run_websocket_listener(
+    bind_address: SocketAddr,
+) -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
+    let listener = TcpListener::bind(bind_address).await?;
+    let local_addr = listener.local_addr()?;
+    tracing::info!("codex-exec-server listening on ws://{local_addr}");
+
+    loop {
+        let (stream, peer_addr) = listener.accept().await?;
+        tokio::spawn(async move {
+            match accept_async(stream).await {
+                Ok(websocket) => {
+                    run_connection(JsonRpcConnection::from_websocket(
+                        websocket,
+                        format!("exec-server websocket {peer_addr}"),
+                    ))
+                    .await;
+                }
+                Err(err) => {
+                    warn!(
+                        "failed to accept exec-server websocket connection from {peer_addr}: {err}"
+                    );
+                }
+            }
+        });
+    }
+}
+
+#[cfg(test)]
+#[path = "transport_tests.rs"]
+mod transport_tests;

codex-rs/exec-server/src/server/transport_tests.rs

@@ -0,0 +1,54 @@
+use pretty_assertions::assert_eq;
+
+use super::ExecServerTransport;
+
+#[test]
+fn exec_server_transport_parses_default_websocket_listen_url() {
+    let transport = ExecServerTransport::from_listen_url(ExecServerTransport::DEFAULT_LISTEN_URL)
+        .expect("default listen URL should parse");
+    assert_eq!(
+        transport,
+        ExecServerTransport::WebSocket {
+            bind_address: "127.0.0.1:0".parse().expect("valid socket address"),
+        }
+    );
+}
+
+#[test]
+fn exec_server_transport_parses_stdio_listen_url() {
+    let transport =
+        ExecServerTransport::from_listen_url("stdio://").expect("stdio listen URL should parse");
+    assert_eq!(transport, ExecServerTransport::Stdio);
+}
+
+#[test]
+fn exec_server_transport_parses_websocket_listen_url() {
+    let transport = ExecServerTransport::from_listen_url("ws://127.0.0.1:1234")
+        .expect("websocket listen URL should parse");
+    assert_eq!(
+        transport,
+        ExecServerTransport::WebSocket {
+            bind_address: "127.0.0.1:1234".parse().expect("valid socket address"),
+        }
+    );
+}
+
+#[test]
+fn exec_server_transport_rejects_invalid_websocket_listen_url() {
+    let err = ExecServerTransport::from_listen_url("ws://localhost:1234")
+        .expect_err("hostname bind address should be rejected");
+    assert_eq!(
+        err.to_string(),
+        "invalid websocket --listen URL `ws://localhost:1234`; expected `ws://IP:PORT`"
+    );
+}
+
+#[test]
+fn exec_server_transport_rejects_unsupported_listen_url() {
+    let err = ExecServerTransport::from_listen_url("http://127.0.0.1:1234")
+        .expect_err("unsupported scheme should fail");
+    assert_eq!(
+        err.to_string(),
+        "unsupported --listen URL `http://127.0.0.1:1234`; expected `stdio://` or `ws://IP:PORT`"
+    );
+}