# Add Rate Limiting to a Vapor App

Yes. An agent adds an async middleware that limits requests per client with a token bucket, answers 429 with rate-limit headers, tests it, and opens a PR.

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

## What the agent does

The agent reads how requests flow through the app before it adds a limit. In a project generated from vapor/template, `Package.swift` uses Swift tools 6.3, depends on `vapor` from 4.121.4 with `fluent` and a database driver when the project chose one, and turns on upcoming features such as `ExistentialAny` and `MemberImportVisibility`, so new code must be strict about `any` and imports. `Sources/App/configure.swift` registers the database, adds `CreateTodo` to `app.migrations`, and calls `routes(app)`; it has a commented-out `app.middleware.use(FileMiddleware(...))` line that shows where global middleware goes. `Sources/App/routes.swift` registers `GET /`, `GET /hello` and the `TodoController` collection, whose `boot` groups `GET`, `POST` and `DELETE` under `todos`. `Tests/AppTests/AppTests.swift` uses Swift Testing with `VaporTesting`: a `withApp` helper that makes an `Application` in `.testing`, runs `configure`, migrates and reverts, and tests that call `app.testing().test(.GET, "hello")`. There is no rate limiting and no dependency that provides one.

It adds `Sources/App/Middleware/RateLimitMiddleware.swift`, an `AsyncMiddleware` whose `respond(to:chainingTo:)` asks a `RateLimiter` actor for a token before calling the next responder. The actor keeps a token bucket per client key with a capacity, a refill rate and the time of the last refill, computes the refill from the elapsed time on each request, and drops idle buckets after a sweep interval so memory does not grow with every address that ever connected. An actor is the right tool here because Vapor runs handlers on many event loops and Swift 6 strict concurrency, which the package's settings lean into, will not accept a shared dictionary guarded by nothing. The client key is the first address in `X-Forwarded-For` when the app sits behind a proxy and `req.remoteAddress` otherwise, chosen by a `trustProxy` flag so a deployment that is not behind one cannot be spoofed by a header.

When a token is available the middleware calls the chain and adds `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` to the response; when none is, it throws `Abort(.tooManyRequests)` with a `Retry-After` header computed from the refill rate, so Vapor's error middleware renders the body and the client knows when to try again. The limits are a `RateLimitConfiguration` read in `configure.swift` from `Environment.get` with defaults, and the middleware is registered with `app.middleware.use` there, before `routes(app)`, so it applies to every route including the todo endpoints. A `RouteGroup` variant, `routes.grouped(RateLimitMiddleware(...))`, is shown in the pull request for the case where only `POST /todos` should be limited.

Tests go in `Tests/AppTests/RateLimitTests.swift` in the file's existing style: a `@Suite` with the same `withApp` helper, a configuration with a small capacity so the test does not need many requests, a test that sends one more request than the capacity to `hello` and asserts the last answer is `429` with `Retry-After` set, a test that `X-RateLimit-Remaining` counts down, a test that two different client addresses keep separate buckets, and an actor test that advances an injected clock and asserts tokens refill. Before pushing, the agent runs `swift build` and `swift test`, the commands the template's own `test-template.yml` workflow runs, and pastes the results into the pull request.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add rate limiting to this Vapor app and open a pull request. Read Package.swift, Sources/App/configure.swift, Sources/App/routes.swift, Sources/App/entrypoint.swift, Sources/App/Controllers/TodoController.swift, Tests/AppTests/AppTests.swift and the workflows in .github/workflows first. Add Sources/App/Middleware/RateLimitMiddleware.swift as an AsyncMiddleware backed by a RateLimiter actor with a token bucket per client, a refill computed from elapsed time, idle-bucket cleanup, and an injectable clock. Key clients by the first X-Forwarded-For address only when a trustProxy flag is set, else by req.remoteAddress. Add X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset to allowed responses and throw Abort(.tooManyRequests) with Retry-After when the bucket is empty. Read capacity, refill rate and trustProxy from Environment in configure.swift with defaults and register the middleware with app.middleware.use before routes(app). Do not add a dependency. Write Tests/AppTests/RateLimitTests.swift with Swift Testing and VaporTesting covering the 429 after capacity, the countdown header, separate buckets per client and refill with the injected clock. Run swift build and swift test and paste the results in the pull request. Do not change the todo routes.",
  "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 adds `Sources/App/Middleware/RateLimitMiddleware.swift` with the `RateLimiter` actor and `RateLimitConfiguration`, adds `Tests/AppTests/RateLimitTests.swift`, and edits `configure.swift` by the lines that read the configuration and register the middleware. `Package.swift`, `routes.swift` and `TodoController.swift` are untouched. The description lists the environment variables and their defaults, shows a `429` response with its headers, explains the `trustProxy` choice, and pastes the `swift build` and `swift test` output.

On a repository with the template's `test-template.yml` workflow, the pull request builds and runs the suite with the same toolchain, so a strict-concurrency error from the actor or a failing refill test shows before review.

A reviewer checks the defaults against the traffic they expect, confirms whether the app runs behind a proxy and sets `trustProxy` accordingly, and decides whether the health or static routes should be exempt, which is a `grouped` call away. Then they watch `X-RateLimit-Remaining` on a staging deployment under a load tool before turning the limit down.

## Run it on every Vapor service exposed to the public

A team with several Vapor services sends one `POST /o/{org}/sessions` per repository with this prompt and that repository in `resources`. Each run reads its own `configure.swift` and route groups, so a service with an authenticated API group gets the limit keyed by user instead of address, and each run opens its own pull request.

Give the API key a `webhook_url` and Rush POSTs `run.completed` when each turn ends, with the `session_url` to read the pull request and the test output from.

## Why run it on Rush?

A rate limiter is concurrency code, and the mistakes that matter, a bucket shared across event loops without isolation or a refill that drifts, do not show in a code read. In a Rush sandbox the agent compiles the middleware under the package's strict Swift 6 settings, runs the suite with an injected clock to check the refill arithmetic and with two client addresses to check isolation, and keeps every command and its output in the run's record, so the pull request shows the limiter behaving rather than describing how it should.

The middleware uses only what Vapor already provides: `AsyncMiddleware`, `Abort`, `Environment` and the testing helpers the template ships with. No package is added, so there is no third-party limiter to track, and the same request works on any Vapor 4 app whether or not it uses Fluent.

## Frequently asked questions

### Is the limit per route or for the whole app?

As registered, for the whole app, because `app.middleware.use` in `configure.swift` runs it before every route. The pull request shows the `routes.grouped(RateLimitMiddleware(...))` form for limiting one group, such as `POST /todos`, with its own capacity.

### What happens behind a load balancer?

Every request would arrive from the balancer's address and share one bucket. Setting `trustProxy` makes the middleware key on the first `X-Forwarded-For` address instead. It is off by default so a client cannot pick its own bucket by sending the header to an app that is not behind a proxy.

### Does the state survive a restart or multiple instances?

No. The buckets live in an actor in the process. That is right for one instance and for limits meant to stop a single client hammering an endpoint. Several instances that must share one limit need a store such as Redis, and the pull request names where the actor would be swapped for one.

### Why a token bucket and not a fixed window?

A fixed window lets a client send twice the limit across a boundary. A token bucket refills continuously, so a short burst up to the capacity is allowed and a sustained rate above the refill is not. The refill test advances the injected clock and asserts the arithmetic.

## More Vapor jobs

- [Add Request ID Logging to a Vapor App](https://getrush.ai/run/add-request-id-logging/vapor/)
- [Add Security Headers to a Vapor App](https://getrush.ai/run/add-security-headers/vapor/)
- [Add Seed Data to a Vapor App](https://getrush.ai/run/add-seed-data/vapor/)

## The same job on other stacks

- [Add Rate Limiting to an Actix Web API](https://getrush.ai/run/add-rate-limiting/actix/)
- [Add Rate Limiting to an AdonisJS API](https://getrush.ai/run/add-rate-limiting/adonisjs/)
- [Add Rate Limiting to an aiohttp App](https://getrush.ai/run/add-rate-limiting/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/)
