@zgeoff/atc 3.3.1 → 3.4.1

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

@@ -0,0 +1,171 @@
+import type { SocketHandler } from 'bun';
+import type { DaemonFeature } from '../protocol/daemon-features';
+import {
+  MAX_CHUNK,
+  MAX_LINE,
+  PROTOCOL_V,
+  decodeMessage,
+  encodeMessage,
+} from '../protocol/protocol';
+import { registerTestCleanup } from './register-test-cleanup';
+
+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>>>>;
+
+  // Who stops the daemon: the current test, once it finishes, or the
+  // caller alone, for a process that runs it outside any test; the test
+  // unless set.
+  readonly owner?: 'test' | 'caller';
+}
+
+/**
+ * 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. It stops
+ * once the current test finishes, so it must run inside a test, unless the
+ * options make the caller its owner; `stop` or disposal stops it sooner, and
+ * a second stop does nothing.
+ */
+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);
+  const stop = options.owner === 'caller' ? server.stop : registerTestCleanup(server.stop);
+
+  return {
+    requests,
+    connections,
+    port: server.port,
+    stop,
+    [Symbol.dispose]: 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,55 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
+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. It stops once the current test finishes, so it must run
+ * inside a test; disposal stops it sooner, and a second stop does nothing.
+ */
+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);
+    },
+  });
+
+  const stop = registerTestCleanup(() => server.stop(true));
+
+  return {
+    url: `http://127.0.0.1:${String(server.port)}`,
+    requests,
+    [Symbol.dispose]: () => {
+      void stop();
+    },
+  };
+}

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

@@ -0,0 +1,47 @@
+import type { Socket } from 'bun';
+import { registerTestCleanup } from './register-test-cleanup';
+
+interface StubRecordingListener {
+  // Resolves with the server's side of the first connection it accepts.
+  readonly accepted: Promise<Socket>;
+
+  // What each read took from any connection, decoded, in arrival order.
+  readonly received: readonly string[];
+  readonly [Symbol.dispose]: () => void;
+}
+
+/**
+ * A stand-in for a peer that a test writes through: it listens on the unix
+ * socket path, hands the test the server's side of the first connection it
+ * accepts, records what each read takes from any connection, and sends
+ * nothing of its own. It stops, dropping every connection it holds, once
+ * the current test finishes, so it must run inside a test; disposal stops it
+ * sooner, and a second stop does nothing.
+ */
+export function startStubRecordingListener(path: string): StubRecordingListener {
+  const accepted = Promise.withResolvers<Socket>();
+  const received: string[] = [];
+
+  const server = Bun.listen({
+    unix: path,
+    socket: {
+      open(socket) {
+        accepted.resolve(socket);
+      },
+      data(_socket, data) {
+        received.push(data.toString());
+      },
+      error() {},
+    },
+  });
+
+  const stop = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
+  return {
+    accepted: accepted.promise,
+    received,
+    [Symbol.dispose]: stop,
+  };
+}

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

@@ -0,0 +1,43 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
+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.
+ * It stops once the current test finishes, so it must run inside a test;
+ * disposal stops it sooner, and a second stop does nothing.
+ */
+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() {},
+    },
+  });
+
+  const stop = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
+  return {
+    port: server.port,
+    received,
+    [Symbol.dispose]: stop,
+  };
+}

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

@@ -0,0 +1,79 @@
+import { registerTestCleanup } from './register-test-cleanup';
+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. The listener stops once the
+ * current test finishes, so it must run inside a test; disposal stops it
+ * sooner, and a second stop does nothing.
+ */
+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 = registerTestCleanup(() => {
+    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,59 @@
+import { LineDecoder } from '../protocol/line-decoder';
+import { PROTOCOL_V, decodeMessage, encodeMessage } from '../protocol/protocol';
+import { registerTestCleanup } from './register-test-cleanup';
+
+/**
+ * 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.
+ * The listener stops once the current test finishes, so it must run inside
+ * a test; disposal stops it sooner, and a second stop does nothing.
+ */
+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 = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
+  return {
+    lists,
+    methods,
+    [Symbol.dispose]: stop,
+    [Symbol.asyncDispose]: () => {
+      stop();
+
+      return Promise.resolve();
+    },
+  };
+}

package/src/test-utils/start-stub-session-bridge.ts

@@ -0,0 +1,100 @@
+import { isRecord } from '../shared/report';
+import { registerTestCleanup } from './register-test-cleanup';
+
+type BridgeRequest = Readonly<Record<string, unknown>>;
+
+/**
+ * The lines the bridge writes back for one request, in order, or `null` to
+ * end the connection without answering.
+ */
+type BridgeResponder = (request: BridgeRequest) => readonly BridgeRequest[] | null;
+
+interface StubSessionBridge {
+  // Every request line received so far, parsed, in arrival order.
+  readonly requests: readonly BridgeRequest[];
+
+  // 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 [Symbol.dispose]: () => void;
+  readonly [Symbol.asyncDispose]: () => Promise<void>;
+}
+
+/**
+ * A stand-in for the session bridge a remote host's commands dial: listens
+ * on the unix socket path and reads newline-delimited JSON requests,
+ * buffering a partial line per connection. It opens every tap, answering a
+ * `tap.open` request with `ok` under the request's id as the real bridge
+ * does once it attaches the tap, and hands every other request to the
+ * responder, writing back each line it returns. A line that is not a JSON
+ * object reaches the responder as an empty request. The listener stops once
+ * the current test finishes, so it must run inside a test; disposal stops it
+ * sooner, and a second stop does nothing.
+ */
+export function startStubSessionBridge(path: string, respond: BridgeResponder): StubSessionBridge {
+  const requests: BridgeRequest[] = [];
+  let reads = 0;
+
+  const server = Bun.listen<{ pending: string }>({
+    unix: path,
+    socket: {
+      open(socket) {
+        socket.data = { pending: '' };
+      },
+      data(socket, chunk) {
+        reads += 1;
+
+        const lines = `${socket.data.pending}${chunk.toString()}`.split('\n');
+
+        socket.data.pending = lines.pop() ?? '';
+
+        for (const line of lines.filter((text) => text !== '')) {
+          const request = parseRequest(line);
+
+          requests.push(request);
+
+          const answers =
+            request['op'] === 'tap.open' ? [{ id: request['id'], ok: true }] : respond(request);
+
+          if (answers === null) {
+            socket.end();
+
+            return;
+          }
+
+          for (const answer of answers) {
+            socket.write(`${JSON.stringify(answer)}\n`);
+          }
+        }
+      },
+      error() {},
+    },
+  });
+
+  const stop = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
+  return {
+    requests,
+    get reads() {
+      return reads;
+    },
+    [Symbol.dispose]: stop,
+    [Symbol.asyncDispose]: () => {
+      stop();
+
+      return Promise.resolve();
+    },
+  };
+}
+
+function parseRequest(line: string): BridgeRequest {
+  try {
+    const parsed: unknown = JSON.parse(line);
+
+    return isRecord(parsed) && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}

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

@@ -0,0 +1,38 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
+/**
+ * An HTTP stand-in for an upstream that hangs: it listens on a real port of
+ * the loopback address, takes every request, and never answers one. `paths`
+ * holds the request path of each request it took, in order. The server
+ * stops, dropping the connections it holds, once the current test finishes,
+ * so it must run inside a test; disposal stops it sooner, the asynchronous
+ * form resolving once it has stopped, and a second stop does nothing.
+ */
+export function startStubSilentServer() {
+  const paths: string[] = [];
+
+  const server = Bun.serve({
+    port: 0,
+    hostname: '127.0.0.1',
+
+    // A held request would otherwise end after Bun's idle timeout, and the
+    // upstream would stop being one that never answers.
+    idleTimeout: 0,
+    fetch: (request) => {
+      paths.push(new URL(request.url).pathname);
+
+      return new Promise<Response>(() => {});
+    },
+  });
+
+  const stop = registerTestCleanup(() => server.stop(true));
+
+  return {
+    url: `http://127.0.0.1:${String(server.port)}/`,
+    paths,
+    [Symbol.dispose]: () => {
+      void stop();
+    },
+    [Symbol.asyncDispose]: stop,
+  };
+}

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

@@ -0,0 +1,41 @@
+import { join } from 'node:path';
+import { registerTestCleanup } from './register-test-cleanup';
+
+/**
+ * Starts a daemon composed with a fixture source, in a process of its own
+ * with the environment given, and resolves once it listens. Its home, sockets
+ * and state follow that environment as `atc daemon`'s would, so a client
+ * started with the same environment dials it instead of starting its own.
+ * `ATC_TEST_SOURCES` picks its sources, the fixture one unless it holds
+ * `none`; `ATC_TEST_FIXTURE_URL` holds the repository the fixture source
+ * lists, and `ATC_TEST_SOURCE_LOG` a file it appends each listing to.
+ * The process stops once the current test finishes, so it must run inside
+ * a test; disposal stops it sooner, and a second stop does nothing.
+ */
+export async function startStubSourceDaemon(env: Readonly<Record<string, string | undefined>>) {
+  const daemon = Bun.spawn([process.execPath, join(import.meta.dir, 'run-source-daemon.ts')], {
+    env: { ATC_TEST_SOURCES: 'fixture', ...env },
+    stdout: 'pipe',
+    stderr: 'ignore',
+  });
+
+  const stop = registerTestCleanup(async () => {
+    daemon.kill();
+
+    await daemon.exited;
+  });
+
+  const reader = daemon.stdout.getReader();
+
+  const first = await reader.read();
+
+  reader.releaseLock();
+
+  if (first.done) {
+    await stop();
+
+    throw new Error('the source daemon exited before it listened');
+  }
+
+  return { pid: daemon.pid, [Symbol.asyncDispose]: stop };
+}

package/src/test-utils/start-stub-stalled-client.ts

@@ -0,0 +1,61 @@
+import { createConnection } from 'node:net';
+import { PROTOCOL_V, encodeMessage } from '../protocol/protocol';
+import { registerTestCleanup } from './register-test-cleanup';
+
+interface StubStalledClient {
+  // Each chunk the client has read off its connection, in order.
+  readonly chunks: readonly unknown[];
+
+  // How many bytes have arrived on the connection and wait unread.
+  readonly countUnreadBytes: () => number;
+  readonly [Symbol.dispose]: () => void;
+}
+
+/**
+ * A stand-in for a daemon client that stops reading: it connects to the
+ * daemon's unix socket, sends a `daemon.hello` with no auth as `client`,
+ * reads the first chunk the daemon sends, and then holds its next read on
+ * a promise that never resolves, so whatever the daemon sends it after
+ * that backs up. Resolves once that first chunk arrives. The connection is
+ * destroyed once the current test finishes, so it must run inside a test;
+ * disposal destroys it sooner, and a second stop does nothing.
+ */
+export async function startStubStalledClient(
+  socketPath: string,
+  client: string,
+): Promise<StubStalledClient> {
+  const held = Promise.withResolvers<void>();
+  const first = Promise.withResolvers<void>();
+  const chunks: unknown[] = [];
+  const socket = createConnection(socketPath);
+
+  const stop = registerTestCleanup(() => {
+    socket.destroy();
+  });
+
+  socket.write(
+    encodeMessage({
+      v: PROTOCOL_V,
+      id: 1,
+      m: 'daemon.hello',
+      p: { client, auth: { scheme: 'none' } },
+    }),
+  );
+
+  void (async () => {
+    for await (const chunk of socket) {
+      chunks.push(chunk);
+      first.resolve();
+
+      await held.promise;
+    }
+  })();
+
+  await first.promise;
+
+  return {
+    chunks,
+    countUnreadBytes: () => socket.readableLength,
+    [Symbol.dispose]: stop,
+  };
+}