docs(specs): add S05-B rate limiting

What

Add S05-B: Rate limiting, the S05 Phase 2 increment that delivers the service's shared rate-limiting primitive:

  • a ratelimit-purpose Redis client (redis-ratelimit),
  • a namespace-keyed GCRA limiter wrapping go-redis/redis_rate (the wrapper owns the ar:ratelimit: key grammar),
  • the admission check the Maven virtual-read arm runs after repository resolution and before virtual resolution, with ADR-004's Observe → Warn → Enforce modes, fail-open degradation, and a bounded denial record,
  • a ratelimittest.FakeLimiter test double for consumer refusal-shape tests.

Why

S30's Maven virtual read path answers its 429 row through this primitive, and the mount lands with #1181's plan, which owns the check on all six pull arms; S30's plan drops its Maven-only mount step in !3103 (merged). S05 defers rate-limiting primitives to Phase 2 "per workload demand" — #1181's Beta 429 reports are that demand. The primitive's spec is the merge-order prerequisite for the mount.

Operator decisions recorded in Resolutions

  1. Fail open on every check error, with short redis.ratelimit timeouts and no command retries so a check fails fast.
  2. Import go-redis/redis_rate rather than in-house Lua (ADR-004 names the Container Registry's GCRA pattern).
  3. A dedicated ratelimit purpose client, not the shared cache.
  4. The consumer owns Retry-After; S30 pins its fixed value of 5.
  5. Namespace keying only in this increment; principal and IP keying land with their own consumers and key contracts. This order deviates from ADR-004's IP-first rollout; the deviation is recorded in Resolutions and escalated in handbook MR !21345.

Governing ADRs

  • ADR-004, Rate Limits: conforms on the mechanism (Redis counters, GCRA), the namespace scope, and the Observe → Warn → Enforce phases. Deviation: ADR-004 introduces IP-based limits first and configures all limits in the Observe phase; this increment ships namespace keying only and defers the IP and principal classes. The deviation is recorded in the spec's Resolutions and escalated in handbook MR !21345, which also reconciles the Observe-phase "all limits" sentence, the Warn-phase notification mechanism, and the rate-limit configuration location.
  • ADR-006, Technology Stack: conforms; ratelimit is a Redis dependency under the stack's cache/state section.

Tests

Documentation-only MR: no .go files change, so the test-first authorship flow and a spec-coverage table do not apply (go-testing.md, "The flow does not apply to: Documentation-only MRs"). The spec's Acceptance Criteria state their own test mapping, which the implementation MR carries.

Verified by the repository's documentation hooks (markdownlint, lychee, vale, gitleaks, editorconfig) and the MR pipeline. No e2e scenario is added or affected, and no user documentation changes: the MR ships no runtime behavior.

Size

The diff is 611 changed lines, above the 500-line guideline: 587 insertions and 24 deletions across 6 documentation files.

File group Lines
S05-B spec: docs/specs/S05-b-rate-limiting.md 563
Consumer spec: docs/specs/S30-maven-virtual.md 31
S05 foundation: docs/specs/S05-distributed-state.md, docs/specs/S05-a-cache-abstractions.md 15
Catalogs: docs/specs/S03-b-metrics.md, docs/specs/README.md 2

A split would not help review: the spec is one contract, and the S30, S05, and catalog updates are that contract's cross-references. Splitting would strand them behind an unmerged spec.

Related to #1181

Edited by Moaz Khalifa

Merge request reports

Loading
Loading