src/site-convergence.ts

Functions

Imports

It imports src/env.ts, src/ops-sites.ts, src/ops-types/sites.ts, src/ops-types/views.ts, src/secret-presence.ts, src/site-operator.ts, src/site-repair.ts. Imported by src/portal-convergence.ts.

Source

1import type { Env } from "./env";
2import { readSiteConfig } from "./ops-sites";
3import type { OpsSiteConfig, SiteOperator } from "./ops-types/sites";
4import type { ConvergenceCheck, ConvergenceSite } from "./ops-types/views";
5import { REPAIR_AUDIT_ACTION } from "./site-repair";
6import { callOperator, tokenSet, toolRefusal, type FetchLike } from "./site-operator";
7import { readStoredSecrets } from "./secret-presence";
8
9// THE CONVERGENCE VIEW (job_09e5f6cbf782): per site that opted in, what its own operator
10// API says (sync_status: the repository count against D1, the search index and the Ask
11// index, and any named divergence) beside what its health route says per content type,
12// each failing check with the repair it maps to and whether Capsid may run it, and the
13// site Worker's secrets by name, set or not. The operator API and the health route are read
14// live when the Portal asks: a view a pass old shows a repair that already ran as still
15// needed. The secret names are the watcher's last read (src/secret-presence.ts), because no
16// Portal request calls Cloudflare (test/ops-cloudflare.test.ts).
17// Every part fails on its own and says why, so one unreadable part is never shown as zero.
18
19const HEALTH_TIMEOUT_MS = 10_000;
20const TEXT_MAX = 300;
21const STATUS_FIELDS_MAX = 40;
22const RECENT_REPAIRS = 5;
23
24const clip = (s: string) => (s.length > TEXT_MAX ? `${s.slice(0, TEXT_MAX - 1)}…` : s);
25
26/** A health body's checks, each with the repair it maps to. Only the fields the view shows
27 *  are kept, as text or numbers: the body is the site's, read as data. */
28export function healthChecks(body: unknown, operator: SiteOperator): ConvergenceCheck[] {
29  const checks = (body as { checks?: unknown } | null)?.checks;
30  if (!Array.isArray(checks)) return [];
31  const out: ConvergenceCheck[] = [];
32  for (const c of checks) {
33    if (!c || typeof c !== "object" || typeof (c as { name?: unknown }).name !== "string") continue;
34    const row = c as Record<string, unknown>;
35    const name = clip(row.name as string);
36    const tool = Object.hasOwn(operator.repairs, name) ? operator.repairs[name] : null;
37    const said = [row.detail, row.message, row.reason].find((v) => typeof v === "string") as string | undefined;
38    const num = (v: unknown) => (typeof v === "number" && Number.isFinite(v) ? v : null);
39    out.push({
40      name,
41      ok: row.ok === true,
42      detail: said ? clip(said) : null,
43      expected: num(row.expected),
44      present: num(row.present),
45      repair: tool,
46      repair_refusal: tool ? toolRefusal(operator, tool) : null,
47    });
48  }
49  return out;
50}
51
52/** sync_status's scalar fields as label and text, and its divergence list as lines. */
53export function statusFields(data: unknown): Array<{ key: string; value: string }> {
54  if (!data || typeof data !== "object") return [];
55  const out: Array<{ key: string; value: string }> = [];
56  for (const [key, value] of Object.entries(data as Record<string, unknown>)) {
57    if (out.length >= STATUS_FIELDS_MAX) break;
58    if (typeof value === "number" || typeof value === "boolean") out.push({ key, value: String(value) });
59    else if (typeof value === "string") out.push({ key, value: clip(value) });
60    else if (key === "divergences" && value && typeof value === "object") {
61      const d = value as { known?: unknown; list?: unknown; divergences?: unknown };
62      const list = Array.isArray(d.list) ? d.list : Array.isArray(d.divergences) ? d.divergences : Array.isArray(value) ? (value as unknown[]) : null;
63      if (d.known === false) out.push({ key, value: "not known (the record could not be read)" });
64      else if (list) out.push({ key, value: list.length === 0 ? "none" : clip(list.map((x) => (typeof x === "string" ? x : JSON.stringify(x))).join("; ")) });
65    }
66  }
67  return out;
68}
69
70async function readHealth(fetchImpl: FetchLike, url: string): Promise<{ status: number; body: unknown; error: string | null }> {
71  try {
72    const res = await fetchImpl(url, { headers: { "user-agent": "capsid", "cache-control": "no-cache" }, redirect: "manual", signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS) });
73    return { status: res.status, body: await res.json().catch(() => null), error: null };
74  } catch (err) {
75    return { status: 0, body: null, error: clip(err instanceof Error ? err.message : String(err)) };
76  }
77}
78
79/** One site's view. */
80async function readSiteConvergence(env: Env, site: OpsSiteConfig, fetchImpl: FetchLike, now: Date): Promise<ConvergenceSite> {
81  const base = { namespace: site.namespace, name: site.name, origin: site.origin ?? "", read_at: now.toISOString() };
82  if (!site.origin || !site.operator) {
83    return { ...base, operator: null, problem: site.operator_problem ?? "no operator API configured", status: null, health: null, secrets: null, recent: [] };
84  }
85  const operator = site.operator;
86  const secretSet = tokenSet(env, operator);
87
88  const status = secretSet
89    ? await callOperator(env, { origin: site.origin, operator }, "sync_status", fetchImpl, { reading: true }).then((c) =>
90        c.ok ? { ok: true as const, fields: statusFields(c.data), error: null } : { ok: false as const, fields: [], error: c.error }
91      )
92    : { ok: false as const, fields: [], error: `the Capsid Worker secret ${operator.auth_var} is not set, so the operator API was not called.` };
93
94  const h = site.health_path ? await readHealth(fetchImpl, site.origin + site.health_path) : null;
95  const health = !h
96    ? { ok: false, http_status: null, checks: [], error: "the site has no health route configured" }
97    : { ok: h.status === 200 && (h.body as { ok?: unknown } | null)?.ok === true, http_status: h.status || null, checks: healthChecks(h.body, operator), error: h.error };
98
99  const stored = await readStoredSecrets(env, site.namespace);
100  const secrets: ConvergenceSite["secrets"] =
101    operator.secrets.length === 0
102      ? { state: "none", script: null, rows: [], reason: "the configuration names no secrets to check" }
103      : stored ?? { state: "none", script: null, rows: [], reason: "the watcher has not read this Worker's secret names yet; it does on its next pass" };
104
105  const { results } = await env.DB.prepare(
106    "SELECT actor, params, at FROM audit_log WHERE action = ?1 AND namespace = ?2 ORDER BY id DESC LIMIT ?3"
107  )
108    .bind(REPAIR_AUDIT_ACTION, site.namespace, RECENT_REPAIRS)
109    .all<{ actor: string; params: string | null; at: string }>();
110  const recent = (results ?? []).map((r) => {
111    let p: Record<string, unknown> = {};
112    try {
113      p = r.params ? (JSON.parse(r.params) as Record<string, unknown>) : {};
114    } catch {
115      p = {};
116    }
117    return {
118      // audit_log.at is SQLite's "YYYY-MM-DD HH:MM:SS" in UTC.
119      at: /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(r.at) ? `${r.at.replace(" ", "T")}Z` : r.at,
120      actor: r.actor,
121      tool: typeof p.tool === "string" ? p.tool : "?",
122      via: typeof p.via === "string" ? p.via : null,
123      converged: typeof p.converged === "boolean" ? p.converged : null,
124      error: typeof p.error === "string" ? clip(p.error) : null,
125    };
126  });
127
128  return {
129    ...base,
130    operator: { path: operator.path, auth_var: operator.auth_var, secret_set: secretSet, repairs: operator.repairs, weekly: operator.weekly },
131    problem: null,
132    status,
133    health,
134    secrets,
135    recent,
136  };
137}
138
139/** Every site that opted in, or has a stored configuration it cannot use. */
140export async function readConvergence(env: Env, fetchImpl: FetchLike, now: Date): Promise<ConvergenceSite[]> {
141  const config = (await readSiteConfig(env.DB)).filter((c) => c.origin && (c.operator || c.operator_problem));
142  const out: ConvergenceSite[] = [];
143  for (const site of config) out.push(await readSiteConvergence(env, site, fetchImpl, now));
144  return out;
145}