Rate Limiting (Implementation)¶
This page covers the implementation of app-side rate limiting: the middleware and Redis-backed counters. The block list, attack-pattern rejection, signed Workers, and client IP resolution are on IP Blocker. The Cloudflare edge runs its own rate-limit rule on the credential endpoints ahead of these; see the DevOps network-ingress threat model. For the public-facing limits and 429 responses, see API → Auth Endpoints.
Source files:
backend/internal/middleware/rate_limiter.gobackend/internal/platform/cache/cache.go(theRateLimitLua script)
Middleware chain¶
internal/wiring/router.go (SetupRouter) wires the security middlewares onto the global chi router with r.Use, in order:
r.Use(middleware.SecurityHeaders(cfg.Server.Env))
r.Use(middleware.WorkerAuth(cfg.Abuse.WorkerAuthSecret))
r.Use(app.IPBlocker.BlockMiddleware())
r.Use(app.IPBlocker.SuspiciousActivityMiddleware())
/health, /ready, and /metrics are registered on a bare root mux that mounts this router underneath, so no middleware that can reject a request (IP blocking, CORS, rate limits, auth) ever sees a probe or scrape. Every process mode (API, WS, async) serves them through SetupRouter.
The /api/v1 group then applies app.RateLimiter.APILimit() as a baseline. The tighter auth limiters are passed into the auth domain's route registrar as func(http.Handler) http.Handler params, keeping routes.go free of any middleware import:
auth.RegisterPublicRoutes(r, app.Handlers.AuthHandler, app.Handlers.SessionHandler,
app.RateLimiter.RegisterLimit(), app.RateLimiter.LoginLimit(), app.RateLimiter.ResetPasswordLimit(),
app.RateLimiter.OTPLimit(), app.RateLimiter.OTPSendAccountLimit())
RateLimiter¶
RateLimiter.Limit(RateLimitConfig) is a generic per-IP limiter, and RateLimiter.LimitAccount(RateLimitConfig) is its per-account twin. The config:
type RateLimitConfig struct {
KeyPrefix string // e.g. "login_ip"
MaxRequests int // e.g. 10
Window time.Duration // e.g. 15*time.Minute
ErrorMessage string // surfaced in the 429 body
FailClosed bool // reject with 503 when Redis is unreachable
}
For every request, Limit builds {KeyPrefix}:{client_ip} and calls cache.RateLimit(ctx, key, max, window), which runs the following Lua script atomically:
local current = redis.call("INCR", KEYS[1])
if tonumber(current) == 1 then
redis.call("EXPIRE", KEYS[1], ARGV[1])
end
return current
RateLimit returns allowed = current <= max. The window is fixed: it starts at the first request and the counter resets when the key expires. When not allowed, the middleware sets Retry-After and returns 429 Too Many Requests via api.TooManyRequests, without calling the next handler.
If Redis returns an error, the outcome depends on FailClosed. The credential presets (register, login, OTP, reset-password, OTP-send-per-account) fail closed with 503 and Retry-After, since an unthrottled window there is a brute-force window. APILimit fails open so a Redis outage does not take the API down. Both log rate limiter backend unavailable with the key prefix.
Per-account limits¶
LimitAccount reads the JSON body's email field, lowercases and trims it, and keys on {KeyPrefix}:{first 16 bytes of SHA-256, hex}, so keys carry no address. The body is restored for the handler. A body without the field passes through and the handler rejects it. Large apps limit both dimensions: the IP limit stops one source spraying many accounts, and the account limit stops many sources hammering one account. Login already has a per-account lockout in the auth service and OTP verify has a per-address attempt budget, so the account limiter is used where neither existed: OTP send.
A signed first-party Worker skips every per-IP limiter too. WorkerAuth runs on the global router, ahead of the /api/v1 baseline and the auth route limiters, and the limiter reads the identity it put on the request context rather than re-verifying. A Worker's egress IP is shared, and the synthetic login probes (every minute, plus a bad-password probe every 5 minutes) would otherwise trip LoginLimit(). Account-keyed limits (LimitAccount) and the login lockout still apply to Workers. An unsigned or invalidly signed request from the same IP is limited as usual.
Internal client IPs (see IP Blocker → Internal addresses) skip every per-IP limiter. When client-IP resolution is broken, all callers collapse onto one internal address, and a per-IP limit on it would throttle the whole app. Per-user limits in the services (OTP attempts per email, login lockout per account, enrichment per user) still apply.
Preset limits¶
RateLimiter exposes these presets (login and OTP limits relax to 100 outside production):
| Method | Key | Limit | Use |
|---|---|---|---|
APILimit() |
IP | 600 / 1m | Baseline ceiling on every /api/v1/* route |
RegisterLimit() |
IP | 5 / 1h | Registration |
LoginLimit() |
IP | 10 / 15m | Login (all variants), WebAuthn login |
OTPLimit() |
IP | 10 / 15m | OTP send and verify (one shared bucket) |
OTPSendAccountLimit() |
5 / 1h | OTP send, per address whatever the source IP | |
ResetPasswordLimit() |
IP | 5 / 1h | Reset-password submission |
DataExportLimit() |
account | 5 / 24h | Personal-data export |
InviteLimit() |
IP | 10 / 1h | Account invite preview, code send and acceptance (works signed out) |
StepUpLimit() |
account | 20 / 15m | Step-up begin and finish, switching into a linked account, linking and unlinking a personal account |
SuspensionReviewLimit() |
IP | 10 / 1h | A suspended member's review request (POST /moderation/review-request) |
ReportLimit() |
account | 20 / 1h | Report filings, review requests and cover photo submissions |
SupportLimit() |
account | 30 / 1h | New support cases and member replies |
GeoCoverUploadLimit() |
account | 10 / 1h | Geo cover photo upload starters |
HelpSuggestLimit() |
IP | 60 / 1m | Help article suggestions |
SupportContactLimit() |
IP | 5 / 1h | The public contact form (fails closed) |
Targeted limiters stack on top of APILimit(): a registration request consumes from both the 600/min baseline and the 5/hour register bucket.
Add new presets in rate_limiter.go rather than passing raw RateLimitConfig from each handler, so the limits stay centrally tunable.
IP blocking and client IP¶
Every IP limiter keys on ClientIP, and the global IP blocker sits ahead of them in the chain. Both are documented on IP Blocker: block list, attack patterns, and trusted proxies. A 429 is never a blocker violation: throttling sheds load on its own, and escalating it to a block would punish users behind a shared carrier NAT.
Adding a new rate-limited endpoint¶
- Add a preset method to
RateLimiterif none of the existing presets fit. - Pass the limiter into the domain's route registrar as a
func(http.Handler) http.Handlergate (routes.go never importsmiddlewaredirectly), then attach it ininternal/wiring/router.go:
// in the domain's routes.go
func RegisterPublicRoutes(r chi.Router, h *Handler, newThingLimit func(http.Handler) http.Handler) {
r.With(newThingLimit).Post("/new-thing", h.NewThing)
}
// in wiring/router.go
foo.RegisterPublicRoutes(r, app.Handlers.FooHandler, app.RateLimiter.LoginLimit())
- Document the limit on API → Auth Endpoints.
Authenticated routes¶
Routes behind JWTAuth aren't rate-limited per-route today. They rely on:
- The auth endpoints' rate limits keeping brute-force off the doorstep
- The global IP blocker, which rejects attack-shaped requests and blocks repeat offenders
- The user being identifiable, so abuse can be tied to an account and dealt with via admin action
If you need a per-user limit on an authenticated route, build a small wrapper that keys on user_id from the JWT context rather than on IP.