Deprecate spoofable RealIP rate-limiting; add LimitBy + KeyFromContext and modernize the key API

[VojtechVitek]

Summary

KeyByRealIP — and LimitByRealIP / WithKeyByRealIP built on it — derive the rate-limit key from client-supplied headers (True-Client-IP, X-Real-IP, X-Forwarded-For) with no proxy-trust check. A remote attacker can forge the key to either:

• Evade the limit — rotate the spoofed header → unbounded buckets, limit defeated; or
• Lock out a victim — pin the header to the victim's IP → exhaust their bucket and 429 them out.

This is the same class of flaw fixed in chi's middleware.RealIP in v5.3.0 (GHSA-9g5q-2w5x-hmxf, GHSA-rjr7-jggh-pgcp, GHSA-3fxj-6jh8-hvhx).

This PR closes the spoofing hole and modernizes the key API around a single, explicit-trust pattern. All deprecated functions keep compiling (doc-only // Deprecated:). httprate has not reached a stable v1, so the deprecated surface may be removed in a future release.

New (supported) API

• LimitBy(requestLimit, windowLength, keyFn, opts...) — canonical entry point; the key is a required positional argument, so every call site states what it limits by.
• KeyFromContext(func(context.Context) string) — reads the key from the request context. Pairs with chi's middleware.GetClientIP (chi v5.3.0+), fed by one of the middleware.ClientIPFrom* middlewares. Generic over the extractor, so non-chi frameworks work too.
• JoinKeys(...KeyFunc) — :-joined multi-dimensional key for LimitBy (the positional-arg equivalent of WithKeyFuncs).

Recommended pattern (rate-limit by trusted client IP)

// Pick exactly ONE chi ClientIPFrom* matching your deployment:
r.Use(middleware.ClientIPFromXFF("10.0.0.0/8"))
// Then rate-limit by the trusted client IP:
r.Use(httprate.LimitBy(100, time.Minute, httprate.KeyFromContext(middleware.GetClientIP)))

There is no safe default IP source — you state your trust model explicitly. If no ClientIPFrom* runs upstream, GetClientIP returns "" and all requests share one global bucket (strictly more restrictive — a footgun, not a security regression).

Deprecations

Security (spoofable — the GHSA):

• KeyByRealIP, WithKeyByRealIP, LimitByRealIP

Footguns / ergonomics (NOT security):

• KeyByIP / WithKeyByIP — key off r.RemoteAddr. Not spoofable, but behind a reverse proxy / LB / CDN that's the proxy's address, so every client behind a proxy shares one bucket — usually the wrong key in production. Use middleware.ClientIPFromRemoteAddr + KeyFromContext(GetClientIP) for the directly-exposed case.
• LimitByIP — superseded by the above.
• Limit → LimitBy(n, t, keyFn, opts...); LimitAll → LimitBy(n, t, Key("*")).

The whole deprecated surface is grouped in deprecated.go. Limit/LimitAll/LimitByIP/LimitByRealIP now delegate to LimitBy, mirroring their documented migration.

Docs / examples / tests / CI

• README: security banner with GHSA links; a "Rate limit by client IP behind a proxy" section with the chi ClientIPFrom* picker; all examples moved to LimitBy.
• _example: runnable demo of both the directly-exposed and behind-a-proxy patterns; chi bumped v5.1.0 → v5.3.0.
• Tests: chi-free unit tests in the root module (KeyFromContext, JoinKeys, and a KeyByRealIP spoof-regression); the chi integration tests that prove the spoof is closed live in the _example submodule. The main module's go.mod stays chi-free; CI runs both modules' tests.

Test plan

• go test ./... passes in the root module.
• cd _example && go test ./... passes (chi integration: RemoteAddr happy path, spoofed-XFF fix-in-action, misconfig single-bucket).
• go vet + gofmt clean in both modules.

Credits

Cross-references the chi advisories above; thanks to @convto, @rezmoss, and @Saku0512 for the original reports.

Fixes #53

[VojtechVitek]

Review — approve ✅

Traced the change end-to-end against the goals in the description; it's correct, behavior-preserving, and well-tested. Notes below.

Security fix is sound

I checked chi v5.3.0's ClientIPFromXFF: it walks X-Forwarded-For right-to-left, skips trusted-CIDR hops, and returns the rightmost non-trusted IP (fail-closed). So in TestLimitByClientIP_SpoofedXFF the trusted proxy appends the attacker's real 203.0.113.5 as the rightmost entry, and the key stays constant no matter what the attacker forges on the left. The test genuinely proves the spoof is closed, not just that the wiring runs.

No behavior change in the deprecated delegations

NewRateLimiter defaults keyFn to Key("*") when none is set, so the rewrites all reduce to the exact same keyFn as before:

• Limit(n, t, opts...) → LimitBy(n, t, Key("*"), opts...) — identical, and a WithKeyFuncs in opts still overrides (LimitBy prepends its key option).
• LimitAll → Key("*"), LimitByIP → KeyByIP, LimitByRealIP → KeyByRealIP.
• JoinKeys is a verbatim rename of composedKeyFunc (trailing-: join format preserved).

go build / go test / go vet / gofmt clean in both modules; CI now runs the _example integration tests too.

One doc fix pushed

The LimitBy and JoinKeys godoc examples showcased JoinKeys(KeyByIP, KeyByEndpoint) — but this PR deprecates KeyByIP, so copy-pasting them tripped a deprecation warning and contradicted the PR's own guidance. Switched the example to KeyFromContext(middleware.GetClientIP) to match the README.

Optional, non-blocking

• deprecated.go canonicalizeIP has an ineffective break inside a switch (breaks the switch, not the loop). Harmless — the !isIPv6 loop condition terminates correctly — and it's verbatim from the original httprate.go, now living in deprecated-only code. Fine to leave; trivial to drop for a clean staticcheck pass.
• LimitBy + a WithKeyFuncs in the trailing options silently lets the option override the positional key. Reasonable (mirrors Limit), just worth being aware of.

Nice, precise cleanup of the key API. 👍

---

Automated by Claude Opus 4.8.

[github-actions]

Benchmark Results

goos: linux
goarch: amd64
pkg: github.com/go-chi/httprate
cpu: AMD EPYC 7763 64-Core Processor                
               │ master.txt  │            pr.txt             │
               │   sec/op    │   sec/op     vs base          │
LocalCounter-4   20.05m ± 2%   19.95m ± 1%  ~ (p=0.143 n=10)

               │  master.txt  │             pr.txt             │
               │     B/op     │     B/op      vs base          │
LocalCounter-4   2.850Mi ± 0%   2.847Mi ± 0%  ~ (p=0.529 n=10)

               │ master.txt  │            pr.txt             │
               │  allocs/op  │  allocs/op   vs base          │
LocalCounter-4   121.5k ± 0%   121.5k ± 0%  ~ (p=0.542 n=10)

[Max12345-ally]

LGTM
see some thoughts

[github-actions]

Benchmark Results

goos: linux
goarch: amd64
pkg: github.com/go-chi/httprate
cpu: AMD EPYC 9V74 80-Core Processor                
               │ master.txt  │            pr.txt             │
               │   sec/op    │   sec/op     vs base          │
LocalCounter-4   15.82m ± 1%   15.72m ± 2%  ~ (p=0.247 n=10)

               │  master.txt  │             pr.txt             │
               │     B/op     │     B/op      vs base          │
LocalCounter-4   2.842Mi ± 0%   2.842Mi ± 0%  ~ (p=0.684 n=10)

               │ master.txt  │            pr.txt             │
               │  allocs/op  │  allocs/op   vs base          │
LocalCounter-4   121.4k ± 0%   121.5k ± 0%  ~ (p=0.566 n=10)