Merge Retry-After on every refused request, stable list pagination and the corrected error contract

This commit is contained in:
Marc-André Bombeck committed 2026-09-10 05:10:05 +02:00
commit 6a2282fef8
80 files changed
+2261 -220

No files matched your search

@@ -0,0 +1,214 @@
/**
* Offset pagination over a tied sort key must not repeat or drop a row.
*
* `/api/measurements` and `/api/labs` page with `skip`/`take` over a single
* non-unique column. Ties are the normal case on both: an Apple Health import
* stamps long runs of samples with one instant and the documented
* `stats:<identifier>:YYYY-MM-DD` rollup convention puts every daily total at
* the same one, while a lab panel drawn in one sitting shares `takenAt` across
* every analyte in it. Without a unique secondary key Postgres may order the
* tied block differently for the query that fetches page N and the one that
* fetches page N+1, so a client mirroring its own history silently receives
* one row twice and never receives another. For a health record that is a
* data-integrity bug, and it is invisible to both sides.
*
* The fixtures are seeded with explicit ids in a deliberately scrambled order,
* so heap order and id order disagree. That is what makes this a real gate:
* asserting only that two pages are disjoint would pass on an unordered scan
* that happened to be stable, whereas the id ordering inside a tied block can
* only hold if the secondary sort key is actually there.
*/
import { NextRequest } from "next/server";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { cookieJar } from "./mock-next-headers";
import { getPrismaClient, truncateAllTables } from "./setup";
const TEST_USER_ID = "user-pagination-tiebreaker";
const TIED_AT = new Date("2026-03-04T09:00:00.000Z");
vi.mock("next/headers", async () => {
const { cookieJar, headerJar } = await import("./mock-next-headers");
return {
headers: vi.fn(async () => ({
get: (name: string) => headerJar.get(name.toLowerCase()) ?? null,
})),
cookies: vi.fn(async () => ({
get: (name: string) => {
const value = cookieJar.get(name);
return value ? { name, value } : undefined;
},
set: (name: string, value: string) => {
cookieJar.set(name, value);
},
delete: (name: string) => {
cookieJar.delete(name);
},
})),
};
});
vi.mock("@/lib/db-compat", () => ({
ensureDbCompatibility: vi.fn().mockResolvedValue(undefined),
}));
/**
* Insertion order deliberately unrelated to id order: 04, 09, 01, 06, 00, …
* A scan that ignores the secondary key returns this sequence; one that
* honours it returns 09, 08, 07, … on a descending sort.
*/
const SCRAMBLED = [4, 9, 1, 6, 0, 8, 3, 7, 2, 5];
/**
* One type per row. The partial unique index on
* `(user_id, type, measured_at, source, sleep_stage)` forbids two live rows of
* the SAME type at one instant, so the tie that actually occurs in production
* is the cross-type one: a daily `stats:` rollup posts steps, distance,
* flights, active energy and the rest at the identical timestamp, and an
* unfiltered history list pages straight through the block.
*/
const TYPES = [
"ACTIVITY_STEPS",
"FLIGHTS_CLIMBED",
"WALKING_RUNNING_DISTANCE",
"ACTIVE_ENERGY_BURNED",
"RESTING_HEART_RATE",
"HEART_RATE_VARIABILITY",
"OXYGEN_SATURATION",
"RESPIRATORY_RATE",
"BODY_TEMPERATURE",
"WEIGHT",
] as const;
beforeEach(async () => {
const prisma = getPrismaClient();
await truncateAllTables(prisma);
cookieJar.clear();
await prisma.user.create({
data: {
id: TEST_USER_ID,
username: "pagination-tiebreaker",
email: "pagination-tiebreaker@example.test",
},
});
const session = await prisma.session.create({
data: {
userId: TEST_USER_ID,
expiresAt: new Date(Date.now() + 60 * 60 * 1000),
},
});
cookieJar.set("healthlog_session", session.id);
// Every row shares one `measuredAt` / `takenAt` — the whole page is one
// tied block, which is the worst case and the realistic one.
for (const n of SCRAMBLED) {
const suffix = String(n).padStart(2, "0");
await prisma.measurement.create({
data: {
id: `tie-measurement-${suffix}`,
userId: TEST_USER_ID,
type: TYPES[n],
value: 80 + n,
unit: "count",
measuredAt: TIED_AT,
source: "APPLE_HEALTH",
},
});
await prisma.labResult.create({
data: {
id: `tie-lab-${suffix}`,
userId: TEST_USER_ID,
analyte: `Analyte ${suffix}`,
value: 1 + n,
unit: "mg/dl",
takenAt: TIED_AT,
},
});
}
});
function get(path: string): NextRequest {
return new NextRequest(`http://localhost${path}`);
}
async function idsOf(
res: Response,
key: "measurements" | "results",
): Promise<string[]> {
const body = (await res.json()) as {
data: Record<string, Array<{ id: string }>>;
};
return body.data[key].map((row) => row.id);
}
describe("offset pagination over a tied sort key (real Postgres)", () => {
it("pages /api/measurements with no duplicate and no gap", async () => {
const { GET } = await import("@/app/api/measurements/route");
const first = await idsOf(
await GET(get("/api/measurements?limit=4&offset=0") as never),
"measurements",
);
const second = await idsOf(
await GET(get("/api/measurements?limit=4&offset=4") as never),
"measurements",
);
const third = await idsOf(
await GET(get("/api/measurements?limit=4&offset=8") as never),
"measurements",
);
const seen = [...first, ...second, ...third];
expect(seen).toHaveLength(10);
expect(new Set(seen).size).toBe(10);
expect([...seen].sort()).toEqual(
SCRAMBLED.map((n) => `tie-measurement-${String(n).padStart(2, "0")}`)
.slice()
.sort(),
);
// The default sort is `measuredAt desc`; with every row tied, the
// tiebreaker is the only thing deciding the order, so it must be
// strictly descending by id across the page boundaries.
expect(seen).toEqual([...seen].sort().reverse());
});
it("pages /api/labs with no duplicate and no gap", async () => {
const { GET } = await import("@/app/api/labs/route");
const first = await idsOf(
await GET(get("/api/labs?limit=4&offset=0") as never),
"results",
);
const second = await idsOf(
await GET(get("/api/labs?limit=4&offset=4") as never),
"results",
);
const third = await idsOf(
await GET(get("/api/labs?limit=4&offset=8") as never),
"results",
);
const seen = [...first, ...second, ...third];
expect(seen).toHaveLength(10);
expect(new Set(seen).size).toBe(10);
expect(seen).toEqual([...seen].sort().reverse());
});
it("keeps the ascending direction stable too", async () => {
const { GET } = await import("@/app/api/measurements/route");
const first = await idsOf(
await GET(get("/api/measurements?limit=5&offset=0&sortDir=asc") as never),
"measurements",
);
const second = await idsOf(
await GET(get("/api/measurements?limit=5&offset=5&sortDir=asc") as never),
"measurements",
);
const seen = [...first, ...second];
expect(new Set(seen).size).toBe(10);
expect(seen).toEqual([...seen].sort());
});
});
@@ -0,0 +1,305 @@
/**
* A real response, parsed against the schema that publishes it.
*
* Nothing in the gate did this before. `pnpm openapi:check` proves the YAML
* matches the registry; `openapi-route-coverage-guard` proves the verb is
* listed. Both pass when the registered schema disagrees with what the handler
* actually sends, and that gap is how `/api/sync/changes` ended up shipping
* five domains against a three-domain contract while the body was invalid
* against its own published schema.
*
* Two responses are covered — the two that were broken:
*
* - `GET /api/sync/changes`, the multi-domain delta the native client mirrors
* its whole history from.
* - a multi-issue 422, whose `details.issues` array is the reason the
* envelope exists and was the field the envelope did not declare.
*
* The check is stricter than `safeParse` alone. Zod strips undeclared keys
* rather than refusing them, so a pass would say nothing about a field the
* server sends and the contract omits — exactly the direction both of those
* drifted in. Comparing the parsed value back to the raw body catches
* the strip: if anything was dropped, the schema is short of the wire.
*
* One limit worth knowing before leaning on that half: `meta` is declared as a
* loose object, deliberately, because real refusals put `removedIn`,
* `replacedBy` and per-integration context there. Loose keys survive the parse,
* so the strip comparison does not reach inside `meta`. A `meta` field that
* ever becomes load-bearing for a client needs its own declaration and its own
* assertion.
*/
import { NextRequest } from "next/server";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { cookieJar } from "./mock-next-headers";
import { getPrismaClient, truncateAllTables } from "./setup";
import { syncChangesResponse } from "@/lib/openapi/routes/sync";
import { errorEnvelope } from "@/lib/openapi/routes/shared";
const TEST_USER_ID = "user-openapi-response-shape";
vi.mock("next/headers", async () => {
const { cookieJar, headerJar } = await import("./mock-next-headers");
return {
headers: vi.fn(async () => ({
get: (name: string) => headerJar.get(name.toLowerCase()) ?? null,
})),
cookies: vi.fn(async () => ({
get: (name: string) => {
const value = cookieJar.get(name);
return value ? { name, value } : undefined;
},
set: (name: string, value: string) => {
cookieJar.set(name, value);
},
delete: (name: string) => {
cookieJar.delete(name);
},
})),
};
});
vi.mock("@/lib/db-compat", () => ({
ensureDbCompatibility: vi.fn().mockResolvedValue(undefined),
}));
beforeEach(async () => {
const prisma = getPrismaClient();
await truncateAllTables(prisma);
cookieJar.clear();
// FEMALE so the cycle module is on by default and the two domains the
// contract used to omit actually carry rows.
await prisma.user.create({
data: {
id: TEST_USER_ID,
username: "openapi-response-shape",
email: "openapi-response-shape@example.test",
gender: "FEMALE",
timezone: "UTC",
},
});
const session = await prisma.session.create({
data: {
userId: TEST_USER_ID,
expiresAt: new Date(Date.now() + 60 * 60 * 1000),
},
});
cookieJar.set("healthlog_session", session.id);
});
/**
* Seed one live row and one soft-deleted row per domain, so every `upserts`
* and every `tombstones` array in the page is non-empty. An all-empty page
* would parse against almost any schema.
*/
async function seedEveryDomain(): Promise<void> {
const prisma = getPrismaClient();
const at = new Date("2026-02-02T08:00:00.000Z");
const gone = new Date("2026-02-02T09:00:00.000Z");
await prisma.measurement.createMany({
data: [
{
id: "shape-measurement-live",
userId: TEST_USER_ID,
type: "WEIGHT",
value: 79.2,
unit: "kg",
measuredAt: at,
source: "MANUAL",
externalId: "shape-live",
},
{
id: "shape-measurement-gone",
userId: TEST_USER_ID,
type: "PULSE",
value: 61,
unit: "bpm",
measuredAt: at,
source: "MANUAL",
externalId: "shape-gone",
deletedAt: gone,
},
],
});
await prisma.moodEntry.createMany({
data: [
{
id: "shape-mood-live",
userId: TEST_USER_ID,
date: "2026-02-02",
mood: "GOOD",
score: 4,
moodLoggedAt: at,
source: "MANUAL",
},
{
id: "shape-mood-gone",
userId: TEST_USER_ID,
date: "2026-02-01",
mood: "OKAY",
score: 3,
moodLoggedAt: at,
source: "MANUAL",
deletedAt: gone,
},
],
});
const medication = await prisma.medication.create({
data: {
id: "shape-medication",
userId: TEST_USER_ID,
name: "Test compound",
dose: "1 tablet",
},
});
await prisma.medicationIntakeEvent.createMany({
data: [
{
id: "shape-intake-live",
userId: TEST_USER_ID,
medicationId: medication.id,
scheduledFor: at,
takenAt: at,
skipped: false,
source: "WEB",
},
{
id: "shape-intake-gone",
userId: TEST_USER_ID,
medicationId: medication.id,
scheduledFor: gone,
takenAt: null,
skipped: true,
source: "WEB",
deletedAt: gone,
},
],
});
await prisma.menstrualCycle.createMany({
data: [
{
id: "shape-cycle-live",
userId: TEST_USER_ID,
startDate: "2026-01-05",
},
{
id: "shape-cycle-gone",
userId: TEST_USER_ID,
startDate: "2025-12-05",
deletedAt: gone,
},
],
});
await prisma.cycleDayLog.createMany({
data: [
{
id: "shape-day-live",
userId: TEST_USER_ID,
date: "2026-01-05",
cycleId: "shape-cycle-live",
flow: "MEDIUM",
source: "MANUAL",
},
{
id: "shape-day-gone",
userId: TEST_USER_ID,
date: "2026-01-04",
source: "MANUAL",
deletedAt: gone,
},
],
});
}
describe("published response schemas against real bodies", () => {
it("parses a full /api/sync/changes page and drops nothing", async () => {
await seedEveryDomain();
const { GET } = await import("@/app/api/sync/changes/route");
const res = await GET(
new NextRequest("http://localhost/api/sync/changes") as never,
);
expect(res.status).toBe(200);
const body = (await res.json()) as { data: unknown };
const parsed = syncChangesResponse.safeParse(body.data);
expect(parsed.error?.issues ?? []).toEqual([]);
expect(parsed.success).toBe(true);
// Every domain actually carried rows, so the parse above was asked a real
// question rather than being handed five empty pairs.
const changes = (
body.data as {
changes: Record<string, { upserts: unknown[]; tombstones: unknown[] }>;
}
).changes;
for (const domain of [
"measurements",
"mood",
"intakes",
"cycleDays",
"cycles",
]) {
expect(changes[domain].upserts.length).toBeGreaterThan(0);
expect(changes[domain].tombstones.length).toBeGreaterThan(0);
}
// Zod strips what it does not declare, so an equal round-trip is the part
// that proves the contract is not short of the wire.
expect(parsed.data).toEqual(body.data);
});
it("parses the cursorExpired short-circuit page too", async () => {
const { GET } = await import("@/app/api/sync/changes/route");
// A cursor whose watermark predates tombstone retention forces the
// early return, which builds its own literal page rather than the one
// the domain walks assemble — a second shape under the same schema.
const { encodeCursor } = await import("@/lib/sync/cursor");
const stale = encodeCursor({
measurements: {
updatedAtMs: Date.now() - 400 * 24 * 60 * 60 * 1000,
id: "long-gone",
},
});
const res = await GET(
new NextRequest(
`http://localhost/api/sync/changes?cursor=${stale}`,
) as never,
);
expect(res.status).toBe(200);
const body = (await res.json()) as { data: { cursorExpired: boolean } };
const parsed = syncChangesResponse.safeParse(body.data);
expect(parsed.error?.issues ?? []).toEqual([]);
expect(parsed.data).toEqual(body.data);
});
it("parses a multi-issue 422 against the published error envelope", async () => {
const { GET } = await import("@/app/api/measurements/route");
const res = await GET(
new NextRequest(
"http://localhost/api/measurements?limit=0&offset=-3&sortDir=sideways",
) as never,
);
expect(res.status).toBe(422);
const body = (await res.json()) as {
details?: { issues: unknown[] };
};
// The envelope exists to report every bad field at once; if only one
// arrives, the fixture stopped exercising the multi-issue path.
expect(body.details?.issues.length ?? 0).toBeGreaterThan(1);
const parsed = errorEnvelope.safeParse(body);
expect(parsed.error?.issues ?? []).toEqual([]);
expect(parsed.data).toEqual(body);
});
});
@@ -0,0 +1,213 @@
/**
* Which 429s carry the rate-limit headers, against a real limiter.
*
* `POST /api/measurements/batch` is the case that matters most: a first-run
* Apple Health import reliably trips its 60-per-minute ceiling, and until now
* the client got a prose sentence and nothing to back off against. The route
* builds its refusal with a bare `apiError(...)`, so this proves the headers
* come from `apiHandler` and the limiter's request-scoped verdict rather than
* from the handler body — which is what makes the other 128 header-less routes
* covered too.
*
* Two more shapes ride along, because the dressing is only honest when the
* numbers describe the ceiling that actually refused:
*
* - `POST /api/withings/sync` consults two buckets — a 5/minute baseline and
* a 1/hour bucket on the expensive full walk. A request the baseline lets
* through and the full bucket refuses must report the full bucket.
* - `POST /api/medications/extract` clears its limiter and can then be
* refused by the daily AI token budget. That 429 belongs to no bucket, so
* it must go out with no rate-limit headers at all rather than one naming
* a bucket that still has room.
*
* Run against a real Postgres because the limiter's window and remainder come
* out of the atomic upsert, and the budget ledger is a real row too; a mocked
* verdict would prove the plumbing and not the numbers.
*/
import { NextRequest } from "next/server";
import { beforeEach, describe, expect, it, vi } from "vitest";
import { cookieJar } from "./mock-next-headers";
import { getPrismaClient, truncateAllTables } from "./setup";
const TEST_USER_ID = "user-rate-limit-headers";
vi.mock("next/headers", async () => {
const { cookieJar, headerJar } = await import("./mock-next-headers");
return {
headers: vi.fn(async () => ({
get: (name: string) => headerJar.get(name.toLowerCase()) ?? null,
})),
cookies: vi.fn(async () => ({
get: (name: string) => {
const value = cookieJar.get(name);
return value ? { name, value } : undefined;
},
set: (name: string, value: string) => {
cookieJar.set(name, value);
},
delete: (name: string) => {
cookieJar.delete(name);
},
})),
};
});
vi.mock("@/lib/db-compat", () => ({
ensureDbCompatibility: vi.fn().mockResolvedValue(undefined),
}));
beforeEach(async () => {
await truncateAllTables(getPrismaClient());
cookieJar.clear();
await getPrismaClient().user.create({
data: {
id: TEST_USER_ID,
username: "rate-limit-headers",
email: "rate-limit-headers@example.test",
},
});
const session = await getPrismaClient().session.create({
data: {
userId: TEST_USER_ID,
expiresAt: new Date(Date.now() + 60 * 60 * 1000),
},
});
cookieJar.set("healthlog_session", session.id);
});
function batchRequest(): NextRequest {
return new NextRequest("http://localhost/api/measurements/batch", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({
entries: [
{
hkIdentifier: "HKQuantityTypeIdentifierBodyMass",
value: 81.4,
unit: "kg",
startDate: "2026-07-20T06:00:00.000Z",
endDate: "2026-07-20T06:00:00.000Z",
externalId: `rl-${Math.random().toString(36).slice(2)}`,
},
],
}),
});
}
describe("429 rate-limit headers (real Postgres)", () => {
it("carries Retry-After and the X-RateLimit triple on a route that attaches none", async () => {
const { POST } = await import("@/app/api/measurements/batch/route");
// Burn the bucket directly rather than posting sixty batches: the route
// and the pre-charge share one key, so the next call through the handler
// is the one that is refused.
const { checkRateLimit } = await import("@/lib/rate-limit");
const key = `measurements:batch:${TEST_USER_ID}`;
for (let i = 0; i < 60; i += 1) {
await checkRateLimit(key, 60, 60_000);
}
const before = Date.now();
const res = await POST(batchRequest() as never);
expect(res.status).toBe(429);
const retryAfter = res.headers.get("Retry-After");
expect(retryAfter).toMatch(/^\d+$/);
const seconds = Number(retryAfter);
expect(seconds).toBeGreaterThan(0);
expect(seconds).toBeLessThanOrEqual(60);
expect(res.headers.get("X-RateLimit-Limit")).toBe("60");
expect(res.headers.get("X-RateLimit-Remaining")).toBe("0");
const reset = res.headers.get("X-RateLimit-Reset");
expect(reset).toBeTruthy();
const resetAt = Date.parse(reset as string);
expect(Number.isNaN(resetAt)).toBe(false);
expect(resetAt).toBeGreaterThan(before);
// The named delay must actually outlast the window it names.
expect(before + seconds * 1000).toBeGreaterThanOrEqual(resetAt - 1_000);
// The body is unchanged — the headers are additive.
const body = (await res.json()) as { data: null; error: string };
expect(body.data).toBeNull();
expect(typeof body.error).toBe("string");
});
it("leaves a successful response without them", async () => {
const { POST } = await import("@/app/api/measurements/batch/route");
const res = await POST(batchRequest() as never);
expect(res.status).toBe(200);
expect(res.headers.get("Retry-After")).toBeNull();
});
it("reports the bucket that refused when a route consults two", async () => {
const { POST } = await import("@/app/api/withings/sync/route");
// Burn only the full-sync bucket. The route's baseline 5/60s bucket is
// untouched, so it passes on the way in and the refusal comes from the
// 1/hour one — the numbers on the wire have to be that one's.
const { checkRateLimit } = await import("@/lib/rate-limit");
await checkRateLimit(`withings-sync-full:${TEST_USER_ID}`, 1, 60 * 60_000);
const res = await POST(
new NextRequest("http://localhost/api/withings/sync", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ fullSync: true }),
}) as never,
);
expect(res.status).toBe(429);
expect(res.headers.get("X-RateLimit-Limit")).toBe("1");
expect(res.headers.get("X-RateLimit-Remaining")).toBe("0");
// The baseline bucket's window is 60 seconds; the hour-long one cannot be
// mistaken for it.
expect(Number(res.headers.get("Retry-After"))).toBeGreaterThan(60);
});
it("leaves a 429 the limiter did not produce undressed", async () => {
// The daily AI budget, not a bucket. The route's own 10-per-5-minutes
// limiter passes on the way in; dressing this refusal with that verdict
// would tell the client nine calls are still free and to retry in five
// minutes, when the budget does not move until UTC midnight.
await getPrismaClient().user.update({
where: { id: TEST_USER_ID },
// A self-hosted local endpoint resolves as the chain's primary, which
// keeps the request on the user-plan ceiling and off the consent gate.
data: { aiBaseUrl: "http://127.0.0.1:11434/v1" },
});
const { buildDateKey, USER_PLAN_CAP } =
await import("@/lib/ai/coach/budget");
await getPrismaClient().coachUsage.create({
data: {
userId: TEST_USER_ID,
dateKey: buildDateKey(),
totalTokens: USER_PLAN_CAP,
messageCount: 1,
},
});
const { POST } = await import("@/app/api/medications/extract/route");
const res = await POST(
new NextRequest("http://localhost/api/medications/extract", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ text: "Mounjaro 5mg weekly Wednesday" }),
}) as never,
);
expect(res.status).toBe(429);
for (const name of [
"Retry-After",
"X-RateLimit-Limit",
"X-RateLimit-Remaining",
"X-RateLimit-Reset",
]) {
expect(res.headers.get(name)).toBeNull();
}
});
});