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 with this body:
{
"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"
}
]
}- 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.
- 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.
- 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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.