# 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 Rush](https://cloud.getrush.ai/run/add-tls/tokio/). Opens 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`

```json
{
  "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.

## 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

- [Upgrade Cargo Dependencies Weekly for a Tokio Service](https://getrush.ai/run/upgrade-cargo-dependencies/tokio/)
- [Write Unit Tests for a Tokio Service](https://getrush.ai/run/write-unit-tests/tokio/)
- [Add cargo-audit to CI for a Tokio Application](https://getrush.ai/run/add-cargo-audit-to-ci/tokio/)

## More jobs like this: Hand off a long task

- [Add Topology Spread Constraints to Kubernetes Deployments](https://getrush.ai/run/add-topology-spread-constraints/kubernetes/)
- [Add towncrier Changelog Fragments to a Python Package](https://getrush.ai/run/add-towncrier-changelog/python/)
- [Wrap Multi-Step Writes in GORM Transactions](https://getrush.ai/run/add-transactions/gorm/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
