@quolu/lattice 0.52.3 → 0.53.0

package/src/bridge-hub-heartbeat.mjs

@@ -0,0 +1,170 @@
+/**
+ * Terminal-side bridge-hub heartbeat client (bh3).
+ *
+ * Wires the pure wire contract in `bridge-hub-protocol.mjs` (bh1) around this
+ * terminal's own state: a persisted terminal identity, the locally active
+ * project set (`todo-dashboard-registry.mjs`), and the configured hub origin
+ * (`bridge-config.mjs`'s `hub` field). It sends `POST /__lattice/hub/register`
+ * on `bridge-hub-server.mjs`'s (bh2) contract — the request body is the raw
+ * `lattice.bridge_hub_registration_request.v1` object, unmodified in transit.
+ *
+ * DHCP addresses are never read or sent here: ADR 0162 has the hub derive
+ * `address` from the registration connection's own source, the same safety
+ * property `bridge-registrar.mjs` relies on. A moved lease is invisible to
+ * this module by design — the next heartbeat just arrives from a new source.
+ */
+
+import { randomBytes } from 'node:crypto';
+import { hostname } from 'node:os';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import { bridgeConfigPaths } from './bridge-config.mjs';
+import { BRIDGE_HUB_HEARTBEAT_INTERVAL_MS, validateBridgeHubRegistrationRequest } from './bridge-hub-protocol.mjs';
+import { readActiveTodoDashboardProjects } from './todo-dashboard-registry.mjs';
+
+export { BRIDGE_HUB_HEARTBEAT_INTERVAL_MS };
+
+const TERMINAL_IDENTITY_SCHEMA = 'lattice.bridge_hub_terminal_identity.v1';
+const HEARTBEAT_RESULT_SCHEMA = 'lattice.bridge_hub_heartbeat_result.v1';
+const REGISTRATION_REQUEST_SCHEMA = 'lattice.bridge_hub_registration_request.v1';
+const REGISTER_PATH = '__lattice/hub/register';
+const DEFAULT_TIMEOUT_MS = 5_000;
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+
+export class BridgeHubHeartbeatError extends Error {
+  constructor(code, message, detail = undefined, cause = undefined) {
+    super(message, { cause });
+    this.name = 'BridgeHubHeartbeatError';
+    this.code = code;
+    if (detail !== undefined) this.detail = detail;
+  }
+}
+
+function terminalIdentityPath(env) {
+  return path.join(bridgeConfigPaths(env).root, 'bridge-hub-terminal.json');
+}
+
+/**
+ * This terminal's stable bridge-hub identity, created once and reused across
+ * restarts. It must survive restarts: registration is a full-state
+ * reconciliation keyed by terminal_id (ADR 0162 Decision 4), so a fresh id on
+ * every daemon start would make the hub see "a new terminal" contesting the
+ * same project_ids the old id still owns until its TTL lapses — a
+ * self-inflicted `BRIDGE_HUB_PROJECT_CONFLICT`.
+ */
+export async function readOrCreateBridgeHubTerminalId({ env = process.env } = {}) {
+  const refs = bridgeConfigPaths(env);
+  await mkdir(refs.root, { recursive: true, mode: 0o700 });
+  const ref = terminalIdentityPath(env);
+  for (;;) {
+    try {
+      const value = JSON.parse(await readFile(ref, 'utf8'));
+      if (value?.schema === TERMINAL_IDENTITY_SCHEMA && IDENTIFIER.test(value.terminal_id)) return value.terminal_id;
+      throw new BridgeHubHeartbeatError('BRIDGE_HUB_TERMINAL_IDENTITY_INVALID',
+        'bridge hub terminal identity file is invalid');
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+    const terminalId = randomBytes(16).toString('hex');
+    try {
+      await writeFile(ref, `${JSON.stringify({ schema: TERMINAL_IDENTITY_SCHEMA, terminal_id: terminalId })}\n`,
+        { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+      return terminalId;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      // Lost the create race to another process; loop back and read what it wrote.
+    }
+  }
+}
+
+/**
+ * The terminal's own display name, shown for every project it registers
+ * (registry entries are per-project but `display_name` is terminal-wide —
+ * ADR 0162 Decision 2). Hostname, not a project name: the active project set
+ * changes heartbeat to heartbeat but the terminal's identity does not.
+ */
+function terminalDisplayName() {
+  return hostname().slice(0, 128) || 'terminal';
+}
+
+/** Build and validate one registration/heartbeat request. Throws rather than
+  * sending a request the hub would reject as malformed. */
+export function buildBridgeHubRegistrationRequest({ terminalId, port, projectIds, adopt = [] }) {
+  const request = {
+    schema: REGISTRATION_REQUEST_SCHEMA,
+    terminal_id: terminalId,
+    display_name: terminalDisplayName(),
+    port,
+    project_ids: [...new Set(projectIds)].sort((left, right) => left.localeCompare(right, 'en')),
+    adopt: [...adopt],
+  };
+  if (!validateBridgeHubRegistrationRequest(request)) {
+    throw new BridgeHubHeartbeatError('BRIDGE_HUB_HEARTBEAT_REQUEST_INVALID',
+      'constructed bridge hub registration request is invalid', { request });
+  }
+  return request;
+}
+
+/**
+ * Send one heartbeat. Never throws for a remote or network failure — the
+ * bridge daemon loop calling this must keep serving locally even when the
+ * hub is unreachable, matching `bridge-registrar.mjs`'s posture. Failures are
+ * returned typed so callers can surface or log them instead of losing them.
+ */
+export async function sendBridgeHubHeartbeat({ hubUrl, request, fetchImpl = fetch, timeoutMs = DEFAULT_TIMEOUT_MS }) {
+  let response;
+  try {
+    response = await fetchImpl(new URL(REGISTER_PATH, hubUrl), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(request),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (error) {
+    return { schema: HEARTBEAT_RESULT_SCHEMA, state: 'unreachable',
+      detail: (error?.message ?? 'network error').slice(0, 500) };
+  }
+  let body = null;
+  try { body = await response.json(); } catch { body = null; }
+  if (response.status !== 200) {
+    return { schema: HEARTBEAT_RESULT_SCHEMA, state: 'rejected', status: response.status, detail: body };
+  }
+  return { schema: HEARTBEAT_RESULT_SCHEMA, state: 'accepted', result: body };
+}
+
+/**
+ * Periodic controller for the bridge daemon's own poll loop
+ * (`bin/lattice-bridge.mjs`). Call `tick({ config })` on every iteration; it
+ * self-throttles to `intervalMs` and is a no-op (no disk or network access)
+ * whenever the terminal has no hub configured, so callers pay only a null
+ * check on the common path.
+ */
+export function createBridgeHubHeartbeatController({
+  env = process.env, fetchImpl = fetch, now = () => Date.now(),
+  intervalMs = BRIDGE_HUB_HEARTBEAT_INTERVAL_MS,
+  readActiveProjects = readActiveTodoDashboardProjects,
+} = {}) {
+  let lastSentAt = null;
+  let lastResult = null;
+  return Object.freeze({
+    async tick({ config }) {
+      if (config?.hub == null) { lastSentAt = null; lastResult = null; return null; }
+      const nowMs = now();
+      if (lastSentAt !== null && nowMs - lastSentAt < intervalMs) return lastResult;
+      lastSentAt = nowMs;
+      const projects = await readActiveProjects({ env });
+      if (projects.length === 0) {
+        lastResult = { schema: HEARTBEAT_RESULT_SCHEMA, state: 'skipped_no_projects' };
+        return lastResult;
+      }
+      const terminalId = await readOrCreateBridgeHubTerminalId({ env });
+      const request = buildBridgeHubRegistrationRequest({
+        terminalId, port: config.listen.port, projectIds: projects.map((project) => project.project_id),
+      });
+      lastResult = await sendBridgeHubHeartbeat({ hubUrl: config.hub.url, request, fetchImpl });
+      return lastResult;
+    },
+    lastHeartbeatResult: () => lastResult,
+  });
+}

package/src/bridge-hub-protocol.mjs

@@ -0,0 +1,198 @@
+/**
+ * Bridge hub registration protocol — the wire contract between a terminal's
+ * `lattice bridge` and the hub that aggregates them for the public dashboard.
+ *
+ * This module owns validation and pure registry mutation only. It does not open
+ * a socket, read a clock, or touch disk — that belongs to the hub server (bh2)
+ * and the terminal heartbeat client (bh3). Keeping the contract pure lets it be
+ * characterization-tested before either side exists, and keeps bh2/bh3 from
+ * inventing their own conflict or staleness rules.
+ *
+ * Design decisions this module encodes (see docs/adr/0162 for the full record):
+ *
+ * - The registry is keyed by `project_id`, not `terminal_id`, because hub routes
+ *   `/projects/<id>/*` by project. A terminal that owns several projects appears
+ *   as several entries sharing the same terminal_id/address/port.
+ * - The request never carries an address. The caller passes the address the
+ *   registration connection actually arrived from (`remoteAddress`); a terminal
+ *   can only ever register itself, the same safety property bridge-registrar.mjs
+ *   already relies on for the ssh-based upstream registrar.
+ * - A registration call declares a terminal's *complete* current project
+ *   portfolio and replaces that terminal's prior contribution wholesale. A
+ *   project the terminal owned before but omits now is released — there is no
+ *   separate "deregister" verb, and no partial application: a heartbeat either
+ *   lands in full or is rejected in full.
+ * - A project_id already owned by a *different* terminal is a conflict unless
+ *   named in `adopt`. Conflicts are collected and reported together — a batch
+ *   never partially lands, so a caller is never left unsure which half won.
+ * - Staleness is read-time only. `projectBridgeHubRegistry` marks an entry
+ *   'offline' once `last_seen_at` exceeds the TTL; it never deletes the entry.
+ *   The plan's fail-closed requirement is "show offline", not "make it vanish".
+ */
+
+const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+const MAX_PROJECT_IDS = 256;
+
+/** Suggested terminal heartbeat cadence. Not part of the wire contract — the hub
+ * owns both constants and can retune them without a protocol version bump. */
+export const BRIDGE_HUB_HEARTBEAT_INTERVAL_MS = 30_000;
+/** Grace window after the last heartbeat before a project is shown offline. */
+export const BRIDGE_HUB_HEARTBEAT_TTL_MS = 90_000;
+
+export class BridgeHubProtocolError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'BridgeHubProtocolError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+function identifier(value) {
+  return typeof value === 'string' && IDENTIFIER.test(value);
+}
+
+function uniqueIdentifierArray(value, { min = 0, max = MAX_PROJECT_IDS } = {}) {
+  return Array.isArray(value) && value.length >= min && value.length <= max
+    && value.every(identifier) && new Set(value).size === value.length;
+}
+
+function sorted(ids) {
+  return [...ids].sort((left, right) => left.localeCompare(right, 'en'));
+}
+
+/** A terminal's registration/heartbeat request, as it crosses the wire. */
+export function validateBridgeHubRegistrationRequest(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).sort().join(',') === 'adopt,display_name,port,project_ids,schema,terminal_id'
+    && value.schema === 'lattice.bridge_hub_registration_request.v1'
+    && identifier(value.terminal_id)
+    && typeof value.display_name === 'string' && value.display_name.length > 0
+    && value.display_name === value.display_name.trim()
+    && Number.isSafeInteger(value.port) && value.port > 0 && value.port <= 65_535
+    && uniqueIdentifierArray(value.project_ids, { min: 1 })
+    && uniqueIdentifierArray(value.adopt, { max: value.project_ids.length })
+    && value.adopt.every((projectId) => value.project_ids.includes(projectId));
+}
+
+/** A single project's routing entry as stored in the hub registry. */
+function validRegistryEntry(entry) {
+  return entry !== null && typeof entry === 'object' && !Array.isArray(entry)
+    && Object.keys(entry).sort().join(',')
+      === 'address,display_name,last_seen_at,port,project_id,registered_at,terminal_id'
+    && identifier(entry.project_id) && identifier(entry.terminal_id)
+    && typeof entry.display_name === 'string' && entry.display_name.length > 0
+    && typeof entry.address === 'string' && entry.address.length > 0
+    && Number.isSafeInteger(entry.port) && entry.port > 0 && entry.port <= 65_535
+    && Number.isFinite(Date.parse(entry.registered_at)) && Number.isFinite(Date.parse(entry.last_seen_at));
+}
+
+export function validateBridgeHubRegistryEntry(value) {
+  return validRegistryEntry(value);
+}
+
+function validRegistry(registry) {
+  return Array.isArray(registry) && registry.every(validRegistryEntry);
+}
+
+/**
+ * Apply one registration/heartbeat call to a registry snapshot. Pure: takes the
+ * current entries and returns the next ones plus a result summary, mutating
+ * nothing. Throws `BridgeHubProtocolError` for an invalid request or an
+ * unresolved project_id conflict; on throw, `registry` is guaranteed untouched
+ * because nothing is written until every conflict check has passed.
+ */
+export function applyBridgeHubRegistration({ registry, request, remoteAddress, now = new Date() }) {
+  if (!validRegistry(registry)) {
+    throw new BridgeHubProtocolError('BRIDGE_HUB_REGISTRY_INVALID', 'bridge hub registry is invalid');
+  }
+  if (!validateBridgeHubRegistrationRequest(request)) {
+    throw new BridgeHubProtocolError('BRIDGE_HUB_REGISTRATION_INVALID', 'bridge hub registration request is invalid');
+  }
+  if (typeof remoteAddress !== 'string' || remoteAddress.length === 0) {
+    throw new BridgeHubProtocolError('BRIDGE_HUB_REGISTRATION_INVALID', 'remote address is required');
+  }
+  if (!(now instanceof Date) || !Number.isFinite(now.getTime())) {
+    throw new BridgeHubProtocolError('BRIDGE_HUB_REGISTRATION_INVALID', 'now must be a valid Date');
+  }
+  const { terminal_id: terminalId, display_name: displayName, port, project_ids: projectIds, adopt } = request;
+  const requestedSet = new Set(projectIds);
+  const adoptSet = new Set(adopt);
+
+  const conflicts = registry
+    .filter((entry) => requestedSet.has(entry.project_id)
+      && entry.terminal_id !== terminalId && !adoptSet.has(entry.project_id))
+    .map((entry) => ({ project_id: entry.project_id, owning_terminal_id: entry.terminal_id }));
+  if (conflicts.length > 0) {
+    throw new BridgeHubProtocolError('BRIDGE_HUB_PROJECT_CONFLICT',
+      'one or more project_ids are already owned by a different terminal',
+      {
+        conflicts: conflicts.sort((left, right) => left.project_id.localeCompare(right.project_id, 'en')),
+        next_action: 're-register naming the conflicting project_ids in adopt',
+      });
+  }
+
+  const registeredAtByProject = new Map(registry
+    .filter((entry) => entry.terminal_id === terminalId)
+    .map((entry) => [entry.project_id, entry.registered_at]));
+  const adopted = sorted(projectIds.filter((projectId) => adoptSet.has(projectId)
+    && !registeredAtByProject.has(projectId)));
+  // Full-state reconciliation: every entry this terminal owned is dropped, then
+  // rebuilt from `projectIds`. A project omitted from this call — dropped
+  // locally, or never re-sent after a crash — is released, not left as a
+  // phantom no future heartbeat can retract.
+  const others = registry.filter((entry) => entry.terminal_id !== terminalId && !requestedSet.has(entry.project_id));
+  const mine = projectIds.map((projectId) => ({
+    project_id: projectId,
+    terminal_id: terminalId,
+    display_name: displayName,
+    address: remoteAddress,
+    port,
+    registered_at: registeredAtByProject.get(projectId) ?? now.toISOString(),
+    last_seen_at: now.toISOString(),
+  }));
+  const nextRegistry = [...others, ...mine]
+    .sort((left, right) => left.project_id.localeCompare(right.project_id, 'en'));
+
+  return {
+    registry: nextRegistry,
+    result: {
+      schema: 'lattice.bridge_hub_registration_result.v1',
+      terminal_id: terminalId,
+      address: remoteAddress,
+      port,
+      registered: sorted(projectIds),
+      adopted,
+    },
+  };
+}
+
+/**
+ * Read-time projection for the aggregate `/projects/` view and per-project
+ * routing. Never mutates or drops entries — a terminal that stopped
+ * heartbeating shows as 'offline' forever, not gone, until it either
+ * re-registers or a different terminal explicitly adopts the project.
+ */
+export function projectBridgeHubRegistry({ registry, now = new Date(), ttlMs = BRIDGE_HUB_HEARTBEAT_TTL_MS }) {
+  if (!validRegistry(registry)) {
+    throw new BridgeHubProtocolError('BRIDGE_HUB_REGISTRY_INVALID', 'bridge hub registry is invalid');
+  }
+  if (!(now instanceof Date) || !Number.isFinite(now.getTime())) {
+    throw new BridgeHubProtocolError('BRIDGE_HUB_REGISTRATION_INVALID', 'now must be a valid Date');
+  }
+  if (!Number.isSafeInteger(ttlMs) || ttlMs <= 0) {
+    throw new BridgeHubProtocolError('BRIDGE_HUB_REGISTRATION_INVALID', 'ttlMs must be a positive integer');
+  }
+  return registry
+    .map((entry) => ({
+      schema: 'lattice.bridge_hub_registry_projection_entry.v1',
+      project_id: entry.project_id,
+      terminal_id: entry.terminal_id,
+      display_name: entry.display_name,
+      address: entry.address,
+      port: entry.port,
+      status: now.getTime() - Date.parse(entry.last_seen_at) <= ttlMs ? 'online' : 'offline',
+      last_seen_at: entry.last_seen_at,
+    }))
+    .sort((left, right) => left.project_id.localeCompare(right.project_id, 'en'));
+}