mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-16 23:33:29 +00:00
POST /api/insights/ecg takes one recording per request: the stable recording id the client already has, the on-device timestamp, the sampling rate, the waveform as integer micro-volts, the lead, the average heart rate, and the device's own verdict. Same gating as the reads (auth, the insights module, the insightStatus surface), userId from the session, APPLE_HEALTH the only source a client may claim. sampleCount and durationSeconds are derived here, and nothing about the waveform is ever interpreted. The write body now lives in one place, src/lib/ecg/persist-recording.ts, shared by the Withings sync, the export-archive importer and the new route. Three writers with three persistence bodies is how the two ends of one rule drift apart. Migration 0291 adds the second unique index on (user_id, source, recorded_at, sampling_frequency). The archive importer identifies a strip by a hash of its content and a live client by the device's own sample uuid, so the same physical recording arriving through both doors carried two different ids and would have landed twice. One device does not record two different strips at the same instant at the same sampling rate, so the constraint is sound and the convergence stops being a convention. The table already holds rows on deployed instances and two writers have been filling it since v1.19.0, so the index cannot just be created: a pre-existing collision would abort the migration. The migration resolves duplicates first, keeping the row with the most samples (a stored strip beats a verdict-only row), then the one linked to its event measurement, then the most recently written, then the lowest id so the choice is total. The losers' event link is salvaged onto the keeper first, so resolving a duplicate never costs the recording its place in the event timeline. If that resolution is wrong on some instance, the failure is visible at deploy time and not later: db:migrate:deploy runs on boot, so the container crash-loops with the migration named in the logs and the release never serves traffic. A deploy that finishes in under thirty seconds did not run it. The GET list and detail routes and the export-archive path are unchanged; this is a second door, not a replacement.
214 lines
6.9 KiB
TypeScript
214 lines
6.9 KiB
TypeScript
/**
|
|
* The one persistence body for an ECG recording, whichever door it came
|
|
* through.
|
|
*
|
|
* Three writers put rows in `ecg_recordings`: the Withings OAuth sync, the
|
|
* Apple Health `export.zip` importer, and the live `POST /api/insights/ecg`
|
|
* ingest. They disagree about where a recording comes from and about how it
|
|
* is identified, and about nothing else — so encryption, the derived
|
|
* `sampleCount` / `durationSeconds`, the upsert, and the duplicate rule live
|
|
* here and only here.
|
|
*
|
|
* Two identities, one row:
|
|
*
|
|
* - `(userId, source, externalRecordingId)` is the SOURCE's own idea of a
|
|
* recording. The archive importer derives it from the recording's
|
|
* content (a hash), the live ingest sends the device's stable sample
|
|
* uuid, Withings sends its `signalid`. A re-post under the same id
|
|
* overwrites in place.
|
|
* - `(userId, source, recordedAt, samplingFrequency)` is what the recording
|
|
* actually IS. One device does not produce two different recordings for
|
|
* the same instant at the same sampling rate, so this catches the same
|
|
* physical strip arriving under two different source ids — the archive's
|
|
* content hash and the live sync's sample uuid for one Apple Watch ECG.
|
|
* The second arrival is reported as `duplicate` and writes nothing.
|
|
*
|
|
* The duplicate is resolved by an explicit lookup rather than by reading the
|
|
* shape of a Prisma unique-violation error: the database index is the
|
|
* structural backstop for a concurrent race, not the thing the outcome is
|
|
* derived from. A race that slips past the lookup still cannot create a twin
|
|
* — it raises `P2002`, and the handler below re-resolves it to the same
|
|
* `duplicate` verdict.
|
|
*
|
|
* The waveform is encrypted BEFORE the transaction opens, so a crypto failure
|
|
* fails closed without a write transaction ever existing. Both the ciphertext
|
|
* buffer and the caller's plaintext sample array are zero-filled afterwards;
|
|
* callers must not reuse `samples` after the call.
|
|
*/
|
|
import { Prisma } from "@/generated/prisma/client";
|
|
import type {
|
|
MeasurementSource,
|
|
PrismaClient,
|
|
RhythmClassification,
|
|
} from "@/generated/prisma/client";
|
|
import { encryptWaveformToBytes } from "@/lib/withings/ecg-waveform-codec";
|
|
|
|
/**
|
|
* What the write did.
|
|
*
|
|
* - `inserted` — a new row.
|
|
* - `updated` — a row with this source id already existed and was overwritten.
|
|
* - `duplicate` — this exact recording is already stored under a DIFFERENT
|
|
* source id (the other door). Nothing was written; `id` names the row that
|
|
* already holds it.
|
|
*/
|
|
export type EcgPersistOutcome = "inserted" | "updated" | "duplicate";
|
|
|
|
export interface EcgRecordingWrite {
|
|
userId: string;
|
|
source: MeasurementSource;
|
|
/** The source's own stable id for this recording. */
|
|
externalRecordingId: string;
|
|
recordedAt: Date;
|
|
/** Integer micro-volt samples. Zero-filled by this function. */
|
|
samples: number[];
|
|
/** Signal sampling rate in Hz; 0 when the source omitted it. */
|
|
samplingFrequency: number;
|
|
lead?: string | null;
|
|
averageHeartRate?: number | null;
|
|
/** The DEVICE's own verdict, verbatim. Never derived from the waveform. */
|
|
rhythmClassification?: RhythmClassification | null;
|
|
/** FK to the paired EVENT measurement row, when the writer knows it. */
|
|
measurementId?: string | null;
|
|
}
|
|
|
|
export interface EcgPersistResult {
|
|
outcome: EcgPersistOutcome;
|
|
/** The row holding this recording — the written one, or the twin. */
|
|
id: string;
|
|
sampleCount: number;
|
|
durationSeconds: number | null;
|
|
}
|
|
|
|
/**
|
|
* `sampleCount / samplingFrequency`, or null when the source omitted the
|
|
* frequency — a strip with no sampling rate has no knowable duration, and
|
|
* dividing by zero would store Infinity.
|
|
*/
|
|
export function ecgDurationSeconds(
|
|
sampleCount: number,
|
|
samplingFrequency: number,
|
|
): number | null {
|
|
return samplingFrequency > 0 ? sampleCount / samplingFrequency : null;
|
|
}
|
|
|
|
type TransactionalClient = Pick<PrismaClient, "$transaction">;
|
|
|
|
export async function persistEcgRecording(
|
|
input: EcgRecordingWrite,
|
|
db: TransactionalClient,
|
|
): Promise<EcgPersistResult> {
|
|
const {
|
|
userId,
|
|
source,
|
|
externalRecordingId,
|
|
recordedAt,
|
|
samples,
|
|
samplingFrequency,
|
|
} = input;
|
|
|
|
const sampleCount = samples.length;
|
|
const durationSeconds = ecgDurationSeconds(sampleCount, samplingFrequency);
|
|
|
|
// Encryption happens before the transaction opens. A crypto failure
|
|
// therefore fails closed without a write transaction ever existing, and
|
|
// plaintext never reaches the row.
|
|
const waveformEncrypted = encryptWaveformToBytes(samples);
|
|
|
|
const sourceKey = {
|
|
userId_source_externalRecordingId: {
|
|
userId,
|
|
source,
|
|
externalRecordingId,
|
|
},
|
|
};
|
|
const recordingKey = {
|
|
userId_source_recordedAt_samplingFrequency: {
|
|
userId,
|
|
source,
|
|
recordedAt,
|
|
samplingFrequency,
|
|
},
|
|
};
|
|
|
|
// Built field-by-field from the typed input; the parsed request object is
|
|
// never spread into `data`.
|
|
const columns = {
|
|
recordedAt,
|
|
waveformEncrypted,
|
|
samplingFrequency,
|
|
sampleCount,
|
|
durationSeconds,
|
|
lead: input.lead ?? null,
|
|
averageHeartRate: input.averageHeartRate ?? null,
|
|
rhythmClassification: input.rhythmClassification ?? null,
|
|
measurementId: input.measurementId ?? null,
|
|
};
|
|
|
|
try {
|
|
return await db.$transaction(async (tx) => {
|
|
const existing = await tx.ecgRecording.findUnique({
|
|
where: sourceKey,
|
|
select: { id: true },
|
|
});
|
|
|
|
if (!existing) {
|
|
const twin = await tx.ecgRecording.findUnique({
|
|
where: recordingKey,
|
|
select: { id: true },
|
|
});
|
|
if (twin) {
|
|
return {
|
|
outcome: "duplicate" as const,
|
|
id: twin.id,
|
|
sampleCount,
|
|
durationSeconds,
|
|
};
|
|
}
|
|
}
|
|
|
|
const row = await tx.ecgRecording.upsert({
|
|
where: sourceKey,
|
|
create: { userId, source, externalRecordingId, ...columns },
|
|
update: columns,
|
|
select: { id: true },
|
|
});
|
|
|
|
return {
|
|
outcome: existing ? ("updated" as const) : ("inserted" as const),
|
|
id: row.id,
|
|
sampleCount,
|
|
durationSeconds,
|
|
};
|
|
});
|
|
} catch (err) {
|
|
// A concurrent writer claimed the recording between the lookup and the
|
|
// write. The index held; re-resolve to the same honest verdict rather
|
|
// than surfacing a constraint violation to a client that did nothing
|
|
// wrong.
|
|
if (
|
|
err instanceof Prisma.PrismaClientKnownRequestError &&
|
|
err.code === "P2002"
|
|
) {
|
|
const twin = await db.$transaction(async (tx) =>
|
|
tx.ecgRecording.findUnique({
|
|
where: recordingKey,
|
|
select: { id: true },
|
|
}),
|
|
);
|
|
if (twin) {
|
|
return {
|
|
outcome: "duplicate",
|
|
id: twin.id,
|
|
sampleCount,
|
|
durationSeconds,
|
|
};
|
|
}
|
|
}
|
|
throw err;
|
|
} finally {
|
|
waveformEncrypted.fill(0);
|
|
samples.fill(0);
|
|
}
|
|
}
|