Skip to content

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:

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() email 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

  1. Add a preset method to RateLimiter if none of the existing presets fit.
  2. Pass the limiter into the domain's route registrar as a func(http.Handler) http.Handler gate (routes.go never imports middleware directly), then attach it in internal/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())
  1. 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.