@zgeoff/atc 2.20.0 → 2.23.0

package/src/daemon/start-tcp-listener.ts

@@ -0,0 +1,165 @@
+import type { DaemonConnection, TCPPeer } from './daemon-connection';
+import { findTokenFingerprint } from './find-token-fingerprint';
+import { HandshakeThrottle } from './handshake-throttle';
+
+// The slice of an accepted socket a protocol connection writes to and ends.
+interface ListenerSocket {
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- a socket write takes a buffer with no readonly form
+  readonly write: (data: Uint8Array) => number;
+  readonly end: () => void;
+}
+
+interface TCPListenerOptions {
+  readonly host: string;
+  readonly port: number;
+  readonly tokens: readonly string[];
+
+  // How long a handshake waits once its address has failed too often.
+  readonly failureDelayMs: number;
+
+  // How many delayed handshakes may wait at once across every address.
+  readonly maxDelayedHandshakes: number;
+
+  // Builds the protocol connection for a newly accepted socket, and
+  // releases it once the socket closes.
+  readonly openConnection: (socket: ListenerSocket, peer: TCPPeer) => DaemonConnection;
+
+  // oxlint-disable-next-line prefer-readonly-parameter-types -- a connection is a live object the daemon releases
+  readonly closeConnection: (connection: DaemonConnection) => void;
+}
+
+export interface TCPListener {
+  // The port the listener bound, which a requested port of 0 leaves to the
+  // kernel.
+  readonly port: number;
+
+  // Replaces the tokens a handshake may present, closing at once every
+  // connection whose handshake token is not among them. Null drops every
+  // token: every connection closes and every handshake is refused.
+  readonly setTokens: (tokens: readonly string[] | null) => void;
+  readonly stop: () => void;
+}
+
+/**
+ * Starts the TCP listener for the client protocol. Every connection must
+ * open with a `daemon.hello` that carries a bearer token from the token
+ * file, and acts only as the principals its requests give, never as the
+ * daemon's owner. A delayed handshake ends early, refused, once its socket
+ * closes, and a handshake that would wait while the cap of delayed
+ * handshakes is full is refused at once and counted as a failure, so a
+ * flood across many sockets holds at most the cap of waits.
+ */
+export function startTCPListener(opts: TCPListenerOptions): TCPListener {
+  let tokens: readonly string[] | null = opts.tokens;
+
+  const throttle = new HandshakeThrottle(opts.failureDelayMs);
+  const connections = new Set<DaemonConnection>();
+
+  let delayed = 0;
+
+  // Ends the delayed handshake of each open socket once it closes.
+  const closedSockets = new WeakMap<object, (value: 'closed') => void>();
+
+  const server = Bun.listen<DaemonConnection>({
+    hostname: opts.host,
+    port: opts.port,
+    socket: {
+      open(socket) {
+        const address = socket.remoteAddress;
+        const closed = Promise.withResolvers<'closed'>();
+
+        closedSockets.set(socket, closed.resolve);
+
+        const peer: TCPPeer = {
+          verifyHandshake: async (presented) => {
+            const delay = throttle.getDelay(address, Date.now());
+
+            if (delay > 0 && delayed >= opts.maxDelayedHandshakes) {
+              throttle.recordFailure(address, Date.now());
+
+              return null;
+            }
+
+            if (delay > 0) {
+              delayed++;
+
+              const elapsed = Promise.withResolvers<'elapsed'>();
+
+              const timer = setTimeout(() => {
+                elapsed.resolve('elapsed');
+              }, delay);
+
+              const waited = await Promise.race([elapsed.promise, closed.promise]);
+
+              clearTimeout(timer);
+
+              delayed--;
+
+              if (waited === 'closed') {
+                return null;
+              }
+            }
+
+            const fingerprint =
+              tokens === null || presented === null
+                ? null
+                : findTokenFingerprint(tokens, presented);
+
+            if (fingerprint === null) {
+              throttle.recordFailure(address, Date.now());
+            }
+
+            return fingerprint;
+          },
+          recordFailure: () => {
+            throttle.recordFailure(address, Date.now());
+          },
+        };
+
+        socket.data = opts.openConnection(socket, peer);
+
+        connections.add(socket.data);
+      },
+      data(socket, buf) {
+        socket.data.applyChunk(socket.data.decodeChunk(buf));
+      },
+      drain(socket) {
+        socket.data.drain();
+      },
+      close(socket) {
+        closedSockets.get(socket)?.('closed');
+        closedSockets.delete(socket);
+        connections.delete(socket.data);
+        opts.closeConnection(socket.data);
+      },
+      error() {},
+    },
+  });
+
+  return {
+    port: server.port,
+    setTokens(next) {
+      tokens = next;
+
+      const kept =
+        next === null
+          ? new Set<string>()
+          : new Set(next.map((token) => findTokenFingerprint([token], token)));
+
+      for (const connection of connections) {
+        const fingerprint = connection.tokenFingerprint;
+
+        if (fingerprint !== null && !kept.has(fingerprint)) {
+          connection.dispose();
+        }
+      }
+    },
+    stop() {
+      for (const connection of connections) {
+        connection.dispose();
+      }
+
+      server.stop(true);
+    },
+  };
+}

package/src/federation/build-binding-payload-hash.ts

@@ -0,0 +1,34 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * The SHA-256 of a keyed request's params as canonical JSON: object keys
+ * sorted by UTF-16 code unit at every depth, with the idempotency key and
+ * the replay-only flag left out, so a retry that differs only in key order
+ * or in whether it only replays hashes the same and one with another
+ * payload does not. Code-unit order never ties
+ * two distinct keys, as a locale comparison can for two spellings of one
+ * accented letter.
+ */
+export function buildBindingPayloadHash(params: Readonly<Record<string, unknown>>): string {
+  const { idempotencyKey: _ignored, replayOnly: _replayOnly, ...payload } = params;
+
+  return createHash('sha256')
+    .update(JSON.stringify(sortKeysByCodeUnit(payload)))
+    .digest('hex');
+}
+
+function sortKeysByCodeUnit(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((item) => sortKeysByCodeUnit(item));
+  }
+
+  if (typeof value === 'object' && value !== null) {
+    return Object.fromEntries(
+      Object.entries(value)
+        .toSorted(([a], [b]) => Number(a > b) - Number(a < b))
+        .map(([key, item]) => [key, sortKeysByCodeUnit(item)]),
+    );
+  }
+
+  return value;
+}

package/src/federation/build-daemon-outdated-error.ts

@@ -0,0 +1,14 @@
+import type { DaemonFeature } from '../protocol/daemon-features';
+import { GatewayError } from './gateway-error';
+
+/**
+ * The refusal for a call that relies on a feature the daemon's handshake
+ * did not announce, holding the daemon's name and the missing feature.
+ */
+export function buildDaemonOutdatedError(daemon: string, feature: DaemonFeature): GatewayError {
+  return new GatewayError(
+    'daemon_outdated',
+    `daemon '${daemon}' runs an atc build without ${feature}; call without the option that needs it, or upgrade that daemon`,
+    { daemon, feature },
+  );
+}

package/src/federation/build-events-filter-hash.ts

@@ -0,0 +1,16 @@
+import { createHash } from 'node:crypto';
+
+/**
+ * The hash a gateway events cursor holds of the filters it was read
+ * under: the session filter, as the caller sent it, and the kind filter.
+ * A cursor read under one filter is refused under another, since its
+ * per-daemon positions only make sense for the events that filter kept.
+ */
+export function buildEventsFilterHash(
+  session: string | null,
+  kinds: readonly string[] | null,
+): string {
+  const canonical = JSON.stringify([session, kinds === null ? null : kinds.toSorted()]);
+
+  return createHash('sha256').update(canonical).digest('base64url').slice(0, 22);
+}

package/src/federation/build-gateway-error.ts

@@ -0,0 +1,45 @@
+import { DaemonError } from '../protocol/daemon-error';
+import { buildRuledValue } from './build-ruled-value';
+import { ERROR_DATA_RULES } from './id-rules';
+import type { RegistryDaemon } from './types';
+
+/**
+ * A daemon's error as the gateway returns it: the same code, every id in
+ * its `data` rewritten for the daemon, and every daemon id its message
+ * quotes, from the data or from the request, replaced by its gateway id.
+ * `requestIDs` maps each daemon id the request carried to the gateway id
+ * the caller sent.
+ */
+export function buildGatewayError(
+  error: Readonly<DaemonError>,
+  daemon: Pick<RegistryDaemon, 'name' | 'incarnation'>,
+  requestIDs: ReadonlyMap<string, string>,
+): DaemonError {
+  if (error.data === undefined) {
+    return new DaemonError(error.code, buildQuotedMessage(error.message, requestIDs));
+  }
+
+  const rewritten = buildRuledValue(error.data, ERROR_DATA_RULES, daemon);
+  const data = typeof rewritten === 'object' && rewritten !== null ? { ...rewritten } : error.data;
+
+  const quoted = new Map(requestIDs);
+
+  for (const field of ERROR_DATA_RULES.keys()) {
+    const inner = error.data[field];
+    const outer = Reflect.get(data, field);
+
+    if (typeof inner === 'string' && typeof outer === 'string') {
+      quoted.set(inner, outer);
+    }
+  }
+
+  return new DaemonError(error.code, buildQuotedMessage(error.message, quoted), data);
+}
+
+// The message with each quoted daemon id replaced, longest first so an id
+// that contains another is replaced whole.
+function buildQuotedMessage(message: string, ids: ReadonlyMap<string, string>): string {
+  const ordered = [...ids].toSorted(([a], [b]) => b.length - a.length);
+
+  return ordered.reduce((text, [inner, outer]) => text.replaceAll(inner, outer), message);
+}

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

@@ -0,0 +1,14 @@
+import type { RegistryDaemon } from './types';
+
+/**
+ * The id the gateway returns for a daemon's id: `<name>.<incarnation>.<id>`.
+ * The name is the daemon's logical identity and the incarnation the state
+ * identity pinned behind it, so an id held across a rebind of the name
+ * never reaches the new daemon.
+ */
+export function buildGatewayID(
+  daemon: Pick<RegistryDaemon, 'name' | 'incarnation'>,
+  id: string,
+): string {
+  return `${daemon.name}.${daemon.incarnation}.${id}`;
+}

package/src/federation/build-gateway-result.ts

@@ -0,0 +1,31 @@
+import { isRecord } from '../shared/report';
+import { buildRuledValue } from './build-ruled-value';
+import { ID_RULES } from './id-rules';
+import type { RegistryDaemon } from './types';
+
+/**
+ * A daemon method's answer as the gateway returns it, every id field in
+ * the method's rules rewritten for the daemon that answered. Throws for a
+ * method without rules, so no answer leaves the gateway unchecked, and for
+ * `events.read`, whose answer goes through the event merge, which owns its
+ * cursors.
+ */
+export function buildGatewayResult(
+  method: string,
+  result: Readonly<Record<string, unknown>>,
+  daemon: Pick<RegistryDaemon, 'name' | 'incarnation'>,
+): Readonly<Record<string, unknown>> {
+  if (method === 'events.read') {
+    throw new Error('an events.read answer is rewritten by the event merge');
+  }
+
+  const rules = ID_RULES[method];
+
+  if (rules === undefined) {
+    throw new Error(`the gateway has no id rules for ${method}`);
+  }
+
+  const rewritten = buildRuledValue(result, rules, daemon);
+
+  return isRecord(rewritten) ? rewritten : result;
+}

package/src/federation/build-ruled-value.ts

@@ -0,0 +1,53 @@
+import { isRecord } from '../shared/report';
+import { buildGatewayID } from './build-gateway-id';
+import type { IDRule } from './id-rules';
+import type { RegistryDaemon } from './types';
+
+type DaemonRef = Pick<RegistryDaemon, 'name' | 'incarnation'>;
+
+/**
+ * A daemon answer with every field a rule covers rewritten for the
+ * gateway: ids carry the daemon's name and incarnation, and a locator's
+ * daemon ID gives way to them. A `cursor` field is left for the event
+ * merge, a `keep` object is still searched for ruled fields below it, and
+ * an `opaque` value passes whole.
+ * Fields without a rule pass unchanged.
+ */
+export function buildRuledValue(
+  value: unknown,
+  rules: ReadonlyMap<string, IDRule>,
+  daemon: DaemonRef,
+  path = '',
+): unknown {
+  const rule = rules.get(path);
+
+  if (rule === 'opaque') {
+    return value;
+  }
+
+  if (rule === 'id' && typeof value === 'string') {
+    return buildGatewayID(daemon, value);
+  }
+
+  if (rule === 'locator' && isRecord(value)) {
+    const { daemonID: _daemonID, ...rest } = value;
+
+    return { daemon: daemon.name, incarnation: daemon.incarnation, ...rest };
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item: unknown) => buildRuledValue(item, rules, daemon, `${path}[]`));
+  }
+
+  if (isRecord(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, inner]) => {
+        const innerPath = path === '' ? key : `${path}.${key}`;
+
+        return [key, buildRuledValue(inner, rules, daemon, innerPath)];
+      }),
+    );
+  }
+
+  return value;
+}

package/src/federation/collect-unruled-id-paths.ts

@@ -0,0 +1,46 @@
+import { isRecord } from '../shared/report';
+import type { IDRule } from './id-rules';
+
+// A value that holds one of atc's ids: a session id or daemon ID is a
+// UUID, and a message id is a UUID behind `m-`.
+const ID_PATTERN = /[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}/;
+
+/**
+ * The paths of every string in a daemon answer that holds an id but has no
+ * rule, so a daemon field that starts carrying an id cannot leave the
+ * gateway without its daemon's name. A ruled field and everything below a
+ * ruled locator or an opaque value count as covered.
+ */
+export function collectUnruledIDPaths(
+  value: unknown,
+  rules: ReadonlyMap<string, IDRule>,
+  path = '',
+): string[] {
+  const rule = rules.get(path);
+
+  if (
+    rule === 'locator' ||
+    rule === 'opaque' ||
+    (rule !== undefined && typeof value === 'string')
+  ) {
+    return [];
+  }
+
+  if (typeof value === 'string') {
+    return ID_PATTERN.test(value) ? [path] : [];
+  }
+
+  if (Array.isArray(value)) {
+    return value.flatMap((item: unknown) => collectUnruledIDPaths(item, rules, `${path}[]`));
+  }
+
+  if (isRecord(value)) {
+    return Object.entries(value).flatMap(([key, inner]) => {
+      const innerPath = path === '' ? key : `${path}.${key}`;
+
+      return collectUnruledIDPaths(inner, rules, innerPath);
+    });
+  }
+
+  return [];
+}