All jobs

Add TLS to a Tokio TCP Server

Yes. An agent makes your Tokio server's Connection generic over the stream, adds rustls behind --tls-cert and --tls-key, a TLS client flag and tests, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads how bytes reach the protocol layer before it touches the socket. In a server like tokio-rs/mini-redis, Cargo.toml names tokio 1 with full, bytes 1, clap 4.2 with derive, tracing 0.1 and an optional otel feature; Cargo.lock has no rustls, native-tls or openssl entry. src/connection.rs holds Connection with a stream: BufWriter<TcpStream> and a 4 KB BytesMut read buffer, and Connection::new(socket: TcpStream) is the only constructor. src/server.rs binds nothing itself: server::run(listener: TcpListener, shutdown) accepts in Listener::accept with an exponential backoff from 1 to 64 seconds, takes a permit from a Semaphore of MAX_CONNECTIONS 250, wraps each socket in Connection::new and spawns a Handler. src/bin/server.rs binds 127.0.0.1:{port} and calls server::run(listener, signal::ctrl_c()); src/bin/cli.rs connects with Client::connect(&addr) and src/clients/client.rs does TcpStream::connect(addr) then Connection::new(socket). tests/server.rs and tests/client.rs each start a server on 127.0.0.1:0 inside a spawned task and talk to it over a raw TcpStream.

Because every reader and writer goes through Connection, TLS is a type change there and a handshake in two places. The agent makes Connection<S> generic over S: AsyncRead + AsyncWrite + Unpin + Send, keeps BufWriter<S> and the buffer as they are, and leaves read_frame, parse_frame, write_frame, write_value and write_decimal untouched because they only use AsyncReadExt and AsyncWriteExt. Handler, Client, Subscriber and the apply methods in src/cmd/ that take dst: &mut Connection get the parameter threaded through; BufferedClient and BlockingClient wrap Client and need no protocol changes. A type alias keeps Connection<TcpStream> as the default so the public signatures the examples under examples/ use still compile.

On the server the agent adds tokio-rustls and rustls-pemfile as dependencies and gives server::run a sibling, server::run_tls(listener, acceptor: TlsAcceptor, shutdown), with Listener holding an Option<TlsAcceptor>; after accept() returns a TcpStream, a present acceptor runs acceptor.accept(socket).await and a failed handshake is logged at error level through tracing and dropped without ending the accept loop, since a bad client must not take the server down. src/bin/server.rs gains --tls-cert and --tls-key as a pair of clap arguments that must be given together, reads the PEM files with rustls-pemfile, and builds a ServerConfig with no client auth. The CLI in src/bin/cli.rs gains --tls and --ca <file> so it can connect with a TlsConnector and the server name from --hostname, through a new Client::connect_tls. The shutdown path is unchanged: the broadcast on notify_shutdown and the shutdown_complete channel work the same for a TLS handler.

Tests need a certificate without a network. The agent adds rcgen as a dev-dependency and writes tests/tls.rs, which generates a self-signed certificate for localhost in a temporary directory, starts run_tls on 127.0.0.1:0 the way start_server does in tests/server.rs, then checks a SET and GET round-trip through Client::connect_tls, that a plain TcpStream writing *1\r\n$4\r\nPING\r\n to the TLS port gets no +PONG back, and that a wrong server name fails the handshake. It runs cargo build, cargo build --features otel, cargo test, cargo test --features otel and cargo fmt --all --check, the five steps .github/workflows/ci.yml runs on Ubuntu, macOS and Windows, so the matrix stays green, and keeps the output.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add optional TLS to this Tokio server. Read Cargo.toml, Cargo.lock, src/connection.rs, src/server.rs, src/bin/server.rs, src/bin/cli.rs, src/clients/client.rs, src/clients/blocking_client.rs, src/clients/buffered_client.rs, the apply functions in src/cmd/, tests/server.rs, tests/client.rs and .github/workflows/ci.yml first. Make Connection generic over any AsyncRead + AsyncWrite + Unpin + Send stream with a type alias that keeps the TcpStream form as the default, and thread the parameter through Handler, Client, Subscriber and the cmd apply functions without changing the frame code. Add tokio-rustls and rustls-pemfile; add server::run_tls that takes a TlsAcceptor, performs the handshake after accept, logs and drops a failed handshake without stopping the accept loop, and keeps the semaphore and graceful shutdown as they are. Add --tls-cert and --tls-key to the server binary, required together, and --tls plus --ca to the CLI with a Client::connect_tls that uses the --hostname value as the server name. Add rcgen as a dev-dependency and write tests/tls.rs: a self-signed localhost certificate in a temp dir, a SET and GET round-trip over TLS, a plaintext client that gets no reply from the TLS port, and a wrong server name that fails the handshake. Run cargo build, cargo build --features otel, cargo test, cargo test --features otel and cargo fmt --all --check, fix anything they report, and open a pull request that explains the generic Connection and the two new flags.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that changes Cargo.toml, Cargo.lock, src/connection.rs, src/server.rs, src/bin/server.rs, src/bin/cli.rs, src/clients/client.rs and the apply signatures under src/cmd/, and adds tests/tls.rs. The plaintext path is still the default: mini-redis-server with no flags listens exactly as before, and examples/hello_world.rs compiles without edits.

The description shows the server started with --tls-cert and --tls-key, a set and get through the CLI with --tls --ca, and the output of the five CI commands, so a reviewer can see that both feature configurations build and that rustfmt is clean. The full command log is in the transcript at GET /o/{org}/sessions/{id}/messages.

Before merging, a reviewer decides whether a failed handshake should count against the connection semaphore while it runs, whether the server should also accept a --tls-client-ca for mutual TLS, and whether the Windows job needs rustls with the ring provider rather than the default; the pull request lists those as follow-ups a message to the same session can take on.

Run it on every internal TCP service that still speaks plaintext

A team with several Tokio services runs this once per repository from its own server: one POST /o/{org}/sessions per repository, each with that repository in resources and this prompt as input. Each run reads its own connection type, so a service whose framing lives in a tokio_util::codec::Framed gets the generic parameter there instead, and one already on native-tls gets a note rather than a second TLS stack.

Send a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run it already started rather than opening a second pull request. The key's webhook_url reports run.completed for each run the key starts, with session_url for the pull request link and the test output.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

Adding TLS to a hand-written protocol server touches the one type everything flows through, and the mistakes show up only when a real client connects: a BufWriter that is now over the wrong type, a handshake error that kills the accept loop, a test suite that still opens plain sockets. The agent compiles both feature sets and runs the suite on a clean machine of its own, with a certificate it generated there, so the pull request arrives with proof instead of a promise.

Every cargo command and its output stays with the run, so a reviewer can read the rustfmt check, the otel build and the three TLS tests passing without checking the branch out, and several services can be converted at once, each in its own sandbox with its own pull request.

Frequently asked questions

Does TLS become mandatory?

No. server::run keeps its signature and mini-redis-server with no flags behaves as before. TLS is on only when --tls-cert and --tls-key are both given, and the CLI uses it only with --tls. One process listens either in plaintext or in TLS, not both; say if you want two listeners and the agent adds a second port.

Why rustls rather than OpenSSL?

tokio-rustls is pure Rust, so the three-OS CI matrix in ci.yml needs no system OpenSSL on Windows or macOS, and Cargo.lock had no TLS crate to stay consistent with. If your build already links openssl, say so in the prompt and the agent uses tokio-native-tls instead.

Will the generic Connection break the public API?

The crate exports Connection from lib.rs, so the agent keeps a type alias for the TcpStream form under the old name and makes the generic struct the new type underneath. Code that wrote Connection::new(tcp_stream) compiles unchanged; code that wrote the type in a signature compiles because the alias has the same name.

How do the tests get a certificate?

rcgen generates a self-signed certificate for localhost at test time into a temporary directory, so nothing is committed and nothing expires in the repository. The test that connects with the wrong server name proves the client verifies rather than accepting anything.

Does the OpenTelemetry feature still build?

Yes. The otel feature only changes set_up_logging in src/bin/server.rs, which the TLS flags do not touch, and the agent runs cargo build --features otel and cargo test --features otel as the workflow does to confirm it.

More Tokio jobs

More jobs like this: Hand off a long task

Keep reading