@zgeoff/atc 3.3.0 → 3.4.0

package/src/test-utils/start-output-capture.ts

@@ -0,0 +1,20 @@
+/**
+ * Reads the stream in the background and keeps every chunk it has read, as
+ * text, in arrival order, until the stream ends. `read` returns all the text
+ * read so far, so a test can wait on output from a process that never
+ * exits.
+ */
+// oxlint-disable-next-line prefer-readonly-parameter-types -- reading a stream locks and drains it
+export function startOutputCapture(stream: ReadableStream<Uint8Array>) {
+  let text = '';
+
+  const decoder = new TextDecoder();
+
+  void (async () => {
+    for await (const chunk of stream) {
+      text += decoder.decode(chunk, { stream: true });
+    }
+  })();
+
+  return { read: () => text };
+}

package/src/test-utils/start-stub-dropping-daemon.ts

@@ -0,0 +1,103 @@
+import type { DaemonFeature } from '../protocol/daemon-features';
+import {
+  MAX_CHUNK,
+  MAX_LINE,
+  PROTOCOL_V,
+  decodeMessage,
+  encodeMessage,
+} from '../protocol/protocol';
+
+interface DroppingDaemonOptions {
+  // The features the first handshake announces.
+  readonly features: readonly DaemonFeature[];
+
+  // The features every later handshake announces, as a daemon restarted on
+  // another build would; the first handshake's features when absent.
+  readonly retryFeatures?: readonly DaemonFeature[];
+}
+
+/**
+ * A daemon on a unix socket whose connection drops mid-request: it answers
+ * each handshake as a daemon does, announcing the features the options give, ends the connection
+ * that carries the first request of any other method without answering it,
+ * and answers every later one with a session `s-1`. `keys` records the
+ * idempotency key each of those requests carried, `undefined` for one that
+ * carried none. `reads` counts the reads it has taken from every connection,
+ * so a test can wait until one piece of a split write has arrived. Stop it
+ * with `stop`, or hold it with `using`.
+ */
+export function startStubDroppingDaemon(socketPath: string, options: DroppingDaemonOptions) {
+  const keys: unknown[] = [];
+  let hellos = 0;
+  let reads = 0;
+
+  const server = Bun.listen<{ buffer: string }>({
+    unix: socketPath,
+    socket: {
+      open(socket) {
+        socket.data = { buffer: '' };
+      },
+      data(socket, buf) {
+        reads += 1;
+
+        const lines = `${socket.data.buffer}${buf.toString()}`.split('\n');
+
+        socket.data.buffer = lines.pop() ?? '';
+
+        for (const line of lines) {
+          const decoded = decodeMessage(line);
+
+          if (decoded.kind !== 'request') {
+            continue;
+          }
+
+          if (decoded.msg.m === 'daemon.hello') {
+            hellos += 1;
+
+            const announced =
+              hellos === 1 ? options.features : (options.retryFeatures ?? options.features);
+
+            socket.write(
+              encodeMessage({
+                v: PROTOCOL_V,
+                id: decoded.msg.id,
+                ok: {
+                  daemon: 'atc/dropping-build',
+                  limits: { maxLine: MAX_LINE, maxChunk: MAX_CHUNK },
+                  lastUsedAgent: 'claude',
+                  features: announced,
+                },
+              }),
+            );
+
+            continue;
+          }
+
+          keys.push(decoded.msg.p?.['idempotencyKey']);
+
+          if (keys.length === 1) {
+            socket.end();
+            continue;
+          }
+
+          socket.write(
+            encodeMessage({ v: PROTOCOL_V, id: decoded.msg.id, ok: { session: { id: 's-1' } } }),
+          );
+        }
+      },
+    },
+  });
+
+  return {
+    keys,
+    get reads() {
+      return reads;
+    },
+    stop() {
+      server.stop(true);
+    },
+    [Symbol.dispose]() {
+      server.stop(true);
+    },
+  };
+}

package/src/test-utils/start-stub-impd-info.ts

@@ -0,0 +1,32 @@
+/**
+ * An impd stand-in on a real HTTP port of the loopback address. Every call
+ * is answered with HTTP 200 and the body impd's RPC sends for system info,
+ * `{ json: info }`, so a client reads `info.features` as impd's features;
+ * the test sets `info.features` to what impd should report. `paths` holds
+ * the request path of each call, in order. Disposal stops the server; the
+ * asynchronous form resolves once it has stopped.
+ */
+export function startStubImpdInfo() {
+  const paths: string[] = [];
+  const info: { features: unknown } = { features: undefined };
+
+  const server = Bun.serve({
+    port: 0,
+    hostname: '127.0.0.1',
+    fetch: (request) => {
+      paths.push(new URL(request.url).pathname);
+
+      return Response.json({ json: info });
+    },
+  });
+
+  return {
+    url: `http://127.0.0.1:${String(server.port)}`,
+    paths,
+    info,
+    [Symbol.dispose]: () => {
+      void server.stop(true);
+    },
+    [Symbol.asyncDispose]: () => server.stop(true),
+  };
+}

package/src/test-utils/start-stub-impd.ts

@@ -0,0 +1,138 @@
+import type { ServerWebSocket } from 'bun';
+import { isRecord } from '../shared/report';
+
+// What the stand-in does with an exec open: refuse it as a start whose
+// broker is not ready, start it and count its stdin bytes as `wc -c` does,
+// or start it and exit 2 at once without reading stdin.
+type StubExecReply = 'refuse' | 'count' | 'exit-early';
+
+/**
+ * Starts an impd stand-in on a real HTTP port. It records the authorization
+ * header of each call and WebSocket upgrade, and the path and input of each
+ * RPC call. It answers a call with the answer the caller set for its path in
+ * `answers`, or else as system info, and answers a tunnel listen as
+ * listening, keeping that control socket in `controls` so a caller can
+ * announce a guest connection on it. It records each exec open message in
+ * `execOpens` and answers it as `exec.reply` says, a refusal as a start
+ * whose broker is not ready by default. It takes no WebSocket message over
+ * 2 MiB, as impd refuses one over its own limit. Disposal stops the server
+ * and drops every open connection at once.
+ */
+export function startStubImpd() {
+  const authorizations: (string | null)[] = [];
+  const calls: { path: string; input: unknown }[] = [];
+
+  const answers = new Map<string, { status: number; json: unknown }>();
+
+  const controls: ServerWebSocket[] = [];
+  const execOpens: unknown[] = [];
+  const exec: { reply: StubExecReply } = { reply: 'refuse' };
+
+  const counted = new WeakMap<ServerWebSocket, number>();
+
+  const server = Bun.serve({
+    port: 0,
+    hostname: '127.0.0.1',
+    fetch: async (request, bunServer) => {
+      authorizations.push(request.headers.get('authorization'));
+
+      const path = new URL(request.url).pathname;
+
+      const isUpgraded = (path === '/tunnel' || path === '/exec') && bunServer.upgrade(request);
+      const text = isUpgraded ? '' : await request.text();
+      const body: unknown = text === '' ? null : JSON.parse(text);
+
+      if (!isUpgraded) {
+        calls.push({ path, input: isRecord(body) ? body['json'] : undefined });
+      }
+
+      const answer = answers.get(path) ?? {
+        status: 200,
+        json: { features: { sessionOffsets: true, leases: true } },
+      };
+
+      return isUpgraded
+        ? undefined
+        : Response.json({ json: answer.json }, { status: answer.status });
+    },
+    websocket: {
+      maxPayloadLength: 2 * 1024 * 1024,
+      message: (socket, message) => {
+        const seen = counted.get(socket);
+
+        if (typeof message !== 'string') {
+          if (seen !== undefined) {
+            counted.set(socket, seen + message.byteLength - 1);
+          }
+
+          return;
+        }
+
+        const parsed: unknown = JSON.parse(message);
+
+        if (!isRecord(parsed)) {
+          return;
+        }
+
+        if (parsed['type'] === 'stdin_eof' && seen !== undefined) {
+          const count = new TextEncoder().encode(`${String(seen)}\n`);
+
+          socket.send(new Uint8Array([1, ...count]));
+          socket.send(JSON.stringify({ type: 'exit', code: 0, signal: null }));
+
+          return;
+        }
+
+        if (parsed['type'] === 'start' || parsed['type'] === 'attach') {
+          execOpens.push(parsed);
+
+          if (exec.reply === 'refuse') {
+            socket.send(
+              JSON.stringify({
+                type: 'error',
+                code: 'PRECONDITION_FAILED',
+                message: 'the broker is not ready',
+                data: { reason: 'broker_not_ready', detail: 'the broker CA did not install' },
+              }),
+            );
+
+            return;
+          }
+
+          socket.send(JSON.stringify({ type: 'started', pid: 7 }));
+
+          if (exec.reply === 'count') {
+            counted.set(socket, 0);
+
+            return;
+          }
+
+          socket.send(JSON.stringify({ type: 'exit', code: 2, signal: null }));
+
+          return;
+        }
+
+        if (parsed['type'] === 'listen') {
+          controls.push(socket);
+
+          socket.send(
+            JSON.stringify({ type: 'listening', listener: 'l1', path: '/tmp/r.sock', port: null }),
+          );
+        }
+      },
+    },
+  });
+
+  return {
+    url: `http://127.0.0.1:${String(server.port)}`,
+    authorizations,
+    calls,
+    answers,
+    controls,
+    execOpens,
+    exec,
+    [Symbol.dispose]: () => {
+      void server.stop(true);
+    },
+  };
+}

package/src/test-utils/start-stub-legacy-daemon.ts

@@ -0,0 +1,166 @@
+import type { SocketHandler } from 'bun';
+import type { DaemonFeature } from '../protocol/daemon-features';
+import {
+  MAX_CHUNK,
+  MAX_LINE,
+  PROTOCOL_V,
+  decodeMessage,
+  encodeMessage,
+} from '../protocol/protocol';
+
+interface ReceivedRequest {
+  readonly m: string;
+  readonly p: Readonly<Record<string, unknown>> | undefined;
+}
+
+// A TCP address to listen on in place of a unix socket; port 0 lets the
+// kernel choose one.
+interface StubLegacyDaemonTCPAddress {
+  readonly hostname: string;
+  readonly port: number;
+}
+
+interface StubLegacyDaemonOptions {
+  readonly features?: readonly DaemonFeature[];
+
+  // The protocol version the daemon speaks; a hello on any other version is
+  // refused with `protocol_mismatch`, as a real daemon refuses it.
+  readonly protocol?: number;
+
+  readonly replies?: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+}
+
+/**
+ * An older atc daemon listening on a unix socket, or on the TCP address
+ * given in its place, and speaking the current
+ * protocol version, or the one `protocol` holds. Its `daemon.hello` announces `features` when the options
+ * hold that list, and announces none without it, as a daemon from before
+ * features did. It answers `daemon.hello`, `daemon.ping`, and each method in
+ * `replies` with that method's reply, and refuses every other method with
+ * `unknown_method`. Every request it receives is recorded in `requests`, and
+ * `connections` counts the connections it accepted and those still open.
+ * `port` holds the TCP port it bound, `null` on a unix socket. Stop
+ * it with `stop`, or hold it with `using`.
+ */
+export function startStubLegacyDaemon(
+  address: string | StubLegacyDaemonTCPAddress,
+  options: StubLegacyDaemonOptions = {},
+) {
+  const answers: Readonly<Record<string, Readonly<Record<string, unknown>>>> = {
+    'daemon.hello': {
+      daemon: 'atc/legacy-build',
+      limits: { maxLine: MAX_LINE, maxChunk: MAX_CHUNK },
+      lastUsedAgent: 'claude',
+      ...(options.features === undefined ? {} : { features: options.features }),
+    },
+    'daemon.ping': {},
+    ...options.replies,
+  };
+
+  const protocol = options.protocol ?? PROTOCOL_V;
+  const requests: ReceivedRequest[] = [];
+  const connections = { accepted: 0, open: 0 };
+
+  const handlers: SocketHandler<{ buffer: string }> = {
+    open(socket) {
+      socket.data = { buffer: '' };
+      connections.accepted += 1;
+      connections.open += 1;
+    },
+    close() {
+      connections.open -= 1;
+    },
+    data(socket, chunk) {
+      const lines = `${socket.data.buffer}${chunk.toString()}`.split('\n');
+
+      socket.data.buffer = lines.pop() ?? '';
+
+      for (const line of lines) {
+        const decoded = decodeMessage(line);
+
+        if (decoded.kind !== 'request') {
+          continue;
+        }
+
+        const req = decoded.msg;
+
+        requests.push({ m: req.m, p: req.p });
+
+        if (req.m === 'daemon.hello' && req.v !== protocol) {
+          const client = req.p?.['client'];
+
+          socket.write(
+            encodeMessage({
+              v: protocol,
+              id: req.id,
+              err: {
+                code: 'protocol_mismatch',
+                msg: `${String(client)} speaks protocol v${req.v}, daemon atc/legacy-build speaks v${protocol}; restart the daemon so both run the same build`,
+              },
+            }),
+          );
+
+          continue;
+        }
+
+        const answer = answers[req.m];
+
+        const reply =
+          answer === undefined
+            ? {
+                v: protocol,
+                id: req.id,
+                err: { code: 'unknown_method' as const, msg: `unknown method '${req.m}'` },
+              }
+            : { v: protocol, id: req.id, ok: answer };
+
+        socket.write(encodeMessage(reply));
+      }
+    },
+  };
+
+  const server = startListener(address, handlers);
+
+  return {
+    requests,
+    connections,
+    port: server.port,
+    stop() {
+      server.stop();
+    },
+    [Symbol.dispose]() {
+      server.stop();
+    },
+  };
+}
+
+// Listens on the unix socket path, or on the TCP address in its place, and
+// returns the port bound, `null` for a unix socket.
+function startListener(
+  address: string | StubLegacyDaemonTCPAddress,
+  handlers: Readonly<SocketHandler<{ buffer: string }>>,
+): { readonly port: number | null; readonly stop: () => void } {
+  if (typeof address === 'string') {
+    const unix = Bun.listen<{ buffer: string }>({ unix: address, socket: handlers });
+
+    return {
+      port: null,
+      stop: () => {
+        unix.stop(true);
+      },
+    };
+  }
+
+  const tcp = Bun.listen<{ buffer: string }>({
+    hostname: address.hostname,
+    port: address.port,
+    socket: handlers,
+  });
+
+  return {
+    port: tcp.port,
+    stop: () => {
+      tcp.stop(true);
+    },
+  };
+}

package/src/test-utils/start-stub-mcp-server.ts

@@ -0,0 +1,50 @@
+interface StubMCPRequest {
+  readonly method: string;
+  readonly path: string;
+  readonly authorization: string | null;
+  readonly type: string | null;
+  readonly body: unknown;
+}
+
+interface StubMCPServer {
+  readonly url: string;
+
+  // Every request the stand-in received, in arrival order.
+  readonly requests: readonly StubMCPRequest[];
+
+  readonly [Symbol.dispose]: () => void;
+}
+
+/**
+ * A stand-in for an MCP HTTP server on a loopback port: it answers every
+ * request with the JSON body given, and records each request's method,
+ * path, authorization and content-type headers, and JSON body. `url` holds
+ * its origin. Disposal stops it; hold the result with `using`.
+ */
+export function startStubMCPServer(answer: unknown): StubMCPServer {
+  const requests: StubMCPRequest[] = [];
+
+  const server = Bun.serve({
+    hostname: '127.0.0.1',
+    port: 0,
+    async fetch(request) {
+      requests.push({
+        method: request.method,
+        path: new URL(request.url).pathname,
+        authorization: request.headers.get('authorization'),
+        type: request.headers.get('content-type'),
+        body: await request.json(),
+      });
+
+      return Response.json(answer);
+    },
+  });
+
+  return {
+    url: `http://127.0.0.1:${String(server.port)}`,
+    requests,
+    [Symbol.dispose]: () => {
+      void server.stop(true);
+    },
+  };
+}

package/src/test-utils/start-stub-refusing-listener.ts

@@ -0,0 +1,38 @@
+interface StubRefusingListener {
+  readonly port: number;
+
+  // What each read took from any connection, decoded, in arrival order.
+  readonly received: readonly string[];
+
+  readonly [Symbol.dispose]: () => void;
+}
+
+/**
+ * A stand-in for a daemon's TCP listener refusing a connection whose first
+ * line is not a handshake: on a loopback port, it records what each read
+ * takes from a connection and ends that connection, answering nothing.
+ * Disposal stops it; hold the result with `using`.
+ */
+export function startStubRefusingListener(): StubRefusingListener {
+  const received: string[] = [];
+
+  const server = Bun.listen({
+    hostname: '127.0.0.1',
+    port: 0,
+    socket: {
+      data(socket, data) {
+        received.push(data.toString());
+        socket.end();
+      },
+      error() {},
+    },
+  });
+
+  return {
+    port: server.port,
+    received,
+    [Symbol.dispose]: () => {
+      server.stop(true);
+    },
+  };
+}

package/src/test-utils/start-stub-reporter-socket.ts

@@ -0,0 +1,77 @@
+import { waitFor } from './wait-for';
+
+interface StubReporterSocket {
+  // Every complete line received so far, newline removed, in arrival order.
+  readonly lines: readonly string[];
+
+  // How many reads the stand-in has taken from its connections, so a test
+  // can wait until one piece of a split write has arrived.
+  readonly reads: number;
+  readonly waitForLine: (timeoutMs?: number) => Promise<string>;
+  readonly [Symbol.dispose]: () => void;
+  readonly [Symbol.asyncDispose]: () => Promise<void>;
+}
+
+/**
+ * A stand-in for the daemon's reporter socket: listens on the unix socket
+ * path and collects each newline-terminated line any connection writes,
+ * buffering a partial line per connection, as the daemon reads the lines
+ * hook and report commands send. It never writes back, and leaves each
+ * connection for the sender to close. `waitForLine` resolves with the first
+ * line once one has arrived, and rejects naming the socket when none arrives
+ * within `timeoutMs`, 5 seconds by default. Disposal stops the listener; hold the
+ * result with `using` or `await using`.
+ */
+export function startStubReporterSocket(path: string): StubReporterSocket {
+  const lines: string[] = [];
+  let reads = 0;
+
+  const server = Bun.listen<{ pending: string }>({
+    unix: path,
+    socket: {
+      open(socket) {
+        socket.data = { pending: '' };
+      },
+      data(socket, chunk) {
+        reads += 1;
+
+        const parts = `${socket.data.pending}${chunk.toString()}`.split('\n');
+
+        socket.data.pending = parts.pop() ?? '';
+
+        lines.push(...parts);
+      },
+      error() {},
+    },
+  });
+
+  const stop = () => {
+    server.stop(true);
+  };
+
+  return {
+    lines,
+    get reads() {
+      return reads;
+    },
+    waitForLine: (timeoutMs = 5000) =>
+      waitFor(
+        () => {
+          const [first] = lines;
+
+          if (first === undefined) {
+            throw new Error(`no line has arrived at ${path}`);
+          }
+
+          return first;
+        },
+        { timeoutMs },
+      ),
+    [Symbol.dispose]: stop,
+    [Symbol.asyncDispose]: () => {
+      stop();
+
+      return Promise.resolve();
+    },
+  };
+}

package/src/test-utils/start-stub-restore-daemon.ts

@@ -0,0 +1,58 @@
+import { LineDecoder } from '../protocol/line-decoder';
+import { PROTOCOL_V, decodeMessage, encodeMessage } from '../protocol/protocol';
+
+/**
+ * A daemon stand-in on a unix socket path that speaks the real wire format
+ * to a fleet restore check: it answers every `fleet.restore` with an empty
+ * result, answers each other request with the next reply the test pushes
+ * onto `lists`, and withholds the answer to any request that finds `lists`
+ * empty. `methods` holds the method of each request it took, in order.
+ * Disposal stops the listener; hold the result with `using` or
+ * `await using`.
+ */
+export function startStubRestoreDaemon(socketPath: string) {
+  const lists: Readonly<Record<string, unknown>>[] = [];
+  const methods: string[] = [];
+
+  // Each connection gets a decoder of its own, so a partial line from one
+  // client never joins a line from another.
+  const server = Bun.listen<{ lines: LineDecoder }>({
+    unix: socketPath,
+    socket: {
+      open(socket) {
+        socket.data = { lines: new LineDecoder() };
+      },
+      data(socket, buf) {
+        const requests = socket.data.lines
+          .splitChunk(buf)
+          .map((line) => decodeMessage(line))
+          .filter((decoded) => decoded.kind === 'request');
+
+        for (const request of requests) {
+          methods.push(request.msg.m);
+
+          const ok = request.msg.m === 'fleet.restore' ? {} : lists.shift();
+
+          if (ok !== undefined) {
+            socket.write(encodeMessage({ v: PROTOCOL_V, id: request.msg.id, ok }));
+          }
+        }
+      },
+    },
+  });
+
+  const stop = () => {
+    server.stop(true);
+  };
+
+  return {
+    lists,
+    methods,
+    [Symbol.dispose]: stop,
+    [Symbol.asyncDispose]: () => {
+      stop();
+
+      return Promise.resolve();
+    },
+  };
+}