All jobs

Add Health Checks to a Leptos App

Yes. An agent adds /health/live and /health/ready to your Leptos app's Axum server, kept out of the Leptos route list, with Playwright tests and 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 how the server is assembled before it adds a route, since in a Leptos app the Axum router and the Leptos route list are two different things. In a project made from leptos-rs/start-axum, src/main.rs builds the server only under #[cfg(feature = "ssr")]: it reads get_configuration(None), calls generate_route_list(App) to turn the <Routes> in src/app.rs into Axum routes, registers them with .leptos_routes(&leptos_options, routes, …), sets .fallback(leptos_axum::file_and_error_handler(shell)) for static files and the Page not found. view, and serves on site-addr, 127.0.0.1:3000 in Cargo.toml. Cargo.toml has axum 0.8, tokio 1 with only rt-multi-thread, leptos, leptos_router, leptos_meta and leptos_axum at 0.8, all server crates optional behind the ssr feature, with hydrate for the WebAssembly side. src/app.rs declares one route, StaticSegment(""), rendering HomePage. There is no /health, no /ready, and a load balancer that probes the app today gets the full rendered home page.

It adds a health module compiled only with ssr, with two Axum handlers. GET /health/live returns 200 with {"status":"ok"} as axum::Json and does nothing else, so it stays true while the process runs. GET /health/ready runs the checks the prompt names, which for the template is one: that the site-root directory from LeptosOptions exists and holds the pkg bundle, since a server started before cargo leptos build finished would serve a shell with no WebAssembly. Each check is a (name, Result) pair; a failure answers 503 with the failing names, and both handlers set Cache-Control: no-store. The agent registers them with .route("/health/live", get(live)) and .route("/health/ready", get(ready)) before .leptos_routes, so the fallback never sees them, and keeps the handlers out of app.rs so the hydrate build never compiles them. tokio keeps rt-multi-thread only; nothing new is needed for the checks.

The template tests with Playwright through cargo leptos end-to-end, which runs npx playwright test in end2end/ against the server it starts, so the agent adds end2end/tests/health.spec.ts beside example.spec.ts: a request to http://localhost:3000/health/live must answer 200 with status equal to ok, /health/ready must answer 200 with every check named, and /health/nothing must still answer with the Page not found. view, proving the fallback is intact. It adds a Rust unit test too, calling the ready handler with a LeptosOptions whose site_root points at an empty temp directory and asserting 503.

In its sandbox the agent installs the nightly toolchain rust-toolchain.toml asks for, adds the wasm32-unknown-unknown target, installs cargo-leptos and sass, runs npm install in end2end, then cargo leptos build, cargo test --features ssr and cargo leptos end-to-end, so the pull request carries a passing run of the template's own test command and not only a unit test.

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 Leptos app. Read Cargo.toml, rust-toolchain.toml, src/main.rs, src/app.rs, src/lib.rs, end2end/playwright.config.ts and end2end/tests first. Add GET /health/live, which always answers 200 with a small JSON body, and GET /health/ready, which answers 200 when the site root from LeptosOptions exists with its pkg directory and 503 naming the failed check otherwise, both with Cache-Control no-store. Put the handlers in a module compiled only with the ssr feature and register them on the Axum router before leptos_routes so the file_and_error_handler fallback never handles them; do not add them to the Leptos Routes in app.rs. Write a Playwright test for both endpoints and for a missing /health path still rendering the not-found view, and a Rust unit test for the 503 case. Install the nightly toolchain, the wasm32 target, cargo-leptos and sass, run cargo leptos build, cargo test --features ssr and cargo leptos end-to-end, and open a pull request. Do not change the existing route or the site address.",
  "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/health.rs, registers it in src/lib.rs under #[cfg(feature = "ssr")], edits src/main.rs to add the two routes, and adds end2end/tests/health.spec.ts. Its description pastes the cargo test and cargo leptos end-to-end output and a curl -i of each endpoint from the built server, including the 503 body produced with the site root pointed elsewhere.

A reviewer decides which checks /health/ready should run once the app has a database or an upstream API (each is one more (name, Result) entry), whether the probes should be unauthenticated on a public host, and whether a Kubernetes manifest or a load balancer config should now point its liveness and readiness probes at the two paths.

Run it on every new Leptos service

A team that starts services from the same template runs this once per new repository from its own server: one POST /o/{org}/sessions per repository, each with that 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 rather than opening a second pull request. Each run reads its own main.rs: a service that already has a database pool in with_state gets a readiness check that pings it, and one on leptos_actix instead of Axum gets the same two handlers as Actix routes.

The useful repeat is the probe itself. An automation with a schedule trigger in a Project runs every morning, with a cron such as 0 7 * * * in your timezone, and the prompt "request /health/live and /health/ready on the staging host and report the status and body of each"; one run a day keeps its output, so a readiness failure after a deploy is seen before a customer sees it.

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

Why run it on Rush?

A health route in a Leptos app is easy to put in the wrong place: inside <Routes> it ships to the browser bundle and renders a view, after the fallback it is never reached, and without the ssr gate it breaks the WebAssembly build. The agent reads the feature flags and the router order first and proves the result with the template's own end-to-end command, nightly toolchain and all.

The toolchain install, the build and the test runs stay with the run and are in the pull request, so a reviewer sees the 503 case exercised and not described. The same request runs across every Leptos service a team keeps at once.

Frequently asked questions

Why not add the health route in app.rs?

Because <Routes> describes views that are rendered on the server and hydrated in the browser, and generate_route_list turns them into Axum routes that return HTML. A probe wants a tiny JSON answer and must not compile into the hydrate build; a plain Axum route in a module behind #[cfg(feature = "ssr")] does both.

Does the order of the routes matter?

Yes. file_and_error_handler is the router's fallback for anything the Leptos routes do not match, serving static files from the site root or the not-found view. The health routes are added with .route before .leptos_routes, so Axum matches them first; the Playwright test for /health/nothing confirms the fallback still handles everything else.

What does readiness check in a template with no database?

That the server can serve the app: the site-root directory from LeptosOptions exists and contains the pkg directory with the compiled bundle. That is what a fresh container lacks until cargo leptos build has run. Each later dependency is added as another named check in health.rs.

Why install nightly Rust?

The template's rust-toolchain.toml pins the nightly channel, and cargo-leptos expects it along with the wasm32-unknown-unknown target and sass for style/main.scss. The agent installs what the project asks for, so the end-to-end run is the same one a developer gets locally.

More Leptos jobs

The same job on other stacks

Keep reading