# Add Rate Limiting to a Koa App

Yes. An agent puts koa-ratelimit in front of your Koa routes with a memory or Redis store, sets the limit headers, tests the 429 with supertest, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-rate-limiting/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 app is wired before it limits anything. In a Koa project like koajs/examples, every example is a directory with an `app.js` that exports `module.exports = new Koa()` and only listens when run directly (`if (!module.parent) app.listen(3000)`), which is what lets the tests mount the app on an ephemeral port. The root `package.json` pins `koa` at `^2.2.0`, `@koa/router` at `^8.0.5`, `koa-body`, `koa-basic-auth`, `koa-session` and `koa-logger`, with `mocha` `^5.0.0`, `supertest` `^3.0.0` and `should` as dev dependencies; the `test` script is `NODE_ENV=test mocha --harmony --reporter spec --require should */test.js`, `lint` is `eslint .` with `eslint-config-koa`, and `engines` asks for Node `>= 7.6`. `.travis.yml` runs `npm run lint` and `npm test` on Node stable and 8. There is no limiter anywhere: `blog/app.js` mounts `logger()`, a `render` helper, `koaBody()` and a router with `GET /`, `GET /post/new`, `GET /post/:id` and `POST /post`, which pushes the request body onto an in-memory `posts` array, and `base-auth/app.js` wraps `koa-basic-auth` (name `tj`, pass `tobi`) in a handler that turns a 401 into a `WWW-Authenticate: Basic` response.

The agent adds `koa-ratelimit` to `dependencies` and mounts it in the two examples where it matters. In `blog/app.js` a general limiter goes right after `logger()` and before `router.routes()`: `ratelimit({ driver: 'memory', db: new Map(), duration: 60000, max: 100, id: (ctx) => ctx.ip, errorMessage: 'Too many requests, slow down.', headers: { remaining: 'Rate-Limit-Remaining', reset: 'Rate-Limit-Reset', total: 'Rate-Limit-Total' } })`. A second, stricter instance with a lower `max` is attached only to `POST /post` by passing it as route middleware (`router.post('/post', writeLimit, create)`), so reads keep the generous budget and writes get the tight one. In `base-auth/app.js` the limiter is placed after the custom 401 handler and before `auth({ name: 'tj', pass: 'tobi' })`, so one client guessing passwords is refused with a 429 after `max` attempts instead of getting unlimited tries. `max` and `duration` are read from `RATE_LIMIT_MAX` and `RATE_LIMIT_WINDOW_MS` with the defaults above, and the agent sets `app.proxy = true` only in the pull request description as a question, because `ctx.ip` behind a load balancer reads `X-Forwarded-For` only when that flag is on and the agent cannot know how the app is deployed.

Tests follow the shape the repository already uses. `blog/test.js` builds its `request` with `supertest.agent(app.listen())` and uses `should`, so the agent extends it with a `describe('rate limit')` block that sets `process.env.RATE_LIMIT_MAX = '3'` before `require('./app')`, sends four `GET /` requests, asserts the first three answer 200 with `Rate-Limit-Remaining` counting down to 0 and the fourth answers 429 with the `errorMessage` body and a `Retry-After` header. `base-auth/test.js` is new: three wrong-password requests get 401, the fourth gets 429 whether the password is right or not. Because `mocha` loads every `*/test.js` in one process and each `app.js` holds its own `new Map()`, the counters do not leak between examples, and the agent says so in a comment next to the env override.

The agent runs `npm install`, `npm test` and `npm run lint` in its sandbox and keeps the output. It reads `koa-ratelimit`'s own `engines` field from the installed package and compares it with the repository's `node >= 7.6`; if the limiter needs a newer Node, the pull request says which version and leaves `engines` for you to change. `.travis.yml`, `.eslintrc.yml` and the other examples are untouched, and `Readme.md` gets one line under the example list describing the two limited apps and the env variables.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add rate limiting to this Koa app with koa-ratelimit. Read package.json, the test script, .travis.yml and each app.js first. Use the memory driver with a Map, key on ctx.ip, set the remaining, reset and total headers, and read max and window from RATE_LIMIT_MAX and RATE_LIMIT_WINDOW_MS with sensible defaults. Put a general limiter in front of the routes and a stricter one on write routes as route middleware, and put a limiter in front of any basic-auth check so password guessing is throttled. Do not set app.proxy; ask about it in the PR description. Add supertest tests in the existing mocha style that drive a client over the limit and assert the 429, the error message and the headers. Run npm test and npm run lint, check koa-ratelimit's engines field against the repository's, and include the output. Do not change the CI config. Open a pull request.",
  "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

What comes back is a pull request that changes `package.json` (the new dependency), `blog/app.js`, `base-auth/app.js` and `blog/test.js`, and adds `base-auth/test.js` plus one line in `Readme.md`. The limiter code is a handful of lines per app; the diff is mostly tests.

The description lists each limiter with its `max`, `duration` and where it is mounted, quotes the `mocha` summary and the `eslint` result, states the `engines` comparison, and asks one question: whether the app runs behind a proxy and should set `app.proxy = true` so `ctx.ip` is the client and not the balancer. Every command and its full output is in the transcript at `GET /o/{org}/sessions/{id}/messages`.

Before merging, a reviewer checks the two limits against real traffic, decides the proxy question, and considers whether the memory driver is enough: it counts per process, so two instances behind a balancer each allow `max`. A follow-up message to the same session can switch to `driver: 'redis'` with `ioredis` once a Redis URL exists.

## Run it on every Koa service with no rate limit

A team with several Koa services starts one run per repository with one `POST /o/{org}/sessions` each, the repository in `resources` and this prompt as `input`. Each run reads its own router and auth middleware, so a service with a login route gets the strict limiter there and a service that is only an API gets the general one.

Send a `request_id`, a UUID v5 of the repository's full name, so a retried call returns the run it already started. The key's `webhook_url` reports when each run the key starts finishes, with the run's final answer in `result`.

## Why run it on Rush?

Adding a limiter is easy; knowing where it belongs in a middleware chain and proving the 429 actually fires is the work. The agent reads the order of `app.use` calls, places the limiter so the 401 handler still wraps it, and drives the app over the limit with supertest in a sandbox of its own, so nothing on your machine is touched and the test output is kept.

The pull request carries the mounted middleware, the tests that hit the limit and the passing run, so review is reading a diff rather than reproducing a flood of requests locally. Several services can be done at once, each in its own sandbox with its own pull request.

## Frequently asked questions

### Does it need Redis?

No. The memory driver keeps counters in a `Map` inside the process, which is right for one instance and for tests. If you run several instances, say so in the prompt and the agent uses `driver: 'redis'` with an `ioredis` client and a `REDIS_URL` variable instead.

### Will the limiter break the existing tests?

The defaults are high enough that the existing supertest cases never reach them, and the new rate-limit tests lower `RATE_LIMIT_MAX` through the environment before requiring the app. Each example app holds its own `Map`, so counters do not cross between test files run in one mocha process.

### What about clients behind a proxy or load balancer?

`ctx.ip` is the socket address unless `app.proxy = true`, in which case Koa reads `X-Forwarded-For`. The agent does not guess your deployment: it leaves the flag off and asks in the pull request. Turning it on without a trusted proxy lets a client spoof its own key.

### Can I limit only the POST routes?

Yes. The limiter is a normal middleware, so the agent passes a separate instance as route middleware on the write routes and leaves the general one off if you ask. Say which routes and what budget in the prompt.

## More Koa jobs

- [Add Request ID Logging to a Koa App](https://getrush.ai/run/add-request-id-logging/koa/)
- [Add Request Timeouts to a Koa App](https://getrush.ai/run/add-request-timeouts/koa/)
- [Add Security Headers to a Koa App](https://getrush.ai/run/add-security-headers/koa/)

## The same job on other stacks

- [Add Rate Limiting to a Ktor API](https://getrush.ai/run/add-rate-limiting/ktor/)
- [Add Rate Limiting to a LangGraph Agent](https://getrush.ai/run/add-rate-limiting/langgraph/)
- [Add Rate Limiting to a Leptos Server](https://getrush.ai/run/add-rate-limiting/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/)
