What the agent does
The agent reads the kernel and the routes before adding a package, because AdonisJS puts rate limits on routes through named middleware rather than a global setting. In a project like the api kit in adonisjs/starter-kits, package.json pins @adonisjs/core 7 with @adonisjs/auth, @adonisjs/lucid on better-sqlite3, @adonisjs/session, @adonisjs/shield, @adonisjs/cors, VineJS and Tuyau, with Japa for node ace test; there is no @adonisjs/limiter. start/kernel.ts registers the server middleware, the router middleware for bodyparser, session, shield and initialize_auth_middleware, and one named middleware, auth. start/routes.ts mounts /api/v1 with auth/signup and auth/login open, and account/profile and account/logout behind middleware.auth(). app/controllers/access_tokens_controller.ts calls User.verifyCredentials and issues an access token; app/controllers/new_account_controller.ts creates the user with signupValidator. start/env.ts validates NODE_ENV, PORT, HOST, LOG_LEVEL, APP_KEY, APP_URL and SESSION_DRIVER; .env.test sets SESSION_DRIVER=memory; adonisrc.ts declares unit and functional test suites and tests/ holds only bootstrap.ts.
It installs the package the way the framework expects: node ace add @adonisjs/limiter, which registers the provider in adonisrc.ts, adds LIMITER_STORE to start/env.ts, and creates config/limiter.ts and start/limiter.ts. The agent chooses the memory store as the default for this kit, which runs one process on SQLite, keeps the database store commented in the config for a deployment with several instances, and adds LIMITER_STORE=memory to .env.example and .env.test.
start/limiter.ts then defines two throttles with limiter.define. The general one allows a quota per minute keyed on ctx.request.ip(); the auth one allows a few attempts per minute keyed on the address and the submitted email together, with blockFor so a client that keeps guessing after the quota waits longer, and a limitExceeded message that does not reveal whether the account exists. In start/routes.ts the /api/v1 group gets .use(throttle) and the auth group gets the stricter one as well, so login and signup are counted twice and the smaller quota wins. The middleware answers E_TOO_MANY_REQUESTS as a 429 with X-RateLimit-Limit, X-RateLimit-Remaining, Retry-After and X-RateLimit-Reset, and app/exceptions/handler.ts is left alone since the default rendering already matches the kit's JSON responses.
The first functional test in the kit goes in tests/functional/rate_limit.spec.ts. It uses the Japa API client that tests/bootstrap.ts already configures, posts a wrong password to /api/v1/auth/login until the response is 429, asserts the three headers, and checks that a request from the account group under a valid token is still served. A group.each.setup hook calls limiter.clear(['memory']) so tests do not leak quota into each other. The agent runs node ace migration:run, node ace test, npm run typecheck and npm run lint, and updates the endpoint list in README.md.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add rate limiting to this AdonisJS API. Read package.json, adonisrc.ts, start/kernel.ts, start/routes.ts, start/env.ts, .env.example, .env.test, config/auth.ts, app/controllers/access_tokens_controller.ts, app/controllers/new_account_controller.ts, app/validators/user.ts, tests/bootstrap.ts and README.md first. Run node ace add @adonisjs/limiter with the memory store, keep the database store commented in config/limiter.ts for multi-instance deployments, and add LIMITER_STORE=memory to .env.example and .env.test. In start/limiter.ts define a general throttle keyed on the client address for the whole /api/v1 group and a stricter auth throttle keyed on address plus email with blockFor for the auth group, with a limitExceeded message that does not reveal whether an account exists. Apply them in start/routes.ts. Write tests/functional/rate_limit.spec.ts with the Japa API client, asserting the 429 and the X-RateLimit-Limit, X-RateLimit-Remaining and Retry-After headers, with limiter.clear(['memory']) in a group.each.setup hook. Run node ace migration:run, node ace test, npm run typecheck and npm run lint, update the endpoint list in README.md, and open a pull request that lists the quotas and the store choice.",
"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
What comes back is a pull request that adds config/limiter.ts, start/limiter.ts and tests/functional/rate_limit.spec.ts, changes adonisrc.ts, start/env.ts, start/routes.ts, .env.example, .env.test, README.md and package.json with its lockfile. The description states the two quotas, the key each one uses, the blockFor duration on the auth throttle, and that the store is memory with the database alternative one uncomment away.
The run's record keeps the node ace add output, the migration, the node ace test run with the new functional suite, and the typecheck and lint runs, so a reviewer can see the 429 asserted rather than described.
Before merging, a reviewer looks at how the API is deployed. Behind a proxy, ctx.request.ip() honours the trustProxy option of the HTTP config in config/app.ts, which the kit does not set, and on more than one instance the database store or a Redis one replaces memory; the pull request names both as the decisions it did not make.
Run it on every Linear issue labelled rate-limit
In the console, add an automation to the Project with this prompt and a linear trigger on linear.issue.labeled with the label rate-limit. Labelling an issue starts one run with the issue after the prompt; the run reads which routes the issue names, which may be a single webhook endpoint rather than the auth group, applies the throttle there and opens a pull request that links the issue. Changes made by an app integration never fire the trigger, so a bot relabelling issues does not start runs.
The same body sent to POST /o/{org}/sessions with the repository in resources starts one run by hand. A request_id that is a UUID v5 of the issue identifier makes a retried call return that run instead of a second pull request.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
A limiter is only as good as its key and its placement: keyed on an address the proxy hides, or placed on a group the login route is not in, it passes review and protects nothing. The agent runs the kit's own scaffolding command, reads the routes it produced, and drives the login endpoint over the quota in its own sandbox, so the pull request shows the 429 and its headers in a test rather than in a sentence.
The sandbox is the agent's own machine, with the SQLite database migrated and the full node ace test run kept in the record. The same request can go to every AdonisJS service in the org at once, and each pull request carries its own evidence.
Frequently asked questions
Which store should I use?
memory for a single process and for tests, which is why .env.test sets it. For several instances, the database store works on the kit's SQLite, PostgreSQL or MySQL connection and adds a rate_limits migration, and a Redis store needs @adonisjs/redis configured first. The pull request keeps memory as the default and leaves the database block ready.
Does it slow every request?
The throttle middleware runs only on routes or groups that call .use() with it. The root / route and anything outside /api/v1 are untouched, and the memory store is an in-process counter.
Will the login throttle lock out a whole office behind one NAT?
The auth key is the address plus the submitted email, so one person guessing a password does not block their colleagues logging into other accounts. The general throttle is per address, and its quota is sized for normal API use; the pull request names it so it can be raised.
How do I test my own routes against it?
Follow tests/functional/rate_limit.spec.ts: the Japa API client posts in a loop and asserts the status and headers, and limiter.clear(['memory']) in a group.each.setup hook resets the counters between tests. Never clear a Redis store in tests unless the limiter has a database of its own, because clearing flushes it.
More AdonisJS jobs
The same job on other stacks
- Add Rate Limiting to an aiohttp App (aiohttp)
- Add Rate Limiting to an ASP.NET Core API (ASP.NET Core)
- Add Rate Limiting to an Axum API (Axum)