# 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`