All jobs

Add Graceful Shutdown to an Axum API

Yes. An agent makes your Axum server stop on SIGTERM, finish in-flight requests, close the SQLx pool, and opens a PR with a test that proves it.

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 starts by finding where the server is started and what it holds open. In an API shaped like launchbadge/realworld-axum-sqlx, Cargo.toml pins axum 0.3.4, tokio 1.14 with only the macros and rt-multi-thread features, sqlx 0.5 on Postgres and env_logger for output. src/main.rs parses Config with clap, builds a PgPoolOptions pool with max_connections(50), runs the embedded migrations with sqlx::migrate!() and calls http::serve(config, db). In src/http/mod.rs, serve wraps api_router() in a ServiceBuilder with an AddExtensionLayer carrying ApiContext and a TraceLayer, then calls axum::Server::bind on 0.0.0.0:8080 and awaits .serve(app.into_make_service()). Nothing listens for a signal: a SIGTERM from Docker or Kubernetes kills the process mid-request, and the pool's connections are dropped without being closed.

The fix stays inside the versions the lockfile already has. axum::Server in 0.3 is hyper 0.14's Server, which has with_graceful_shutdown, so no crate moves. The agent adds the signal feature to tokio in Cargo.toml, writes a shutdown_signal future in src/http/mod.rs that waits on tokio::signal::ctrl_c() and, under cfg(unix), on SignalKind::terminate() through tokio::select!, and passes it to .with_graceful_shutdown(shutdown_signal()). hyper then stops accepting connections, lets requests already being handled finish and resolves the future. serve keeps a clone of the PgPool outside the ApiContext so that, once the server future returns, it calls db.close().await and logs the shutdown through the log facade env_logger already prints.

Because the crate exposes config and http from src/lib.rs and builds one binary, the proof is an integration test in tests/graceful_shutdown.rs that drives the real executable through env!("CARGO_BIN_EXE_realworld-axum-sqlx"). It starts the server with the DATABASE_URL and HMAC_KEY the workflow already exports, polls GET /api/tags until it answers, sends SIGTERM with kill on the child's pid, and asserts that the process exits with status 0 within a bounded wait rather than being killed, and that a new connection is refused afterwards. On Windows the test is skipped with cfg(unix), matching the signal branch.

Before pushing, the agent runs the same steps as .github/workflows/rust.yml: sqlx db setup against the Postgres service, cargo build --verbose, cargo test --verbose, then cargo run in the background and the Realworld Postman collection from the abonander/realworld checkout the workflow pins. It also runs cargo fmt --check and cargo clippy, and adds a short section to README.md on how the binary stops.

Start it with one API call

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

{
  "agent": "claude",
  "input": "Add graceful shutdown to this Axum API and open a pull request. Read Cargo.toml, Cargo.lock, src/main.rs, src/lib.rs, src/http/mod.rs, .env.sample and .github/workflows/rust.yml first; do not upgrade axum, hyper, tokio or sqlx. Add the signal feature to tokio. In src/http/mod.rs write an async shutdown_signal that completes on ctrl_c and, on unix, on SIGTERM, and pass it to the server with with_graceful_shutdown. Keep a clone of the PgPool outside ApiContext and close it after the server future returns, logging the shutdown with the log crate. Add tests/graceful_shutdown.rs: start the built binary with the DATABASE_URL and HMAC_KEY from the environment, wait until GET /api/tags answers, send SIGTERM to the child, and assert it exits with status 0 within a bounded wait and that a new connection is then refused; gate the test on unix. Run sqlx db setup, cargo build --verbose, cargo test --verbose, cargo fmt --check and cargo clippy, then run the server and the Realworld Postman collection the workflow uses, and paste the output in the pull request description. Document how the server stops in README.md. Do not change any route, extractor or migration.",
  "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 with the signal feature on tokio in Cargo.toml, the shutdown_signal future and the with_graceful_shutdown call in src/http/mod.rs, the pool close after the server returns, a new tests/graceful_shutdown.rs, and a README section. Cargo.lock does not change, because a feature flag on a crate already in the lockfile adds no version. The description shows the test's output and the log lines the binary prints when it receives SIGTERM.

The repository's Rust workflow runs on the pull request with its Postgres service container, so the new test runs under cargo test --verbose with the workflow's DATABASE_URL, and the Postman collection still runs against cargo run after it. The agent pushes one commit for the server change and one for the test and README.

A reviewer checks that the signal future covers both ctrl_c and SIGTERM, that the pool is closed after the server future and not before, that the test waits on exit status rather than sleeping a fixed time, and that users, profiles and articles are untouched. Then they confirm their deployment sends SIGTERM and waits before SIGKILL.

Run it on every new Rust service

A team that runs several Axum APIs behind the same deployment starts one run per repository with POST /o/{org}/sessions, this prompt and the repository in resources. Each run reads its own serve function and pool setup, so a service that holds a Redis client or a background task gets those closed in the same place, and each opens its own pull request.

The key's webhook_url receives run.completed for each run it starts, with a session_url for the result, so a script can collect the pull request links and open them for review together.

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

Why run it on Rush?

Shutdown bugs only show under a real signal against a real process, which is why they survive code review. In a Rush sandbox the agent builds the binary, starts it against Postgres, sends SIGTERM from the test and reads the exit status and the log output; every command and its output is kept in the run's transcript, so the pull request links to the evidence rather than describing it.

The change is checked by the repository's own gates before anyone opens it: the build, the unit tests, the new integration test and the Realworld Postman collection that rust.yml runs. The same request works unchanged on every Axum service the team owns, each in its own sandbox at the same time.

Frequently asked questions

Does axum 0.3 support graceful shutdown without an upgrade?

Yes. axum::Server in that release is hyper 0.14's Server, whose with_graceful_shutdown takes any future and stops accepting connections when it completes. The agent only adds the signal feature to tokio, which the lockfile already pins at 1.14, so no dependency version moves.

What happens to requests that are running when the signal arrives?

hyper finishes the connections it is already serving and closes idle keep-alive connections, then resolves the server future. Only after that does the agent's code close the SQLx pool, so a handler in the middle of a query keeps its connection until it answers.

Will it wait forever for a stuck request?

The server itself waits for in-flight connections to finish. Your orchestrator's termination grace period is the upper bound, after which it sends SIGKILL; the pull request documents that in README.md so the deployment's grace period is set on purpose rather than by default.

Does the test slow down the suite?

It starts one process, waits until GET /api/tags answers, sends the signal and waits on the exit status, so it takes as long as one startup plus one shutdown. It is gated on unix because the SIGTERM branch is, and it uses the same DATABASE_URL the existing workflow exports.

More Axum jobs

The same job on other stacks

Keep reading