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

```yaml
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)