src/health.ts

Functions

Imports

It imports src/doc-index.ts, src/env.ts, src/ops-types/sites.ts, src/store-probe.ts, src/time.ts. Imported by src/backup.ts, src/ops-snapshot.ts, src/routes.ts, src/site-check.ts, src/watcher-detect.ts, src/watcher-gather.ts, src/watcher.ts.

Source

1import type { Env } from "./env";
2import type { HealthSnapshot } from "./ops-types/sites";
3import { probeFts } from "./store-probe";
4import { aiSearchUsage } from "./doc-index";
5import { HOUR_MS } from "./time";
6
7export const BACKUP_LAST_OK_KEY = "backup:last-ok";
8// Daily cron is 24h; 26h is that plus a 2h grace so one slow run does not warn.
9export const BACKUP_STALE_HOURS = 26;
10
11async function backupFreshness(
12  env: Env
13): Promise<{ last_ok: string | null; age_hours: number | null; warning?: string }> {
14  let lastOk: string | null = null;
15  try {
16    lastOk = await env.APP_KV.get(BACKUP_LAST_OK_KEY);
17  } catch (err) {
18    return {
19      last_ok: null,
20      age_hours: null,
21      warning: `backup freshness unreadable: ${(err instanceof Error ? err.message : String(err)).slice(0, 80)}`,
22    };
23  }
24  if (!lastOk) return { last_ok: null, age_hours: null, warning: "no successful backup recorded" };
25  const stamped = Date.parse(lastOk);
26  // NaN compares false against the threshold, so without this an unreadable stamp
27  // would pass as fresh with no warning.
28  if (Number.isNaN(stamped)) {
29    return { last_ok: lastOk, age_hours: null, warning: `${BACKUP_LAST_OK_KEY} is not a parseable time: ${lastOk.slice(0, 40)}` };
30  }
31  const ageMs = Date.now() - stamped;
32  const ageHours = Math.round((ageMs / HOUR_MS) * 10) / 10;
33  const result: { last_ok: string; age_hours: number; warning?: string } = { last_ok: lastOk, age_hours: ageHours };
34  if (ageMs > BACKUP_STALE_HOURS * HOUR_MS) {
35    result.warning = `last successful backup was ${ageHours}h ago, over the ${BACKUP_STALE_HOURS}h threshold`;
36  }
37  return result;
38}
39
40function probeError(err: unknown): string {
41  return `error: ${(err instanceof Error ? err.message : String(err)).slice(0, 120)}`;
42}
43
44// The two bindings beside the store. Each probe reads a key that need not exist: a
45// null answer proves the binding resolves. Reported as fields, left out of status.
46async function probeBindings(env: Env): Promise<{ media: string; app_kv: string }> {
47  let media = "unbound";
48  if (env.MEDIA) {
49    try {
50      await env.MEDIA.head("health-probe");
51      media = "ok";
52    } catch (err) {
53      media = probeError(err);
54    }
55  }
56  let app_kv = "unbound";
57  if (env.APP_KV) {
58    try {
59      await env.APP_KV.get("health-probe");
60      app_kv = "ok";
61    } catch (err) {
62      app_kv = probeError(err);
63    }
64  }
65  return { media, app_kv };
66}
67
68export interface HealthReport extends HealthSnapshot {
69  // Capsid's own hybrid searches this month against its cap (design-hybrid-search 3.5).
70  // Informational; null when KV cannot be read, absent from snapshots taken before it.
71  ai_search?: { month: string; hybrid: number; cap: number } | null;
72}
73
74// /health serializes this and the watcher's pass records it for Capsid Portal, so the
75// Portal shows the same values the live gate asserts.
76export async function healthReport(env: Env): Promise<HealthReport> {
77  const provenance = {
78    sha: env.BUILD_SHA ?? "unknown",
79    dirty: env.BUILD_DIRTY === "true",
80    builtAt: env.BUILT_AT ?? null,
81  };
82
83  let d1 = "unbound";
84  let fts = "skipped";
85  try {
86    const one = await env.DB.prepare("SELECT 1 AS ok").first<{ ok: number }>();
87    d1 = one?.ok === 1 ? "ok" : `unexpected: ${JSON.stringify(one)}`;
88  } catch (err) {
89    d1 = `error: ${(err instanceof Error ? err.message : String(err)).slice(0, 120)}`;
90  }
91  if (d1 === "ok") fts = await probeFts(env.DB);
92
93  // Informational. A store without d1_migrations is null, not a health failure.
94  let schema_version: string | null = null;
95  if (d1 === "ok") {
96    try {
97      const row = await env.DB.prepare("SELECT name FROM d1_migrations ORDER BY id DESC LIMIT 1").first<{ name: string }>();
98      schema_version = row?.name ?? null;
99    } catch {
100      schema_version = null;
101    }
102  }
103
104  const backup = await backupFreshness(env);
105  const bindings = await probeBindings(env);
106  const ai_search = await aiSearchUsage(env).catch(() => null);
107
108  // Status is the store only: the live gate polls it after a deploy, and a 503 fails it.
109  const healthy = d1 === "ok" && fts === "ok";
110  return { status: healthy ? "ok" : "degraded", ...provenance, schema_version, store: { d1, fts }, bindings, backup, ai_search };
111}
112
113export async function handleHealth(env: Env): Promise<Response> {
114  const report = await healthReport(env);
115  return Response.json(report, { status: report.status === "ok" ? 200 : 503 });
116}