work work hard work

docs/router/rate-limiting-routes.md

@@ -0,0 +1,90 @@
+# 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)