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 with this body:
{
"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"
}
]
}- 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 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.
The use case this job follows, with its automation and trigger: Hand off a long task.
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
The same job on other stacks
- Add Rate Limiting to an Actix Web API (Actix Web)
- Add Rate Limiting to an AdonisJS API (AdonisJS)
- Add Rate Limiting to an aiohttp App (aiohttp)