fix(api): put a ceiling under the single-record writes

The batch endpoints have been capped at 60 calls a minute since they
were written. The per-record siblings a naive or older client loops
over — the measurement create, the mood entry, both medication-intake
writes, a lab result, a custom-metric entry, a cycle day-log, a
vaccination, an allergy, a biomarker and an encounter — had no ceiling
at all. That is backwards from the risk: the batch endpoint is the one
a well-behaved client uses, and the unlimited path is the one a broken
loop finds.

All eleven share one generous per-account bucket, `record-write`, at
300 requests a minute. Five writes a second sustained for a full minute
is beyond any hand-driven session and any sync burst, and every one of
these routes is already wrapped in `withIdempotency`, so an honest
retry storm is deduplicated before it is counted — the bucket exists to
cut off the pathological loop, not to shape traffic. It keys on the
ACTING account, the precedent the delegable medication routes set, so a
delegate burns their own allowance rather than locking the record's
owner out of their own log.

The eleven operations publish the bucket name and the cap instead of
the generic refusal, on the shared 429 that already declares
`Retry-After` and the rate-limit triple. A test pulls the key and the
window out of the query the limiter runs and holds the published
sentence to them, so the paragraph cannot drift away from the bucket it
describes.
This commit is contained in:
Marc-André Bombeck committed 2026-09-10 07:42:07 +02:00
1 parent 040b430e73
commit ab6c1cd917
35 files changed
+804 -358

No files matched your search

+2
View File
@@ -30,6 +30,7 @@ import {
idempotencyKeyParameter,
idempotentWrite,
recordRefusal,
recordWriteRateLimitResponse,
stdResponses,
} from "./shared";
@@ -125,6 +126,7 @@ export const allergyPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
...stdResponses,
...recordWriteRateLimitResponse,
},
},
},
+2
View File
@@ -25,6 +25,7 @@ import {
idempotencyKeyParameter,
idempotentWrite,
recordRefusal,
recordWriteRateLimitResponse,
stdResponses,
} from "./shared";
@@ -125,6 +126,7 @@ export const biomarkerPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
...conflict,
...stdResponses,
...recordWriteRateLimitResponse,
},
},
},
+2
View File
@@ -27,6 +27,7 @@ import {
idempotencyKeyParameter,
idempotentWrite,
recordRefusal,
recordWriteRateLimitResponse,
stdResponses,
} from "./shared";
@@ -314,6 +315,7 @@ export const customMetricPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
...notFound,
...stdResponses,
...recordWriteRateLimitResponse,
},
},
},
+2
View File
@@ -35,6 +35,7 @@ import {
idempotentWrite,
malformedJsonResponse,
recordRefusal,
recordWriteRateLimitResponse,
stdResponses,
} from "./shared";
@@ -710,6 +711,7 @@ export const cyclePaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
...cycleDisabledOnADelegableRoute,
...stdResponses,
...recordWriteRateLimitResponse,
},
},
},
+2
View File
@@ -38,6 +38,7 @@ import {
idempotencyKeyParameter,
idempotentWrite,
recordRefusal,
recordWriteRateLimitResponse,
stdResponses,
} from "./shared";
@@ -273,6 +274,7 @@ export const encounterPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
...stdResponses,
...recordWriteRateLimitResponse,
},
},
},
+2
View File
@@ -22,6 +22,7 @@ import {
idempotencyKeyParameter,
idempotentWrite,
recordRefusal,
recordWriteRateLimitResponse,
stdResponses,
} from "./shared";
@@ -161,6 +162,7 @@ export const labsPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
...stdResponses,
...recordWriteRateLimitResponse,
},
},
},
+2
View File
@@ -21,6 +21,7 @@ import {
measurementSourceEnum,
measurementTypeEnum,
recordRefusal,
recordWriteRateLimitResponse,
stdResponses,
} from "./shared";
@@ -885,6 +886,7 @@ export const measurementPaths: NonNullable<ZodOpenApiObject["paths"]> = {
// After the spread: `stdResponses` carries a generic 422 that would
// otherwise overwrite this one.
...stdResponses,
...recordWriteRateLimitResponse,
"422": {
description:
"Validation failed, or (`measurement.create.source_not_permitted`) a narrow `measurements:write` credential named `APPLE_HEALTH` as the source. Refused rather than relabelled, so the caller can fix the payload instead of discovering rows it did not ask for.",
+3 -1
View File
@@ -35,6 +35,7 @@ import {
idempotentWrite,
invalidBaseTokenResponse,
recordRefusal,
recordWriteRateLimitResponse,
stdResponses,
} from "../shared";
@@ -289,7 +290,7 @@ export const medicationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
content: { "application/json": { schema: errorEnvelope } },
},
"401": stdResponses["401"],
"429": stdResponses["429"],
...recordWriteRateLimitResponse,
},
},
},
@@ -1153,6 +1154,7 @@ export const medicationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
content: { "application/json": { schema: errorEnvelope } },
},
...stdResponses,
...recordWriteRateLimitResponse,
},
},
get: {
+2
View File
@@ -56,6 +56,7 @@ import {
invalidBaseTokenResponse,
moduleDisabledResponse,
recordRefusal,
recordWriteRateLimitResponse,
stdResponses,
updatedAtTokenField,
} from "./shared";
@@ -1636,6 +1637,7 @@ export const moodPaths: NonNullable<ZodOpenApiObject["paths"]> = {
...duplicateTimestampResponse,
...recordRefusal(),
...stdResponses,
...recordWriteRateLimitResponse,
},
},
},
+26
View File
@@ -289,6 +289,32 @@ export const stdResponses = {
},
};
/**
* The 429 the shared single-record write bucket answers with.
*
* The batch endpoints have been capped at 60 calls a minute since they were
* written and the per-record siblings were not capped at all, which is exactly
* backwards: the batch endpoint is the one a well-behaved client uses. The
* eleven single-record creates now share one generous per-account bucket, and
* this is the response that names it — a client that meets a ceiling should be
* able to read which one it met without a bug report.
*
* Spread AFTER `...stdResponses` so it replaces the generic 429 on those
* operations. The headers block is the one the standard 429 already declares.
*
* `record-write-rate-limit-contract.test.ts` holds the numbers in this sentence
* to the constants in `src/lib/rate-limit.ts`, so the paragraph cannot drift
* away from the bucket it describes.
*/
export const recordWriteRateLimitResponse = {
"429": {
description:
"Rate limit exceeded. This route shares one per-account bucket with the other single-record writes — `record-write:<accountId>`, 300 requests per 60 seconds — keyed on the ACTING account, so a delegate burns their own allowance rather than the record owner's. Nothing was written. The `Retry-After`, `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers describe that bucket; back off on `Retry-After` rather than guessing. A client with more than a handful of rows to send should use the batch endpoint for its domain instead of looping this one.",
content: { "application/json": { schema: errorEnvelope } },
headers: stdResponses["429"].headers,
},
};
// ── Idempotent writes ────────────────────────────────────────────────
/**
+2
View File
@@ -38,6 +38,7 @@ import {
idempotencyKeyParameter,
idempotentWrite,
recordRefusal,
recordWriteRateLimitResponse,
stdResponses,
} from "./shared";
@@ -263,6 +264,7 @@ export const vaccinationPaths: NonNullable<ZodOpenApiObject["paths"]> = {
},
},
...stdResponses,
...recordWriteRateLimitResponse,
},
},
},