Summary
Requests may pass through restRateLimit, createBillingRateLimitMiddleware, gateway per-user token buckets, per-key tiered limits in rateLimiter.ts, quota and credits limiters and login throttling. docs/gateway-rate-limiting.md and docs/tiered-rate-limits.md each describe only one layer.
Why this matters
Clients cannot predict which 429 they hit or which Retry-After applies, and operators misconfigure overlapping limits.
Scope
Add a combined overview in docs/gateway-rate-limiting.md: layer order per route prefix, keying (user, IP, API key), env variables, storage backend and multi-instance behaviour, and response headers.
Relevant code in CalloraOrg/Callora-Backend:
docs/gateway-rate-limiting.mddocs/tiered-rate-limits.mdsrc/middleware/rateLimit.tssrc/services/rateLimiter.ts
Priority
Medium
Acceptance criteria
- Each limiter class/middleware is listed with its env variables
- Order of evaluation per route prefix is documented
- Keying strategy is explicit
- Response headers and error codes are listed
Validation
Cross-check env names with src/config/env.ts during review.
Non-goals
- Typo-only, formatting-only, or cosmetic changes.
- Unrelated refactors, dependency upgrades, or broad rewrites.
- Removing safeguards or weakening validation to make tests pass.
Contributor application
Before coding, describe the affected modules, proposed state/invariant changes, test strategy, compatibility considerations, and an estimate. Wait for assignment before starting implementation.
PR requirements
Use a feature branch and include Closes #<issue-number>. Address every criterion, map criteria to code and tests, explain security and failure-mode handling, and ensure CI passes.
Quality review
A maintainer will assess correctness, completeness, test depth, compatibility, observability, and adverse-case handling. A substantive implementation is required; merge or CI status alone does not guarantee reward eligibility.
Generated by Claude Code
Summary
Requests may pass through restRateLimit, createBillingRateLimitMiddleware, gateway per-user token buckets, per-key tiered limits in rateLimiter.ts, quota and credits limiters and login throttling. docs/gateway-rate-limiting.md and docs/tiered-rate-limits.md each describe only one layer.
Why this matters
Clients cannot predict which 429 they hit or which Retry-After applies, and operators misconfigure overlapping limits.
Scope
Add a combined overview in docs/gateway-rate-limiting.md: layer order per route prefix, keying (user, IP, API key), env variables, storage backend and multi-instance behaviour, and response headers.
Relevant code in CalloraOrg/Callora-Backend:
docs/gateway-rate-limiting.mddocs/tiered-rate-limits.mdsrc/middleware/rateLimit.tssrc/services/rateLimiter.tsPriority
Medium
Acceptance criteria
Validation
Cross-check env names with src/config/env.ts during review.
Non-goals
Contributor application
Before coding, describe the affected modules, proposed state/invariant changes, test strategy, compatibility considerations, and an estimate. Wait for assignment before starting implementation.
PR requirements
Use a feature branch and include
Closes #<issue-number>. Address every criterion, map criteria to code and tests, explain security and failure-mode handling, and ensure CI passes.Quality review
A maintainer will assess correctness, completeness, test depth, compatibility, observability, and adverse-case handling. A substantive implementation is required; merge or CI status alone does not guarantee reward eligibility.
Generated by Claude Code