@zgeoff/atc 3.3.0 → 3.4.0

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

@@ -0,0 +1,98 @@
+import { isRecord } from '../shared/report';
+
+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. Disposal stops the
+ * listener; hold the result with `using` or `await using`.
+ */
+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 = () => {
+    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,33 @@
+/**
+ * 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. Disposal stops
+ * the server and drops the connections it holds; the asynchronous form
+ * resolves once it has stopped.
+ */
+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>(() => {});
+    },
+  });
+
+  return {
+    url: `http://127.0.0.1:${String(server.port)}/`,
+    paths,
+    [Symbol.dispose]: () => {
+      void server.stop(true);
+    },
+    [Symbol.asyncDispose]: () => server.stop(true),
+  };
+}

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

@@ -0,0 +1,39 @@
+import { join } from 'node:path';
+
+/**
+ * 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.
+ * Disposal stops the process; hold the result with `await using`.
+ */
+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 = 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-listener.ts

@@ -0,0 +1,40 @@
+import { createServer } from 'node:net';
+import type { Socket } from 'node:net';
+
+interface StubStalledListener {
+  readonly [Symbol.dispose]: () => void;
+}
+
+/**
+ * A stand-in for a peer that stops reading: it listens on the unix socket
+ * path and accepts every connection but never reads from it, so what the
+ * kernel does not buffer stays queued on the sender's side. Resolves once
+ * it listens. Disposal destroys every connection it accepted and stops it;
+ * hold the result with `using`.
+ */
+export async function startStubStalledListener(path: string): Promise<StubStalledListener> {
+  const peers = new Set<Socket>();
+
+  const server = createServer((peer) => {
+    peer.pause();
+    peers.add(peer);
+  });
+
+  const listening = Promise.withResolvers<void>();
+
+  server.listen(path, () => {
+    listening.resolve();
+  });
+
+  await listening.promise;
+
+  return {
+    [Symbol.dispose]: () => {
+      for (const peer of peers) {
+        peer.destroy();
+      }
+
+      server.close();
+    },
+  };
+}

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

@@ -0,0 +1,38 @@
+import type { DaemonClient } from '../client/daemon-client';
+import type { EventMsg } from '../protocol/protocol';
+
+/**
+ * Makes the client the session's tap and acks each message the tap is
+ * handed, the way an agent's inbox reader does, so the daemon drains the
+ * whole backlog one message per ack. `messages` holds each InboxMessage in
+ * the order it arrived and `closed` each InboxClosed. The client's event
+ * callback is replaced.
+ */
+// oxlint-disable-next-line prefer-readonly-parameter-types -- a client is a live connection the tap drives
+export async function startStubTap(client: DaemonClient, session: string) {
+  const messages: EventMsg[] = [];
+  const closed: EventMsg[] = [];
+
+  // An ack that a closing connection never answers changes nothing the
+  // caller reads.
+  const sendAck = async (message: unknown) => {
+    try {
+      await client.sendRequest('message.ack', { session, message });
+    } catch {}
+  };
+
+  client.onEvent = (event) => {
+    if (event.ev === 'InboxMessage') {
+      messages.push(event);
+      void sendAck(event['message']);
+    }
+
+    if (event.ev === 'InboxClosed') {
+      closed.push(event);
+    }
+  };
+
+  await client.sendRequest('session.tap', { session });
+
+  return { messages, closed };
+}

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

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+import { PROTOCOL_V } from '../protocol/protocol';
+
+interface StubTCPDaemon {
+  readonly port: number;
+
+  // Every request method the stand-in received, in arrival order.
+  readonly seen: 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 before it sends
+  // the next.
+  readonly reads: number;
+  readonly [Symbol.dispose]: () => void;
+}
+
+// The two request fields the stand-in reads; every other field passes
+// unread.
+const REQUEST = z.object({ id: z.number(), m: z.string() });
+
+/**
+ * A stand-in for an atc daemon's TCP listener on a loopback port: it reads
+ * newline-delimited protocol requests and answers each with an ok that holds
+ * the request's method, recording every method in `seen`. It sends no
+ * handshake of its own and checks no token. `reads` counts the reads it has
+ * taken from every connection. Disposal stops it.
+ */
+export function startStubTCPDaemon(): StubTCPDaemon {
+  const seen: string[] = [];
+  let reads = 0;
+
+  const server = Bun.listen<{ buffer: string }>({
+    hostname: '127.0.0.1',
+    port: 0,
+    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.filter((part) => part !== '')) {
+          const request = REQUEST.parse(JSON.parse(line));
+
+          seen.push(request.m);
+
+          socket.write(
+            `${JSON.stringify({ v: PROTOCOL_V, id: request.id, ok: { m: request.m } })}\n`,
+          );
+        }
+      },
+      error() {},
+    },
+  });
+
+  return {
+    port: server.port,
+    seen,
+    get reads() {
+      return reads;
+    },
+    [Symbol.dispose]: () => {
+      server.stop(true);
+    },
+  };
+}

package/src/test-utils/start-stub-telemetry-collector.ts

@@ -0,0 +1,26 @@
+/**
+ * A stand-in for better-auth's telemetry endpoint on a real HTTP port of the
+ * loopback address. A process whose `BETTER_AUTH_TELEMETRY_ENDPOINT` holds
+ * `url` sends its telemetry here. Every request is answered with HTTP 204,
+ * and `received` holds the URL of each request, in order. Disposal stops the
+ * server and resolves once it has stopped.
+ */
+export function startStubTelemetryCollector() {
+  const received: string[] = [];
+
+  const server = Bun.serve({
+    hostname: '127.0.0.1',
+    port: 0,
+    fetch: (request) => {
+      received.push(request.url);
+
+      return new Response(null, { status: 204 });
+    },
+  });
+
+  return {
+    url: `http://127.0.0.1:${String(server.port)}/`,
+    received,
+    [Symbol.asyncDispose]: () => server.stop(true),
+  };
+}

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

@@ -0,0 +1,215 @@
+import { join } from 'node:path';
+import type { Socket } from 'bun';
+import { DaemonClient } from '../client/daemon-client';
+import { startDaemon } from '../daemon/daemon';
+import type { DaemonHandle, DaemonOptions } from '../daemon/daemon';
+import type { EventMsg } from '../protocol/protocol';
+import { setupTempDir } from './setup-temp-dir';
+
+/**
+ * Where a test daemon keeps its sockets and state, all inside one temp
+ * directory, so the daemon's lock and record files land there too.
+ */
+interface TestDaemonPaths {
+  readonly dir: string;
+  readonly socketPath: string;
+  readonly reporterSocketPath: string;
+  readonly eventsSocketPath: string;
+  readonly dbPath: string;
+  readonly statusPath: string;
+}
+
+/**
+ * Every daemon option except the paths and the build string, which the
+ * harness owns.
+ */
+type TestDaemonOptions = Omit<
+  DaemonOptions,
+  'socketPath' | 'reporterSocketPath' | 'eventsSocketPath' | 'dbPath' | 'statusPath' | 'build'
+>;
+
+/**
+ * Builds the options for one boot from the daemon's paths. It runs before
+ * every boot, so it may also write what the daemon reads at start, such as
+ * a token file or a fake agent binary under the directory.
+ */
+type TestDaemonOptionsBuilder = (
+  paths: TestDaemonPaths,
+) => TestDaemonOptions | Promise<TestDaemonOptions>;
+
+interface TestDaemonConfig {
+  // The temp directory's name prefix.
+  readonly prefix?: string;
+  readonly options?: TestDaemonOptionsBuilder;
+}
+
+// The build string the daemon and every client the harness opens send in
+// their handshake.
+const BUILD = 'atc/test-build';
+
+/**
+ * A real daemon in a fresh temp directory, with a client that has already
+ * sent its handshake. The options builder chooses what the daemon wires;
+ * the harness sets the paths and the build, and collects the daemon's log
+ * lines unless the options set their own log. `events` collects every event
+ * the main client receives, across restarts. `openClient` opens another
+ * client over the unix socket and sends its handshake with the given
+ * params; `openTCPClient` connects to the TCP listener and sends nothing, so
+ * the test drives that handshake itself. `sendHookLines` writes reporter
+ * lines to the reporter socket and resolves once the daemon has closed the
+ * connection. `stop` closes every client and stops the daemon; `restart`
+ * does the same, then boots on the same paths and state with the options
+ * given or the last ones, and opens a new main client. Disposal stops what
+ * is running and removes the directory; hold the result with `await using`.
+ */
+export async function startTestDaemon(config: TestDaemonConfig = {}) {
+  await using stack = new AsyncDisposableStack();
+
+  const tmp = stack.use(setupTempDir(config.prefix ?? 'atc-test-daemon-'));
+
+  const paths: TestDaemonPaths = {
+    dir: tmp.dir,
+    socketPath: join(tmp.dir, 'daemon.sock'),
+    reporterSocketPath: join(tmp.dir, 'reporter.sock'),
+    eventsSocketPath: join(tmp.dir, 'events.sock'),
+    dbPath: join(tmp.dir, 'state.db'),
+    statusPath: join(tmp.dir, 'status.json'),
+  };
+
+  const logs: string[] = [];
+  const events: EventMsg[] = [];
+
+  const clients = new Set<DaemonClient>();
+
+  let buildOptions: TestDaemonOptionsBuilder = config.options ?? (() => ({}));
+  let live: DaemonHandle | null = null;
+
+  const openClient = async (hello: Readonly<Record<string, unknown>> = {}) => {
+    const client = await DaemonClient.open(paths.socketPath);
+
+    clients.add(client);
+
+    await client.sendRequest('daemon.hello', {
+      client: BUILD,
+      auth: { scheme: 'none' },
+      ...hello,
+    });
+
+    return client;
+  };
+
+  const stop = async () => {
+    const stopping = live;
+
+    live = null;
+
+    for (const client of clients) {
+      client.stop();
+    }
+
+    clients.clear();
+
+    await stopping?.stop();
+  };
+
+  stack.defer(stop);
+
+  const boot = async () => {
+    const options = await buildOptions(paths);
+
+    const daemon = await startDaemon({
+      log: (line) => {
+        logs.push(line);
+      },
+      ...options,
+      socketPath: paths.socketPath,
+      reporterSocketPath: paths.reporterSocketPath,
+      eventsSocketPath: paths.eventsSocketPath,
+      dbPath: paths.dbPath,
+      statusPath: paths.statusPath,
+      build: BUILD,
+    });
+
+    live = daemon;
+
+    const client = await openClient();
+
+    client.onEvent = (event) => {
+      events.push(event);
+    };
+
+    return { daemon, client };
+  };
+
+  let current = await boot();
+
+  const owned = stack.move();
+
+  return {
+    ...paths,
+    build: BUILD,
+    logs,
+    events,
+    get daemon(): DaemonHandle {
+      return current.daemon;
+    },
+    get client(): DaemonClient {
+      return current.client;
+    },
+    openClient,
+    async openTCPClient(): Promise<DaemonClient> {
+      const port = current.daemon.listenPort;
+
+      if (port === null) {
+        throw new Error('the test daemon started without a TCP listener');
+      }
+
+      const client = await DaemonClient.open({ hostname: '127.0.0.1', port });
+
+      clients.add(client);
+
+      return client;
+    },
+    async sendHookLines(...lines: readonly Readonly<Record<string, unknown>>[]): Promise<void> {
+      const payload = Buffer.from(lines.map((line) => `${JSON.stringify(line)}\n`).join(''));
+      const closed = Promise.withResolvers<void>();
+      let sent = 0;
+
+      // A socket write accepts only what fits its buffer, so the rest goes
+      // out as the socket drains, and the connection ends once all of it
+      // has gone.
+      // oxlint-disable-next-line prefer-readonly-parameter-types -- a socket is a live handle
+      const sendRemainder = (socket: Socket) => {
+        sent += socket.write(payload.subarray(sent));
+
+        if (sent === payload.length) {
+          socket.end();
+        }
+      };
+
+      await Bun.connect({
+        unix: paths.reporterSocketPath,
+        socket: {
+          open: sendRemainder,
+          drain: sendRemainder,
+          close() {
+            closed.resolve();
+          },
+          data() {},
+          error() {},
+        },
+      });
+
+      await closed.promise;
+    },
+    stop,
+    async restart(options: TestDaemonOptionsBuilder = buildOptions): Promise<void> {
+      await stop();
+
+      buildOptions = options;
+
+      current = await boot();
+    },
+    [Symbol.asyncDispose]: () => owned.disposeAsync(),
+  };
+}