Marc-André Bombeck eddb67975d Publish the idempotency contract the server has honoured all along ...

`withIdempotency` has made writes safe to retry since v1.5.x. It was described
in route comments and in no schema, so an app generated against
`docs/api/openapi.yaml` could not learn that a retry was safe. The iOS side
asked for it; the mechanism does not change, only what it says about itself.

34 operations now declare `Idempotency-Key` and the `X-Idempotent-Replay`
header, plus the 409 that refuses a duplicate still in flight. The description
leads with the one silent failure in the mechanism: a key that misses
`^[A-Za-z0-9_\-:.]{8,128}$` is IGNORED rather than refused, so the write
proceeds unprotected and looks exactly like a request that carried no key.

## What the work turned up

Three things the contract had wrong or missing, none of them the thing being
built:

- `/api/insights/chat` describes `withIdempotency()` in its header comment and
  applies it nowhere. The Coach chat is not retry-safe. Its prose says it is.
- `/api/measurements` exports GET, POST, PUT and DELETE and wraps only POST.
  Publishing the header per PATH would have promised a safe retry on two
  methods that do not honour one — the dangerous direction, so the guard works
  per OPERATION.
- `/api/insights/feedback` and `/api/admin/backups/{id}/restore` are not in the
  document at all. Both are named in the guard's exemption list with a reason,
  not filtered out silently.

## The guard

`idempotency-contract-publication.test.ts` reads the expected set out of the
route tree on every run — nothing is hand-listed, so it cannot fall behind the
code. It fails in both directions: a new wrapped route that forgets to publish,
and a published claim no handler honours.

A fourth assertion checks the exemption list itself is still true. It earned
its place immediately: the first draft exempted the whole `/api/medications`
family on the strength of a grep for path literals that came back empty. The
paths are not written as literals there; the emitted document carries 19 of
them. The test went red, the claim was wrong, the list is two entries now.
Measure the artefact, not the source that builds it.

2026-08-21 18:32:29 +02:00

1.5 MiB

Raw Blame History