@zgeoff/atc 3.3.1 → 3.4.1

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

@@ -0,0 +1,44 @@
+import { createServer } from 'node:net';
+import type { Socket } from 'node:net';
+import { registerTestCleanup } from './register-test-cleanup';
+
+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. Once the current test finishes, it destroys every connection
+ * it accepted and stops, so it must run inside a test; disposal does so
+ * sooner, and a second stop does nothing.
+ */
+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;
+
+  const stop = registerTestCleanup(() => {
+    for (const peer of peers) {
+      peer.destroy();
+    }
+
+    server.close();
+  });
+
+  return {
+    [Symbol.dispose]: stop,
+  };
+}

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,75 @@
+import { z } from 'zod';
+import { PROTOCOL_V } from '../protocol/protocol';
+import { registerTestCleanup } from './register-test-cleanup';
+
+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. 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 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() {},
+    },
+  });
+
+  const stop = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
+  return {
+    port: server.port,
+    seen,
+    get reads() {
+      return reads;
+    },
+    [Symbol.dispose]: stop,
+  };
+}

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

@@ -0,0 +1,32 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
+/**
+ * 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. The server stops
+ * once the current test finishes, so it must run inside a test; disposal
+ * stops it sooner and resolves once it has stopped, and a second stop does
+ * nothing.
+ */
+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 });
+    },
+  });
+
+  const stop = registerTestCleanup(() => server.stop(true));
+
+  return {
+    url: `http://127.0.0.1:${String(server.port)}/`,
+    received,
+    [Symbol.asyncDispose]: stop,
+  };
+}

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

@@ -0,0 +1,41 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
+interface StubUnansweringListener {
+  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 that accepts a connection and never answers it:
+ * on a loopback port, it records what each read takes from a connection,
+ * sends nothing back, and keeps the connection open. 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 startStubUnansweringListener(): StubUnansweringListener {
+  const received: string[] = [];
+
+  const server = Bun.listen({
+    hostname: '127.0.0.1',
+    port: 0,
+    socket: {
+      data(_socket, data) {
+        received.push(data.toString());
+      },
+    },
+  });
+
+  const stop = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
+  return {
+    port: server.port,
+    received,
+    [Symbol.dispose]: stop,
+  };
+}

package/src/test-utils/start-stub-unanswering-unix-listener.ts

@@ -0,0 +1,38 @@
+import { registerTestCleanup } from './register-test-cleanup';
+
+interface StubUnansweringUnixListener {
+  // 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 socket that takes a connection and never answers
+ * it: it listens on the unix socket path, records what each read takes from
+ * a connection, sends nothing back, and keeps the connection open. 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 startStubUnansweringUnixListener(path: string): StubUnansweringUnixListener {
+  const received: string[] = [];
+
+  const server = Bun.listen({
+    unix: path,
+    socket: {
+      data(_socket, data) {
+        received.push(data.toString());
+      },
+    },
+  });
+
+  const stop = registerTestCleanup(() => {
+    server.stop(true);
+  });
+
+  return {
+    received,
+    [Symbol.dispose]: stop,
+  };
+}

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

@@ -0,0 +1,229 @@
+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 { registerTestCleanup } from './register-test-cleanup';
+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. That disposal runs once the current
+ * test finishes, so it must run inside a test; disposing sooner runs it
+ * then, and a second disposal does nothing. A first boot that fails runs it
+ * before the start rejects.
+ */
+export async function startTestDaemon(config: TestDaemonConfig = {}) {
+  const tmp = setupTempDir(config.prefix ?? 'atc-test-daemon-');
+
+  // Registered after the directory, so it releases first: the daemon stops
+  // before its directory is removed.
+  const stack = new AsyncDisposableStack();
+
+  const dispose = registerTestCleanup(() => stack.disposeAsync());
+
+  stack.use(tmp);
+
+  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 };
+  };
+
+  // A boot that fails stops what it started and removes the directory
+  // before the start rejects.
+  let current = await boot().catch(async (error: unknown) => {
+    await dispose();
+
+    throw error;
+  });
+
+  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]: dispose,
+  };
+}