feat(rateLimit): rate limit headers and retryAfter - #82

Summary

rateLimit rejects with TooManyRequests, but a client can't tell when to try again or how close it is to the limit. Providers like GitHub, OpenAI or IONOS answer with Retry-After and rate limit headers; this adds the same, opt-in.

• headers option (default false): sets the limit on context.http.headers for REST clients.
  • 'legacy': X-RateLimit-Limit, -Remaining, -Reset (epoch seconds).
  • 'draft-6', 'draft-7', 'draft-8': that version of the IETF RateLimit header fields draft, in the formats of express-rate-limit's standardHeaders.
  • A function (info, context) => headers for a scheme of your own, e.g. X-RateLimit-Remaining-Requests. info is { limit, remaining, reset, window, limited }.
• On a rejection, Retry-After is added and the headers also go on error.data.headers. Feathers' REST error handlers (Express and Koa, checked against v5.0.53) send only the error's status and body, not the headers hooks set, so the docs show the middleware that sends them.
• error.data.retryAfter (seconds) on every rejection, with or without headers, so socket clients get it too. Socket.io has no standard for this; retryAfter keeps the name and unit of the HTTP header.
• A limiter store that fails with an error instead of a RateLimiterRes still throws TooManyRequests, without headers.

No breaking change: without headers, the only difference is the added data.retryAfter.

Security note

The docs say to send headers only where the bucket is the caller's own (per user or IP). On a shared bucket (a static key or the default context.path), remaining tells every caller how much everyone else is calling. On a login or another brute-force target, the headers help an attacker pace just under the limit.

error.data.rateLimitRes already exposes the same points to clients today, since data is serialized with the error. A TODO(next major) marks dropping it from the error; it stays on context.params.rateLimit for the server.

Other Information

• Tests for every format, a custom function, headers and Retry-After on a rejection, retryAfter without headers, and no headers by default. The full suite passes; the hook is at 97% coverage.
• Docs are in rate-limit.hook.md and the option's JSDoc (rendered by the docs site); no separate docs PR.

🤖 Generated with Claude Code