What the agent does
The agent reads the app before it sets a timer. In an app laid out like javieraviles/node-typescript-koa-rest, package.json depends on koa ^2.13.1, @koa/router ^10.0.0, koa-jwt ^4.0.0, koa-helmet ^6.1.0, @koa/cors ^3.1.0, typeorm ^0.2.32, pg ^8.5.1, winston ^3.3.3 and cron ^1.8.2, tests with jest ^26.6.3 through ts-jest, and pins engines to node 14.x.x. src/server.ts calls createConnection with a postgres URL from src/config.ts, synchronize: true and an empty extra: {}, then builds the app: helmet's content security policy, cors(), the winston middleware from src/logger.ts, bodyParser(), the unprotected router, jwt({ secret }) with .unless({ path: [/^\/swagger-/] }), the protected router, cron.start(), and finally app.listen(config.port, ...) whose return value is dropped. src/logger.ts times each request, catches thrown errors into ctx.status = err.status || 500, and logs METHOD url status ms at error, warn or info by status. src/controller/user.ts reaches the database through getManager().getRepository(User). tests/controller/user.test.ts mocks typeorm and class-validator with jest.mock, so the suite runs without a database. Dockerfile builds on node:14-alpine; .github/workflows/ci.yml runs npm run build and npm run test on Node 12 before a Heroku deploy.
There are three timers to set and the app sets none of them. First the server itself: the agent keeps the http.Server that app.listen returns and sets server.headersTimeout, server.requestTimeout and server.keepAliveTimeout. On Node 14, requestTimeout exists from 14.11.0 with a default of 0, meaning off; once set, a client that has not delivered the whole request in time gets a 408 and the connection closes, without the request ever reaching Koa. headersTimeout defaults to 60000 ms and keepAliveTimeout to 5000, and the agent sets the keep-alive value above the idle timeout of whatever sits in front of the app, which the README names as the thing to check on Heroku's router. The values come from src/config.ts as requestTimeoutMs, headersTimeoutMs and keepAliveTimeoutMs, read from the environment and listed in .example.env.
Second, a handler timeout. src/middleware/timeout.ts races next() against a timer: when the timer wins, it sets ctx.status = 503, a JSON body naming the limit, and a Retry-After header, and logs at warn, which the existing logger does anyway for any status at or above 400. It is mounted after the logger and before bodyParser, so the elapsed time it enforces covers routing, JWT verification and the controller. The agent is explicit about what this cannot do: a handler that lost the race keeps running until its own awaits finish, and anything it assigns to ctx.body afterwards is ignored because Koa has already responded. That is why there is a third timer: extra: { statement_timeout: config.dbStatementTimeoutMs } in the TypeORM connection options, which pg applies to every connection so a slow query is cancelled by Postgres rather than abandoned by Node. The handler limit is set a little above the statement limit, so the usual slow path answers with the database error, not the 503.
The tests follow the suite's own style. tests/middleware/timeout.test.ts uses jest.useFakeTimers(): with a limit of 50 ms, a next that resolves after 100 ms of advanced time leaves ctx.status at 503 and the body naming the limit, a next that resolves at once leaves the context untouched, and a next that throws still propagates so the logger's catch sees it. src/config.ts gets a test that the three environment variables parse as integers and fall back to the defaults when unset. CI runs on Node 12, where requestTimeout does not exist, so the agent moves setup-node to 14.x to match engines and the Docker image, and guards the assignment so an older runtime starts anyway. It runs npm run lint (which runs tsc --noEmit and eslint) and npm test before the pull request opens.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add request timeouts to this Koa and TypeScript app. Read package.json, src/server.ts, src/config.ts, src/logger.ts, src/protectedRoutes.ts, src/unprotectedRoutes.ts, src/controller/user.ts, tests/controller/user.test.ts, .example.env, Dockerfile and .github/workflows/ci.yml first. Keep the http.Server returned by app.listen and set headersTimeout, requestTimeout and keepAliveTimeout from new config values read from the environment with defaults; guard requestTimeout for runtimes that lack it. Add src/middleware/timeout.ts that races next() against a configurable limit and answers 503 with a JSON body and Retry-After when the limit passes, mounted after the logger and before bodyParser. Pass statement_timeout through the TypeORM extra options so Postgres cancels slow queries. Add the variables to .example.env and a README section that explains what the handler timeout can and cannot stop. Write jest tests with fake timers for the middleware and for the config parsing. Move the CI setup-node version to 14.x to match engines. Run npm run lint and npm test, then open a pull request that quotes the output.",
"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/middleware/timeout.ts, tests/middleware/timeout.test.ts and tests/config.test.ts, and changes src/server.ts (the kept server and its three timers, the middleware, the extra block), src/config.ts (four new values), .example.env, README.md and .github/workflows/ci.yml (the Node version). Its description quotes the npm test output, and shows the request the middleware refuses with a curl against a route the agent slowed on purpose in a scratch branch it does not push, so the reviewer can see the 503 body and the Retry-After header without reproducing it.
A reviewer checks the order of the limits (statement_timeout below the handler limit, both below requestTimeout), whether keepAliveTimeout exceeds the proxy's idle timeout in their deployment, and the one behaviour that surprises people: a 503 from the middleware does not stop the controller, so a slow save can still commit after the client was told to retry. The README paragraph the agent writes covers that, and the statement timeout is the mitigation for the database side of it.
The swagger routes and the JWT exemption are untouched. A request that finishes inside the limits sees no new header and no changed body.
Run it on every Datadog monitor on p99 latency
Datadog's webhook integration can send custom headers, so a monitor can call a Rush webhook trigger directly with Authorization: Bearer <its secret>. That trigger adds the alert after the prompt and fills in no placeholder, and an automation's runs are read-only, so a handler on the reader's own server receives the monitor's webhook instead and sends this body to POST /o/{org}/sessions with the slow route's name added to the prompt and a request_id that is a UUID v5 of the alert id, so a redelivered alert returns the run it already started. The run reads the route, checks which of the three limits would have caught it, and opens a pull request that adjusts the one that applies.
An automation on the Project with a schedule trigger set to every: 1d runs read-only and comments when a new route was added without the middleware in front of it or when the limits in .example.env and the README have drifted apart.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
Timeouts are easy to add and hard to prove, because the failure they guard against only appears under a slow client or a slow query. The agent runs the real server in its own sandbox, holds a connection open past headersTimeout, slows a handler past the middleware limit, and keeps the responses with the pull request. A reviewer reads a 408, a 503 and a passing suite rather than a paragraph about resilience.
A team with several Koa services has the same three timers to set in each and a different proxy in front of each. One run per repository gives one pull request per service, with defaults that match what that service's server.ts and README say about where it is deployed.
Frequently asked questions
Why three timeouts instead of one middleware?
They stop different things. headersTimeout and requestTimeout live on the Node server and refuse slow clients before Koa runs. The middleware bounds the time a handler takes to answer. statement_timeout lets Postgres cancel the query itself, which is the only one of the three that stops work rather than just the response.
Does the middleware cancel the handler?
No. It responds 503 and the handler's remaining awaits still run; Koa ignores a body assigned after the response went out. The README says so, and the statement timeout exists so the usual slow case, a query, is cancelled at the database.
Is Node 14 enough for requestTimeout?
From 14.11.0, yes; the app pins node 14.x.x and builds on node:14-alpine. The CI workflow used Node 12, which lacks it, so the pull request moves setup-node to 14.x and the assignment is guarded for older runtimes.
Which status code for a handler timeout?
503 with Retry-After, because the request was well-formed and the server could not serve it in time, which is the case a client should retry. 408 is reserved for the server-level request timeout, where the client was the slow party.
Will the existing tests still pass?
Yes. They mock typeorm and call controllers directly, so neither the server timers nor the middleware is in their path. The new tests use fake timers and never open a socket.
More Koa jobs
The same job on other stacks
- Add Connection Timeouts to a Tokio Server (Tokio)
- Add Request Timeouts to an Actix Web App (Actix Web)
- Add Request Timeouts to an aiohttp App (aiohttp)