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

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"