# Add Graceful Shutdown on SIGTERM to a Tokio Server

Yes. An agent makes your Tokio server stop accepting on SIGTERM, lets open connections finish within a deadline, proves it with a test, and opens a PR.

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

## What the agent does

The agent starts from how the server stops today. In a Tokio server laid out like tokio-rs/mini-redis, `src/bin/server.rs` binds a `TcpListener` and calls `server::run(listener, signal::ctrl_c())`, so the only signal the process ever reacts to is SIGINT. `src/server.rs` already has the drain machinery: `run` holds a `broadcast::Sender` called `notify_shutdown` and an `mpsc::Sender` called `shutdown_complete_tx`, each accepted connection gets a `Shutdown` wrapper from `src/shutdown.rs` around a subscribed receiver plus a clone of the completion sender, and after the `select!` between `server.run()` and the shutdown future it drops both senders and waits on `shutdown_complete_rx.recv()` until every handler task has dropped its clone. What is missing is SIGTERM, which is what `docker stop`, Kubernetes and systemd send, and a limit on how long that final wait may take.

It adds the signal first. `Cargo.toml` enables `tokio` with `features = ["full"]`, so `tokio::signal::unix::signal(SignalKind::terminate())` is available with no new dependency. The agent writes a `shutdown_signal` future in `src/bin/server.rs` that completes on either `ctrl_c()` or the SIGTERM stream and passes it to `server::run` in place of `signal::ctrl_c()`. The CI matrix in `.github/workflows/ci.yml` builds on `windows-latest` as well as Ubuntu and macOS, so the SIGTERM branch is behind `#[cfg(unix)]` with a `ctrl_c`-only future on other targets, and the binary keeps compiling on all three.

Then it bounds the drain. A handler in `Handler::run` returns as soon as `self.shutdown.recv()` fires between frames, but a client that has sent half a frame, or a subscriber parked in `SUBSCRIBE` that never sends another, keeps its task alive and `shutdown_complete_rx.recv()` waiting for it. The agent wraps that final wait in `tokio::time::timeout` with a duration `run` takes as a parameter, logs `shutdown timed out` with the number of connections still open through the `tracing` macros the file already uses, and returns so the process exits; the Semaphore permit and the `Connection` buffers drop with the task. `MAX_CONNECTIONS` and the new deadline become one small `Config` passed to `run`, since both are hard-coded constants the comment in `server.rs` already says a real application would make configurable.

The proof is a test in `tests/server.rs`, next to the existing `start_server` helper that spawns `server::run` with `ctrl_c()` on a port bound to `127.0.0.1:0`. The new test passes a `oneshot` receiver as the shutdown future instead, opens a client that has sent `*2\r\n$3\r\nGET\r\n` and nothing more, fires the oneshot, and asserts that `run` returns within the deadline rather than hanging; a second test opens a connection, completes a `SET`, fires shutdown and asserts the server returns promptly with no timeout logged. It runs `cargo test`, `cargo test --features otel` and `cargo fmt --all --check`, the three commands `ci.yml` runs, and opens the pull request with their output.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add graceful shutdown on SIGTERM to this Tokio server. Read Cargo.toml, src/bin/server.rs, src/server.rs, src/shutdown.rs, src/connection.rs, tests/server.rs and .github/workflows/ci.yml first. In src/bin/server.rs write a shutdown_signal future that completes on ctrl_c or on SIGTERM (tokio::signal::unix, behind cfg(unix) because CI builds on Windows) and pass it to server::run. In src/server.rs bound the final wait on shutdown_complete_rx with tokio::time::timeout using a drain deadline passed into run alongside the connection limit; log a warning naming how many connections were still open when the deadline passed. Add tests in tests/server.rs: one where a client has sent a partial frame and run returns within the deadline, one where an idle connection lets run return promptly. Run cargo test, cargo test --features otel and cargo fmt --all --check, and open a pull request with the output.",
  "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 `src/bin/server.rs`, `src/server.rs` and `tests/server.rs`, with no new crate in `Cargo.toml`. The description shows the signal future, the `timeout` around the drain and the new `run` signature, and quotes the `cargo test` output for both features and the `cargo fmt` check.

The run's record keeps each command and its output, so a reviewer sees the partial-frame test pass against the deadline rather than reads that it does, and sees the Windows path compile under the `cfg` split.

Before merging, a reviewer picks the deadline. A container runtime gives a process a fixed grace period before SIGKILL, and the drain deadline has to be shorter than it, so the pull request names the default it chose and where to change it, and the reviewer sets it against their own `stop_grace_period` or `terminationGracePeriodSeconds`.

## Run it on every Linear issue labelled agent

Shutdown bugs arrive as issues: a deploy that waits for SIGKILL, a client whose last command was lost on restart. With Linear connected under Settings → Connections in the console, add an automation to the Project with a `linear` trigger on `linear.issue.labeled` and the label `agent`. Its saved prompt asks for what this one asks for: read the entry point and the server module, handle SIGTERM, bound the drain, add the tests and open a pull request. The trigger adds the issue after the prompt and fills in no placeholder, so the grace period the operator needs comes from the issue text.

The trigger fires only when someone in your Rush org adds the label, and a change made by an app integration never fires it. A burst of labels is held to the automation's `max_runs_per_hour`. A team with several Tokio services sends this body once per repository from its own server instead, each with its repository in `resources` and a `request_id` that is a UUID v5 of the repository's full name, so a retried call returns the run already started.

## Why run it on Rush?

A shutdown bug only shows under a signal, and reproducing it means a server, a client stuck mid-frame and a timer, all at once. The agent runs that experiment in its own sandbox: it starts the binary, sends a half frame with the client it wrote, sends SIGTERM and watches whether the process exits, and the record keeps every command and its output. On a laptop that experiment is a one-off nobody writes down; here it is the evidence attached to the pull request.

The change is small and easy to review, which is why it is worth running on every service rather than one. Each repository gets its own sandbox, its own `cargo test` run and its own pull request, at once, and a reviewer reads a diff of about three files per service with the test output beside it.

## Frequently asked questions

### Does this change the drain logic that already exists?

No. The broadcast channel, the `Shutdown` wrapper and the completion channel stay as they are. The change adds a second signal that triggers them and a deadline on the wait at the end, so a connection that never reaches a safe point cannot hold the process open.

### What happens to a command that is mid-flight when SIGTERM arrives?

It finishes. The handler checks for shutdown only between frames, so a `SET` that has been fully read is applied and its reply written before the task returns. A connection that has sent part of a frame and stopped is the one the deadline covers, since its read never completes.

### Why keep SIGINT at all?

Because `cargo run` in a terminal and Ctrl-C send SIGINT, and the tutorial server has always stopped on it. The future the agent writes completes on either signal, so local use does not change and the container case is added.

### Will the Windows build still pass?

Yes. `tokio::signal::unix` does not exist on Windows, and CI builds there, so the SIGTERM branch is compiled only on Unix targets and the Windows build keeps the `ctrl_c` future alone. The agent runs the test suite under the same commands the workflow runs.

## More Tokio jobs

- [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/)
- [Add Prometheus Metrics to a Tokio Server](https://getrush.ai/run/add-prometheus-metrics/tokio/)

## The same job on other stacks

- [Add Graceful Shutdown to an Actix Web App](https://getrush.ai/run/add-graceful-shutdown/actix/)
- [Add Graceful Shutdown to an Axum API](https://getrush.ai/run/add-graceful-shutdown/axum/)
- [Add Graceful Shutdown to a Go chi API](https://getrush.ai/run/add-graceful-shutdown/chi/)

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