app/lib/health/snapshot.mjs

Functions

Imports

It imports no other module of this repo. Imported by app/lib/health/snapshot.server.ts.

Source

1// Written only by /api/health, which the watchdog polls, so the tile's AGE is the watchdog's liveness:
2// nothing else may stamp this key. Measured: running the suite in the home loader cost about 1.2 s.
3
4/** One key, not a prefix: a prefix would invite a second writer. */
5export const HEALTH_SNAPSHOT_KEY = "health:snapshot";
6
7/** Restates the watchdog cron in wrangler.watchdog.jsonc, which a Worker cannot read. Change both together. */
8export const HEALTH_POLL_INTERVAL_SECONDS = 15 * 60;
9
10/** Three intervals: a Cron Trigger is best effort, and a tile that flaps on one missed poll gets muted. */
11export const HEALTH_SNAPSHOT_STALE_AFTER_SECONDS = 3 * HEALTH_POLL_INTERVAL_SECONDS;
12
13/**
14 * @typedef {{ ok: boolean, total: number, failed: number, readAt: string }} HealthSnapshot
15 */
16
17/**
18 * @typedef {(
19 *   | { state: "fresh", ok: boolean, total: number, failed: number, readAt: string, ageSeconds: number }
20 *   | { state: "stale", ok: boolean, total: number, failed: number, readAt: string, ageSeconds: number }
21 *   | { state: "missing" }
22 *   | { state: "unreadable" }
23 * )} HealthTile
24 */
25
26/**
27 * Fails to "missing" in every uncertain direction, including a FUTURE timestamp: this is untyped KV JSON,
28 * and a cached page presenting a bad value as a verdict would be lying.
29 *
30 * @param {unknown} snapshot the parsed KV value, or null
31 * @param {number} nowMs
32 * @returns {HealthTile}
33 */
34export function healthTile(snapshot, nowMs) {
35  if (!snapshot || typeof snapshot !== "object") return { state: "missing" };
36
37  const value = /** @type {Record<string, unknown>} */ (snapshot);
38  const { ok, total, failed, readAt } = value;
39
40  if (typeof readAt !== "string") return { state: "missing" };
41  if (typeof ok !== "boolean") return { state: "missing" };
42  if (!Number.isFinite(total) || !Number.isFinite(failed)) return { state: "missing" };
43
44  const takenMs = Date.parse(readAt);
45  if (!Number.isFinite(takenMs)) return { state: "missing" };
46
47  const ageSeconds = Math.floor((nowMs - takenMs) / 1000);
48  if (ageSeconds < 0) return { state: "missing" };
49
50  return {
51    state: ageSeconds > HEALTH_SNAPSHOT_STALE_AFTER_SECONDS ? "stale" : "fresh",
52    ok,
53    total: /** @type {number} */ (total),
54    failed: /** @type {number} */ (failed),
55    readAt,
56    ageSeconds,
57  };
58}
59
60/**
61 * No seconds: on a fifteen minute schedule "47 seconds ago" claims a precision the arrangement lacks.
62 *
63 * @param {number} ageSeconds
64 * @returns {string}
65 */
66export function formatAge(ageSeconds) {
67  if (ageSeconds < 60) return "under a minute ago";
68  const minutes = Math.floor(ageSeconds / 60);
69  if (minutes < 60) return `${minutes} minute${minutes === 1 ? "" : "s"} ago`;
70  const hours = Math.floor(minutes / 60);
71  if (hours < 24) return `${hours} hour${hours === 1 ? "" : "s"} ago`;
72  const days = Math.floor(hours / 24);
73  return `${days} day${days === 1 ? "" : "s"} ago`;
74}
75
76/**
77 * Counts only: per-check details carry an R2 key and shadow table names, and the home page is public.
78 *
79 * @param {{ ok: boolean, checks: Array<{ ok: boolean }> }} body
80 * @param {string} readAt an ISO 8601 timestamp
81 * @returns {HealthSnapshot}
82 */
83export function snapshotFromBody(body, readAt) {
84  return {
85    ok: body.ok,
86    total: body.checks.length,
87    failed: body.checks.filter((c) => !c.ok).length,
88    readAt,
89  };
90}