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.FakeLimitertest 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
- Fail open on every check error, with short
redis.ratelimittimeouts and no command retries so a check fails fast. - Import
go-redis/redis_raterather than in-house Lua (ADR-004 names the Container Registry's GCRA pattern). - A dedicated
ratelimitpurpose client, not the sharedcache. - The consumer owns
Retry-After; S30 pins its fixed value of5. - 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;
ratelimitis 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