Router Rate Limiting

Audience: Stella Ops operators configuring gateway admission control. Scope: How rate limiting behaves, the instance and environment scopes, and the YAML configuration model. For per-route limits, see Per-Route Rate Limiting.

Router rate limiting is a gateway-owned control-plane feature implemented in StellaOps.Router.Gateway. It enforces limits centrally so microservices do not implement ad-hoc HTTP throttling.

Behavior

When a request is denied the Router returns:

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Try again in 12 seconds.",
  "retryAfter": 12,
  "limit": 100,
  "current": 101,
  "window": 60,
  "scope": "environment"
}

Model

Two scopes exist:

Environment checks are gated by an activation threshold (process_back_pressure_when_more_than_per_5min) to avoid unnecessary Valkey calls at low traffic.

Configuration

Configuration is under the rate_limiting root.

Minimal (instance only)

rate_limiting:
  process_back_pressure_when_more_than_per_5min: 5000

  for_instance:
    rules:
      - per_seconds: 60
        max_requests: 600

Environment (Valkey)

rate_limiting:
  process_back_pressure_when_more_than_per_5min: 0  # always check environment

  for_environment:
    valkey_connection: "valkey.stellaops.local:6379"
    valkey_bucket: "stella-router-rate-limit"

    circuit_breaker:
      failure_threshold: 5
      timeout_seconds: 30
      half_open_timeout: 10

    rules:
      - per_seconds: 60
        max_requests: 600

Rule stacking (AND logic)

Multiple rules on the same target are evaluated with AND semantics:

rate_limiting:
  for_environment:
    rules:
      - per_seconds: 1
        max_requests: 10
      - per_seconds: 3600
        max_requests: 3000

If any rule is exceeded the request is denied. The Router returns the most restrictive Retry-After among violated rules.

Microservice overrides

Overrides are replacement, not merge:

rate_limiting:
  for_environment:
    rules:
      - per_seconds: 60
        max_requests: 600

    microservices:
      scanner:
        rules:
          - per_seconds: 10
            max_requests: 50

Route overrides

Route-level configuration is under:

rate_limiting.for_environment.microservices.<microservice>.routes.<route_name>

See Per-Route Rate Limiting for match types and specificity rules.

Notes

Testing