mirror of
https://github.com/MBombeck/HealthLog.git
synced 2026-11-08 04:32:42 +00:00
Marc-André Bombeck
46047e57c0
A history backfill carried one access token through walks that outlive it. After an hour every request answered 401, which classifies as a revoked grant, so the account was parked at error_reauth with a refresh token that was still valid, and every later run skipped it until a manual reconnect. Running beside the hourly sync, the backfill also pushed the account over Google's per-minute quota, and each 429 failed its whole collection. - Walks take a token source that renews the access token before it expires and once more when Google refuses it mid-walk. - A 429 is waited out (Retry-After, RetryInfo, else a doubling backoff) and the request repeated; it is never a reauth. - error_reauth only short-circuits a run when the token endpoint refused the grant (needsReauth). A connection parked by a data request's 401 refreshes on its next run and clears itself when that run completes. - One run per account at a time: syncs, the backfill and the sleep repair share an advisory lock. The hourly poll skips a held account, a manual sync answers 409 sync_in_progress, the backfill waits a bounded time. - A backfill attempt records each collection it finishes cleanly (backfill_progress) and the next attempt resumes with the rest. - The incremental watermark is stamped with the cycle's start, not its end. Overlapping sleep segments that share a stage and an end share the natural key (type, measuredAt, source, sleepStage). A re-score that moved one row onto a sibling's slot threw P2002 and failed the sync on every run. - A batch keeps one reading per natural key, chosen the same way each time (longer segment, then smaller externalId). - A move that still collides is settled by reconcileExternalMeasurement, which retires the stale row, instead of failing the sync. - Updates run before inserts, and the key-format rescue no longer re-keys a row this batch is moving. - The sleep replace-by-window protects every session's fresh rows, so two overlapping sessions no longer tombstone and resurrect each other hourly. Refs #1194, #1195
prisma/
The database layer. HealthLog runs PostgreSQL 16 via Prisma 7. This directory holds the single schema file and the forward-only migration history; the generated client is emitted elsewhere.
Contents
schema.prisma— 61 models, one file.cuid()primary keys,snake_casecolumns via@map(...), encrypted columns mostly suffixed*Encrypted(search the file; there are 24 encrypted column references). Thegenerator clientblock emits to../src/generated/prisma(imported as@/generated/prisma).migrations/— numbered, forward-only SQL migrations (0001_…upward).migration_lock.tomlpins the provider topostgresql.
Migration workflow
# author a migration from a schema edit
pnpm dlx prisma migrate dev --name <short_snake_case_name>
# regenerate the client after any schema change
pnpm dlx prisma generate
Number a new migration with the next free prefix. The production entrypoint runs prisma migrate deploy on boot, so every migration must apply cleanly forward — there is no down-migration path. Always include the migration file in the same change as the schema edit.
Conventions
- Encryption is fail-closed:
*Encryptedcolumns are written through@/lib/crypto(AES-256-GCM, versioned key ids); never store plaintext in an encrypted column. Key rotation isscripts/rotate-encryption-key.ts+docs/ops/encryption-key-rotation.md. - The generated client under
src/generated/prismais build output — do not edit it. - Schema-touching changes that affect the API surface must regenerate
docs/api/openapi.yaml(see../CLAUDE.md).
Related: ../src/lib/README.md (db.ts, rollups/), ../docs/ops/ (migrations + backup runbooks).