Files
HealthLog/src/lib/openapi/routes/ai-runs.ts
T
Marc-André Bombeck 0acf3da575 feat(documents): read documents and lab scans in the background
"Read with AI" and the lab scan used to run their model calls inside the
request. At the default response time a read of three calls outlasted the
100 s a proxy in front of the server commonly allows, and the person saw a
cut connection for a read the server was still doing.

Both now run as a background run (`DocumentAiRun`, migration 0366):

- `POST /api/documents/inbound/{id}/index` with `Prefer: respond-async`
  answers 202 with a run id once every quick refusal has passed. Without
  the header it answers exactly as before, which the iPhone app relies on.
  A second request while a read of the same document is queued or running
  attaches to that run.
- `POST /api/labs/ocr/extract` always answers 202. Only the web client
  calls it.
- `GET /api/ai-runs/{id}` serves the run: the same body the synchronous
  route answers with, or the failure code and status it would have given.
  Scoped to the caller; another account's run is a 404.

The worker (`document-ai-run`, a long queue with a one-hour expiry, one
job per run under `lockedPass`) claims the run, asks the capability again
for the record and re-checks the wire for the provider it picks, sets the
run's deadline from the person's AI response time and refuses a read that
cannot fit the job's expiry. Sync route and worker run one body per kind,
so the two paths cannot drift. Budget is reserved at enqueue and settled
once by whoever ends the run.

Input and result are sealed with labelled AES-256-GCM, registered for key
rotation; the input is dropped when the run ends. A five-minute reaper
fails a run no worker took within fifteen minutes (and hands its
reservation back), fails a run past its deadline, and deletes a finished
run after an hour. Runs are outside backups and inside the data wipe.

The web client polls through the query-key factory and says, calmly, that
the read continues in the background, and when no worker has picked it up.
2026-10-03 18:18:56 +02:00

99 lines
3.9 KiB
TypeScript

/**
* OpenAPI route table for background document AI runs (`/api/ai-runs/*`).
* The request header and the 202 the queuing routes share live in
* `./ai-run-accepted.ts`, so this module can read the result schemas of the
* routes it serves without an import cycle.
*
* Part of the OpenAPI route table; aggregated in `./index.ts`.
*
* iOS coordination (v1.40): `POST /api/documents/inbound/{id}/index` keeps
* its 200 body when the request carries no `Prefer` header. A client that
* sends `Prefer: respond-async` gets 202 with a run id and polls the run here;
* the result is the same body the route would have answered with.
* `POST /api/labs/ocr/extract` (web only) always answers 202.
*/
import type { ZodOpenApiObject } from "zod-openapi";
import { z } from "zod/v4";
import { documentIndexResponse } from "./documents";
import { ocrExtractResponse } from "./ocr";
import { dataEnvelope, errorEnvelope, stdResponses } from "./shared";
const aiRun = z
.object({
id: z.string(),
kind: z.enum(["DOCUMENT_INDEX", "LABS_OCR_EXTRACT"]),
documentId: z
.string()
.nullable()
.describe("The document a document run reads; null for a lab scan."),
status: z.enum(["QUEUED", "RUNNING", "SUCCEEDED", "FAILED"]),
result: z
.union([documentIndexResponse, ocrExtractResponse])
.nullable()
.describe(
"Present once `status` is `SUCCEEDED`: the body the queuing route answers with synchronously. `DOCUMENT_INDEX` carries `DocumentIndexResponse`, `LABS_OCR_EXTRACT` carries `OcrExtractResponse`.",
),
error: z
.object({
code: z.string(),
message: z.string(),
status: z.number().int(),
})
.nullable()
.describe(
"Present once `status` is `FAILED`: the `meta.errorCode`, message and HTTP status the queuing route would have answered with, or one of the run's own codes: `aiRuns.workerUnavailable` (no worker took the run within fifteen minutes), `aiRuns.timedOut` (the read outlived the calls the AI response time allows), `aiRuns.failed` (anything else).",
),
createdAt: z.string(),
startedAt: z.string().nullable(),
finishedAt: z.string().nullable(),
queuedForMs: z
.number()
.int()
.nullable()
.describe(
"While queued, how long the run has waited for a worker. A long wait usually means the background worker is not running.",
),
retryAfterMs: z
.number()
.int()
.nullable()
.describe(
"While not terminal, when to poll again (also sent as `Retry-After`, in seconds). Null once the run has ended.",
),
})
.meta({
id: "AiRun",
description:
"One background document AI run. Results and failures stay readable for an hour after the run ends; the run is then deleted and answers 404.",
});
export const aiRunPaths: NonNullable<ZodOpenApiObject["paths"]> = {
"/api/ai-runs/{id}": {
get: {
tags: ["Documents"],
summary: "Poll a background document AI run",
description:
"Where one background read stands, and its result or failure once it ends. Scoped to the caller: another account's run, a run that never existed, and a run more than an hour past its end are the same 404 `aiRuns.notFound`. A plain read of the caller's own run; it calls no model and asks no AI capability (those were asked when the run was queued, and again in the worker before anything left the server). Auth via cookie or Bearer.",
parameters: [
{ name: "id", in: "path", required: true, schema: { type: "string" } },
],
responses: {
"200": {
description: "The run.",
content: {
"application/json": {
schema: dataEnvelope(aiRun, "AiRunEnvelope"),
},
},
},
"404": {
description: "`aiRuns.notFound`.",
content: { "application/json": { schema: errorEnvelope } },
},
...stdResponses,
},
},
},
};