git.stella-ops.org/docs/modules/router/rate-limiting.md

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