91 lines
2.5 KiB
Markdown
91 lines
2.5 KiB
Markdown
# 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)
|