Add rate limiting
A rate limit is a promise about fairness and safety: no single caller can consume the
service, and callers are told how to behave. Decide what you limit (a key), how (an
algorithm), where the counters live (shared, atomic), and what clients see; then test the
boundary exactly, including under concurrent requests. Sources: RFC 6585 (429), RFC
9110 (Retry-After), IETF draft-ietf-httpapi-ratelimit-headers (RateLimit,
RateLimit-Policy), OWASP Authentication and Credential Stuffing Prevention cheat sheets,
Redis documentation on atomic scripts.
Steps
- Name the threat and the key. Credential stuffing, a noisy client, scraping, or a
downstream to protect. The key follows: user id, API key, tenant, IP (weakest: NAT
and IPv6 rotation; use a /64 for IPv6), or a combination. Derive the IP from the
trusted proxy chain only, never a raw client-supplied
X-Forwarded-For. Call
search_lore for existing limiter middleware.
- Choose the algorithm for the behaviour you want. Token bucket / GCRA: bursts up
to capacity, steady refill (most APIs). Sliding-window counter: smooth rate, little
memory. Fixed window: simplest, allows 2× bursts at window edges. Concurrency limit
(semaphore): protects a downstream's capacity, not a rate. Use the repo's, gateway's
or a maintained library's implementation before writing one.
- Share and atomically update the counters. An in-process counter behind a load
balancer is not a limit. Use the shared store with one atomic operation per decision:
a Redis Lua script or
INCR whose returned value is compared, never GET then SET
(concurrent requests all read the same value and all pass). Set the TTL in the same
atomic step: an INCR followed by a separate EXPIRE that fails leaves a key that
never expires, locking the caller out forever. Use the store's clock (Redis TIME)
so instance clock skew cannot widen the window.
- Fail open or closed on purpose. If the store is unavailable: fail open for
ordinary reads (availability), fail closed or fall back to a conservative local limit
for login, password reset, OTP and costly writes. Put a short timeout on the store
call. Comment the decision and test it.
- Tell the client. Reject with
429 and Retry-After (seconds). Emit the repo's
rate-limit headers; if the repo has none, use the current IETF draft fields,
RateLimit-Policy: "default";q=100;w=60 and RateLimit: "default";r=42;t=18, on
successful responses as well as rejections. Retry-After takes precedence over
RateLimit. Legacy X-RateLimit-* headers stay if clients depend on them. Never
leak other tenants' identifiers in a partition key. Document it (the
openapi-contract skill).
- Throttle authentication without enabling lockout abuse. Limit per account and
per source; prefer progressive delays or a challenge over hard account lockout (an
attacker can lock a victim out); return the same response whether or not the account
exists. Never disable a security limit for convenience.
- Check early and cheaply. Run the limiter before expensive work (body parsing,
downstream calls) where the key is available; for authenticated keys, after cheap
token validation. Keep key derivation allocation-free.
- Leave a way out. Allow-lists for internal callers, per-tenant overrides in
config, and a rejection metric by limit name (not by user id; cardinality) with an
alert, so a limit locking out a real customer is seen within minutes.
Tests (injected clock or a tiny configured window; never sleep through a real one)
- Boundary: exactly N requests pass, request N+1 gets
429 with Retry-After and
correct RateLimit values; after the window/refill the next request passes.
- Concurrency: fire N + 20 requests in parallel against the real store (a test
Redis/container) → exactly N succeed (the
concurrency-and-async skill's step 9).
Repeat across two app instances sharing the store → the combined count is still N.
- Failure: store unavailable → the documented fail-open/closed behaviour per
surface; the key always carries a TTL (inspect it after a simulated partial failure).
- Spoofed
X-Forwarded-For from an untrusted hop does not change the key.
- Login: per-account limit trips regardless of source IP; responses identical for
existing and non-existing accounts.
Done when
The tests above pass for the limited surfaces and each acceptance criterion has
evidence via the record-evidence skill.
Review checklist
Capture lore
This skill is one of the places durable, reusable knowledge naturally surfaces:
While placing the limiter you learn which surfaces are limited by which key and whether each fails open or closed when the store is down. That kind of fact is lore. Capture it via the lore-capture
protocol in your brief (CLAUDE.factory.md, step 11 "Memory contribution"):
call the Memory MCP suggest_lore once at the close of your work — reusable
conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.
1---2name: rate-limiting3description: Use when a ticket protects a surface from overload or abuse — per-user or per-key request limits, login-attempt throttling, a quota, backpressure to a downstream, "someone is hammering the API" — and the limit must be correct across instances, communicated to clients, and never lock out legitimate use. Invoke for any throttle, quota, or 429 behaviour.4stack: [node, python, go, java, rust, csharp, kotlin, ruby]5area: backend6metadata:7 source: https://skillmd.com/skills/tmj-90/rate-limiting8---910# Add rate limiting1112A rate limit is a promise about fairness and safety: no single caller can consume the13service, and callers are told how to behave. Decide what you limit (a key), how (an14algorithm), where the counters live (shared, atomic), and what clients see; then test the15boundary exactly, including under concurrent requests. Sources: RFC 6585 (`429`), RFC169110 (`Retry-After`), IETF draft-ietf-httpapi-ratelimit-headers (`RateLimit`,17`RateLimit-Policy`), OWASP Authentication and Credential Stuffing Prevention cheat sheets,18Redis documentation on atomic scripts.1920## Steps21221. **Name the threat and the key.** Credential stuffing, a noisy client, scraping, or a23 downstream to protect. The key follows: user id, API key, tenant, IP (weakest: NAT24 and IPv6 rotation; use a /64 for IPv6), or a combination. Derive the IP from the25 trusted proxy chain only, never a raw client-supplied `X-Forwarded-For`. Call26 `search_lore` for existing limiter middleware.272. **Choose the algorithm for the behaviour you want.** Token bucket / GCRA: bursts up28 to capacity, steady refill (most APIs). Sliding-window counter: smooth rate, little29 memory. Fixed window: simplest, allows 2× bursts at window edges. Concurrency limit30 (semaphore): protects a downstream's capacity, not a rate. Use the repo's, gateway's31 or a maintained library's implementation before writing one.323. **Share and atomically update the counters.** An in-process counter behind a load33 balancer is not a limit. Use the shared store with one atomic operation per decision:34 a Redis Lua script or `INCR` whose returned value is compared, never `GET` then `SET`35 (concurrent requests all read the same value and all pass). Set the TTL in the same36 atomic step: an `INCR` followed by a separate `EXPIRE` that fails leaves a key that37 never expires, locking the caller out forever. Use the store's clock (Redis `TIME`)38 so instance clock skew cannot widen the window.394. **Fail open or closed on purpose.** If the store is unavailable: fail open for40 ordinary reads (availability), fail closed or fall back to a conservative local limit41 for login, password reset, OTP and costly writes. Put a short timeout on the store42 call. Comment the decision and test it.435. **Tell the client.** Reject with `429` and `Retry-After` (seconds). Emit the repo's44 rate-limit headers; if the repo has none, use the current IETF draft fields,45 `RateLimit-Policy: "default";q=100;w=60` and `RateLimit: "default";r=42;t=18`, on46 successful responses as well as rejections. `Retry-After` takes precedence over47 `RateLimit`. Legacy `X-RateLimit-*` headers stay if clients depend on them. Never48 leak other tenants' identifiers in a partition key. Document it (the49 `openapi-contract` skill).506. **Throttle authentication without enabling lockout abuse.** Limit per account and51 per source; prefer progressive delays or a challenge over hard account lockout (an52 attacker can lock a victim out); return the same response whether or not the account53 exists. Never disable a security limit for convenience.547. **Check early and cheaply.** Run the limiter before expensive work (body parsing,55 downstream calls) where the key is available; for authenticated keys, after cheap56 token validation. Keep key derivation allocation-free.578. **Leave a way out.** Allow-lists for internal callers, per-tenant overrides in58 config, and a rejection metric by limit name (not by user id; cardinality) with an59 alert, so a limit locking out a real customer is seen within minutes.6061## Tests (injected clock or a tiny configured window; never sleep through a real one)6263- Boundary: exactly N requests pass, request N+1 gets `429` with `Retry-After` and64 correct `RateLimit` values; after the window/refill the next request passes.65- **Concurrency:** fire N + 20 requests in parallel against the real store (a test66 Redis/container) → exactly N succeed (the `concurrency-and-async` skill's step 9).67 Repeat across two app instances sharing the store → the combined count is still N.68- **Failure:** store unavailable → the documented fail-open/closed behaviour per69 surface; the key always carries a TTL (inspect it after a simulated partial failure).70- Spoofed `X-Forwarded-For` from an untrusted hop does not change the key.71- Login: per-account limit trips regardless of source IP; responses identical for72 existing and non-existing accounts.7374## Done when7576The tests above pass for the limited surfaces and each acceptance criterion has77evidence via the `record-evidence` skill.7879## Review checklist8081- [ ] Threat and key named; IP derived from trusted proxies only.82- [ ] Counters shared; each decision one atomic operation with its TTL.83- [ ] Fail-open/closed decided per surface, commented, tested.84- [ ] `429` + `Retry-After`; rate-limit headers per repo convention or IETF draft.85- [ ] Login throttling fails closed and cannot be used to lock out a victim.86- [ ] A parallel-requests test proves exactly N pass.8788## Capture lore8990This skill is one of the places durable, reusable knowledge naturally surfaces:91**While placing the limiter you learn which surfaces are limited by which key and whether each fails open or closed when the store is down.** That kind of fact is *lore*. Capture it via the **lore-capture92protocol in your brief** (`CLAUDE.factory.md`, step 11 "Memory contribution"):93call the Memory MCP `suggest_lore` once at the close of your work — reusable94conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.