Files
HealthLog/src/lib/jobs/insight-pregenerate-shared.ts
T
Marc-André Bombeck 43361bd74e fix(daily): write the briefing for the reader's own morning and readings
With signals of the day resting on today's readings only, the briefing
had to be written after those readings, and it was only written at the
04:30 Berlin warm, the post-sleep morning refresh, or a page open on a
day-old cache. A morning blood pressure or weigh-in never became a
signal, and since an earlier day's briefing is no longer served, a
reader in Los Angeles or Seoul had none for most of the day: the Berlin
warm lands the previous evening there, or at noon.

The snapshot read every surface goes through (dashboard, iOS, digest,
morning push) now asks for a briefing for today at two moments: the
first read of the reader's local day with no briefing written today,
and the first read after a signal metric's first reading of the day
that the briefing has not read. Each reason is claimed once per user
per local day in a Postgres bucket and remembered in-process, so later
reads cost no query; no write path needs a hook.

A claim enqueues one today warm: immediately for a new day, after a
five-minute window for readings, so a burst (weigh-in, then blood
pressure) folds into one job. The warm writes the comprehensive
briefing only, past the one-hour freshness gate but under the failure
backoff, the daily forced-warm cap (two per 24 h) and the content-hash
gate.

Worst case per user per local day: one enqueue per reason, at most
eight (the day plus seven signal reading types, measured over a day of
reads every two minutes); at most two forced comprehensive attempts
under the existing cap, each at most three completions (the answer, a
JSON retry, a grounding retry), so six provider calls at the ceiling.
A warm whose data has not changed costs at most the existing
once-a-day paragraph re-roll, inside the same cap.
2026-10-05 22:09:41 +02:00

248 lines
9.4 KiB
TypeScript
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* v1.8.7.1 — generator-free contract for the insight-pregenerate queue.
*
* The on-demand warm route (`POST /api/insights/pregenerate`) enqueues a
* forced full-warm job here without importing the concrete generators
* (which would pull the whole `comprehensive-generate` + seven `*-status`
* tree into the route bundle and risk an import cycle). The worker-only
* pipeline (`runInsightPregenerate`, `forceWarmUser`) lives in
* `insight-pregenerate.ts`, which re-exports the queue name from here so
* there is a single source of truth.
*
* Mirrors the `insight-status-generate-shared.ts` split exactly: queue
* name + payload type + enqueue helper in the generator-free module, the
* concrete dispatch in the worker module.
*/
import type { SupportedLocale } from "@/lib/insights/status-shared";
import { getGlobalBoss } from "@/lib/jobs/boss-instance";
import { annotate } from "@/lib/logging/context";
export const INSIGHT_PREGENERATE_QUEUE = "insight-pregenerate";
/**
* The job's expiry: three hours. The scheduled pass walks up to 200 accounts
* with a comprehensive generation each, which can outlast pg-boss's fifteen
* minute default; past it pg-boss retried the job beside the pass still
* running. The pass now stops itself at three quarters of this (`jobBudget`)
* and holds a lock (`lockedPass`), and every send and the schedule carry it.
*/
export const INSIGHT_PREGENERATE_EXPIRE_SECONDS = 3 * 60 * 60;
export interface InsightPregeneratePayload {
/** Set on the nightly scheduled tick (informational; the handler keys
* its batch behaviour off the ABSENCE of `userId`/`force`). */
triggeredAt?: string;
/**
* Forced single-user warm. When `force` is set the worker runs the
* full per-user warm for `userId` directly, bypassing the candidate
* scan AND the per-user 20 h budget bucket.
*/
userId?: string;
force?: boolean;
/**
* Locale to warm on the forced path. Carries the reader's full UI locale
* (one of the six); the handler validates it and defaults an absent or
* unrecognised value to English.
*/
locale?: SupportedLocale;
/**
* A briefing-for-today warm (`enqueueTodayBriefingWarm`): the day started
* with no briefing written today, or a signal metric got its first
* reading of the day after the briefing was written. Runs the
* comprehensive briefing only, past the one-hour freshness gate (a
* reading at 07:05 after a warm at 07:00 is exactly what it is for), and
* under the same failure backoff and daily forced-warm cap.
*/
today?: boolean;
}
/**
* Fire-and-forget enqueue used by the on-demand warm route. A
* `singletonKey` per user collapses repeated requests within a short
* window into one queued job, so a client that taps the button twice
* (or the auto-trigger races a manual tap) can't double-warm. The key
* is deliberately locale-free: a German web session and an English
* Accept-Language client racing each other would otherwise enqueue two
* near-identical full warms back to back; the first job's locale wins
* the window and the other locale warms lazily through the read-path
* enqueue (v1.16.8). No-ops cleanly when the global boss instance is
* not available (e.g. a web process without an embedded worker) — the
* nightly cron remains the catch-net.
*/
export async function enqueueForceWarm(payload: {
userId: string;
locale: SupportedLocale;
}): Promise<void> {
const boss = getGlobalBoss();
if (!boss) {
annotate({
action: { name: "insights.pregenerate.force.no_boss" },
meta: { locale: payload.locale },
});
return;
}
try {
await boss.send(
INSIGHT_PREGENERATE_QUEUE,
{
userId: payload.userId,
force: true,
locale: payload.locale,
} satisfies InsightPregeneratePayload,
{
singletonKey: `force:${payload.userId}`,
expireInSeconds: INSIGHT_PREGENERATE_EXPIRE_SECONDS,
// De-dupe within a 6-minute window. v1.16.8 — widened from 120 s:
// the client's revalidation poll runs up to ~250 s after a stale
// page-open, so a 2-minute singleton let the tail of one poll
// cycle enqueue a second (and third) full warm while the first
// was still running. 360 s outlives the poll horizon, so a stale
// page-open collapses to exactly one queued warm; the worker-side
// freshness re-check in `forceWarmUser` is the second guard.
singletonSeconds: 360,
// Transient provider / pool failures retry with backoff instead
// of leaving every cache cold until the nightly cron.
retryLimit: 3,
retryDelay: 60,
retryBackoff: true,
},
);
annotate({
action: { name: "insights.pregenerate.force.enqueued" },
meta: { locale: payload.locale },
});
} catch {
// Enqueue is best-effort; a failure here just means the caches stay
// cold until the next poll / nightly cron warms them.
}
}
/**
* How long a today warm waits before it runs, and the window that folds
* every request inside it into one job. A morning weigh-in, the blood
* pressure five minutes later and the sync that brings both arrive as one
* burst; one warm after the burst reads all of it.
*/
export const TODAY_WARM_DELAY_SECONDS = 5 * 60;
/**
* Enqueue the briefing-for-today warm. `immediate` is for the day's first
* read with no briefing written today, where nobody is waiting on a burst
* of readings; otherwise the job starts after the burst window. The
* singleton per user folds requests in the window into one job; what runs
* is still bounded by the warm's own gates (failure backoff, the daily
* forced-warm cap) and the generation's content-hash gate.
*/
export async function enqueueTodayBriefingWarm(payload: {
userId: string;
locale: SupportedLocale;
immediate: boolean;
}): Promise<void> {
const boss = getGlobalBoss();
if (!boss) {
annotate({
action: { name: "insights.pregenerate.today.no_boss" },
meta: { locale: payload.locale },
});
return;
}
try {
await boss.send(
INSIGHT_PREGENERATE_QUEUE,
{
userId: payload.userId,
force: true,
today: true,
locale: payload.locale,
} satisfies InsightPregeneratePayload,
{
singletonKey: `today:${payload.userId}`,
singletonSeconds: TODAY_WARM_DELAY_SECONDS,
startAfter: payload.immediate ? 0 : TODAY_WARM_DELAY_SECONDS,
expireInSeconds: INSIGHT_PREGENERATE_EXPIRE_SECONDS,
retryLimit: 2,
retryDelay: 60,
retryBackoff: true,
},
);
annotate({
action: { name: "insights.pregenerate.today.enqueued" },
meta: { locale: payload.locale, immediate: payload.immediate },
});
} catch {
// Best-effort, like every warm enqueue: the next read asks again.
}
}
/**
* Delay before the single bounded retry of a failed nightly comprehensive
* warm. 45 minutes: far enough out that a transient 02:30–04:30 provider
* brown-out has usually cleared, early enough that the retry lands before
* the user's morning visit.
*/
export const PREGENERATE_RETRY_DELAY_SECONDS = 45 * 60;
/**
* Bounded intra-day retry for a user whose NIGHTLY comprehensive warm
* failed. Without this, a single 04:30 provider hiccup left the user's
* briefing stale until the next night: the nightly tick is the only
* scheduled machinery, the GET path's warm enqueue only fires once the
* cache crosses the 24 h freshness line (often mid-evening), and the POST
* cache short-circuit served the stale payload all day.
*
* Enqueues ONE delayed forced single-user warm (the same `forceWarmUser`
* pipeline the on-demand route uses), so every existing bound still
* applies at execution time: the job-start freshness re-check, the
* failure backoff, and the per-user daily forced-warm cap. `singletonKey`
* collapses repeated failures within the window into one queued retry.
* Best-effort like `enqueueForceWarm`: no boss instance → annotated no-op,
* the nightly tick remains the catch-net.
*/
export async function enqueuePregenerateFailureRetry(payload: {
userId: string;
locale: SupportedLocale;
}): Promise<void> {
const boss = getGlobalBoss();
if (!boss) {
annotate({
action: { name: "insights.pregenerate.retry.no_boss" },
meta: { locale: payload.locale },
});
return;
}
try {
await boss.send(
INSIGHT_PREGENERATE_QUEUE,
{
userId: payload.userId,
force: true,
locale: payload.locale,
} satisfies InsightPregeneratePayload,
{
startAfter: PREGENERATE_RETRY_DELAY_SECONDS,
// Distinct from the on-demand `force:` key so a user's page-open
// warm can never swallow the scheduled retry (and vice versa);
// one retry per user per window.
singletonKey: `retry:${payload.userId}`,
expireInSeconds: INSIGHT_PREGENERATE_EXPIRE_SECONDS,
singletonSeconds: 3600,
// A worker crash mid-warm re-runs the job; a warm that completes
// with a failed comprehensive does NOT throw, so this cannot loop.
retryLimit: 2,
retryDelay: 300,
retryBackoff: true,
},
);
annotate({
action: { name: "insights.pregenerate.retry.enqueued" },
meta: {
locale: payload.locale,
delay_seconds: PREGENERATE_RETRY_DELAY_SECONDS,
},
});
} catch {
// Best-effort: a failed enqueue leaves the nightly tick as the
// catch-net, exactly the pre-retry behaviour.
}
}