What the agent does
The agent starts by reading how requests reach the router, because a tRPC limiter is a procedure middleware rather than an HTTP one. In a project like trpc/examples-next-prisma-starter, src/pages/api/trpc/[trpc].ts hands every call to createNextApiHandler with createContext from src/server/context.ts, where createContextInner returns an empty object and createContext receives the Next.js request but reads nothing from it. src/server/trpc.ts creates the initTRPC instance with a superjson transformer and exports publicProcedure, router, mergeRouters and createCallerFactory; src/server/routers/_app.ts mounts a healthcheck query and the post router, whose list, byId and add procedures in post.ts validate input with zod. package.json runs on pnpm with @trpc/server on its canary tag, Next.js 15 in the pages router, vitest for test-unit and Playwright for test-e2e, and .github/workflows/main.yml runs both against a Postgres service on Node 22.
Then it threads the client address through the context, since the context is the only thing a middleware can key on. createContextInner gains an ip field, and createContext fills it from the first entry of the request's x-forwarded-for header, falling back to req.socket.remoteAddress, so the same code works behind Vercel's proxy and on a bare next start. src/server/env.ts already validates DATABASE_URL and NODE_ENV with zod, so two optional variables for the quota and the window go there with defaults, instead of a number buried in a middleware.
The limiter itself is rate-limiter-flexible with its memory store, one instance for reads and a smaller one for writes, created in src/server/rate-limit.ts. A t.middleware in trpc.ts calls consume(ctx.ip) and, when the store rejects, throws a TRPCError with code TOO_MANY_REQUESTS and the milliseconds until the next point in its message. rateLimitedProcedure replaces publicProcedure on healthcheck, post.list and post.byId, and post.add gets the write limiter on top. The handler's responseMeta hook, which [trpc].ts leaves as a commented placeholder, is filled in so a batch whose errors include TOO_MANY_REQUESTS is sent with a Retry-After header.
Tests prove the limit fires without a database. The existing src/server/routers/post.test.ts builds a caller with createCaller(ctx) and writes a post through Prisma; the new src/server/rate-limit.test.ts builds a caller with an ip in the context and calls healthcheck in a loop until the error's code is TOO_MANY_REQUESTS, then checks that a second address is still served. The agent runs pnpm test-unit, pnpm typecheck and pnpm lint, installs Postgres in its sandbox for pnpm prebuild and the Playwright smoke test in playwright/smoke.test.ts, which adds a post and reloads, and confirms the defaults leave that flow well under the quota.
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 tRPC API. Read package.json, .github/workflows/main.yml, src/pages/api/trpc/[trpc].ts, src/server/context.ts, src/server/trpc.ts, src/server/env.ts, src/server/routers/_app.ts, src/server/routers/post.ts, src/server/routers/post.test.ts, vitest.config.mts and playwright/smoke.test.ts first. Add an ip field to the context, read from the first x-forwarded-for entry or the socket address. Add rate-limiter-flexible with the memory store in src/server/rate-limit.ts, with the quota and window read from two optional env vars validated in src/server/env.ts with defaults. Write a t.middleware in src/server/trpc.ts that consumes a point per call and throws a TRPCError with code TOO_MANY_REQUESTS, export a rateLimitedProcedure and use it on healthcheck, post.list and post.byId, and give post.add a stricter write limiter as well. Set Retry-After through responseMeta in [trpc].ts when a response carries that error. Write src/server/rate-limit.test.ts using createCaller with an ip in the context, with no database. Run pnpm test-unit, pnpm typecheck and pnpm lint, then start Postgres, run pnpm prebuild and pnpm test-e2e, and open a pull request that names the env vars and their defaults.",
"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 changes src/server/context.ts, src/server/trpc.ts, src/server/env.ts, src/server/routers/_app.ts, src/server/routers/post.ts and src/pages/api/trpc/[trpc].ts, adds src/server/rate-limit.ts and src/server/rate-limit.test.ts, and adds one dependency to package.json and pnpm-lock.yaml. The description names the two environment variables and their defaults, lists which procedures carry which limiter, and says where the client address is read from so a reviewer can check it against their proxy.
The run's record keeps the pnpm test-unit, pnpm typecheck, pnpm lint and pnpm test-e2e output, so the reviewer can see the new test reach the error and the smoke test still pass with the limiter in front of it, rather than taking the description's word for it.
Before merging, a reviewer decides whether a memory store is enough. On one Node process it is; on several instances the same package takes a Redis store, and the pull request names that as the follow-up and the file where the store is created.
Run it on every tRPC service with no rate limit
A team with several tRPC backends starts one run per repository with one POST /o/{org}/sessions each, this prompt as input and the repository in resources. Each run reads its own createContext and router tree, so a service on the app router with a fetch adapter gets the address read from opts.req.headers instead of a Node socket, and a service whose procedures already branch on a session keys the limiter on the user id when one is present.
Send a request_id, a UUID v5 of the repository's full name, so a retried call returns the run already started instead of opening a second pull request. The key's webhook_url receives run.completed for each run the key starts, with the final answer in result.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The difficult part of this change is not the middleware but proving where it sits: a limiter on publicProcedure that nothing imports, or one keyed on an address the context never receives, passes review and does nothing. The agent runs the real test suite and the real Playwright flow in a sandbox of its own, with Postgres installed there, so the pull request arrives with the limit observed firing and the existing flows observed passing.
Each command's output stays with the run. A reviewer reads the test that hit TOO_MANY_REQUESTS and the e2e log in the record, and the same request can go to every tRPC service in the org at once, each in its own sandbox with its own pull request.
Frequently asked questions
Why a tRPC middleware instead of an Express or Next.js one?
tRPC batches several procedure calls into one HTTP request through httpBatchStreamLink, so an HTTP limiter counts a batch of ten as one. A t.middleware runs once per procedure, can tell a read from a mutation, and throws a typed TRPCError the client already knows how to handle.
Does it work on Vercel?
The address comes from x-forwarded-for first, which Vercel and most proxies set, with the socket address as the fallback for next start on a bare host. The memory store is per process, so on serverless functions each instance counts separately; the pull request says so and names the Redis store as the fix.
Will the Playwright smoke test start failing?
It should not. smoke.test.ts loads the page, adds one post and reloads, which is a handful of calls. The agent runs pnpm test-e2e after the change and keeps the output, and the defaults are set so a normal session never reaches the quota.
What does the client see when it is limited?
A tRPC error with code TOO_MANY_REQUESTS, which maps to HTTP 429, and a Retry-After header set through responseMeta. On the client, loggerLink prints it in development like any other error, and useQuery exposes it in its error field.
More tRPC jobs
The same job on other stacks
- Add Rate Limiting to a Vapor App (Vapor)
- Add Rate Limiting to an Actix Web API (Actix Web)
- Add Rate Limiting to an AdonisJS API (AdonisJS)