# Add Health Check Endpoints to a Rocket App

Yes. An agent adds liveness and readiness routes to your Rocket app, pings Postgres through the existing Diesel pool for readiness, tests both, and opens a PR.

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

## What the agent does

The agent reads the app before it mounts a route. In an app laid out like TatriX/realworld-rust-rocket, `Cargo.toml` names the crate `realworld` at 0.6.0 on edition 2021, with `rocket 0.5.0-rc.1` (`json` feature only), `rocket_sync_db_pools 0.1.0-rc.1` with `diesel_postgres_pool`, `diesel 1.4.8` with `postgres` and `chrono`, `rocket_cors`, `validator`, `jsonwebtoken`, `scrypt` and `dotenv`, and `once_cell` as a dev dependency; `rust-toolchain` pins `nightly`, which `Cargo.lock` confirms the versions for. `src/lib.rs` builds the instance in a `#[launch]` function: `rocket::custom(config::from_env())`, nineteen routes mounted under `/api`, `database::Db::fairing()`, a CORS fairing, `AppState::manage()`, and a `404` catcher that answers `{"status": "error", "reason": "Resource was not found."}`. `src/config.rs` reads `PORT` (default 8000) and `DATABASE_URL` (required) into a Figment with a `databases.diesel_postgres_pool.url` entry. `src/database/mod.rs` declares `#[database("diesel_postgres_pool")] pub struct Db(diesel::PgConnection)`, and a route such as `get_tags` in `src/routes/tags.rs` takes `db: Db` and runs its query inside `db.run(move |conn| ...).await`. `tests/common.rs` builds the app with `realworld::rocket()` into a `rocket::local::blocking::Client` kept behind a `OnceCell<Mutex<_>>`, and `tests/tags.rs` dispatches `GET /api/tags` and asserts the JSON shape. `.travis.yml` and the README run tests against a local Postgres seeded with `init.sql` and `diesel migration run`; there is no GitHub Actions workflow.

The agent adds `src/routes/health.rs` with two routes and mounts them at the root, not under `/api`, because a load balancer probe is not part of the public API. `GET /health` is liveness: it takes no guard and answers `200` with `{"status": "ok"}`, so it says only that the process is up and routing. `GET /health/ready` is readiness: it takes `db: Db` and runs `diesel::sql_query("SELECT 1").execute(conn)` inside `db.run`, answering `200` with `{"status": "ok", "database": "ok"}` when the statement runs and `status::Custom(Status::ServiceUnavailable, Json(...))` with the error's text when it does not. The guard matters as much as the query: when the pool cannot hand out a connection, `rocket_sync_db_pools` fails the `Db` guard with a `503` before the handler runs, so readiness reports both a dead database and an exhausted pool without extra code, and the pull request says so.

`src/lib.rs` gains a second `mount("/", routes![routes::health::live, routes::health::ready])` and `src/routes/mod.rs` a `pub mod health;`. Nothing else in the instance changes: the JWT guard in `src/auth.rs` is not applied to these routes, CORS still only matters for browser calls, and the `404` catcher keeps answering for anything else at the root. The README gains a Health section that names the two paths, says which one to use for a Kubernetes liveness probe and which for readiness, and warns against pointing a liveness probe at the database route, which would restart a healthy process every time Postgres blinked.

The tests follow `tests/common.rs`. `tests/health.rs` locks the shared client, dispatches `GET /health` and asserts `200` and the body, then dispatches `GET /health/ready` and asserts `200` with `database` equal to `ok`; the existing suite already needs a reachable Postgres, so this adds no new requirement. A failing-database test is not written, because the shared client holds one pool for the whole suite and breaking it would fail the other files; the pull request notes that and shows a manual check instead. In the sandbox the agent installs Postgres with `sudo apt-get install -y postgresql`, runs `psql -f init.sql` and `diesel migration run` as the README says, then `cargo test` on the pinned nightly, and opens the pull request with that output.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add health check endpoints to this Rocket app. Read Cargo.toml, rust-toolchain, .env, init.sql, README.md, src/lib.rs, src/config.rs, src/database/mod.rs, src/routes/mod.rs, src/routes/tags.rs, src/errors.rs, tests/common.rs and tests/tags.rs first. Add src/routes/health.rs with GET /health that answers 200 {status: ok} with no guards, and GET /health/ready that takes the Db connection guard, runs SELECT 1 through diesel::sql_query inside db.run, and answers 200 with database ok or 503 with the error text. Mount both at the root, not under /api. Add tests/health.rs in the style of tests/common.rs that asserts both routes answer 200 against the test database. Add a README section that says which route a liveness probe should use and which a readiness probe should use, and why liveness must not depend on the database. Set up Postgres as the README describes, run diesel migration run and cargo test, then open a pull request that quotes the test 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

The pull request adds `src/routes/health.rs` and `tests/health.rs`, and changes `src/lib.rs` (one more `mount`), `src/routes/mod.rs` (the module line) and `README.md` (the Health section). `Cargo.toml` and `Cargo.lock` do not change, because `diesel::sql_query`, `rocket::response::status::Custom` and `rocket::serde::json` are all in crates the app already depends on. Its description quotes the `cargo test` run, shows a `curl -i` against each route with the database up, and shows the `503` body from the readiness route with Postgres stopped, as a manual check that the test suite cannot make.

A reviewer checks that the liveness route has no `Db` guard, since a probe that restarts the process when the database is slow is the common mistake here, and that the readiness query is `SELECT 1` and not a table read that would fail on an empty database. They decide whether the routes belong at the root or under a prefix their ingress strips, and whether `/health/ready` should also check the JWT secret is present, which `AppState::manage()` already panics on at startup in release builds.

The nineteen API routes, the CORS fairing and the `404` catcher behave exactly as before, and a client that never calls the new paths sees no difference.

## Run it on every new Rocket service

A team with several Rocket services sends this body once per repository from its own server, each `POST /o/{org}/sessions` naming that repository in `resources` with a `request_id` that is a UUID v5 of the repository name, so a retried call returns the run it already started. Each run reads its own `lib.rs` and pool declaration and decides what readiness should check, which differs between a service on Postgres and one on Redis.

An automation on the Project with a `schedule` trigger set to `every: 1d` runs read-only and comments when the README's probe paths and the mounted routes have drifted apart, or when a new fairing added a dependency that readiness should cover.

## Why run it on Rush?

A health endpoint is small, and the mistake in it is structural: a liveness probe that touches the database, or a readiness route that answers `200` while the pool is empty. The agent builds the real app on the pinned nightly in its own sandbox, runs the suite against a real Postgres, stops the database to see the `503`, and keeps all of it with the pull request, so the reviewer sees the probe behave rather than reads that it should.

Across a fleet, the same two routes go into every service and the readiness check is different in each. One run per repository gives one pull request per service, with tests in that service's own harness and a README paragraph that matches its own pool.

## Frequently asked questions

### Why two routes instead of one?

Because orchestrators ask two questions. Liveness asks whether the process should be restarted, and must not depend on the database. Readiness asks whether traffic should be routed here now, and should. `/health` answers the first with no guards and `/health/ready` the second through the pool.

### What does readiness return when Postgres is down?

`503` with a JSON body carrying the error text. If the pool cannot hand out a connection at all, the `Db` request guard fails with `503` before the handler runs, so both failure modes look the same to the probe.

### Why mount at the root rather than under /api?

The `/api` prefix is the public RealWorld API that the CORS and JWT setup serve. A probe path is operational, so it lives beside the API rather than inside it. Moving it is a one-line change in `lib.rs` if an ingress expects a prefix.

### Does this need a new crate?

No. `diesel::sql_query`, `rocket::response::status::Custom` and `rocket::serde::json::Json` are already available through the dependencies in `Cargo.toml`, so the lock file does not change.

### Do the tests need a database?

Yes, the same one the existing suite needs: `tests/common.rs` builds the whole app with its pool, and `.env` points at a local Postgres seeded with `init.sql` and the Diesel migrations. The health tests add no further setup.

## More Rocket jobs

- [Add OpenAPI Docs to a Rocket API](https://getrush.ai/run/add-openapi-docs/rocket/)
- [Add Prometheus Metrics to a Rocket App](https://getrush.ai/run/add-prometheus-metrics/rocket/)
- [Add Rate Limiting to a Rocket API](https://getrush.ai/run/add-rate-limiting/rocket/)

## The same job on other stacks

- [Add Health Checks to an Express and Sequelize API](https://getrush.ai/run/add-health-checks/sequelize/)
- [Add Health Checks to a Socket Mode Slack Bolt App](https://getrush.ai/run/add-health-checks/slack-bolt/)
- [Add a Health Check Endpoint to a Slim 4 App](https://getrush.ai/run/add-health-checks/slim/)

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