All jobs

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 RushOpens 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 with this body:

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

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

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

The same job on other stacks

Keep reading