From 323504e41ef016891808941271a0e551aa0c7035 Mon Sep 17 00:00:00 2001 From: Nicky Leach Date: Tue, 17 Nov 2026 15:14:48 -0800 Subject: [PATCH] perf(runner): enable TCP_NODELAY for loopback PRP (#22091) ## Thinking Path > - Paperclip manages AI agents for work. > - Native Runner exchanges commands and events over WebSocket PRP. > - Both Runner connection modes use TCP sockets. > - Several small frames can follow each other during a start. > - Loopback peers can receive those frames promptly with TCP_NODELAY. ## Linked Issues or Issue Description **What existing behavior does this improve?** Delivery of PRP command results and events on local TCP connections. **Subsystem affected** Native Runner PRP transport. **Current behavior** Runner uses the default TCP setting for acknowledged small writes on its accepted and outbound PRP sockets. In an A/B test with a loopback model fixture, enabling TCP_NODELAY on the accepted Runner socket reduced median time to observe turn.started by 29 to 52 ms, depending on the provider and session state. **Proposed behavior** Enable TCP_NODELAY on accepted and outbound PRP sockets before the WebSocket handshake when the connected peer address is loopback. **Reason and benefit** The controller receives turn-start events sooner. The outbound path shares the same setup rule and has socket-option coverage. **Breaking changes** The change is a per-connection socket option. Existing launch arguments, durable checkpoints, and PRP frames carry forward. ## What Changed - Share initial stream configuration between the listener and dialer. - Check the actual peer address before enabling TCP_NODELAY. - Complete a real WebSocket handshake in one test for each connection mode and read back the option. ## Verification - `cargo fmt --manifest-path packages/paperclip-runner/runner/Cargo.toml --all --check` - `cargo test --offline --locked -p paperclip-runner-core --lib durable::transport::tests` passed locally on macOS (27 passed). - Both new tests failed on the original socket setup and passed with the change. - `cargo test --offline --locked -p paperclip-runner-core --lib --bins --test listener_accept` passed locally on macOS (676 passed, 4 ignored). ## Risks - TCP can send more small packets during high-volume local output. The check limits the option to loopback peers. The earlier A/B measured turn-start timing on the listener path. ## Model Used - OpenAI GPT-6 (Codex), with source inspection and local Rust tests. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g., `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --- .../runner/DURABLE_TRANSPORT.md | 3 ++ .../src/durable/tests/loopback_nodelay.rs | 47 +++++++++++++++++++ .../runner-core/src/durable/transport.rs | 12 ++++- 3 files changed, 60 insertions(+), 2 deletions(-) create mode 100644 packages/paperclip-runner/runner/crates/runner-core/src/durable/tests/loopback_nodelay.rs diff --git a/packages/paperclip-runner/runner/DURABLE_TRANSPORT.md b/packages/paperclip-runner/runner/DURABLE_TRANSPORT.md index ff9a14d0891..45f65c6dc0a 100644 --- a/packages/paperclip-runner/runner/DURABLE_TRANSPORT.md +++ b/packages/paperclip-runner/runner/DURABLE_TRANSPORT.md @@ -14,6 +14,9 @@ checks for an incoming connection every 10 ms (or sooner, when that delay is smaller). It never redials, so a connection does not wait out the reconnect delay after a disconnect or an authority rotation. +In both modes, Runner enables `TCP_NODELAY` before the WebSocket handshake +when the connected peer is on loopback. + Choose one form. Both require `PAPERCLIP_RUNNER_BOOTSTRAP_TICKET`. Recovery uses the same entry point. The Runner rejects `--source-reconcile`. diff --git a/packages/paperclip-runner/runner/crates/runner-core/src/durable/tests/loopback_nodelay.rs b/packages/paperclip-runner/runner/crates/runner-core/src/durable/tests/loopback_nodelay.rs new file mode 100644 index 00000000000..010835d2987 --- /dev/null +++ b/packages/paperclip-runner/runner/crates/runner-core/src/durable/tests/loopback_nodelay.rs @@ -0,0 +1,47 @@ +#[test] +fn loopback_listener_enables_tcp_nodelay() { + let listener = TcpListener::bind("0.0.0.0:0").unwrap(); + listener.set_nonblocking(true).unwrap(); + let port = listener.local_addr().unwrap().port(); + let path = "/api/runner/v1/connect/run_1".to_owned(); + let stream = TcpStream::connect((Ipv4Addr::LOCALHOST, port)).unwrap(); + let client = thread::spawn({ + let url = format!("ws://127.0.0.1:{port}{path}"); + move || client(url, stream).unwrap() + }); + let endpoint = RunnerTransportEndpoint::Listen { listener, path }; + let Some(RunnerSocket::Listen(socket)) = endpoint + .open(64 * 1024, None, Instant::now() + Duration::from_secs(5)) + .unwrap() + else { + panic!("expected an accepted PRP socket"); + }; + client.join().unwrap(); + assert!(socket.get_ref().nodelay().unwrap()); +} + +#[test] +fn loopback_dial_enables_tcp_nodelay() { + let listener = TcpListener::bind("127.0.0.1:0").unwrap(); + let config = config(listener.local_addr().unwrap().port()); + let endpoint = RunnerTransportEndpoint::new(&config.connect_url, &config.run_id).unwrap(); + let server = thread::spawn(move || { + let (stream, _) = listener.accept().unwrap(); + accept(stream).unwrap() + }); + let Some(RunnerSocket::Dial(socket)) = endpoint + .open( + config.max_frame_bytes, + None, + Instant::now() + Duration::from_secs(5), + ) + .unwrap() + else { + panic!("expected an outbound PRP socket"); + }; + server.join().unwrap(); + let MaybeTlsStream::Plain(stream) = socket.get_ref() else { + panic!("expected a plaintext loopback socket"); + }; + assert!(stream.nodelay().unwrap()); +} diff --git a/packages/paperclip-runner/runner/crates/runner-core/src/durable/transport.rs b/packages/paperclip-runner/runner/crates/runner-core/src/durable/transport.rs index fe648064c29..d777483b000 100644 --- a/packages/paperclip-runner/runner/crates/runner-core/src/durable/transport.rs +++ b/packages/paperclip-runner/runner/crates/runner-core/src/durable/transport.rs @@ -289,7 +289,7 @@ impl RunnerTransportEndpoint { let deadline = bounded_operation_deadline(connect_deadline, AUTH_TIMEOUT)?; let connector = ca_bundle_path.map(custom_tls_connector).transpose()?; ensure_connection_deadline(deadline)?; - stream.set_nonblocking(true).map_err(|error| { + configure_prp_tcp_stream(&stream).map_err(|error| { DurableRunnerError::invalid(format!( "WebSocket stream configuration failed: {error}" )) @@ -336,7 +336,7 @@ impl RunnerTransportEndpoint { ))) } }; - stream.set_nonblocking(true).map_err(|error| { + configure_prp_tcp_stream(&stream).map_err(|error| { DurableRunnerError::invalid(format!( "runner ingress stream configuration failed: {error}" )) @@ -393,6 +393,13 @@ impl RunnerTransportEndpoint { } } +fn configure_prp_tcp_stream(stream: &TcpStream) -> io::Result<()> { + if stream.peer_addr()?.ip().is_loopback() { + stream.set_nodelay(true)?; + } + stream.set_nonblocking(true) +} + fn validate_listener_authority(authority: &str) -> Result { let address: SocketAddr = authority.parse().map_err(|_| { DurableRunnerError::invalid( @@ -1775,6 +1782,7 @@ mod tests { include!("tests/acpx_park_relaunch.rs"); include!("tests/ack_release_poll.rs"); include!("tests/indeterminate_terminal_ack.rs"); + include!("tests/loopback_nodelay.rs"); use std::net::{IpAddr, Ipv4Addr, TcpListener}; use std::path::PathBuf;