Per-Route Rate Limiting (Router)

This guide explains how to apply per-route rate limits in the Stella Ops Router gateway (StellaOps.Router.Gateway). It is written for platform operators who tune ingress throughput, and assumes you are already familiar with the baseline rate-limiting model in the full configuration guide.

Overview

Per-route rate limiting lets you apply different limits to specific HTTP paths within the same microservice — for example, a strict limit on scan submission while leaving status polling generous.

Configuration is nested under each microservice:

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

Configuration

Example (rules + routes)

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

    # Default environment rules (used when no microservice override exists)
    rules:
      - per_seconds: 60
        max_requests: 600

    microservices:
      scanner:
        # Default rules for the microservice (used when no route override exists)
        rules:
          - per_seconds: 60
            max_requests: 600

        routes:
          scan_submit:
            pattern: "/api/scans"
            match_type: exact
            rules:
              - per_seconds: 10
                max_requests: 50

          scan_status:
            pattern: "/api/scans/*"
            match_type: prefix
            rules:
              - per_seconds: 1
                max_requests: 100

          scan_by_id:
            pattern: "^/api/scans/[a-f0-9-]+$"
            match_type: regex
            rules:
              - per_seconds: 1
                max_requests: 50

Match types

match_type supports:

exact: exact path match (case-insensitive), ignoring a trailing /.
prefix: literal prefix match; patterns commonly end with * (e.g. /api/scans/*).
regex: regular expression (compiled at startup; invalid regex fails fast).

Specificity rules

When multiple routes match a path, the most specific match wins:

exact
prefix (longest prefix wins)
regex (longest pattern wins)

Inheritance (resolution)

Rate limiting rules resolve with replacement semantics:

routes.<route_name>.rules replaces the microservice rules.
microservices.<name>.rules replaces the environment rules.
If a level provides no rules, the next-less-specific level applies.

Notes

Per-route rate limiting applies at the environment scope (Valkey-backed).
The Router returns 429 Too Many Requests and a Retry-After header when a limit is exceeded.