Rate limiting DX: promote common recipes to first-class helpers? (follow-up to #38/#39)

Context

#38 / #39 fixed the proxy-identity footgun the right way: ip_identifier stays on request.client.host, ASGI owns XFF, CannotIdentifyClient replaces the shared "unknown" bucket.

This is a follow-up discussion from migrating a richer FastAPI Redis limiter (ArchiPy, now deprecated toward this SDK). Algorithm + identity model are in good shape. Remaining gaps are mostly DX: patterns the guide already shows as recipes, that apps re-copy.

Not asking to reverse #39. Not asking for JWT/auth coupling or query-param keying in core.

What the guide already covers well

Need	Today
Behind a proxy (Uvicorn)	--proxy-headers + --forwarded-allow-ips
Servers without proxy support	Inline proxied_ip_identifier recipe (peer gate + right→left)
CDN single-value headers	Tip: keep in app identifier
Burst + sustained	Recipe via RateLimitBackend / stacked deps
Custom identity	identifier= + header_identifier example
Bypass some traffic	skip_when=

Possible promotions (please weigh)

1. Ship proxied_ip_identifier(trusted_proxies=...) as a public helper

The “Servers without proxy-header support” snippet is ~20 lines every non-Uvicorn app will copy. A tested helper would:

• take trusted_proxies: Sequence[str | IPv4Network | IPv6Network]
• gate on peer, walk XFF right→left (same rules as the doc / Uvicorn)
• raise CannotIdentifyClient when peer/client missing
• stay opt-in via identifier= — default ip_identifier unchanged

Ask: worth a first-class export, or keep as docs-only to avoid re-owning proxy logic?

2. Convenience for method skips (e.g. CORS OPTIONS)

Common pattern from the prior limiter: skip OPTIONS by default or via config.

Today:

skip_when=lambda r: r.method == "OPTIONS"

Possible sugar: skip_methods={"OPTIONS"} on rate_limit() / global limiter, composed with skip_when if both set.

Ask: useful API, or too thin on top of skip_when?

3. Multi-window / burst+sustained helper

Guide already has a backend recipe. Prior API used stacked windows on one dependency.

Possible DX:

dependencies=rate_limits("10/second", "1000/hour")  # → list[Depends]
# or
Depends(rate_limit("10/second", scope="burst")),
Depends(rate_limit("1000/hour", scope="sustained")),

Second form already works; first is sugar + distinct auto-scopes.

Ask: helper worth it, or docs example of two Depends enough?

4. Docs-only (no API)

If 1–3 stay out of core, still useful guide additions from migration experience:

• Skip CORS preflight with skip_when
• Prefer authenticated identifier over IP when available (sketch only — no JWT dependency)
• Migration note: stacked Depends replaces “additional windows”

Explicit non-goals

• Parsing XFF inside default ip_identifier (settled in #39)
• Built-in JWT / session helpers
• Query-param dimensional Redis keys
• Changing fail-open default
• New algorithms (sliding window / token bucket)

Asks

1. Any of 1 / 2 / 3 interesting for pre-1.0, or keep everything as recipes?
2. If only one: which has the best cost/benefit?
3. Prefer a focused follow-up PR after you pick, vs leave this as tracking / docs-only?

Happy to help with whichever subset you want — discussion only for now, no PR attached.

Start with the guide’s proxy, skip_when, identifier, and stacked Depends recipes, then inspect the existing rate_limit and ip_identifier APIs referenced in the issue. Compare the proposed helpers’ scope and maintenance cost; done means selecting a focused pre-1.0 direction, rather than implementing a change while the discussion remains undecided.