Initial Commit

openspec/specs/api-rate-limit/spec.md

@@ -0,0 +1,88 @@
+<!-- markdownlint-disable MD024 -->
+
+# Capability Spec Delta: api-rate-limit (api-rate-limit)
+
+**Package**: `@suaveplan/api-rate-limit`
+**Status**: PROPOSED
+
+> Every requirement below carries a `**Verified by:**` line at authoring time.
+
+## ADDED Requirements
+
+### Requirement: Token-bucket gate with route-declared rpm and burst
+
+The package SHALL produce a `Middleware` enforcing a token bucket per key, parametrised by the route's `rateLimit.rpm` and `rateLimit.burst`. The bucket SHALL refill at `rpm/60` tokens per second up to `burst` tokens. Each request consumes one token; an empty bucket returns 429 with a `Retry-After` header equal to the refill ETA in seconds.
+
+#### Scenario: burst window allows N requests
+
+- WHEN a route declares `rpm: 60, burst: 5` and 5 requests arrive within 100ms for the same key
+- THEN all 5 requests pass
+
+#### Scenario: 6th request in burst window is rejected
+
+- WHEN a 6th request arrives in the same 100ms window
+- THEN the response is 429 with `Retry-After` set to a positive integer AND `api.rate_limit.exceeded_total{key_kind}` increments by 1
+
+**Verified by:** `src/middleware/middleware.test.ts::"burst window allows N requests"` AND `src/middleware/middleware.test.ts::"sixth request in burst window is rejected with Retry-After"`
+
+---
+
+### Requirement: Refill is deterministic against a FakeClock
+
+The package SHALL refill the bucket based on the supplied `Clock`. Advancing the clock by 1 second on an empty bucket with `rpm: 60` MUST restore exactly 1 token.
+
+#### Scenario: clock advance refills tokens
+
+- WHEN the bucket is empty and `clock.advance("1s")` runs
+- THEN the next request consuming 1 token succeeds
+
+**Verified by:** `src/middleware/middleware.test.ts::"clock advance refills tokens deterministically"`
+
+---
+
+### Requirement: Key selector resolves per route
+
+The package SHALL resolve the rate-limit key from the route's `rateLimit.key` option. Selector kinds: `"tenant"`, `"principal"`, `"ip"`, and `{ kind: "custom", select }`. When the route does not specify a kind, the default is `"principal"` if a principal is resolved, else `"ip"`.
+
+#### Scenario: tenant key isolates buckets
+
+- WHEN two requests with different `tenantId` hit a route declaring `key: "tenant"`
+- THEN each tenant has its own bucket AND neither affects the other
+
+#### Scenario: default falls back to IP when no principal
+
+- WHEN no principal is resolved AND the route does not specify a key
+- THEN the IP address is used
+
+**Verified by:** `src/selector/selector.test.ts::"tenant key isolates buckets"` AND `src/selector/selector.test.ts::"default falls back to IP without principal"`
+
+---
+
+### Requirement: Denial counter increments only on the denial transition
+
+The package SHALL increment `api.rate_limit.exceeded_total` once per denied request — every denied request contributes one increment. The counter MUST be labelled with `plugin`, `route`, and `key_kind`.
+
+#### Scenario: each denied request increments by exactly 1
+
+- WHEN 10 requests are denied for the same key within the same window
+- THEN the counter increases by exactly 10 AND each increment carries the correct label set
+
+**Verified by:** `src/middleware/middleware.spec-conformance.test.ts::"denial increments api.rate_limit.exceeded_total exactly once per denied request"`
+
+---
+
+### Requirement: Host-level defaults override route declarations cleanly
+
+The package SHALL accept default budgets from `host.json` (per-tenant default rpm/burst, per-IP default rpm/burst). Route-declared budgets MUST override the defaults. When a route declares no `rateLimit` and no host default applies, the middleware is a no-op.
+
+#### Scenario: route override beats host default
+
+- WHEN a host default is `rpm: 100` and a route declares `rpm: 10`
+- THEN the route's limit (10) applies to that route
+
+#### Scenario: no declaration, no host default → no-op
+
+- WHEN neither route nor host declares a budget
+- THEN the middleware passes the request through without checking any bucket
+
+**Verified by:** `src/middleware/middleware.test.ts::"route override beats host default"` AND `src/middleware/middleware.test.ts::"no-op when neither route nor host declares"`