src/ops-sites.ts

Functions

Imports

It imports src/ops-types/sites.ts, src/site-operator.ts, src/store-guards.ts. Imported by src/controls-perform.ts, src/controls-plan.ts, src/inbox.ts, src/live-checks.ts, src/model-drift.ts, src/ops-cloudflare.ts, src/ops-feed.ts, src/ops-snapshot.ts, src/routes.ts, src/shared-code.ts, src/site-check.ts, src/site-convergence.ts, src/site-key.ts, src/site-repair.ts, src/site-reports.ts, src/watcher-detect.ts, src/watcher-gather.ts, src/watcher.ts, src/workers-builds.ts.

Source

1import type { OpsSiteConfig, SiteMapDrift } from "./ops-types/sites";
2import { auditStatement } from "./store-guards";
3import { parseOperator } from "./site-operator";
4
5// The sites the watcher probes for Capsid Portal (capsid/research/design-ops-console.md),
6// read from configuration, not code. Ruled 2026-09-29: "Portal
7// monitoring is optional and configured per install". The rows live in D1 (ops_sites,
8// migrations/0022_ops_sites.sql) and are edited in the Portal's Settings view through
9// the same preview and perform as every other control (src/portal-actions.ts). This
10// module reads them, validates an edit, and writes one.
11//
12// A row with an origin is a site. A row with no origin says its namespace serves no
13// site, so the site-map drift check can tell a decision from an omission. With no row
14// that has an origin, the watcher probes nothing and the Portal hides the Sites view.
15//
16// Why a table and not one settings record: each row is edited on its own, with a
17// guarded UPDATE on its revision, so two edits to different sites cannot overwrite
18// each other, and a stale preview of one site is refused without touching the rest.
19// The schema holds the platform to two values and the origin and platform to both or
20// neither. And the backup dumps every table in TABLES (src/backup.ts), so the
21// configuration is in the nightly dump with no extra step.
22
23export interface OpsSite {
24  namespace: string;
25  name: string;
26  origin: string;
27  // The site's own health route, or null where it has none; the probe then reads the
28  // root, which proves liveness and nothing more.
29  healthPath: string | null;
30  platform: "cloudflare" | "vercel";
31  // The Worker script that serves the site, named only where it is known. Every other
32  // Cloudflare site is resolved on each pass from the account's Workers custom domains
33  // (src/ops-cloudflare.ts), and one that resolves to nothing is shown as unresolved
34  // rather than guessed.
35  script?: string;
36  // Probed in-process through healthReport() instead of over HTTP: a Worker fetching
37  // its own workers.dev hostname is not a reliable probe of itself. Set by the seed for
38  // Capsid's own row only; the Portal cannot set it, and an edit that changes the
39  // origin clears it.
40  self?: true;
41}
42
43export type { OpsSiteConfig, SiteMapDrift };
44
45const SITE_PLATFORMS = ["cloudflare", "vercel"] as const;
46type SitePlatform = (typeof SITE_PLATFORMS)[number];
47
48// A bound, not a page: one row per namespace, and namespaces are registered by hand.
49const SITE_ROWS_LIMIT = 500;
50
51interface SiteRow {
52  namespace: string;
53  name: string;
54  origin: string | null;
55  health_path: string | null;
56  platform: SitePlatform | null;
57  script: string | null;
58  self_probe: number;
59  revision: number;
60  updated_at: string;
61  operator: string | null;
62}
63
64const SITE_COLUMNS = "namespace, name, origin, health_path, platform, script, self_probe, revision, updated_at, operator";
65
66function configFrom(row: SiteRow): OpsSiteConfig {
67  return {
68    namespace: row.namespace,
69    name: row.name,
70    origin: row.origin,
71    health_path: row.health_path,
72    platform: row.platform,
73    script: row.script,
74    self_probe: row.self_probe === 1,
75    revision: row.revision,
76    updated_at: row.updated_at,
77    ...operatorFrom(row.operator),
78  };
79}
80
81/** The stored operator JSON, parsed by the same rules an edit passes. A stored value that
82 *  no longer passes (a ceiling tightened since) is not used, and the reason is shown. */
83function operatorFrom(raw: string | null | undefined): Pick<OpsSiteConfig, "operator" | "operator_problem"> {
84  if (raw === null || raw === undefined) return { operator: null, operator_problem: null };
85  const parsed = parseOperator(raw);
86  return parsed.ok ? { operator: parsed.operator, operator_problem: null } : { operator: null, operator_problem: parsed.refusal };
87}
88
89/** Every configured row, sites and no-site declarations, by namespace. */
90export async function readSiteConfig(db: D1Database): Promise<OpsSiteConfig[]> {
91  const { results } = await db.prepare(`SELECT ${SITE_COLUMNS} FROM ops_sites ORDER BY namespace LIMIT ?1`).bind(SITE_ROWS_LIMIT).all<SiteRow>();
92  return (results ?? []).map(configFrom);
93}
94
95/** The rows that are sites, in the shape the probes and the Cloudflare read take. */
96export function sitesFrom(config: readonly OpsSiteConfig[]): OpsSite[] {
97  const out: OpsSite[] = [];
98  for (const c of config) {
99    if (c.origin === null || c.platform === null) continue;
100    out.push({
101      namespace: c.namespace,
102      name: c.name,
103      origin: c.origin,
104      healthPath: c.health_path,
105      platform: c.platform,
106      ...(c.script ? { script: c.script } : {}),
107      ...(c.self_probe ? { self: true as const } : {}),
108    });
109  }
110  return out;
111}
112
113// unmapped: registered, but in no row. unknown: in a row, but not registered.
114export function siteMapDrift(registered: readonly string[], config: readonly OpsSiteConfig[]): SiteMapDrift {
115  const covered = new Set(config.map((c) => c.namespace));
116  const known = new Set(registered);
117  return {
118    unmapped: registered.filter((ns) => !covered.has(ns)).sort(),
119    unknown: [...covered].filter((ns) => !known.has(ns)).sort(),
120  };
121}
122
123// ---- Validation -------------------------------------------------------------------------
124
125export interface SiteInput {
126  namespace: string;
127  name: string;
128  // null: the namespace serves no site.
129  origin: string | null;
130  health_path: string | null;
131  platform: SitePlatform | null;
132  script: string | null;
133  // The operator JSON as it will be stored, null to clear it, or undefined to leave an
134  // edited row's value as it is (an edit from a form that does not show it).
135  operator?: string | null;
136}
137
138export type Validated = { ok: true; site: SiteInput } | { ok: false; refusal: string };
139
140const NAMESPACE_SHAPE = /^[a-z0-9][a-z0-9-]{0,63}$/;
141const LABEL_SHAPE = /^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$/;
142const SCRIPT_SHAPE = /^[a-z0-9]([a-z0-9_-]{0,61}[a-z0-9])?$/;
143// Unreserved URL characters and the separator only: no query, no fragment, no percent
144// escape, no space. The probe appends this to the origin as it stands.
145const HEALTH_PATH_SHAPE = /^\/[A-Za-z0-9._~/-]{0,199}$/;
146const NAME_MAX = 80;
147const LOCAL_SUFFIXES = [".localhost", ".local", ".internal", ".home.arpa"];
148
149/** A hostname a probe may fetch: lowercase DNS labels, at least two, no IP literal and
150 *  no local name. Returns the refusal, or null when it is fine. */
151export function hostnameRefusal(host: string): string | null {
152  if (host.length === 0 || host.length > 253) return `the hostname '${host}' must be 1 to 253 characters.`;
153  if (host !== host.toLowerCase()) return `the hostname '${host}' must be lowercase.`;
154  if (host.startsWith("[") || /^[0-9.]+$/.test(host)) return `'${host}' is an IP address; a site is named by its hostname.`;
155  if (host === "localhost" || LOCAL_SUFFIXES.some((s) => host.endsWith(s))) {
156    return `'${host}' is a local name, which a probe from Cloudflare cannot reach.`;
157  }
158  const labels = host.split(".");
159  if (labels.length < 2) return `'${host}' is a single-label name; a site needs a public hostname such as example.com.`;
160  for (const label of labels) {
161    if (!LABEL_SHAPE.test(label)) return `'${label}' in '${host}' is not a hostname label: letters, digits and inner hyphens, 1 to 63 characters.`;
162  }
163  if (/^[0-9]+$/.test(labels[labels.length - 1])) return `'${host}' ends in a numeric label, which no public hostname does.`;
164  return null;
165}
166
167/** The origin as https://host, or the refusal. Nothing but a scheme and a host: no
168 *  credentials, no port, no path, no query and no fragment. */
169export function originFrom(raw: string): { ok: true; origin: string } | { ok: false; refusal: string } {
170  const match = /^https:\/\/([^/?#@:]+)\/?$/.exec(raw);
171  if (!match) {
172    if (!/^https:\/\//i.test(raw)) return { ok: false, refusal: `the origin must start with https://; got '${raw}'.` };
173    return {
174      ok: false,
175      refusal: `the origin is https:// and a hostname only, with no user, port, path, query or fragment; put a health route in the health path. Got '${raw}'.`,
176    };
177  }
178  const host = match[1];
179  const bad = hostnameRefusal(host);
180  if (bad) return { ok: false, refusal: bad };
181  return { ok: true, origin: `https://${host}` };
182}
183
184/** The refusal for a health path, or null. Starts with /, unreserved characters only,
185 *  no empty or dot segment. */
186export function healthPathRefusal(path: string): string | null {
187  if (!HEALTH_PATH_SHAPE.test(path)) {
188    return `the health path '${path}' must start with / and use only letters, digits and - . _ ~ /, at most 200 characters, with no query or fragment.`;
189  }
190  const segments = path.split("/").slice(1);
191  if (segments.some((s, i) => (s === "" && i < segments.length - 1) || s === "." || s === "..")) {
192    return `the health path '${path}' has an empty, '.' or '..' segment.`;
193  }
194  return null;
195}
196
197/** A Portal edit's params, checked and normalized. Blank fields arrive absent. */
198export function validateSite(p: Record<string, string | undefined>): Validated {
199  const refuse = (refusal: string): Validated => ({ ok: false, refusal });
200  const namespace = p.namespace ?? "";
201  if (!NAMESPACE_SHAPE.test(namespace)) return refuse(`'${namespace}' is not a namespace name: lowercase letters, digits and hyphens.`);
202  const name = p.name ?? namespace;
203  // oxlint-disable-next-line no-control-regex -- refusing control characters is the point
204  if (name.length > NAME_MAX || /[\u0000-\u001f\u007f]/.test(name)) return refuse(`the name must be at most ${NAME_MAX} characters with no control characters.`);
205
206  // operator: absent leaves an edit's stored value alone, "none" clears it, anything else
207  // is the JSON, checked whole and stored in its normalized form.
208  let operator: string | null | undefined;
209  if (p.operator === "none") operator = null;
210  else if (p.operator !== undefined) {
211    const parsed = parseOperator(p.operator);
212    if (!parsed.ok) return refuse(parsed.refusal);
213    operator = JSON.stringify(parsed.operator);
214  }
215
216  if (!p.origin) {
217    if (operator) return refuse("a namespace that serves no site has no operator API.");
218    if (p.health_path || p.platform || p.script) {
219      return refuse("a namespace that serves no site takes no health path, platform or script. Give an origin to make it a site.");
220    }
221    return { ok: true, site: { namespace, name, origin: null, health_path: null, platform: null, script: null, operator: null } };
222  }
223  const origin = originFrom(p.origin);
224  if (!origin.ok) return refuse(origin.refusal);
225  if (!p.platform || !(SITE_PLATFORMS as readonly string[]).includes(p.platform)) {
226    return refuse(`the platform must be one of ${SITE_PLATFORMS.join(", ")}; got '${p.platform ?? ""}'.`);
227  }
228  const platform = p.platform as SitePlatform;
229  if (p.health_path) {
230    const bad = healthPathRefusal(p.health_path);
231    if (bad) return refuse(bad);
232  }
233  if (p.script) {
234    if (platform !== "cloudflare") return refuse("only a Cloudflare site names a Worker script.");
235    if (!SCRIPT_SHAPE.test(p.script)) return refuse(`'${p.script}' is not a Worker script name: lowercase letters, digits, - and _.`);
236  }
237  return {
238    ok: true,
239    site: { namespace, name, origin: origin.origin, health_path: p.health_path ?? null, platform, script: p.script ?? null, ...(operator !== undefined ? { operator } : {}) },
240  };
241}
242
243/** One line for a preview: what the row is. */
244export function describeSite(site: Pick<SiteInput, "origin" | "health_path" | "platform" | "script" | "name">): string {
245  if (site.origin === null) return `"${site.name}", serves no site (not probed)`;
246  const probe = site.health_path ? `${site.origin}${site.health_path}` : `${site.origin}/ (no health route, so the root)`;
247  return `"${site.name}", probed at ${probe}, on ${site.platform}${site.script ? `, Worker script ${site.script}` : ""}`;
248}
249
250// ---- Writes -----------------------------------------------------------------------------
251
252export type SiteResult = { ok: true; site: OpsSiteConfig } | { ok: false; refusal: string };
253
254/** One row, or null. */
255export async function readSiteRow(db: D1Database, namespace: string): Promise<OpsSiteConfig | null> {
256  const row = await db.prepare(`SELECT ${SITE_COLUMNS} FROM ops_sites WHERE namespace = ?1`).bind(namespace).first<SiteRow>();
257  return row ? configFrom(row) : null;
258}
259
260/** Add a row. A namespace that already has one is refused, not replaced. */
261export async function addSite(db: D1Database, actor: string, site: SiteInput): Promise<SiteResult> {
262  const won = await db
263    .prepare(
264      `INSERT INTO ops_sites (namespace, name, origin, health_path, platform, script, operator)
265       VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7) ON CONFLICT(namespace) DO NOTHING RETURNING namespace`
266    )
267    .bind(site.namespace, site.name, site.origin, site.health_path, site.platform, site.script, site.operator ?? null)
268    .first<{ namespace: string }>();
269  if (!won) return { ok: false, refusal: `${site.namespace} already has a row. Edit it instead.` };
270  const after = await readSiteRow(db, site.namespace);
271  if (!after) return { ok: false, refusal: `${site.namespace} was added and then removed before it could be read back.` };
272  await db.batch([auditStatement(db, actor, "ops-site-added", site.namespace, null, { after })]);
273  return { ok: true, site: after };
274}
275
276/** Replace a row's fields, only if it is still at `revision`. An origin change clears
277 *  the in-process probe, which is right for Capsid's own origin only. */
278export async function editSite(db: D1Database, actor: string, site: SiteInput, revision: number): Promise<SiteResult> {
279  const before = await readSiteRow(db, site.namespace);
280  if (!before) return { ok: false, refusal: `${site.namespace} has no row to edit. Add it instead.` };
281  const selfProbe = before.self_probe && before.origin === site.origin ? 1 : 0;
282  const won = await db
283    .prepare(
284      `UPDATE ops_sites SET name = ?3, origin = ?4, health_path = ?5, platform = ?6, script = ?7, self_probe = ?8,
285         operator = CASE WHEN ?9 = 1 THEN ?10 ELSE operator END,
286         revision = revision + 1, updated_at = datetime('now')
287       WHERE namespace = ?1 AND revision = ?2 RETURNING revision`
288    )
289    .bind(site.namespace, revision, site.name, site.origin, site.health_path, site.platform, site.script, selfProbe, site.operator === undefined ? 0 : 1, site.operator ?? null)
290    .first<{ revision: number }>();
291  if (!won) {
292    return { ok: false, refusal: `${site.namespace} changed since the preview (it is at revision ${before.revision}, the preview read ${revision}). Preview again.` };
293  }
294  const after = await readSiteRow(db, site.namespace);
295  if (!after) return { ok: false, refusal: `${site.namespace} was edited and then removed before it could be read back.` };
296  await db.batch([auditStatement(db, actor, "ops-site-edited", site.namespace, null, { before, after })]);
297  return { ok: true, site: after };
298}
299
300/** Remove a row, only if it is still at `revision`. The prior row goes in the audit
301 *  row, which is the only copy afterwards outside the nightly dump. */
302export async function removeSite(db: D1Database, actor: string, namespace: string, revision: number): Promise<SiteResult> {
303  const before = await readSiteRow(db, namespace);
304  if (!before) return { ok: false, refusal: `${namespace} has no row to remove.` };
305  const won = await db
306    .prepare("DELETE FROM ops_sites WHERE namespace = ?1 AND revision = ?2 RETURNING namespace")
307    .bind(namespace, revision)
308    .first<{ namespace: string }>();
309  if (!won) {
310    return { ok: false, refusal: `${namespace} changed since the preview (it is at revision ${before.revision}, the preview read ${revision}). Preview again.` };
311  }
312  await db.batch([auditStatement(db, actor, "ops-site-removed", namespace, null, { before })]);
313  return { ok: true, site: before };
314}