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
This commit is contained in:
Nicky Leach authored and GitHub committed 2026-11-17 23:14:48 +00:00
1 parent f295e496db
commit 323504e41e
3 files changed
+60 -2

No files matched your search

@@ -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`.
@@ -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());
}
@@ -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<SocketAddr, DurableRunnerError> {
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;