# Add Fuzz Tests to a Tokio Protocol Parser

Yes. An agent adds a cargo-fuzz target for your Tokio server's frame parser, seeds it with the test suite's wire bytes, runs it in its sandbox and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-fuzz-tests/tokio/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent reads the parser and the way the server calls it before it writes a fuzz target, because a target that calls the API differently from production finds different bugs. In a server like tokio-rs/mini-redis, `src/frame.rs` defines `Frame` with `Simple`, `Error`, `Integer(u64)`, `Bulk(Bytes)`, `Null` and `Array(Vec<Frame>)` variants and two entry points over a `Cursor<&[u8]>`: `Frame::check`, which validates that a whole frame is present and well formed, and `Frame::parse`, whose doc comment says the message has already been validated with `check` and whose fallback arm is `unimplemented!()`. `src/connection.rs` honours that contract in `read_frame`: it calls `check`, resets the cursor with `set_position(0)`, then calls `parse`. Lengths come through `get_decimal`, which uses the `atoi` crate on a line, `$-1` is the only accepted negative bulk length, and `get_line` scans for `\r\n`. `Cargo.toml` is edition 2018 with `bytes`, `tokio` with `full`, `atoi` and `clap`, and `.github/workflows/ci.yml` runs `cargo build`, `cargo test`, both again with `--features otel`, and `cargo fmt --all --check` on Ubuntu, macOS and Windows.

The existing coverage is thin and hand-written: `tests/frame_validation.rs` has one case, that `$-2\r\n` is rejected with `protocol error; invalid frame format`, and `tests/server.rs` drives a real `TcpStream` with literal byte strings such as `*2\r\n$3\r\nGET\r\n$5\r\nhello\r\n`. Those literals are the seed corpus. The agent runs `cargo fuzz init`, which creates a `fuzz/` crate with its own workspace and `libfuzzer-sys`, and writes `fuzz/fuzz_targets/frame.rs`: for each input it calls `check`; if that succeeds it resets the cursor and calls `parse`, asserting that `parse` returns `Ok` and leaves the cursor at the same position `check` reached. That is the invariant `read_frame` relies on, stated as code. A second target, `frame_display`, formats every parsed frame with `Display`, since `Frame::Bulk` falls back to a debug print for non-UTF-8 bytes and that path has no test.

It seeds `fuzz/corpus/frame/` with the byte strings from the tests plus a few hand-made edge inputs: a bulk length larger than the payload, a non-UTF-8 simple string, an integer line with a leading sign, and arrays nested several levels, because `check` recurses once per level and the depth is unbounded in the code. The fuzzer needs a nightly toolchain, so the agent installs one with `rustup toolchain install nightly` in its sandbox and runs `cargo +nightly fuzz run frame -- -max_total_time=120` and the same for the second target, keeping the full output. If a run finds a crash the artifact is committed under `fuzz/artifacts/` and the pull request describes the input and the panic message; if none is found, it says that, not that the parser is correct.

CI gets a `fuzz` job in `ci.yml` on Ubuntu only: install nightly, `cargo install cargo-fuzz`, run each target with a bounded `-max_total_time`, and upload `fuzz/artifacts` when the job fails. The existing jobs are untouched, and because `cargo fuzz init` gives `fuzz/` its own `[workspace]`, `cargo fmt --all --check` and `cargo test` at the root behave exactly as before. The README gains a short section on running the fuzzers locally.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add fuzz tests for the Redis protocol frame parser in this repository. Read src/frame.rs, src/connection.rs, the existing tests and the CI workflow first. Use cargo-fuzz: initialise the fuzz crate, write a target that calls Frame::check and then Frame::parse exactly as Connection::read_frame does and asserts that parse succeeds and consumes the same bytes whenever check succeeds, and a second target that formats every parsed frame with Display. Seed the corpus with the literal byte strings from the test suite plus edge cases for oversized lengths, invalid UTF-8, signed integers and deeply nested arrays. Install a nightly toolchain, run each target for a bounded time, and report exactly what happened: commit any crash artifact with the input and panic message, or say that no crash was found. Add a bounded fuzz job to the GitHub workflow without changing the existing jobs. Include the commands and output. Open a pull request.",
  "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 adds `fuzz/Cargo.toml`, `fuzz/fuzz_targets/frame.rs`, `fuzz/fuzz_targets/frame_display.rs`, a seed corpus under `fuzz/corpus/`, a `fuzz` job in `.github/workflows/ci.yml` and a README section. `src/` is unchanged unless a crash was found, in which case the crashing input is committed as an artifact and the parser is left for you to decide on.

The description quotes the tail of each `cargo fuzz run` with its executions-per-second line and the final status, lists the seed inputs and what each exercises, and names any crash with its input bytes and the panic message. The commands and full output are in the transcript at `GET /o/{org}/sessions/{id}/messages`.

Before merging, a reviewer checks the invariant in the first target matches how the server really uses the parser, picks the `-max_total_time` the CI budget allows, and, if a crash was reported, decides whether the fix belongs in `check` or in the caller. A follow-up message to the same session can make the fix once that is decided.

## Run it on every parser or codec crate that reads bytes from the network

A team with several Tokio services that each parse their own wire format starts one run per repository with one `POST /o/{org}/sessions` each, the repository in `resources` and this prompt as `input`, naming the parser module. Each run reads its own validate-then-parse contract and existing byte-string tests, so the targets and corpus match that service rather than a template.

Send a `request_id`, a UUID v5 of the repository's full name, so a retried call returns the run it already started. The key's `webhook_url` reports when each run the key starts finishes, with the run's final answer in `result`.

## Why run it on Rush?

Fuzzing a parser is cheap to set up and expensive to babysit: a nightly toolchain, a corpus, minutes of CPU per target, and a crash report that has to be read, minimised and written up. The agent does all of it in a sandbox of its own and keeps every command and every line of fuzzer output, so the pull request shows what ran and for how long.

The target encodes the contract the server already relies on, check then parse, so a finding is a real bug in the path production takes, not a panic in an API nobody calls that way. Several services can be covered at once, each in its own sandbox with its own pull request and its own corpus.

## Frequently asked questions

### Why fuzz check-then-parse instead of parse alone?

`Frame::parse` documents that its input has already passed `check` and ends in `unimplemented!()` for anything else, so calling it on raw bytes panics by design and proves nothing. The server only ever calls `parse` after `check` succeeds, and the target reproduces that sequence and asserts the two agree.

### Does this need nightly Rust?

Yes, for the fuzzer. `cargo fuzz` builds targets with sanitizer flags that only nightly exposes, so the agent installs a nightly toolchain in its sandbox and the CI job does the same. The library, its tests and `cargo fmt --all --check` keep running on stable exactly as before.

### Will a fuzz job make CI slow?

It runs for the `-max_total_time` you choose and only on Ubuntu, in its own job, so the existing build and test matrix is unaffected. The pull request suggests a value and shows what the agent used in the sandbox; longer runs belong on a schedule rather than every push.

### What if the fuzzer finds something?

The crashing input is committed under `fuzz/artifacts/` and the description shows the bytes and the panic. The agent does not patch the parser in the same pull request, because the prompt asks for tests; a follow-up message to the same session can fix it and add the input as a regression test.

## More Tokio jobs

- [Add Graceful Shutdown on SIGTERM to a Tokio Server](https://getrush.ai/run/add-graceful-shutdown/tokio/)
- [Add an MSRV Check to a Tokio Project](https://getrush.ai/run/add-msrv-check/tokio/)
- [Add Mutation Testing to a Tokio Project](https://getrush.ai/run/add-mutation-testing/tokio/)

## The same job on other stacks

- [Add libFuzzer Fuzz Tests to a CMake Project](https://getrush.ai/run/add-fuzz-tests/cmake/)
- [Add Fuzz Tests to a Go CLI](https://getrush.ai/run/add-fuzz-tests/go-cli/)
- [Add Fuzz Tests to a Rust Project](https://getrush.ai/run/add-fuzz-tests/rust/)

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