40 lines
1.8 KiB
Markdown
40 lines
1.8 KiB
Markdown
# Router · Rate Limiting
|
|
|
|
This page is the module-level dossier for centralized rate limiting in the Router gateway (`StellaOps.Router.Gateway`).
|
|
|
|
## What it is
|
|
- A **gateway responsibility** that applies policy and protects both the Router process and upstream microservices.
|
|
- Configurable by environment, microservice, and (for environment scope) by route.
|
|
- Deterministic outputs and bounded metric cardinality by default.
|
|
|
|
## How it works
|
|
|
|
### Scopes
|
|
- **for_instance**: in-memory sliding window counters (fast path).
|
|
- **for_environment**: Valkey-backed fixed windows (distributed coordination).
|
|
|
|
### Inheritance
|
|
- Environment defaults → microservice override → route override.
|
|
- Replacement semantics: a more-specific `rules` set replaces the parent rules.
|
|
|
|
### Rule stacking
|
|
- Multiple rules on a target are evaluated with AND logic.
|
|
- Denials return the most restrictive `Retry-After` across violated rules.
|
|
|
|
## Operational posture
|
|
- Valkey failures are fail-open (availability over strict enforcement).
|
|
- Activation gate reduces Valkey load at low traffic.
|
|
- Circuit breaker prevents cascading latency when Valkey is degraded.
|
|
|
|
## Migration notes (avoid double-limiting)
|
|
- Prefer centralized enforcement at the Router; remove service-level HTTP limiters after Router limits are validated.
|
|
- Roll out in phases (high limits → soft limits → production limits).
|
|
- If a microservice must keep internal protection (e.g., expensive job submission), ensure it is semantically distinct from HTTP admission control and does not produce conflicting client UX.
|
|
|
|
## Documents
|
|
- Configuration guide: `docs/router/rate-limiting.md`
|
|
- Per-route guide: `docs/router/rate-limiting-routes.md`
|
|
- Ops runbook: `docs/operations/router-rate-limiting.md`
|
|
- Testing: `tests/StellaOps.Router.Gateway.Tests/` and `tests/load/router-rate-limiting-load-test.js`
|
|
|