@zgeoff/atc 2.20.0 → 2.22.0

package/src/federation/parse-gateway-id.ts

@@ -0,0 +1,28 @@
+import type { GatewayRegistry, RegistryDaemon } from './types';
+
+/**
+ * The daemon a gateway id routes to and the daemon's own id inside it, or
+ * null for an id the gateway must answer as one that never existed: a
+ * malformed id, an unknown daemon name, or an incarnation other than the
+ * one the registry pins behind the name.
+ */
+export function parseGatewayID(
+  value: string,
+  registry: GatewayRegistry,
+): { readonly daemon: RegistryDaemon; readonly id: string } | null {
+  const first = value.indexOf('.');
+  const second = first === -1 ? -1 : value.indexOf('.', first + 1);
+
+  if (second === -1) {
+    return null;
+  }
+
+  const daemon = registry.daemons.get(value.slice(0, first));
+  const id = value.slice(second + 1);
+
+  if (daemon === undefined || value.slice(first + 1, second) !== daemon.incarnation || id === '') {
+    return null;
+  }
+
+  return { daemon, id };
+}

package/src/federation/parse-gateway-registry.ts

@@ -0,0 +1,123 @@
+import { isRecord } from '../shared/report';
+import { MAX_EVENTS_CURSOR_BYTES } from './max-events-cursor-bytes';
+import { MAX_REGISTRY_DAEMONS } from './max-registry-daemons';
+import type { GatewayRegistry, RegistryDaemon } from './types';
+
+// A daemon name: never a `.`, which separates the parts of a gateway id.
+const NAME_PATTERN = /^[a-z][a-z0-9-]{0,30}$/;
+
+// A daemon ID as a daemon mints it: a lowercase UUID.
+const DAEMON_ID_PATTERN = /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/;
+
+// `<host>:<port>`, with an IPv6 host in brackets.
+const ADDRESS_PATTERN = /^(?:\[(?<v6>[^\]]+)\]|(?<host>[^:[\]]+)):(?<port>\d{1,5})$/;
+
+type ParsedGatewayRegistry =
+  | { readonly ok: true; readonly registry: GatewayRegistry }
+  | { readonly ok: false; readonly errors: readonly string[] };
+
+/**
+ * Parses a registry file's JSON and the environment the tokens come from.
+ * Every daemon needs a name matching `^[a-z][a-z0-9-]{0,30}$`, an address,
+ * a pinned `daemonID`, and a non-empty token in `ATC_GATEWAY_TOKEN_<NAME>`
+ * (the name upper-cased, `-` as `_`). `defaultDaemon` is required and must
+ * be one of the daemons. A registry lists at most as many daemons as an
+ * events cursor across all of them can hold. Any problem refuses the whole registry, so the
+ * gateway never starts with part of its fleet.
+ */
+export function parseGatewayRegistry(
+  raw: unknown,
+  env: Readonly<Record<string, string | undefined>>,
+): ParsedGatewayRegistry {
+  if (!isRecord(raw) || !isRecord(raw['daemons']) || Array.isArray(raw['daemons'])) {
+    return { ok: false, errors: ['the registry must be an object whose daemons is an object'] };
+  }
+
+  const daemons = new Map<string, RegistryDaemon>();
+
+  const errors: string[] = [];
+
+  for (const [name, entry] of Object.entries(raw['daemons'])) {
+    const parsed = parseRegistryDaemon(name, entry, env);
+
+    if (typeof parsed === 'string') {
+      errors.push(parsed);
+    } else {
+      daemons.set(name, parsed);
+    }
+  }
+
+  const count = Object.keys(raw['daemons']).length;
+
+  if (count === 0) {
+    errors.push('the registry lists no daemon');
+  }
+
+  if (count > MAX_REGISTRY_DAEMONS) {
+    errors.push(
+      `the registry lists ${count} daemons, over the limit of ${MAX_REGISTRY_DAEMONS}, the most whose events cursor fits ${MAX_EVENTS_CURSOR_BYTES} bytes`,
+    );
+  }
+
+  const defaultDaemon = raw['defaultDaemon'];
+
+  if (typeof defaultDaemon !== 'string') {
+    errors.push('defaultDaemon is required and must name a daemon in the registry');
+  } else if (!Object.hasOwn(raw['daemons'], defaultDaemon)) {
+    errors.push(`defaultDaemon '${defaultDaemon}' is not a daemon in the registry`);
+  }
+
+  if (errors.length > 0 || typeof defaultDaemon !== 'string') {
+    return { ok: false, errors };
+  }
+
+  return { ok: true, registry: { daemons, defaultDaemon } };
+}
+
+// One daemon entry, or the problem that refuses it.
+function parseRegistryDaemon(
+  name: string,
+  entry: unknown,
+  env: Readonly<Record<string, string | undefined>>,
+): RegistryDaemon | string {
+  if (!NAME_PATTERN.test(name)) {
+    return `daemon name '${name}' must match ^[a-z][a-z0-9-]{0,30}$`;
+  }
+
+  if (!isRecord(entry)) {
+    return `daemon '${name}' must be an object with address and daemonID`;
+  }
+
+  const address = typeof entry['address'] === 'string' ? parseAddress(entry['address']) : null;
+
+  if (address === null) {
+    return `daemon '${name}' needs an address of <host>:<port> with a port from 1 to 65535`;
+  }
+
+  const daemonID = entry['daemonID'];
+
+  if (typeof daemonID !== 'string' || !DAEMON_ID_PATTERN.test(daemonID)) {
+    return `daemon '${name}' needs the daemonID that atc daemon id prints on its host`;
+  }
+
+  const tokenVar = `ATC_GATEWAY_TOKEN_${name.toUpperCase().replaceAll('-', '_')}`;
+  const token = env[tokenVar];
+
+  if (token === undefined || token === '') {
+    return `daemon '${name}' has no token: set ${tokenVar}`;
+  }
+
+  return { name, address, daemonID, incarnation: daemonID.slice(0, 8), token };
+}
+
+function parseAddress(raw: string): { readonly host: string; readonly port: number } | null {
+  const match = ADDRESS_PATTERN.exec(raw);
+  const host = match?.groups?.['v6'] ?? match?.groups?.['host'];
+  const port = Number(match?.groups?.['port']);
+
+  if (host === undefined || !Number.isInteger(port) || port < 1 || port > 65_535) {
+    return null;
+  }
+
+  return { host, port };
+}

package/src/federation/pick-daemon-state.ts

@@ -0,0 +1,46 @@
+import { DaemonError } from '../protocol/daemon-error';
+import { GatewayError } from './gateway-error';
+import type { CallOutcome } from './wait-for-outcome';
+
+/**
+ * A daemon's state as the gateway reports it: `up` when it answered,
+ * `down` when it was unreachable or did not answer in time, `unauthorized`
+ * when it refused the gateway's token, `changed` when another state
+ * identity than the registry pins answered, `outdated` when it lacks a
+ * feature the call needs, and `refused` when it answered the call with its
+ * own error.
+ */
+export type DaemonState = 'up' | 'down' | 'unauthorized' | 'changed' | 'outdated' | 'refused';
+
+/**
+ * The state a daemon is in, judged by how one call to it settled.
+ */
+export function pickDaemonState(outcome: CallOutcome<unknown>): DaemonState {
+  if (outcome.kind === 'answered') {
+    return 'up';
+  }
+
+  if (outcome.kind === 'timeout') {
+    return 'down';
+  }
+
+  const error = outcome.error;
+
+  if (error instanceof GatewayError && error.code === 'daemon_unauthorized') {
+    return 'unauthorized';
+  }
+
+  if (error instanceof GatewayError && error.code === 'daemon_outdated') {
+    return 'outdated';
+  }
+
+  if (error instanceof GatewayError && error.data['reason'] === 'daemon_changed') {
+    return 'changed';
+  }
+
+  if (error instanceof DaemonError) {
+    return 'refused';
+  }
+
+  return 'down';
+}

package/src/federation/plan-event-reads.ts

@@ -0,0 +1,54 @@
+import { decodeGatewayCursor } from './decode-gateway-cursor';
+import type { GatewayRegistry } from './types';
+
+/**
+ * Where one daemon's part of an events read starts: after its own cursor,
+ * or at its latest events for null, which only a read without a gateway
+ * cursor gets; or at its newest event, for a daemon a given gateway cursor
+ * leaves out, such as one added to the registry since. The caller reads
+ * such a daemon once with `events.read` at limit 1 and no cursor, and
+ * pins it at the cursor that answer returns, which is its newest event,
+ * or event 0 for an empty trail; the read then reports it under `started`.
+ * A daemon whose part the cursor holds as null, because it has not answered
+ * since the read that started the cursor, starts at its latest events, as a
+ * first read does: the caller reads it without a cursor, checks whether
+ * older events precede that page, and the read reports it under `started`,
+ * and under `truncated` when older events went unread.
+ */
+export type EventReadStart =
+  | { readonly kind: 'after'; readonly cursor: string | null }
+  | { readonly kind: 'newest' }
+  | { readonly kind: 'latest' };
+
+/**
+ * The daemons an events read asks, each with where its part starts. A read
+ * filtered to a session asks only the daemon that owns the session; any
+ * other read asks every daemon in the registry. Without a gateway cursor
+ * every daemon starts at the start of its trail, as a daemon read without
+ * a cursor does.
+ */
+export function planEventReads(
+  cursor: string | null,
+  filter: string,
+  sessionDaemon: string | null,
+  registry: GatewayRegistry,
+): ReadonlyMap<string, EventReadStart> {
+  const names = sessionDaemon === null ? [...registry.daemons.keys()] : [sessionDaemon];
+  const parts = cursor === null ? null : decodeGatewayCursor(cursor, filter, registry);
+
+  const plan = new Map<string, EventReadStart>();
+
+  for (const name of names) {
+    if (parts === null) {
+      plan.set(name, { kind: 'after', cursor: null });
+    } else if (parts.get(name) === null) {
+      plan.set(name, { kind: 'latest' });
+    } else if (parts.has(name)) {
+      plan.set(name, { kind: 'after', cursor: parts.get(name) ?? null });
+    } else {
+      plan.set(name, { kind: 'newest' });
+    }
+  }
+
+  return plan;
+}

package/src/federation/read-fleet-events.ts

@@ -0,0 +1,279 @@
+import { DaemonError } from '../protocol/daemon-error';
+import type { DaemonFeature } from '../protocol/daemon-features';
+import { decodeCursor } from '../protocol/decode-cursor';
+import { encodeCursor } from '../protocol/encode-cursor';
+import { isRecord } from '../shared/report';
+import { buildEventsFilterHash } from './build-events-filter-hash';
+import { buildGatewayError } from './build-gateway-error';
+import type { DaemonCaller } from './daemon-caller';
+import { GatewayError } from './gateway-error';
+import { mergeEventPages } from './merge-event-pages';
+import type { MergeSource } from './merge-event-pages';
+import { parseGatewayID } from './parse-gateway-id';
+import { planEventReads } from './plan-event-reads';
+import type { EventReadStart } from './plan-event-reads';
+import type { GatewayRegistry, RegistryDaemon } from './types';
+import { waitForOutcome } from './wait-for-outcome';
+
+interface FleetEventsDeps {
+  readonly registry: GatewayRegistry;
+  readonly getCaller: (name: string) => DaemonCaller;
+
+  // How long each daemon may take to answer a read that does not wait.
+  readonly timeoutMs: number;
+}
+
+// The daemon's own default and bounds for a page of events.
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+const MAX_WAIT_MS = 30_000;
+
+/**
+ * One `events.read` across the fleet: every daemon the plan asks is read in
+ * parallel, each within the fan-out time, and the pages merge into one page
+ * under a gateway cursor. A daemon that does not answer in time, or cannot
+ * be reached, is listed under `unavailable` and keeps its position. A read
+ * filtered to one session asks only its daemon, and that daemon's own
+ * refusal, or its lack of the session filter, fails the call. With
+ * `waitMs`, the daemons are first read without waiting; only when none has
+ * an event does each wait, and the call returns as soon as one of them has
+ * an event, the others keeping their positions.
+ */
+export async function readFleetEvents(
+  deps: FleetEventsDeps,
+  params: Readonly<Record<string, unknown>>,
+  required: readonly DaemonFeature[],
+  principal: string,
+): Promise<Readonly<Record<string, unknown>>> {
+  const rawSession = params['session'];
+  const session = typeof rawSession === 'string' && rawSession !== '' ? rawSession : null;
+  const owner = session === null ? null : parseGatewayID(session, deps.registry);
+
+  if (session !== null && owner === null) {
+    throw new DaemonError('no_such_session', `no session '${session}'`);
+  }
+
+  const filter = buildEventsFilterHash(session, null);
+  const cursor = typeof params['cursor'] === 'string' ? params['cursor'] : null;
+  const limit = toBounded(params['limit'], DEFAULT_LIMIT, 1, MAX_LIMIT);
+  const waitMs = toBounded(params['waitMs'], 0, 0, MAX_WAIT_MS);
+  const plan = planEventReads(cursor, filter, owner?.daemon.name ?? null, deps.registry);
+
+  const requestIDs: [string, string][] =
+    owner === null || session === null ? [] : [[owner.id, session]];
+
+  const read: DaemonRead = {
+    deps,
+    required,
+    principal,
+    limit,
+    sessionID: owner?.id ?? null,
+    requestIDs: new Map(requestIDs),
+  };
+
+  const sources = await Promise.all(
+    [...plan].map(([name, start]) => readDaemonSource(read, getDaemon(deps.registry, name), start)),
+  );
+
+  const first = mergeEventPages(sources, filter, limit);
+
+  if (first.events.length > 0 || waitMs === 0) {
+    return { ...first };
+  }
+
+  const waited = await waitForFirstEvents(read, sources, waitMs);
+
+  return { ...mergeEventPages(waited, filter, limit) };
+}
+
+// What every daemon read of one call shares.
+interface DaemonRead {
+  readonly deps: FleetEventsDeps;
+  readonly required: readonly DaemonFeature[];
+  readonly principal: string;
+  readonly limit: number;
+
+  // The daemon's own id of the session a filtered read asks about.
+  readonly sessionID: string | null;
+  readonly requestIDs: ReadonlyMap<string, string>;
+}
+
+function getDaemon(registry: GatewayRegistry, name: string): RegistryDaemon {
+  const daemon = registry.daemons.get(name);
+
+  if (daemon === undefined) {
+    throw new Error(`no daemon '${name}' in the registry`);
+  }
+
+  return daemon;
+}
+
+// One daemon's part of the merge, from where the plan starts it. Only a
+// filtered read's daemon fails the call, and only with its own refusal or
+// a missing feature; any other failure is a daemon that is unavailable.
+async function readDaemonSource(
+  read: DaemonRead,
+  daemon: RegistryDaemon,
+  start: EventReadStart,
+): Promise<MergeSource> {
+  const outcome = await waitForOutcome(readDaemonPart(read, daemon, start), read.deps.timeoutMs);
+
+  if (outcome.kind === 'answered') {
+    return outcome.value;
+  }
+
+  const error = outcome.kind === 'failed' ? outcome.error : null;
+
+  if (read.sessionID !== null && error instanceof DaemonError) {
+    throw buildGatewayError(error, daemon, read.requestIDs);
+  }
+
+  if (
+    read.sessionID !== null &&
+    error instanceof GatewayError &&
+    error.code === 'daemon_outdated'
+  ) {
+    throw error;
+  }
+
+  const before = start.kind === 'after' ? { cursor: start.cursor } : null;
+  const unread = start.kind === 'latest' ? { cursor: null } : before;
+
+  return { daemon, before: unread, page: { kind: 'unavailable' } };
+}
+
+async function readDaemonPart(
+  read: DaemonRead,
+  daemon: RegistryDaemon,
+  start: EventReadStart,
+): Promise<MergeSource> {
+  if (start.kind === 'newest') {
+    const newest = await sendEventsRead(read, daemon, { limit: 1 });
+
+    return { daemon, before: null, page: { kind: 'started', cursor: newest.cursor } };
+  }
+
+  if (start.kind === 'after') {
+    const page = await sendEventsRead(read, daemon, {
+      limit: read.limit,
+      ...(start.cursor === null ? {} : { cursor: start.cursor }),
+    });
+
+    return { daemon, before: { cursor: start.cursor }, page };
+  }
+
+  const page = await sendEventsRead(read, daemon, { limit: read.limit });
+  const olderUnread = await hasOlderEvents(read, daemon, page.events);
+
+  return { daemon, before: { cursor: null }, page, unstarted: { olderUnread } };
+}
+
+// Whether the daemon holds an event older than the first of a page of its
+// latest events, read as the first event after the start of its trail.
+async function hasOlderEvents(
+  read: DaemonRead,
+  daemon: RegistryDaemon,
+  events: readonly Readonly<Record<string, unknown>>[],
+): Promise<boolean> {
+  const [first] = events;
+  const firstID = first === undefined ? null : findEventID(first);
+
+  if (firstID === null) {
+    return false;
+  }
+
+  const oldest = await sendEventsRead(read, daemon, {
+    limit: 1,
+    cursor: encodeCursor({ kind: 'events', id: 0 }),
+  });
+
+  const [oldestEvent] = oldest.events;
+  const oldestID = oldestEvent === undefined ? null : findEventID(oldestEvent);
+
+  return oldestID !== null && oldestID < firstID;
+}
+
+function findEventID(event: Readonly<Record<string, unknown>>): number | null {
+  const raw = event['cursor'];
+  const decoded = typeof raw === 'string' ? decodeCursor(raw) : null;
+
+  return decoded !== null && decoded.kind === 'events' ? decoded.id : null;
+}
+
+// One events.read to one daemon as the call's principal, with the
+// session filter when the read has one.
+async function sendEventsRead(
+  read: DaemonRead,
+  daemon: RegistryDaemon,
+  params: Readonly<Record<string, unknown>>,
+): Promise<{
+  readonly kind: 'read';
+  readonly events: readonly Readonly<Record<string, unknown>>[];
+  readonly cursor: string;
+  readonly more: boolean;
+}> {
+  const answer = await read.deps
+    .getCaller(daemon.name)
+    .sendRequest(
+      'events.read',
+      { ...params, ...(read.sessionID === null ? {} : { session: read.sessionID }) },
+      read.principal,
+      read.required,
+    );
+
+  const rawEvents: unknown = answer['events'];
+  const events = Array.isArray(rawEvents) ? rawEvents.filter((event) => isRecord(event)) : [];
+
+  return {
+    kind: 'read',
+    events,
+    cursor: typeof answer['cursor'] === 'string' ? answer['cursor'] : '',
+    more: answer['more'] === true,
+  };
+}
+
+// Reads again, waiting, each daemon whose page came back empty, and settles
+// once one of them answers with an event or all of them have answered. A
+// daemon still waiting then keeps the empty page it gave before.
+async function waitForFirstEvents(
+  read: DaemonRead,
+  sources: readonly MergeSource[],
+  waitMs: number,
+): Promise<readonly MergeSource[]> {
+  const waited = new Map<MergeSource, MergeSource>();
+
+  const firstEvents = Promise.withResolvers<void>();
+
+  const reads = sources.map(async (source) => {
+    if (source.page.kind !== 'read') {
+      return;
+    }
+
+    const outcome = await waitForOutcome(
+      sendEventsRead(read, getDaemon(read.deps.registry, source.daemon.name), {
+        limit: read.limit,
+        waitMs,
+        cursor: source.page.cursor,
+      }),
+      read.deps.timeoutMs + waitMs,
+    );
+
+    if (outcome.kind === 'answered') {
+      waited.set(source, { ...source, page: outcome.value });
+    }
+
+    if (outcome.kind === 'answered' && outcome.value.events.length > 0) {
+      firstEvents.resolve();
+    }
+  });
+
+  await Promise.race([firstEvents.promise, Promise.all(reads)]);
+
+  return sources.map((source) => waited.get(source) ?? source);
+}
+
+function toBounded(value: unknown, fallback: number, min: number, max: number): number {
+  const given = typeof value === 'number' && Number.isFinite(value) ? Math.trunc(value) : fallback;
+
+  return Math.min(Math.max(given, min), max);
+}

package/src/federation/require-serving-daemon.ts

@@ -0,0 +1,27 @@
+import type { DaemonFeature } from '../protocol/daemon-features';
+import { buildDaemonOutdatedError } from './build-daemon-outdated-error';
+import type { DaemonCaller, DaemonHello } from './daemon-caller';
+import type { RegistryDaemon } from './types';
+
+/**
+ * The handshake of the daemon a call is about to reach, read from the
+ * connection the call rides. Throws `daemon_outdated` with the daemon's
+ * name when that daemon lacks a feature the call needs, so a daemon that
+ * would ignore an option never answers as if it had honoured it, and
+ * whatever the daemon caller throws when the daemon cannot be reached.
+ */
+export async function requireServingDaemon(
+  getCaller: (name: string) => DaemonCaller,
+  daemon: RegistryDaemon,
+  required: readonly DaemonFeature[],
+): Promise<DaemonHello> {
+  const hello = await getCaller(daemon.name).readHello();
+
+  const missing = required.find((feature) => !hello.features.has(feature));
+
+  if (missing !== undefined) {
+    throw buildDaemonOutdatedError(daemon.name, missing);
+  }
+
+  return hello;
+}

package/src/federation/resolve-daemon-request.ts

@@ -0,0 +1,59 @@
+import { DaemonError } from '../protocol/daemon-error';
+import { parseGatewayID } from './parse-gateway-id';
+import type { GatewayRegistry, RegistryDaemon } from './types';
+
+// The request params that hold a gateway id, and the refusal a daemon
+// gives for an id it does not hold, which the gateway gives for an id that
+// routes nowhere.
+const ID_PARAMS: readonly (readonly [string, 'session' | 'message' | 'report'])[] = [
+  ['session', 'session'],
+  ['parent', 'session'],
+  ['message', 'message'],
+  ['report', 'report'],
+];
+
+/**
+ * A daemon request's route: the daemon its id params point at, or null
+ * for a request with none; the params with each gateway id replaced by the
+ * daemon's own id; and each daemon id mapped back to the gateway id the
+ * caller sent, for errors that quote it. An id that is malformed, holds
+ * an unknown name or a stale incarnation, or points at another daemon than
+ * the request's other ids gets the refusal a daemon gives for an id it
+ * never held.
+ */
+export function resolveDaemonRequest(
+  params: Readonly<Record<string, unknown>>,
+  registry: GatewayRegistry,
+): {
+  readonly daemon: RegistryDaemon | null;
+  readonly params: Readonly<Record<string, unknown>>;
+  readonly requestIDs: ReadonlyMap<string, string>;
+} {
+  let daemon: RegistryDaemon | null = null;
+  const rewritten: Record<string, unknown> = { ...params };
+
+  const requestIDs = new Map<string, string>();
+
+  for (const [field, kind] of ID_PARAMS) {
+    const value = params[field];
+
+    if (typeof value !== 'string') {
+      continue;
+    }
+
+    const parsed = parseGatewayID(value, registry);
+
+    if (parsed === null || (daemon !== null && parsed.daemon !== daemon)) {
+      throw kind === 'session'
+        ? new DaemonError('no_such_session', `no session '${value}'`)
+        : new DaemonError('bad_args', `no ${kind} '${value}'`);
+    }
+
+    daemon = parsed.daemon;
+    rewritten[field] = parsed.id;
+
+    requestIDs.set(parsed.id, value);
+  }
+
+  return { daemon, params: rewritten, requestIDs };
+}