All jobs

Add Health Check Endpoints to a Koa API

Yes. An agent adds liveness and readiness routes to your Koa API that check the database through your ORM, outside the JWT guard, with tests, in 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 requests reach the app before it adds two routes, because in a Koa server the order of app.use calls decides whether a health probe gets a 200 or a 401. In an API laid out like javieraviles/node-typescript-koa-rest, src/server.ts opens a TypeORM 0.2 Postgres connection from config.databaseUrl with synchronize: true, then builds the app in order: koa-helmet's content security policy, @koa/cors, a Winston logger middleware from src/logger.ts that times each request and catches errors into the status and body, koa-bodyparser, the unprotectedRouter from src/unprotectedRoutes.ts (a single GET / that answers a hello-world string from src/controller/general.ts), then koa-jwt with the secret from config.jwtSecret, excluding only /swagger- paths, and the protectedRouter, a SwaggerRouter from koa-swagger-decorator with the user routes. A cron job from src/cron.ts starts before app.listen. src/config.ts reads PORT, NODE_ENV, JWT_SECRET and DATABASE_URL from .env, and .example.env documents them. package.json pins Koa 2.13, TypeScript 4.2, Jest 26 with ts-jest, and engines says Node 14; Dockerfile builds on node:14-alpine and exposes 3000, docker-compose.yml runs Postgres 10 and Adminer, and the tests under tests/ mock typeorm and class-validator per file.

The agent adds src/controller/health.ts with two static methods in the style of general.ts, decorated for Swagger. live answers 200 with {"status": "ok"} and the uptime, and nothing else, because a liveness probe that touches the database restarts a healthy process during a database outage. ready runs SELECT 1 through getConnection().query() with a short timeout, and answers 200 with {"status": "ok", "database": "ok"} or 503 with the failure named, so a load balancer stops routing to an instance that cannot serve. Both are registered on unprotectedRouter as GET /health/live and GET /health/ready, which places them before the JWT middleware, so no token is needed and the existing .unless() list stays as it is.

The logger middleware logs every request at info, which makes a probe every few seconds the loudest thing in the log, so the agent adds a check in src/logger.ts that logs /health/ paths at debug. Dockerfile gets a HEALTHCHECK that curls /health/live on port 3000, and README.md gets a short section under the endpoints that says what each route answers and which one a probe should use.

To check it, the agent writes tests/controller/health.test.ts in the same shape as tests/controller/user.test.ts, mocking typeorm so getConnection().query resolves for one case and rejects for another, and asserts the status and body of both methods. It runs npm run lint, which also type-checks, npm test, and npm run build, and starts the server against a Postgres it runs in its sandbox to request both routes with curl, once with the database up and once after stopping it, pasting the four responses into the pull request.

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 Koa API. Read src/server.ts, src/config.ts, src/logger.ts, src/unprotectedRoutes.ts, src/protectedRoutes.ts, src/controller/general.ts, src/controller/index.ts, src/cron.ts, package.json, tsconfig.json, Dockerfile, docker-compose.yml, .example.env, tests/controller/user.test.ts and README.md first. Add a health controller with a liveness route that touches nothing and a readiness route that runs SELECT 1 through the TypeORM connection with a timeout and answers 503 when it fails, register both on the unprotected router so the JWT middleware does not guard them, log health paths at debug in the logger middleware, add a Dockerfile HEALTHCHECK on the liveness route, document both routes in the README, and write a Jest test in the style of the existing controller test that covers the database up and down. Run lint, the tests and the build in your sandbox, start Postgres and the server, curl both routes with the database up and then down, 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

The pull request adds src/controller/health.ts and tests/controller/health.test.ts and changes src/controller/index.ts, src/unprotectedRoutes.ts, src/logger.ts, Dockerfile and README.md. Its description shows the four curl responses with their status codes, the Jest output, and the lint and build results.

The routes appear in the Swagger document the protected router generates, with the response schemas, and answer without a token. The user routes, the JWT guard, the cron job and the database configuration are unchanged, and the CI workflow runs the same build and test steps on the pull request.

Before merging, a reviewer decides which route the platform's probes should call and with what interval, whether the readiness route should also check anything the API depends on beyond Postgres, and whether the HEALTHCHECK interval in the Dockerfile matches how the image is run.

Run it on every service without a health route

A team with several Node services sends this body once per repository to POST /o/{org}/sessions, each with its own 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 instead of opening a second pull request. Each run reads its own server: an Express app gets the routes before its auth middleware, a service on Mongoose gets a ping command instead of SELECT 1, and one that already answers GET / with a health-looking body gets that route left alone and the two new ones beside it.

A webhook_url on the key reports each run.completed with the pull request in result, and a run.failed names a service whose tests did not pass before the change, which is worth knowing on its own.

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

Why run it on Rush?

Two routes are a small change, but the details are where probes go wrong: a liveness check that queries the database, a readiness route behind the token guard, a log full of probe lines, a Dockerfile that never says the container is healthy. The agent reads the middleware order and the logger, places the routes where the framework needs them, and shows the responses with the database up and down from its own sandbox.

The curl output, the tests and the build stay with the run and are pasted into the pull request, so the review is about what readiness should mean here rather than whether the routes answer. Several services can get the same two routes at once, each in its own framework's shape.

Frequently asked questions

Why two routes instead of one /health?

Liveness tells an orchestrator whether to restart the process; readiness tells a load balancer whether to send traffic. Folding the database check into liveness means a database outage restarts every instance, which makes the outage worse. The two routes keep those decisions apart.

Will the JWT middleware block the probes?

No. The routes are registered on the unprotected router, which src/server.ts mounts before koa-jwt, so a request to them never reaches the guard. The .unless() list on the guard is unchanged.

Does the readiness check add load to Postgres?

One SELECT 1 per probe, on the pool TypeORM already keeps open, with a timeout so a hung connection answers 503 quickly instead of stalling the probe. At typical probe intervals that is a handful of trivial queries a minute.

What about the log noise?

The logger middleware logs every request at info; the pull request logs /health/ paths at debug, which config.debugLogging turns off outside development, so production logs show real requests only. Errors on the readiness route still log at error.

More Koa jobs

The same job on other stacks

Keep reading