# Add Rate Limiting to a Gin API

Yes. An agent adds per-client rate limits to your Gin API, tighter on login and registration, answering 429 with Retry-After, with httptest tests and clean lint.

[Run this on Rush](https://cloud.getrush.ai/run/add-rate-limiting/gin/). 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 reach the handlers before it adds a middleware. In a Gin API like gothinkster/golang-gin-realworld-example-app, `go.mod` declares Go 1.21 with `gin-gonic/gin v1.10.0`, GORM `v1.25.12` on the SQLite driver, `golang-jwt/jwt/v5`, `go-playground/validator/v10` and `testify`, and nothing that limits requests. `hello.go` builds `gin.Default()`, turns `RedirectTrailingSlash` off so POST bodies survive, and mounts one `/api` group in three layers: `users.UsersRegister` (`POST /api/users` and `/api/users/login`) before any middleware, then `users.AuthMiddleware(false)` for the anonymous article, tag and profile reads, then `users.AuthMiddleware(true)` for `/api/user`, follows and article writes. `PORT` defaults to 8080 and `common.Init()` opens the SQLite file from `DB_PATH` or `./data/gorm.db`.

`users/middlewares.go` is the model for the new code: `AuthMiddleware(auto401 bool) gin.HandlerFunc` reads the token from an `Authorization: Token …` header or an `access_token` query parameter, parses it with the HMAC method check, and calls `AbortWithStatus(401)` or lets the request through as anonymous. `users/routers.go` shows why login needs the tightest limit: `UsersLogin` answers 401 with the same `Not Registered email or invalid password` message for an unknown email and a wrong password, which is right, but nothing slows a client that tries thousands of passwords, and `UsersRegistration` has no brake either. The agent adds a `common/ratelimit.go` with a token-bucket limiter from `golang.org/x/time/rate` keyed by `c.ClientIP()`, kept in a map behind a mutex with idle entries evicted, taking its limits from environment variables the way `PORT` and `DB_PATH` are read, and a `now` function so tests can move time. On refusal it sets `Retry-After` and aborts with 429 and a body in the `{"errors": {...}}` shape that `common.CommonError` already gives every other error.

Mounting follows the existing layering: the strict limiter goes on the `/api/users` group before `UsersRegister`, and the general one on the router before `/api`, so the `/api/ping` route and the anonymous reads are covered too. `c.ClientIP()` is only as good as Gin's trusted-proxy setting, and `hello.go` never calls `SetTrustedProxies`, so behind a load balancer every request would share the balancer's address; the agent sets the trusted proxies from an environment variable and says so in the pull request rather than leaving the limit to key on one address in production.

Tests follow the files beside them. `users/unit_test.go` and `articles/unit_test.go` build their own routers in `setupRouter()` the same way `hello.go` does, use `httptest.NewRecorder()` with `testify`, open a scratch database with `common.TestDBInit()` in `TestMain` and remove it with `common.TestDBFree()`, and `common/test_helpers.go` has `HeaderTokenMock` for authenticated requests. The new `common/ratelimit_test.go` sends one request over the limit from one `RemoteAddr` and asserts the 429 and the `Retry-After` header, sends from a second address and asserts it is unaffected, and advances the injected clock to show the bucket refills; a login test in `users` does the same through the real handler. Then the agent runs what `.github/workflows/ci.yml` runs: `scripts/gofmt.sh`, which fails on any unformatted file, `scripts/coverage.sh`, which runs `go test -coverprofile -covermode=atomic` per package on Go 1.21, 1.22 and 1.23, `golangci-lint` v1.61 with the `staticcheck`, `unused` and `misspell` linters from `.golangci.yml`, and `gosec`.

## Start it with one API call

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

```json
{
  "agent": "claude",
  "input": "Add rate limiting to this Gin API. Read hello.go, go.mod, users/middlewares.go, users/routers.go, common/utils.go and the existing unit tests first, and keep the layering hello.go uses. Add a middleware keyed by the client address with a token bucket per client, idle entries evicted, limits read from environment variables with sensible defaults, and a clock that tests can replace. Apply a strict limit to the user registration and login routes and a general limit to everything else, answer refused requests with 429, a Retry-After header and an errors body in the same shape as the other error responses, and set Gin's trusted proxies from an environment variable so the client address is right behind a proxy. Add tests with httptest and testify in the style of the existing unit tests: over the limit from one address, a second address unaffected, refill after the window, and the login route through the real handler. Run bash scripts/gofmt.sh, bash scripts/coverage.sh, go vet ./... and golangci-lint run, as the CI workflow does. Do not change go.mod beyond the one new dependency and do not change any workflow. Open a pull request that names the limits, the environment variables and the proxy setting, and quotes the test output.",
  "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 on its own branch adding `common/ratelimit.go` and its test, two lines in `hello.go` that mount the strict and general limiters, a trusted-proxies call, one new line in `go.mod` and `go.sum` for `golang.org/x/time`, and a README note on the new environment variables. The body names the limits per route, the variables, the proxy setting and quotes the coverage and lint output.

The session read names the repository and the pull request, and the transcript keeps every command: the gofmt check, each package's `go test` with coverage, `go vet`, `golangci-lint` and the first test run in which the 429 assertion failed before the middleware was mounted. The `changes` route lists the files with their diff.

Before merging, a reviewer checks that the limiter sits before `UsersRegister` and not after `AuthMiddleware`, that the general limit is high enough for the anonymous article list a frontend polls, that the map of buckets is evicted so memory does not grow with addresses seen, that `SetTrustedProxies` matches the deployment, and that the test's clock is injected rather than sleeping.

## Run it on every API without a rate limit

From your own server, list the repositories the Rush GitHub App installation reaches with `GET /o/{org}/github`, and for each service that has no limiter send `POST /o/{org}/sessions` with this prompt and that repository in `resources`, one call each with its own `request_id`. Each run works in its own sandbox on its own branch and opens its own pull request.

Give the key a `webhook_url` and each turn's end arrives as `run.completed`, `run.failed` or `run.cancelled`, signed per Standard Webhooks, with `data.session_url` to read for the pull request link. A key may have at most `max_concurrent` runs in progress at once, 4 by default, and starting one more is not refused by Rush: it answers `202` with `status: "queued"`, so a batch over many Gin services sends every request at once and each queued run starts as an earlier one finishes.

## Why run it on Rush?

The hard part of a rate limit is not the middleware, it is proving it: the right routes, the right key behind a proxy, a bucket that refills, and tests that do not sleep. The agent writes those tests in the repository's own `httptest` style and runs the full CI script set in its own sandbox, with Go 1.21 to 1.23 as the workflow does, so the pull request arrives with the same checks the merge will run.

Every command and its output stays on the session: the failing test before the middleware existed, the passing run after, the lint result. Several services can get the same treatment at once, each in its own sandbox and pull request, and a follow-up about the limits wakes the same sandbox with the module cache warm.

## Frequently asked questions

### Which library does it use?

`golang.org/x/time/rate`, a token bucket from the Go project with no cgo and no server dependency, which keeps `go.mod` to one new line. For a limit shared across several instances the agent says so in the pull request and leaves a Redis-backed store as a follow-up, since the repository runs on one SQLite file today.

### What is the client behind a load balancer?

Whatever `c.ClientIP()` returns, which depends on Gin's trusted proxies. `hello.go` never sets them, so the agent reads the proxy addresses from an environment variable and calls `SetTrustedProxies`; with none set, Gin keys on the direct peer, which would be the balancer for every request.

### Will the existing tests still pass with a limiter in front?

They build their own routers in `setupRouter()` without it, so they are unaffected until the agent mounts the limiter there too. The defaults are high enough for the existing suites, and the new tests lower them through the environment variables rather than editing the old tests.

### Can it limit by user rather than by address on authenticated routes?

Yes. After `AuthMiddleware(true)` the context holds `my_user_id`, so a second limiter keyed on it can sit on the `/api/user` and article write routes. Ask for it in the prompt; the default keeps one key, the address, because login and registration have no user yet.

## More Gin jobs

- [Add Refresh Tokens to a Gin JWT API](https://getrush.ai/run/add-refresh-tokens/gin/)
- [Add Request IDs and Structured Logging to a Gin API from a Linear Issue](https://getrush.ai/run/add-request-id-logging/gin/)
- [Add Request Timeouts to a Gin API](https://getrush.ai/run/add-request-timeouts/gin/)

## The same job on other stacks

- [Add Rate Limiting to a grammY Telegram Bot](https://getrush.ai/run/add-rate-limiting/grammy/)
- [Add Rate Limiting to a Hono API from a Linear Issue](https://getrush.ai/run/add-rate-limiting/hono/)
- [Add Rate Limiting to a Koa App](https://getrush.ai/run/add-rate-limiting/koa/)

## 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/)
