# Add Graceful Shutdown to a Koa API

Yes. An agent makes your Koa API stop on SIGTERM without dropping requests: drain the server, stop the cron job, close the TypeORM pool, with a test, in a PR.

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

## What the agent does

The agent reads how the process starts and what it holds open before it changes how the process stops. In an API laid out like javieraviles/node-typescript-koa-rest, `src/server.ts` opens a TypeORM 0.2 Postgres connection with `createConnection`, builds the Koa app with `koa-helmet`, `@koa/cors`, the Winston request logger, `koa-bodyparser`, the unprotected router, `koa-jwt` and the protected router, calls `cron.start()` on the `CronJob` from `src/cron.ts` (an hourly job from `config.cronJobExpression`), and then calls `app.listen(config.port)` without keeping the returned server. Nothing in `src/` listens for `SIGTERM` or `SIGINT`, so a stop from Heroku, Docker or a developer's terminal kills the process mid-request, leaves the connection pool to time out on the database side, and ends the cron job wherever it was. `Dockerfile` starts the container with `CMD ["npm", "run", "start"]`, which runs `npm run serve` and then `node dist/server.js`, so the signal reaches npm first; `engines` in `package.json` says Node 14 and the image is `node:14-alpine`.

The agent changes `src/server.ts` to keep the `http.Server` that `app.listen` returns and adds `src/shutdown.ts`, which registers one handler for `SIGTERM` and `SIGINT`. The handler logs the signal, calls `server.close()` so no new connections are accepted and open requests finish, calls `cron.stop()`, closes the TypeORM connection with `getConnection().close()` once the server callback fires, and exits 0. A second signal or a timer, set from a new `shutdownTimeoutMs` field in `src/config.ts` read from `SHUTDOWN_TIMEOUT_MS`, forces exit 1 so a stuck request cannot keep the old process alive during a deploy. Because `server.close()` on Node 14 waits for idle keep-alive sockets too, and `closeIdleConnections` arrives only in later Node versions, the handler tracks sockets on the `connection` event and destroys the idle ones after `close()` is called.

The `Dockerfile` `CMD` becomes `["node", "dist/server.js"]`, so the process that holds the port is the one the container runtime signals, instead of relying on npm to forward it; `README.md` gains two lines on what happens on stop and the new variable, and `.example.env` lists it. The cron callback in `src/cron.ts` only logs, so stopping it is safe; the agent notes in the pull request that a longer job added later should check a shutting-down flag.

To check it, the agent writes `tests/shutdown.test.ts` in the style of `tests/controller/user.test.ts`, mocking `typeorm` so `getConnection().close` is a spy and the cron job so `stop` is one, then invoking the handler with a fake server whose `close` calls back, and asserts the order: close, cron stop, connection close, exit. It runs `npm run lint`, `npm test` and `npm run build`, then starts the built server against a Postgres it runs in its sandbox, opens a slow request with `curl`, sends `SIGTERM` from another shell, and shows that the request completes with 200 and the process exits 0 with the three log lines in order.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add graceful shutdown to this Koa API. Read src/server.ts, src/config.ts, src/cron.ts, src/logger.ts, package.json, Dockerfile, docker-compose.yml, .example.env, tests/controller/user.test.ts and README.md first. Keep the http.Server that app.listen returns, add a shutdown module that handles SIGTERM and SIGINT once: stop accepting connections with server.close, let in-flight requests finish, destroy idle keep-alive sockets (Node 14 has no closeIdleConnections), stop the cron job, close the TypeORM connection, and exit 0; force exit 1 after a timeout read from a new SHUTDOWN_TIMEOUT_MS setting in src/config.ts, documented in .example.env and README.md. Change the Dockerfile CMD to run node dist/server.js directly so the signal reaches the process. Write a Jest test in the style of the existing controller test that mocks typeorm and the cron job and asserts the shutdown order. Run lint, the tests and the build in your sandbox, start Postgres and the built server, send SIGTERM during a slow request and paste the request's status and the process's exit code and log lines into a pull request. Change no route or middleware.",
  "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/shutdown.ts` and `tests/shutdown.test.ts` and changes `src/server.ts`, `src/config.ts`, `Dockerfile`, `.example.env` and `README.md`. Its description shows the Jest output, the lint and build results, and the sandbox experiment: the `curl` status for the request that was in flight when `SIGTERM` arrived, the three shutdown log lines in order, and the exit code.

The routes, middleware order, JWT guard and database options are unchanged; the `CI` workflow builds and tests the branch as it does today. The one behavioural change outside shutdown is the Docker `CMD`, which is why the pull request explains that `SIGTERM` now reaches `node` directly rather than npm.

Before merging, a reviewer sets `SHUTDOWN_TIMEOUT_MS` against the platform's own grace period, so the forced exit fires before the platform's kill does, and decides whether the cron job's future work needs a check of the shutting-down flag.

## Run it on every service without a signal handler

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 entry point: an Express service drains the same way with its own server handle, one on Mongoose closes the client instead of a TypeORM connection, and one already listening for `SIGTERM` gets its existing handler reviewed rather than replaced.

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.

## Why run it on Rush?

Shutdown bugs are only visible when a signal arrives during a request, which is exactly the moment nobody is watching. The agent reproduces that moment in its own sandbox: it builds the app, starts the database, holds a request open, sends the signal and records the status, the logs and the exit code. The pull request carries that record, so the review is about the timeout value and the cron job rather than about whether draining works.

The record also keeps the details that make this job fiddly on an old runtime: the npm wrapper swallowing the signal, Node 14 waiting on keep-alive sockets, the order of closing the pool after the server. Several services can be done at once, each in its own sandbox with its own database.

## Frequently asked questions

### Why change the Dockerfile CMD?

`CMD ["npm", "run", "start"]` makes npm the process that receives `SIGTERM`, and npm does not reliably forward it to the `node` child, so the handler would never run inside the container. Running `node dist/server.js` directly puts the server where the signal lands. The `start` script stays for local use.

### What happens to a request that takes longer than the timeout?

It is cut off when the forced exit fires, which is the same outcome as today but later and logged. The timeout exists so a stuck request cannot block a deploy; set `SHUTDOWN_TIMEOUT_MS` below the platform's own grace period so the process exits on its own terms.

### Does it stop the cron job?

Yes. `cron.stop()` is called as soon as the signal arrives, so no new tick starts during the drain. The job in `src/cron.ts` only logs, so there is no half-finished work to worry about; a job that writes to the database later should check a flag the shutdown module sets.

### Why is Node 14 a concern?

`server.close()` waits for every open socket, including idle keep-alive ones that a client may hold for a long time, and the `closeIdleConnections` method that ends those arrived in a later Node release. The handler tracks sockets as they connect and destroys the idle ones after `close()`, so a drain on Node 14 does not hang until the timeout.

## More Koa jobs

- [Add Health Check Endpoints to a Koa API](https://getrush.ai/run/add-health-checks/koa/)
- [Add Input Validation to a Koa App](https://getrush.ai/run/add-input-validation/koa/)
- [Add JWT Login to a Koa API](https://getrush.ai/run/add-jwt-authentication/koa/)

## The same job on other stacks

- [Add Graceful Shutdown to a Ktor Server](https://getrush.ai/run/add-graceful-shutdown/ktor/)
- [Add Graceful Shutdown to Services Running on Kubernetes](https://getrush.ai/run/add-graceful-shutdown/kubernetes/)
- [Add Graceful Shutdown to a Leptos Axum Server](https://getrush.ai/run/add-graceful-shutdown/leptos/)

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