mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-18 08:02:12 +00:00
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.
This commit is contained in:
1 parent
b8a0aead7f
commit
eddb67975d
22 files changed
+753
-237
No files matched your search
@@ -27,6 +27,8 @@ import {
|
||||
import {
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
} from "./shared";
|
||||
@@ -102,11 +104,13 @@ export const allergyPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
summary: "Record an allergy (v1.25)",
|
||||
description:
|
||||
"Creates one allergy/intolerance record for the caller. The free-text reaction + note are AES-256-GCM encrypted before write. Audits as `allergy.create`.",
|
||||
parameters: [idempotencyKeyParameter],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: { "application/json": { schema: allergyCreateSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"201": {
|
||||
description: "Allergy created.",
|
||||
|
||||
@@ -22,6 +22,8 @@ import {
|
||||
import {
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
} from "./shared";
|
||||
@@ -101,11 +103,13 @@ export const biomarkerPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
summary: "Define a biomarker",
|
||||
description:
|
||||
"Creates a user-scoped biomarker. The optional context note is AES-256-GCM encrypted before write. Audits as `biomarker.create`.",
|
||||
parameters: [idempotencyKeyParameter],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: { "application/json": { schema: createBiomarkerSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"201": {
|
||||
description: "Created biomarker.",
|
||||
|
||||
@@ -50,6 +50,8 @@ import {
|
||||
conflictResponse409,
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
invalidBaseTokenResponse,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
@@ -1285,6 +1287,7 @@ export const coachPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
summary: "Create an anamnesis fact",
|
||||
description:
|
||||
"Creates the first current revision for one closed fact kind. The answer is encrypted before persistence. A second current value for the same kind returns 409; corrections use the revision endpoint.",
|
||||
parameters: [idempotencyKeyParameter],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
@@ -1292,6 +1295,7 @@ export const coachPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"201": {
|
||||
description: "The newly created current revision.",
|
||||
content: {
|
||||
|
||||
@@ -24,6 +24,8 @@ import {
|
||||
import {
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
} from "./shared";
|
||||
@@ -159,11 +161,13 @@ export const customMetricPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
summary: "Define a custom metric",
|
||||
description:
|
||||
"Creates a user-scoped custom metric. Re-creating a name that was previously soft-deleted revives that definition. Audits as `customMetric.create`.",
|
||||
parameters: [idempotencyKeyParameter],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: { "application/json": { schema: createCustomMetricSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"201": {
|
||||
description: "Created custom metric.",
|
||||
content: {
|
||||
@@ -288,6 +292,7 @@ export const customMetricPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
description:
|
||||
"Records a value against the custom metric, snapshotting the metric's unit. Audits as `customMetricEntry.create`.",
|
||||
requestParams: { path: z.object({ id: z.string() }) },
|
||||
parameters: [idempotencyKeyParameter],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
@@ -295,6 +300,7 @@ export const customMetricPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"201": {
|
||||
description: "Created value.",
|
||||
content: {
|
||||
|
||||
@@ -27,6 +27,8 @@ import {
|
||||
import {
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
} from "./shared";
|
||||
@@ -461,11 +463,13 @@ export const cyclePaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
summary: "Capture a single cycle day-log (v1.15.0)",
|
||||
description:
|
||||
"Upserts on `(userId, source, externalId)` when externalId present, else `(userId, date)`. `note` encrypts at rest. 201 on insert, 200 on update. Gated: `cycle.disabled` 403 when the feature is off.",
|
||||
parameters: [idempotencyKeyParameter],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: { "application/json": { schema: cycleDayLogInputSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"200": {
|
||||
description: "Existing day-log updated.",
|
||||
content: {
|
||||
@@ -541,11 +545,13 @@ export const cyclePaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
summary: "Bulk drain cycle day-logs (Outbox / HealthKit) (v1.15.0)",
|
||||
description:
|
||||
"Up to 500 entries; `withIdempotency`; rate-limited `cycle:day-logs:bulk:<userId>` 60/min. Per-entry status: inserted | duplicate | updated | skipped. Always 200.",
|
||||
parameters: [idempotencyKeyParameter],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: { "application/json": { schema: cycleBulkSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"200": {
|
||||
description: "Batch processed (per-entry results).",
|
||||
content: {
|
||||
@@ -565,11 +571,13 @@ export const cyclePaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
summary: "Period-boundary shortcut (v1.15.0)",
|
||||
description:
|
||||
"One-tap started/ended period. `start` opens a new cycle (closing the prior); `end` stamps periodEndDate. Writes the boundary day-log. Gated.",
|
||||
parameters: [idempotencyKeyParameter],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: { "application/json": { schema: cyclePeriodSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"200": {
|
||||
description: "Cycle + boundary day-log.",
|
||||
content: {
|
||||
|
||||
@@ -31,6 +31,8 @@ import {
|
||||
import {
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
} from "./shared";
|
||||
@@ -359,6 +361,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Documents"],
|
||||
summary: "Store a document (no extraction)",
|
||||
description:
|
||||
@@ -397,6 +400,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"200": {
|
||||
description:
|
||||
"Duplicate — the same bytes are already stored: the existing row, with `meta.duplicate: true` at the envelope level.",
|
||||
@@ -1096,6 +1100,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
description:
|
||||
"The ONLY write path out of staging. Commits the user's approvals into the structured stores (labs / conditions / medications) and discards rejections. A low-confidence fact that was never edited cannot be approved (fail-closed). Idempotent (Idempotency-Key). Audits as `documents.inbound.confirm`.",
|
||||
parameters: [
|
||||
idempotencyKeyParameter,
|
||||
{
|
||||
name: "id",
|
||||
in: "path",
|
||||
@@ -1108,6 +1113,7 @@ export const inboundDocumentPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
content: { "application/json": { schema: inboundConfirmSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"200": {
|
||||
description: "Per-decision outcome.",
|
||||
content: {
|
||||
|
||||
@@ -35,6 +35,8 @@ import {
|
||||
import {
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
} from "./shared";
|
||||
@@ -246,6 +248,7 @@ export const encounterPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Records"],
|
||||
summary: "File or book a visit",
|
||||
description:
|
||||
@@ -255,6 +258,7 @@ export const encounterPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
content: { "application/json": { schema: encounterCreateSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"201": {
|
||||
description: "Visit filed.",
|
||||
@@ -467,6 +471,7 @@ export const encounterPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Records"],
|
||||
summary: "Add a practitioner",
|
||||
description:
|
||||
@@ -476,6 +481,7 @@ export const encounterPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
content: { "application/json": { schema: practitionerCreateSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"201": {
|
||||
description: "Practitioner added.",
|
||||
|
||||
@@ -24,6 +24,8 @@ import {
|
||||
import {
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
} from "./shared";
|
||||
@@ -98,6 +100,7 @@ export const familyHistoryPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
summary: "Record a family-history entry (v1.25)",
|
||||
description:
|
||||
"Creates one condition-by-relative record for the caller. The free-text note is AES-256-GCM encrypted before write. Audits as `family-history.create`.",
|
||||
parameters: [idempotencyKeyParameter],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
@@ -105,6 +108,7 @@ export const familyHistoryPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"201": {
|
||||
description: "Entry created.",
|
||||
|
||||
@@ -32,6 +32,8 @@ import {
|
||||
import {
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
} from "./shared";
|
||||
@@ -318,6 +320,7 @@ export const illnessPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
summary: "Open an illness episode (v1.18.1)",
|
||||
description:
|
||||
"Creates one episode for the caller. `onsetAt` defaults to 'now' when omitted; the optional note is AES-256-GCM encrypted before write. A `parentConditionId` must reference an owned, live episode. Audits as `illness.episode.create`. Born-gated.",
|
||||
parameters: [idempotencyKeyParameter],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
@@ -325,6 +328,7 @@ export const illnessPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"201": {
|
||||
description: "Episode created.",
|
||||
@@ -422,7 +426,9 @@ export const illnessPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
description:
|
||||
"Clears `deletedAt`, bringing the episode and its preserved day-logs + encrypted note back into every read. A soft-delete keeps the row and children intact, so restore is a pure flag flip — nothing is re-created (the delete-Undo affordance). Idempotent — restoring a live episode is a no-op. Audits as `illness.episode.restore`. Owner-scoped + born-gated.",
|
||||
requestParams: { path: z.object({ id: z.string() }) },
|
||||
parameters: [idempotencyKeyParameter],
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"200": {
|
||||
description: "Episode restored.",
|
||||
|
||||
@@ -19,6 +19,8 @@ import {
|
||||
import {
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
} from "./shared";
|
||||
@@ -139,11 +141,13 @@ export const labsPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
summary: "Record a lab result",
|
||||
description:
|
||||
'Creates a single lab result for the caller. The optional `source` marks provenance (`"MANUAL"` | `"OCR"`); it defaults to `"MANUAL"` when omitted, so the legacy hand-entry contract is unchanged. The on-device-OCR client posts `"OCR"` after the human confirms the parsed values — the raw image never touches the server on this path. The optional note is AES-256-GCM encrypted before write. Audits as `labResult.create`.',
|
||||
parameters: [idempotencyKeyParameter],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: { "application/json": { schema: createLabResultSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"201": {
|
||||
description: "Created lab result.",
|
||||
@@ -232,6 +236,7 @@ export const labsPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
summary: "Restore soft-deleted lab results",
|
||||
description:
|
||||
"Un-tombstones 1..200 of the caller's soft-deleted lab results in one pass (the delete-Undo affordance). A foreign / live id is a silent no-op. Audits via the wide-event ledger.",
|
||||
parameters: [idempotencyKeyParameter],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
@@ -243,6 +248,7 @@ export const labsPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"200": {
|
||||
description: "Restore count.",
|
||||
|
||||
@@ -21,6 +21,8 @@ import {
|
||||
import {
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
} from "./shared";
|
||||
@@ -61,6 +63,7 @@ export const measurementReminderPaths: NonNullable<ZodOpenApiObject["paths"]> =
|
||||
summary: "Create a Vorsorge reminder (v1.17.1)",
|
||||
description:
|
||||
"Creates a reminder and computes its server-authoritative nextDueAt. Exactly one of intervalDays (rolling) or rrule (RFC-5545) is required. Wrapped in withIdempotency. 201 on insert.",
|
||||
parameters: [idempotencyKeyParameter],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
@@ -68,6 +71,7 @@ export const measurementReminderPaths: NonNullable<ZodOpenApiObject["paths"]> =
|
||||
},
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"201": {
|
||||
description: "Reminder created.",
|
||||
|
||||
@@ -20,6 +20,8 @@ import {
|
||||
MODULE_DISABLED_DESCRIPTION,
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
} from "./shared";
|
||||
@@ -764,6 +766,7 @@ export const measurementPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
summary: "Create one measurement (or a small array)",
|
||||
description:
|
||||
"Single ingest. The body may also be a bare ARRAY of the same objects — the mode the iOS client uses for a combined blood-pressure + pulse or dual-value glucose write — in which case `data` is the array of created rows in request order. Use `/api/measurements/batch` for Apple Health upload streams.",
|
||||
parameters: [idempotencyKeyParameter],
|
||||
requestBody: {
|
||||
required: true,
|
||||
content: {
|
||||
@@ -776,6 +779,7 @@ export const measurementPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"201": {
|
||||
description:
|
||||
@@ -889,6 +893,7 @@ export const measurementPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
"/api/measurements/batch": {
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Measurements"],
|
||||
summary: "Apple Health batch ingest",
|
||||
description:
|
||||
@@ -898,6 +903,7 @@ export const measurementPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
content: { "application/json": { schema: batchPayloadSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"200": {
|
||||
description: "Batch processed.",
|
||||
content: {
|
||||
@@ -940,6 +946,7 @@ export const measurementPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
"/api/measurements/bulk-delete": {
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Measurements"],
|
||||
summary: "Bulk soft-delete measurements",
|
||||
description:
|
||||
@@ -951,6 +958,7 @@ export const measurementPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"200": {
|
||||
description: "Bulk delete processed.",
|
||||
@@ -969,6 +977,7 @@ export const measurementPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
"/api/measurements/restore": {
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Measurements"],
|
||||
summary: "Restore soft-deleted measurements",
|
||||
description:
|
||||
@@ -980,6 +989,7 @@ export const measurementPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"200": {
|
||||
description: "Restore processed.",
|
||||
|
||||
@@ -27,6 +27,8 @@ import {
|
||||
conflictResponse409,
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
invalidBaseTokenResponse,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
@@ -171,6 +173,7 @@ const medicationIntakeImportJobStatusEnvelope = dataEnvelope(
|
||||
export const medicationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
"/api/medications/intake/bulk": {
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Medications"],
|
||||
summary: "Bulk medication-intake backfill (iOS SyncMode)",
|
||||
description:
|
||||
@@ -180,6 +183,7 @@ export const medicationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
content: { "application/json": { schema: bulkIntakePayload } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"200": {
|
||||
description: "Batch processed (always 200 on a well-formed body).",
|
||||
content: {
|
||||
@@ -410,6 +414,7 @@ export const medicationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
"/api/medications/{id}/intake": {
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Medications"],
|
||||
summary: "Log an intake event for a medication",
|
||||
description:
|
||||
@@ -422,6 +427,7 @@ export const medicationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
content: { "application/json": { schema: intakeSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"201": {
|
||||
description: "Intake event created.",
|
||||
|
||||
@@ -19,7 +19,13 @@ import {
|
||||
listAssessmentsSchema,
|
||||
} from "@/lib/validations/mental-health";
|
||||
|
||||
import { dataEnvelope, recordRefusal, stdResponses } from "./shared";
|
||||
import {
|
||||
dataEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
} from "./shared";
|
||||
|
||||
createAssessmentSchema.meta({
|
||||
id: "CreateMentalHealthAssessmentRequest",
|
||||
@@ -127,12 +133,14 @@ export const mentalHealthPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
summary: "Record a completed screener",
|
||||
description:
|
||||
"Stores one administration (item answers encrypted) and writes the derived total as a server-owned PHQ9_SCORE / GAD7_SCORE / WHO5_SCORE / SCI_SCORE measurement (source COMPUTED — never client-writable). WHO-5 and SCI totals run HIGHER = better; their follow-up thresholds point downwards (≤ 50 / ≤ 16). On a positive PHQ-9 item-9 the response carries the locale-aware crisis-resource set.",
|
||||
parameters: [idempotencyKeyParameter],
|
||||
requestBody: {
|
||||
content: {
|
||||
"application/json": { schema: createAssessmentSchema },
|
||||
},
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"201": {
|
||||
description: "Assessment recorded.",
|
||||
|
||||
@@ -46,15 +46,17 @@ import {
|
||||
WORK_STATUS_KEYS,
|
||||
} from "@/lib/mood/context-vocabulary";
|
||||
import {
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
MODULE_DISABLED_DESCRIPTION,
|
||||
baseUpdatedAtField,
|
||||
updatedAtTokenField,
|
||||
conflictResponse409,
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
invalidBaseTokenResponse,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
updatedAtTokenField,
|
||||
} from "./shared";
|
||||
|
||||
// ── Request schemas — annotated for spec emission ────────────────────
|
||||
@@ -762,6 +764,7 @@ export const moodPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
"/api/mood-entries/bulk": {
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Mood"],
|
||||
summary: "Bulk mood backfill (iOS SyncMode)",
|
||||
description:
|
||||
@@ -771,6 +774,7 @@ export const moodPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
content: { "application/json": { schema: bulkMoodPayload } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"200": {
|
||||
description: "Batch processed (always 200 on a well-formed body).",
|
||||
content: {
|
||||
@@ -1080,6 +1084,7 @@ export const moodPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Mood"],
|
||||
summary: "Create a mood entry",
|
||||
description:
|
||||
@@ -1089,6 +1094,7 @@ export const moodPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
content: { "application/json": { schema: createMoodEntryRequest } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"201": {
|
||||
description:
|
||||
"Entry created (or upserted in place via `externalId`), with its persisted tag keys, rated factors and context.",
|
||||
@@ -1165,6 +1171,7 @@ export const moodPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
"/api/mood-entries/restore": {
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Mood"],
|
||||
summary: "Restore soft-deleted mood entries",
|
||||
description:
|
||||
@@ -1174,6 +1181,7 @@ export const moodPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
content: { "application/json": { schema: moodEntryIdsPayload } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"200": {
|
||||
description: "`restored` counts the rows actually un-tombstoned.",
|
||||
content: {
|
||||
@@ -1192,6 +1200,7 @@ export const moodPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
"/api/mood-entries/bulk-delete": {
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Mood"],
|
||||
summary: "Soft-delete mood entries in bulk",
|
||||
description:
|
||||
@@ -1201,6 +1210,7 @@ export const moodPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
content: { "application/json": { schema: moodEntryIdsPayload } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"200": {
|
||||
description: "`deleted` counts the rows actually tombstoned.",
|
||||
content: {
|
||||
|
||||
@@ -24,6 +24,8 @@ import {
|
||||
import {
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
} from "./shared";
|
||||
@@ -50,6 +52,7 @@ const catalogTable = NUTRIENT_DEFINITIONS.map(
|
||||
export const nutrientPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
"/api/nutrients/batch": {
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Nutrients"],
|
||||
summary: "Ingest micronutrient day totals (v1.28)",
|
||||
description:
|
||||
@@ -60,6 +63,7 @@ export const nutrientPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
content: { "application/json": { schema: nutrientBatchSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"200": {
|
||||
description:
|
||||
"Batch processed; per-entry statuses inserted | updated | skipped.",
|
||||
@@ -127,6 +131,7 @@ export const nutrientPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
"/api/nutrients/water": {
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Nutrients"],
|
||||
summary: "Manual water quick-add (v1.29)",
|
||||
description:
|
||||
@@ -138,6 +143,7 @@ export const nutrientPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"200": {
|
||||
description: "The MANUAL water row after the write.",
|
||||
content: {
|
||||
|
||||
@@ -17,7 +17,12 @@ import { z } from "zod/v4";
|
||||
|
||||
import { ocrCommitSchema } from "@/lib/validations/labs-ocr";
|
||||
|
||||
import { dataEnvelope, stdResponses } from "./shared";
|
||||
import {
|
||||
dataEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
stdResponses,
|
||||
} from "./shared";
|
||||
|
||||
ocrCommitSchema.meta({
|
||||
id: "OcrCommitRequest",
|
||||
@@ -197,6 +202,7 @@ export const ocrPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
"/api/labs/ocr/commit": {
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Labs"],
|
||||
summary: "Commit confirmed Lab-OCR rows",
|
||||
description:
|
||||
@@ -206,6 +212,7 @@ export const ocrPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
content: { "application/json": { schema: ocrCommitSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"200": {
|
||||
description: "Inserted + skipped rows.",
|
||||
content: {
|
||||
|
||||
@@ -177,6 +177,99 @@ export const stdResponses = {
|
||||
},
|
||||
};
|
||||
|
||||
// ── Idempotent writes ────────────────────────────────────────────────
|
||||
|
||||
/**
|
||||
* What a route wrapped in `withIdempotency` accepts and answers.
|
||||
*
|
||||
* The mechanism has worked since long before it was published: send
|
||||
* `Idempotency-Key` on a write, and a retry of the same key replays the first
|
||||
* response instead of doing the work twice. It was described in route comments
|
||||
* and nowhere a client could read it, so an app generated against the contract
|
||||
* had no way to know a retry was safe. This publishes it.
|
||||
*
|
||||
* Three things a client cannot infer and has to be told:
|
||||
*
|
||||
* 1. **A malformed key is ignored, not refused.** `getIdempotencyKey` tests
|
||||
* `^[A-Za-z0-9_\-:.]{8,128}$` and returns null on a miss, so a key that is
|
||||
* too short or carries a stray character is indistinguishable from sending
|
||||
* none at all — the write proceeds, unprotected, with a 200. This is the
|
||||
* one failure here that is silent, which is why it leads.
|
||||
* 2. **The replay is marked.** A response served from the cache carries
|
||||
* `X-Idempotent-Replay: true`. Without reading it a client cannot tell a
|
||||
* fresh 201 from a replayed one, which matters when the body reports what
|
||||
* was created.
|
||||
* 3. **A concurrent duplicate is refused, not queued.** While the first
|
||||
* request is still running, a second one under the same key gets 409 with
|
||||
* `X-Idempotent-Replay: false` — the header is present in both directions
|
||||
* precisely so the two cases are told apart. Retry after a delay.
|
||||
*
|
||||
* Scope, so nobody reads more into it than is there: only POST, PUT, PATCH and
|
||||
* DELETE are covered (`SUPPORTED_METHODS`), the key is scoped per user and per
|
||||
* `(method, path)`, and `isCachableStatus` refuses to cache 5xx or the
|
||||
* transient 401 / 403 / 408 / 429 — a retry after one of those runs for real.
|
||||
*
|
||||
* `src/__tests__/idempotency-contract-publication.test.ts` holds this to the
|
||||
* routes that actually wrap `withIdempotency`, in both directions, so a new
|
||||
* idempotent route that forgets to say so fails, and so does a claim here for
|
||||
* a route that dropped the wrapper.
|
||||
*/
|
||||
export const idempotencyKeyParameter = {
|
||||
name: "Idempotency-Key",
|
||||
in: "header" as const,
|
||||
required: false,
|
||||
schema: {
|
||||
type: "string" as const,
|
||||
pattern: "^[A-Za-z0-9_\\-:.]{8,128}$",
|
||||
minLength: 8,
|
||||
maxLength: 128,
|
||||
},
|
||||
description:
|
||||
"Makes this write safe to retry. Send the same key again and the first response is replayed rather than the work repeated, marked with `X-Idempotent-Replay: true`. A key that does not match the pattern is IGNORED rather than refused — the write then proceeds unprotected and looks exactly like a request that carried no key, so validate the key on your side. Scoped per user and per (method, path): the same key on a different route is a different key. While a first request under this key is still in flight, a second is refused with 409 rather than queued.",
|
||||
};
|
||||
|
||||
/**
|
||||
* Response headers are Zod here, not an OpenAPI literal — `zod-openapi` types
|
||||
* `headers` as a `ZodObject` and emits the schema from it. Writing the literal
|
||||
* shape by hand typechecks nowhere and was the first thing this file got wrong.
|
||||
*/
|
||||
const idempotentReplayHeaders = z.object({
|
||||
"X-Idempotent-Replay": z.enum(["true", "false"]).meta({
|
||||
description:
|
||||
"`true` when this response was replayed from a stored one rather than produced now; `false` on the 409 that refuses a duplicate still in flight. Absent when the request carried no usable key.",
|
||||
}),
|
||||
});
|
||||
|
||||
interface IdempotentConflictResponse {
|
||||
"409": {
|
||||
description: string;
|
||||
content: { "application/json": { schema: typeof errorEnvelope } };
|
||||
headers: typeof idempotentReplayHeaders;
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* The 409 an idempotent route answers while an earlier request under the same
|
||||
* key is still running, plus the replay header on the way back.
|
||||
*
|
||||
* Cached by identity like {@link recordRefusal} above, for the same reason: a
|
||||
* fresh object per call site would print this paragraph thirty-seven times.
|
||||
*/
|
||||
let idempotentConflictCache: IdempotentConflictResponse | null = null;
|
||||
|
||||
export function idempotentWrite(): IdempotentConflictResponse {
|
||||
if (idempotentConflictCache) return idempotentConflictCache;
|
||||
idempotentConflictCache = {
|
||||
"409": {
|
||||
description:
|
||||
"A request with this `Idempotency-Key` is already in progress. Nothing was written by this call. Retry after a short delay; the response carries `X-Idempotent-Replay: false` to separate it from a replay.",
|
||||
content: { "application/json": { schema: errorEnvelope } },
|
||||
headers: idempotentReplayHeaders,
|
||||
},
|
||||
};
|
||||
return idempotentConflictCache;
|
||||
}
|
||||
|
||||
// ── The delegated-record refusal (v1.37.0) ───────────────────────────
|
||||
|
||||
/**
|
||||
|
||||
@@ -35,6 +35,8 @@ import { measurementReminderDto } from "@/lib/validations/measurement-reminders"
|
||||
import {
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
} from "./shared";
|
||||
@@ -237,6 +239,7 @@ export const vaccinationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
},
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Records"],
|
||||
summary: "Log a vaccination",
|
||||
description:
|
||||
@@ -246,6 +249,7 @@ export const vaccinationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
content: { "application/json": { schema: vaccinationCreateSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
...recordRefusal(),
|
||||
"201": {
|
||||
description: "Dose logged.",
|
||||
|
||||
@@ -13,6 +13,8 @@ import {
|
||||
MODULE_DISABLED_DESCRIPTION,
|
||||
dataEnvelope,
|
||||
errorEnvelope,
|
||||
idempotencyKeyParameter,
|
||||
idempotentWrite,
|
||||
moduleDisabledResponse,
|
||||
recordRefusal,
|
||||
stdResponses,
|
||||
@@ -309,6 +311,7 @@ export const workoutPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
},
|
||||
"/api/workouts/batch": {
|
||||
post: {
|
||||
parameters: [idempotencyKeyParameter],
|
||||
tags: ["Measurements"],
|
||||
summary: "Typed workout batch ingest (v1.4.25 W16b)",
|
||||
description:
|
||||
@@ -318,6 +321,7 @@ export const workoutPaths: NonNullable<ZodOpenApiObject["paths"]> = {
|
||||
content: { "application/json": { schema: createBatchWorkoutSchema } },
|
||||
},
|
||||
responses: {
|
||||
...idempotentWrite(),
|
||||
"200": {
|
||||
description: "Batch processed.",
|
||||
content: {
|
||||
|
||||
Reference in new issue
Block a user