Rate Limiting

The ratelimit package provides an in-process token-bucket limiter (Bucket4j-adjacent), trusted-proxy-aware client-IP extraction, and a login throttle decoupled from the rest of the auth stack. A separate Store contract lets a distributed (Redis) fixed-window counter plug in for multi-instance deployments.

Import

import "github.com/thuongh2/go-security/ratelimit"

Token bucket

limiter, err := ratelimit.NewTokenBucketLimiter(ratelimit.Options{
    Capacity:    100,           // burst
    RefillEvery: time.Second,   // 1 token/sec steady state
})

Field	Description
`Capacity`	Max burst a single key may hold (required, > 0).
`RefillEvery`	Interval at which `RefillTokens` are added back (required, > 0).
`RefillTokens`	Tokens restored every `RefillEvery`. Default 1.
`MaxKeys`	Bounds distinct keys held in memory (LRU-evicted). Default 100,000.
`KeyTTL`	Evicts a key idle longer than this. Default 10m.
`Shards`	Locked map shards (rounded up to a power of two). Default 64.
`Clock`	Injectable time source. Default `time.Now`.

TokenBucketLimiter is self-contained — there’s no pluggable Store for it. Memory is bounded internally (LRU + TTL eviction); it needs no backend to run on a single instance.

d := limiter.Allow("ip:203.0.113.7")
if !d.Allowed {
    // d.RetryAfter, d.Remaining, d.Limit
}

HTTP middleware

trusted, err := ratelimit.NewTrustedProxies("10.0.0.0/8", "172.16.0.0/12")

mw := ratelimit.Middleware(ratelimit.Config{
    Limiter: limiter,
    Trusted: trusted,
    FailOpen: true, // a limiter hiccup must not take down the site
})

chain, err := securityhttp.New(
    securityhttp.WithSessionStore(store, users),
    securityhttp.WithRateLimit(ratelimit.Config{Limiter: limiter, Trusted: trusted, FailOpen: true}),
    securityhttp.WithAuthorize(authz.Routes(authz.AnyRequest().PermitAll())),
)

securityhttp.WithRateLimit takes the ratelimit.Config directly (not a bare limiter) — the config is what carries Trusted, FailOpen, and header behavior through to the assembled chain.

Field	Description
`Limiter`	Performs the check (required).
`KeyFunc`	Derives the key from the request. Default `"ip:" + ClientIP(r, Trusted)`.
`Trusted`	Trusted-proxy set used by the default `KeyFunc`.
`OnLimited`	Handler for a denied request. Default: 429.
`FailOpen`	Admit on a limiter error when true (default false — set explicitly).
`SetHeaders`	Emit `X-RateLimit-*` + `Retry-After`. Default false.

Security warning: do not enable SetHeaders on a login/authentication throttle path. Retry-After (and the remaining-count headers) tell an attacker exactly when to resume, turning the throttle into a precise clock for credential stuffing and password spraying. Leave it false on auth endpoints; it’s only appropriate for cooperative API quota signalling.

Response headers

Only these are emitted (when SetHeaders is true) — there is no X-RateLimit-Reset:

Header	Value
`X-RateLimit-Limit`	Configured capacity for the key
`X-RateLimit-Remaining`	Tokens left after this request
`Retry-After`	Set on a 429, whole seconds until retry (rounded up)

Trusted proxies (the spoofing gate)

TrustedProxies is empty by default, which means X-Forwarded-For is ignored entirely and the client IP is always r.RemoteAddr — construct it only for the CIDRs of your actual load balancer / reverse proxy:

trusted, err := ratelimit.NewTrustedProxies("10.0.0.0/8", "172.16.0.0/12")

With trusted proxies configured and the immediate peer trusted, the X-Forwarded-For chain is walked right-to-left, skipping trusted hops, and the first untrusted address is the client. Otherwise it falls back to RemoteAddr. It never trusts the leftmost (attacker-controlled) entry from an untrusted peer. LoginThrottle slows credential stuffing per username+IP composite key without locking accounts — locking is lockout’s job. It deliberately does not import web/auth: you wire it in with Gate (from a custom handler) or Wrap (as middleware fronting the login path).

loginLimiter, err := ratelimit.NewTokenBucketLimiter(ratelimit.Options{
    Capacity: 5, RefillEvery: 3 * time.Minute,
})
throttle, err := ratelimit.NewLoginThrottle(ratelimit.LoginThrottleOptions{
    Limiter: loginLimiter,
    Trusted: trusted,
})

chain, err := securityhttp.New(
    securityhttp.WithSessionStore(store, users),
    securityhttp.WithLogin("/login", manager),
    securityhttp.WithLoginThrottle(throttle),
)

Wrap("username", 4096) peeks the username from a bounded (4096-byte) copy of the request body without consuming it — the body is restored for the downstream login handler, and an oversized body yields 413 rather than buffering unbounded input. For a custom handler, call Gate directly:

d := throttle.Gate(username, r)
if !d.Allowed { /* 429 */ }

Distributed store (Redis)

The in-process TokenBucketLimiter has no distributed mode. For multi-instance deployments, ratelimit.Store is a separate fixed-window contract (IncrAndExpire / Reset) that a Redis adapter implements — it does not plug into TokenBucketLimiter; a fixed-window limiter is a different algorithm chosen because it’s the primitive Redis can implement atomically (INCR + EXPIRE NX in one round trip). The bundled ratelimit.MemoryStore is the in-process reference implementation of this contract. IncrAndExpire must be atomic — a read-then-write increment is a rate-limit-bypass vulnerability (an attacker parallelizes requests to exceed the limit). The exported ratelimit.StoreConformance harness proves an adapter satisfies this:

func TestRedisRateLimitStore(t *testing.T) {
    ratelimit.StoreConformance(t, func() ratelimit.Store { return newRedisStore(t) })
}

See go-security-redis and docs/INTEGRATION.md for the full adapter spec.

Foundation

Authentication

Authorization

Session & Cookies

OAuth2 & JWT

HTTP Layer

Resilience

Observability

Distributed Stores

Import

Token bucket

HTTP middleware

Response headers

Trusted proxies (the spoofing gate)

Distributed store (Redis)

​Import

​Token bucket

​HTTP middleware

​Response headers

​Trusted proxies (the spoofing gate)

​Login throttle

​Distributed store (Redis)

Import

Token bucket

HTTP middleware

Response headers

Trusted proxies (the spoofing gate)

Login throttle

Distributed store (Redis)