Skip to content

fix: an idempotency claim token, so a late complete or fail cannot end another run's claim - #33

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

saintparish4 merged 5 commits into
masterfrom
fix/truth

Conversation

@saintparish4

Copy link
Copy Markdown
Owner

PR 11 of the trust plan: the idempotency claim token, and two small fixes. Five commits.

Changes

  • docs(adr): fence complete and fail with a claim token. ADR-006. A key that expires or fails can be claimed again by the same client, and complete and fail name only the key, so a first run's late call acts on the second run's claim: its complete stores the wrong response, and its fail releases a claim that is still running.
  • fix(storage): complete and fail only the claim that is named. Each winning claim writes a random claimId on the record. storeResponse and markFailed take it as an option; given one, the DynamoDB write adds claimId = :claimId to its condition, and both in-memory stores compare it the same way.
  • fix(api): return claimId from check, and accept it on complete and fail. check answers a claimId with new, and null otherwise. complete takes it in its body; fail, which had no body, takes an optional one. A call naming a claim that has since been replaced answers 409 not_pending.
  • fix(api): carry X-Request-Id on body-decoding and 500 answers. The correlation middleware sat inside the error handling, so the 400, 422 and 500 answers went out without the header.
  • fix(api): report the demo bucket's resetAt on dashboard status. It was always the empty string.

Compatibility

Nothing breaks. claimId is a new field on the check answer, and optional on complete and fail: a request without one behaves as before, including an empty fail.

Known limits

  • A caller that omits claimId keeps the gap ADR-006 describes. Requiring the token is a later decision.
  • The token does not stop the second execution once a TTL lapses mid-operation. It keeps the first run from ending the second run's claim.
  • The correctness run's idempotency invariant sends no claimId, so the token is covered by unit and LocalStack tests only.

Verified locally

  • Unit: 368 passed. Integration: 171 passed.
  • Invariants A-D on a fresh compose stack: PASS, 0 errors.
  • Against the compose stack: a replaced claim's complete answers 409, a bare fail answers 200, a 400 echoes X-Request-Id, and the dashboard status has a real resetAt.
  • Env drift, monitoring check, scalafmtCheckAll. Terraform checks not run: nothing in Terraform changed.

ADR-006. A key that expires or fails can be claimed again by the same client,
and complete and fail name only the key, so a first run's late call acts on
the second run's claim. check returns a claimId on new, and complete and fail
apply only to the claim that was issued the ID they carry. The token is
optional, so existing clients keep working.
A key that expires or fails is claimed again by the same client, so the
record a first run's late complete or fail reaches is the second run's: live,
Pending, and its client's. The ttl condition could not tell them apart.

Each winning claim now gets a random claimId, written on the record and
returned in IdempotencyResult.New. storeResponse and markFailed take it as an
option; given one, the DynamoDB write adds claimId = :claimId to its
condition, and both in-memory stores compare it the same way. Without one
they behave as before (ADR-006).
check answers a claimId with new, and null otherwise: only the caller that
won the claim holds its token. complete takes it in its body; fail, which had
no body, takes an optional one with the single field, so an empty request
still works. A call naming a claim that has since been replaced answers 409
not_pending, and the message says the key was claimed again.

A request without a claimId behaves as before, so no existing client breaks
(ADR-006). The architecture page also said the breaker lets one probe through
at a time; it is up to half-open-max-calls.
The correlation middleware wrapped the routes alone, inside the error
handling. A request whose handler raised never produced a response for it to
stamp, so the 400, 422 and 500 answers went out without X-Request-Id.
Routes.toHttpApp now takes a middleware to apply around the answered routes,
and Main passes the correlation one.
GET /dashboard/api/status answered resetAt as the empty string. It is now the
store's own value, as on /v1/ratelimit/status, and the current time for a
bucket not yet created.
@saintparish4
saintparish4 merged commit 23fb85b 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