# Add Request Timeouts to a Koa App

Yes. An agent sets socket, header and request timeouts on your Koa server, adds a handler timeout middleware and a statement timeout, tests them, and opens a PR.

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

## 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`

```json
{
  "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"
    }
  ]
}
```

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/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.

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

- [Add Security Headers to a Koa App](https://getrush.ai/run/add-security-headers/koa/)
- [Add Soft Delete to a Koa API](https://getrush.ai/run/add-soft-delete/koa/)
- [Add Structured Logging to a Koa API](https://getrush.ai/run/add-structured-logging/koa/)

## The same job on other stacks

- [Add Connection Timeouts to a Tokio Server](https://getrush.ai/run/add-request-timeouts/tokio/)
- [Add Request Timeouts to an Actix Web App](https://getrush.ai/run/add-request-timeouts/actix/)
- [Add Request Timeouts to an aiohttp App](https://getrush.ai/run/add-request-timeouts/aiohttp/)

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