Skip to content

fix: one error shape on every route, and answers that say when they are degraded - #32

Merged
saintparish4 merged 4 commits into
masterfrom
fix/truth
Oct 1, 2026
Merged

saintparish4 merged 4 commits into
masterfrom
fix/truth

Conversation

@saintparish4

Copy link
Copy Markdown
Owner

PR 9 of the trust plan: API consistency. Four commits, one per finding.

Changes

  • fix(api): one error shape, and say when an answer is degraded. Every answer that is not a 2xx now carries {"error": code, "message": text}. There were five shapes: an empty 401, the auth throttle's {"error":"Rate limited","retryAfter":N}, a dashboard 400 with only error, plain text for an undecodable body or an unknown path, and two different 503 bodies on quota check. Routes.toHttpApp builds the app for Main and the tests, replacing http4s' plain-text handlers. A degraded check is marked: X-Gate-Degraded: true in both modes, error: "degraded" on the reject-all 429, and the profile's capacity rather than a fixed 100 on the allow-all 200. /ready's 503 stays the health document.
  • fix(api): compute status resetAt per algorithm, from Clock. GET /v1/ratelimit/status recomputed resetAt with the token-bucket formula under every algorithm. It now repeats the store's own value. A never-seen key read Instant.now() plus 60 s; it is full, so it resets now.
  • test: make the untestable tests fail, and fix stale comments. The quota-disabled 404 test asserted on an inline copy of the route's match; it now goes through Routes. half-open-max-calls did nothing, because a single-permit semaphore let one probe run at a time: the move to half-open and the claim of a probe slot are now one state update, and a cancelled probe returns its slot. Two comments that disagreed with the code are corrected.
  • fix(storage): refuse complete and fail on an expired record. A late complete on a lapsed claim answered "completed", though the next check claims the key afresh and never replays what was stored. Both calls now require a live record, in the DynamoDB store and both in-memory ones, and the route answers 409.

Body changes a client can see

Most only add a field, or give a body to an answer that was empty or plain text. Two change an existing value:

  • the auth 429's error is "rate_limited", not "Rate limited" (retryAfter is unchanged);
  • quota check's contended 503 is {"error": "contended", "message": ...}, without allowed: false.

docs/API.md lists every code.

Known limit

The expiry condition does not separate a reclaimed key's first owner from its second: both are the same client, so a late complete or fail after a reclaim still acts on the new claim. That needs a claim token, which is the next PR.

Verified locally

  • Unit: 355 passed. Integration: 164 passed.
  • Invariants A-D on a fresh compose stack: PASS, 0 errors.
  • Against the compose stack: a request with no key answers the JSON 401, and a body that is not JSON answers the JSON 400.
  • Env drift, monitoring check, scalafmtCheckAll. Terraform checks not run: nothing in Terraform changed.

Every answer that is not a 2xx now carries {"error": code, "message": text}.
There were five shapes: an empty 401, the auth throttle's
{"error":"Rate limited","retryAfter":N}, a dashboard 400 with only error,
plain text for an undecodable body or an unknown path, and two different 503
bodies on quota check.

- The 401, the auth 429 (retryAfter kept beside the two fields), the 404s and
  the body-decoding 400/422 answer in the error shape. Routes.toHttpApp builds
  the app for Main and the tests, replacing http4s' plain-text handlers.
- The decision bodies (rate-limit 429, quota 429, idempotency 409s) gain an
  error field next to the message they already had.
- A degraded check is marked: X-Gate-Degraded: true in both modes, error
  "degraded" on the reject-all 429, and the profile's capacity rather than a
  fixed 100 on the allow-all 200.
GET /v1/ratelimit/status recomputed resetAt from tokensRemaining with the
token-bucket formula under every algorithm, rounded up to a second, so a leaky
bucket or a sliding window reported a reset its own check would not honor. It
now repeats the store's resetAt. A never-seen key read Instant.now() plus 60 s;
it is full, so it resets now, by the effect clock.

RateLimitStatusResetSpec runs each real store over a fixed item under
TestControl and requires the route to answer that store's value.
- TokenQuotaApiSpec's "404 when token-quota is disabled" asserted on an inline
  copy of the route's match, so it passed whatever Routes did. It now drives
  both quota routes through Routes with no quota API wired.
- half-open-max-calls did nothing: a single-permit semaphore let one probe run
  at a time, and each caller that saw the reset timeout pass set the probe
  count back to zero. The transition and the slot claim are now one state
  update, a late probe cannot undo another's outcome, and a cancelled probe
  hands its slot back. CircuitBreakerHalfOpenSpec admits exactly
  halfOpenMaxCalls probes.
- KinesisPublisher called a drop-oldest queue back-pressure, and
  DynamoDBRateLimitStore described a retry loop it does not have.
Since expiry is checked on claim and read, an expired key is claimable at
once, but storeResponse and markFailed still ignored the ttl. A late complete
on a lapsed claim answered "completed", though the next check claims the key
afresh and never replays what was stored. Both now require the record to be
live, in the DynamoDB store and both in-memory ones, and the route answers 409.

This does not separate a reclaimed key's first owner from its second: both are
the same client, so a late complete after a reclaim still completes the new
claim. Telling them apart needs a claim token the API does not carry; the
store's Scaladoc, a test, and the client guidance say so.
@saintparish4
saintparish4 merged commit 5d20409 into master Oct 1, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant