app/routes/api.health.ts

Functions

Imports

It imports app/lib/backup/age.server.ts, app/lib/client-ip.ts, app/lib/context.ts, app/lib/error-message.mjs, app/lib/health/checks.server.ts, app/lib/health/snapshot.server.ts, app/lib/health/verdicts.mjs, app/lib/rate-limit.mjs. No module of this repo imports it.

Source

1/**
2 * `no-store` is load bearing: a health check served from cache is not a health check. Stated here
3 * although workers/app.ts defaults it, because that default exists for forgotten headers.
4 */
5
6import { clientIp } from "~/lib/client-ip";
7import { getEnv } from "~/lib/context";
8import { limitHit } from "~/lib/rate-limit.mjs";
9import { runHealthChecks } from "~/lib/health/checks.server";
10import { publicHealthBody } from "~/lib/health/verdicts.mjs";
11import { writeHealthSnapshot } from "~/lib/health/snapshot.server";
12import { backupAge } from "~/lib/backup/age.server";
13
14import type { Route } from "./+types/api.health";
15import { errorMessage } from "~/lib/error-message.mjs";
16
17const HEALTH_RATE_LIMIT = 20;
18const HEALTH_RATE_PERIOD_SECONDS = 60;
19
20/** A cacheable 503 would keep reporting a failure after the site recovered. */
21const HEALTH_HEADERS = {
22  "Cache-Control": "no-store",
23  "Content-Type": "application/json; charset=utf-8",
24};
25
26function healthJson(body: unknown, status: number, extra: HeadersInit = {}): Response {
27  /* `Headers` rather than a spread, so a caller cannot shadow `Cache-Control` with a different case. */
28  const headers = new Headers(HEALTH_HEADERS);
29  for (const [name, value] of new Headers(extra)) headers.set(name, value);
30  return new Response(JSON.stringify(body), { status, headers });
31}
32
33/**
34 * The status code is the alert: `curl --fail` reads a 200 carrying `{"ok": false}` as health. The
35 * body carries names and booleans only: details include row counts and an R2 key, and this is public.
36 */
37export async function loader({ request, context }: Route.LoaderArgs) {
38  const env = getEnv(context);
39
40  /*
41   * First because everything below costs: five checks against D1, R2 and AI Search, unauthenticated.
42   * Without the limiter this does not serve.
43   */
44  /*
45   * A limiter that threw is not a limiter that said yes, so 503 rather than fail open. Neither name is
46   * in `REPAIRABLE`, so a broken limiter alerts rather than firing a rebuild.
47   */
48  let verdict: Awaited<ReturnType<typeof limitHit>>;
49  try {
50    verdict = await limitHit(
51      env,
52      `health:${clientIp(request)}`,
53      HEALTH_RATE_LIMIT,
54      HEALTH_RATE_PERIOD_SECONDS,
55    );
56  } catch (error) {
57    // Logged by name: the wire body carries names only, so this line is the whole record of why.
58    console.error(
59      JSON.stringify({
60        alert: "health-rate-limiter-threw",
61        error: errorMessage(error),
62      }),
63    );
64    return healthJson({ ok: false, checks: [{ name: "rate-limiter-failed", ok: false }] }, 503);
65  }
66
67  if (verdict.status === "unavailable") {
68    return healthJson(
69      { ok: false, checks: [{ name: "rate-limiter-unavailable", ok: false }] },
70      503,
71    );
72  }
73  if (verdict.status === "limited") {
74    return healthJson(
75      { ok: false, checks: [{ name: "rate-limited", ok: false }] },
76      429,
77      { "Retry-After": String(verdict.retryAfterSeconds) },
78    );
79  }
80
81  try {
82    const run = await runHealthChecks(env);
83    const body = publicHealthBody(run);
84
85    if (!body.ok) {
86      // `invocation_logs: false` drops the automatic per-request record, not custom logs, so the detail
87      // the wire omits is still recoverable.
88      console.error(
89        JSON.stringify({
90          alert: "health-check-failed",
91          failed: run.failed.map((c) => c.name),
92          detail: run.failed.map((c) => c.detail),
93        }),
94      );
95    }
96
97    /*
98     * Written for both verdicts, or the home tile would keep showing the last good answer while the site
99     * failed. The failure path writes nothing, so the tile ages into `stale`.
100     */
101    await writeHealthSnapshot(env, body, new Date().toISOString());
102
103    /*
104     * Reported beside the checks and NOT one of them: a stale dump must not turn the verdict red,
105     * because ship refuses unless this is ok and the first deploy that adds the dump has none yet.
106     * Two fields and no message, since this is public; the watchdog throws when the dump fails.
107     */
108    return healthJson({ ...body, backup: await backupAge(env) }, body.ok ? 200 : 503);
109  } catch (error) {
110    console.error(
111      JSON.stringify({
112        alert: "health-run-threw",
113        error: errorMessage(error),
114      }),
115    );
116    return healthJson({ ok: false, checks: [{ name: "health-run", ok: false }] }, 503);
117  }
118}
119
120/**
121 * React Router's default 405 has no `Allow` header and a body that says the server broke. No rate
122 * limit: metering costs more than the refusal. `Allow: GET` only, because the platform answers HEAD
123 * by running the loader.
124 */
125export async function action() {
126  return healthJson(
127    { ok: false, checks: [{ name: "method-not-allowed", ok: false }] },
128    405,
129    { Allow: "GET" },
130  );
131}