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

Per-Route Rate Limiting (Router)

This document describes per-route rate limiting configuration for the Router gateway (StellaOps.Router.Gateway).

Overview

Per-route rate limiting lets you apply different limits to specific HTTP paths within the same microservice.

Configuration is nested as:

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:

1. exact
2. prefix (longest prefix wins)
3. 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.

See also

• docs/router/rate-limiting.md (full configuration guide)
• docs/modules/router/rate-limiting.md (module dossier)