@tonalisk-labs/kit 1.0.0 → 1.0.6

package/testing/src/stack/lock.ts

@@ -1,6 +1,14 @@
 import type { ServerResponse } from 'node:http';
 
-import { holdOpen, semaphore } from './gate-server.ts';
+import { holdingsNamed, holdOpen, semaphore } from './gate-server.ts';
+import { STILLNESS, type Stillness, type Watch, watchOf } from './stall.ts';
+
+/** Who asks for a hold, by when their test must end, and the id its request gave. */
+export interface Holder {
+  readonly who: string;
+  readonly deadline: number | undefined;
+  readonly id: string | undefined;
+}
 
 /** Who holds a target's stack: many tests share it, one that disturbs it owns it alone. */
 export type Hold = 'share' | 'own';
@@ -13,6 +21,7 @@ interface Waiting {
 interface Stack {
   sharers: number;
   owned: boolean;
+  readonly watch: Watch;
   /** Each hold's waiters, first come, first served. */
   readonly queued: Readonly<Record<Hold, Waiting[]>>;
 }
@@ -36,21 +45,32 @@ const admit = (stack: Stack): void => {
 };
 
 const take = async (stack: Stack, hold: Hold, gone: AbortSignal): Promise<void> => {
-  const { promise, resolve } = Promise.withResolvers<boolean>();
+  const { promise, resolve, reject } = Promise.withResolvers<boolean>();
+  const queue = stack.queued[hold];
+  // A test that gave up waiting (its timeout), or whose wait stalled, leaves the queue, so it
+  // never holds on.
+  const leave = (): void => {
+    const at = queue.indexOf(waiting);
+    if (at !== -1) {
+      queue.splice(at, 1);
+      admit(stack);
+    }
+  };
+  const done = stack.watch.waiting((stalled) => {
+    leave();
+    reject(stalled);
+  });
   const waiting: Waiting = {
     hold,
     grant: () => {
+      done();
+      stack.watch.moved();
       resolve(true);
     },
   };
-  const queue = stack.queued[hold];
-  // A test that gave up waiting (its timeout) leaves the queue, so it never holds on.
   gone.addEventListener('abort', () => {
-    const at = queue.indexOf(waiting);
-    if (at !== -1) {
-      queue.splice(at, 1);
-      admit(stack);
-    }
+    done();
+    leave();
   });
   queue.push(waiting);
   admit(stack);
@@ -58,6 +78,7 @@ const take = async (stack: Stack, hold: Hold, gone: AbortSignal): Promise<void>
 };
 
 const give = (stack: Stack, hold: Hold): void => {
+  stack.watch.moved();
   if (hold === 'own') {
     stack.owned = false;
   } else {
@@ -67,14 +88,24 @@ const give = (stack: Stack, hold: Hold): void => {
 };
 
 /** A readers-writer lock per target, kept by the stack host. A waiting owner stops no sharer:
- *  owners queue after every shared test, so stopping sharers would only idle workers. */
-export const stackLocks = (): {
+ *  owners queue after every shared test, so stopping sharers would only idle workers. A wait fails
+ *  once no hold on its stack has changed hands for the stillness's stall. */
+export const stackLocks = (
+  stillness: Stillness = STILLNESS,
+): {
   readonly take: (key: string, hold: Hold, gone: AbortSignal) => Promise<void>;
   readonly give: (key: string, hold: Hold) => void;
+  /** The watch over a stack's waits, which a server counts each holder in. */
+  readonly watch: (key: string) => Watch;
 } => {
   const stacks = new Map<string, Stack>();
   const stackOf = (key: string): Stack => {
-    const found = stacks.get(key) ?? { sharers: 0, owned: false, queued: { share: [], own: [] } };
+    const found = stacks.get(key) ?? {
+      sharers: 0,
+      owned: false,
+      watch: watchOf(stillness, { what: `no hold on ${key}`, named: holdingsNamed }),
+      queued: { share: [], own: [] },
+    };
     stacks.set(key, found);
     return found;
   };
@@ -83,25 +114,34 @@ export const stackLocks = (): {
     give: (key, hold) => {
       give(stackOf(key), hold);
     },
+    watch: (key) => stackOf(key).watch,
   };
 };
 
 /** A pool of `size` seats, a holder taking the ones it asks for all at once, in the order asked;
- *  more than the pool has is refused at once, as it could never be seated. */
-export const seatPool = (size: number): ((outgoing: ServerResponse, asked: string) => void) => {
-  const pool = semaphore(size);
-  return (outgoing, asked) => {
+ *  more than the pool has is refused at once, as it could never be seated. A wait fails once no
+ *  seat has changed hands for the stillness's stall. */
+export const seatPool = (
+  size: number,
+  stillness: Stillness = STILLNESS,
+): ((outgoing: ServerResponse, asked: string, holder: Holder) => void) => {
+  const pool = semaphore(size, { stillness, what: 'no seat' });
+  return (outgoing, asked, { who, deadline, id }) => {
     const count = Number(asked);
     if (!Number.isInteger(count) || count < 1 || count > size) {
       outgoing.writeHead(400).end(`the pool seats 1 to ${String(size)} at once, not ${asked}`);
       return;
     }
-    holdOpen(
-      outgoing,
-      async (gone) => pool.take('seats', count, gone),
-      () => {
+    holdOpen(outgoing, {
+      take: async (gone) => pool.take('seats', count, gone),
+      give: () => {
         pool.give(count);
       },
-    );
+      what: `${String(count)} of the Linux browsers' ${String(size)} seats`,
+      who,
+      deadline,
+      watch: pool.watch,
+      id,
+    });
   };
 };

package/testing/src/stack/preview-child.ts

@@ -12,15 +12,27 @@ interface Astro {
     readonly outDir: string;
     readonly logLevel: 'error';
     readonly server: { readonly host: string; readonly port: number };
-  }) => Promise<{ readonly port: number }>;
+  }) => Promise<{ readonly port: number; readonly stop: () => Promise<void> }>;
 }
 
 const isAstro = (value: unknown): value is Astro =>
   isObject(value) && typeof value['preview'] === 'function';
 
-// Its lifeline gone, it stops as a stop would have it.
+interface Lifeline {
+  ended: boolean;
+  server: { readonly stop: () => Promise<void> } | undefined;
+  readonly stopping: Promise<void>[];
+}
+
+const lifeline: Lifeline = { ended: false, server: undefined, stopping: [] };
+
+// Its lifeline gone, it stops its server and ends with nothing left to run, exiting 0. Vite would
+// too, but only where CI isn't "true"; this comes first, and the stop takes Vite's listener away.
 process.stdin.on('end', () => {
-  process.kill(process.pid, 'SIGTERM');
+  lifeline.ended = true;
+  if (lifeline.server !== undefined) {
+    lifeline.stopping.push(lifeline.server.stop());
+  }
 });
 process.stdin.resume();
 const [root = '', outDir = ''] = process.argv.slice(2);
@@ -35,4 +47,9 @@ const server = await astro.preview({
   logLevel: 'error',
   server: { host: '127.0.0.1', port: 0 },
 });
-console.log(`${PREVIEW_READY}${String(server.port)}`);
+lifeline.server = server;
+if (lifeline.ended) {
+  await server.stop();
+} else {
+  console.log(`${PREVIEW_READY}${String(server.port)}`);
+}

package/testing/src/stack/runtime-apple.ts

@@ -9,6 +9,7 @@ import {
   type Expiry,
   type Limits,
   LIMITS,
+  type Network,
   onTheClock,
   pairsOf,
   type Runtime,
@@ -22,6 +23,7 @@ const VERBS = {
   start: 'start',
   logs: 'logs',
   address: 'inspect',
+  network: 'inspect',
   exec: 'exec',
   stop: 'stop',
   remove: 'delete',
@@ -94,6 +96,22 @@ const publishedIn = (id: string, answer: string): Map<number, Address> => {
   );
 };
 
+/** An address as an inspect records it, without its prefix length. */
+const bare = (address: string): string => address.replace(/\/\d+$/u, '');
+
+/** A container's address and its network's gateway, the host's address there, as an inspect
+ *  records them: the address with its prefix length, which goes. */
+const networkIn = (id: string, answer: string): Network => {
+  const networks = field(field(snapshotsIn('inspect', answer)[0], 'status'), 'networks');
+  const attached: unknown = Array.isArray(networks) ? networks.at(0) : undefined;
+  const [own, host] = [field(attached, 'ipv4Address'), field(attached, 'ipv4Gateway')];
+  const settled = field(attached, 'ipv6Address');
+  if (typeof own !== 'string' || typeof host !== 'string') {
+    throw new TypeError(`container inspect ${id} answered no network: ${answer}`);
+  }
+  return { own: bare(own), host, settled: typeof settled === 'string' ? bare(settled) : undefined };
+};
+
 /** The ids a `list` answers. */
 const idsIn = (answer: string): Set<unknown> =>
   new Set(
@@ -190,8 +208,9 @@ const lifecycleOf = (call: Call, ports: Held): Pick<Runtime, 'create' | 'start'
   },
 });
 
-const lookupsOf = (call: Call): Pick<Runtime, 'addresses' | 'labelled'> => ({
+const lookupsOf = (call: Call): Pick<Runtime, 'addresses' | 'labelled' | 'network'> => ({
   addresses: async (id) => publishedIn(id, await call('address', [id])),
+  network: async (id) => networkIn(id, await call('network', [id])),
   labelled: async (key) => labelledIn(await call('list', ['--all', '--format', 'json']), key),
 });
 

package/testing/src/stack/runtime-docker.ts

@@ -1,3 +1,4 @@
+import { isObject } from '../unknown.ts';
 import {
   type Address,
   type Caller,
@@ -5,6 +6,7 @@ import {
   type ContainerSpec,
   type Expiry,
   type Limits,
+  type Network,
   pairsOf,
   type Runtime,
   sharedMemoryOf,
@@ -16,6 +18,7 @@ const VERBS = {
   start: 'start',
   logs: 'logs',
   address: 'port',
+  network: 'inspect',
   exec: 'exec',
   stop: 'stop',
   remove: 'rm',
@@ -57,6 +60,30 @@ const labelledIn = (listing: string): Map<string, string> =>
 
 type Call = Caller['call'];
 
+/** A container's address and its network's gateway, as `docker inspect` gives its networks in
+ *  JSON. On Linux the gateway is the host's own bridge; Docker Desktop's is in its virtual
+ *  machine, so a host server there would be out of the container's reach. */
+const networkIn = (id: string, answer: string, platform: NodeJS.Platform): Network => {
+  if (platform === 'darwin') {
+    throw new Error(
+      "Docker on macOS runs its containers in a virtual machine whose gateway isn't this Mac, so the Linux image's browsers can't reach its servers: run with Apple's container, unset KIT_CONTAINER_RUNTIME",
+    );
+  }
+  const parsed: unknown = JSON.parse(answer);
+  const [attached] = isObject(parsed) ? Object.values(parsed) : [];
+  const [own, host, settled] = isObject(attached)
+    ? [attached['IPAddress'], attached['Gateway'], attached['GlobalIPv6Address']]
+    : [];
+  if (typeof own !== 'string' || typeof host !== 'string' || own === '' || host === '') {
+    throw new TypeError(`docker inspect ${id} answered no network: ${answer}`);
+  }
+  return {
+    own,
+    host,
+    settled: typeof settled === 'string' && settled !== '' ? settled : undefined,
+  };
+};
+
 /** Files go in by `docker cp`, which reads on the host side, so no host directory is shared with
  *  Docker. */
 const lifecycleOf = (call: Call): Pick<Runtime, 'create' | 'start' | 'stop'> => ({
@@ -79,7 +106,16 @@ const lifecycleOf = (call: Call): Pick<Runtime, 'create' | 'start' | 'stop'> =>
   },
 });
 
-const lookupsOf = (call: Call): Pick<Runtime, 'addresses' | 'labelled'> => ({
+const lookupsOf = (
+  call: Call,
+  platform: NodeJS.Platform,
+): Pick<Runtime, 'addresses' | 'labelled' | 'network'> => ({
+  network: async (id) =>
+    networkIn(
+      id,
+      await call('network', ['--format', '{{json .NetworkSettings.Networks}}', id]),
+      platform,
+    ),
   addresses: async (id, ports) =>
     new Map(
       await Promise.all(
@@ -89,10 +125,12 @@ const lookupsOf = (call: Call): Pick<Runtime, 'addresses' | 'labelled'> => ({
         }),
       ),
     ),
+  // A listing cuts each id to 12 characters unless told not to, and a create answers it whole.
   labelled: async (key) =>
     labelledIn(
       await call('list', [
         '--all',
+        '--no-trunc',
         '--filter',
         `label=${key}`,
         '--format',
@@ -106,7 +144,13 @@ export const dockerOf = ({
   command = 'docker',
   limits,
   expiry,
-}: { command?: string; limits?: Limits; expiry?: Expiry } = {}): Runtime & Caller => {
+  platform = process.platform,
+}: {
+  command?: string;
+  limits?: Limits;
+  expiry?: Expiry;
+  platform?: NodeJS.Platform;
+} = {}): Runtime & Caller => {
   const caller = callerOf({
     command,
     verbs: VERBS,
@@ -115,5 +159,5 @@ export const dockerOf = ({
     limits,
     expiry,
   });
-  return Object.assign(caller, lifecycleOf(caller.call), lookupsOf(caller.call));
+  return Object.assign(caller, lifecycleOf(caller.call), lookupsOf(caller.call, platform));
 };

package/testing/src/stack/runtime.ts

@@ -38,6 +38,15 @@ export interface Address {
   readonly port: number;
 }
 
+/** Where a running container is on its network, and where the host is there: the one address a
+ *  host server for the container answers, and the address it listens on. `settled` is the global
+ *  IPv6 address the network gives it some seconds after it starts, where it gives one. */
+export interface Network {
+  readonly own: string;
+  readonly host: string;
+  readonly settled?: string | undefined;
+}
+
 /** How long each call may take on a busy machine, in milliseconds: a create may pull its image,
  *  and a container may take minutes to say it's ready. A hung daemon answers no call at all. */
 export const LIMITS = {
@@ -46,6 +55,7 @@ export const LIMITS = {
   start: 120_000,
   logs: 300_000,
   address: 30_000,
+  network: 30_000,
   exec: 600_000,
   stop: 120_000,
   remove: 120_000,
@@ -70,6 +80,7 @@ export interface Runtime {
     id: string,
     ports: readonly number[],
   ) => Promise<ReadonlyMap<number, Address>>;
+  readonly network: (id: string) => Promise<Network>;
   readonly exec: (id: string, command: readonly string[], signal: AbortSignal) => Promise<string>;
   /** The command line of an exec whose standard input its caller holds. */
   readonly execLine: (id: string, command: readonly string[]) => readonly [string, ...string[]];

package/testing/src/stack/socks.ts

@@ -0,0 +1,233 @@
+// The host's end of the Linux image's shared browsers: a SOCKS5 server on the host's address on
+// their network. Playwright's launch server, unlike its run server, carries no tunnel to the host's
+// loopback (exposeNetwork), so each browser is launched with this server as its proxy. With a SOCKS
+// proxy, Playwright's Chromium resolves no name itself, so every request a browser makes, its
+// page's and its context's own, comes here: the loopback's go to the host's, and the rest out, as
+// a contained browser's went out before.
+import { once } from 'node:events';
+import { connect, createServer, isIP, type Socket } from 'node:net';
+
+import { codeOf } from '../unknown.ts';
+import type { Service } from './process.ts';
+
+/** Where a browser asked to connect. */
+export interface Destination {
+  readonly host: string;
+  readonly port: number;
+}
+
+const VERSION = 5;
+const NO_AUTHENTICATION = 0;
+const NO_ACCEPTABLE_METHOD = 255;
+const CONNECT = 1;
+const TYPE = { ipv4: 1, name: 3, ipv6: 4 } as const;
+const REPLY = {
+  succeeded: 0,
+  failed: 1,
+  networkUnreachable: 3,
+  hostUnreachable: 4,
+  refused: 5,
+  commandUnsupported: 7,
+  addressUnsupported: 8,
+} as const;
+
+/** IPv6's loopback, as `ipv6Of` writes it. */
+const IPV6_LOOPBACK = '0:0:0:0:0:0:0:1';
+
+/** The names and addresses the host's loopback answers: Playwright's `<loopback>`, and all of
+ *  127.0.0.0/8, which is the loopback too. */
+export const onLoopback = (host: string): boolean =>
+  host === 'localhost' ||
+  host.endsWith('.localhost') ||
+  (isIP(host) === 4 && host.startsWith('127.')) ||
+  host === '::1' ||
+  host === IPV6_LOOPBACK;
+
+/** Where a request goes from the host: a name on the loopback to 127.0.0.1, where every edge
+ *  listens and macOS puts names under localhost; any other as it was asked. Behind a SOCKS proxy
+ *  Playwright launches Chromium with `--host-resolver-rules=MAP * ~NOTFOUND`, so nothing else
+ *  reaches out but through here, and the Stripe sandbox's journeys go to checkout.stripe.com. */
+export const routeOf = ({ host, port }: Destination): Destination =>
+  onLoopback(host) && isIP(host) === 0 ? { host: '127.0.0.1', port } : { host, port };
+
+/** A reply with no bound address, which a browser never reads. */
+const reply = (code: number): Buffer =>
+  Buffer.from([VERSION, code, 0, TYPE.ipv4, 0, 0, 0, 0, 0, 0]);
+
+/** Resolves once `socket` has more to read, or is gone. */
+const stirred = async (socket: Socket): Promise<boolean> => {
+  const { promise, resolve } = Promise.withResolvers<boolean>();
+  const done = (): void => {
+    socket.off('readable', done).off('close', done);
+    resolve(true);
+  };
+  socket.on('readable', done).on('close', done);
+  return promise;
+};
+
+/** The next `count` bytes from `socket`, once they have come; a failure if it ends first. */
+const bytesOf = async (socket: Socket, count: number): Promise<Buffer> => {
+  if (count === 0) {
+    return Buffer.alloc(0);
+  }
+  const chunk: unknown = socket.read(count);
+  if (Buffer.isBuffer(chunk) && chunk.length === count) {
+    return chunk;
+  }
+  if (Buffer.isBuffer(chunk) || socket.readableEnded || socket.destroyed) {
+    throw new Error('the client ended its SOCKS message part way');
+  }
+  await stirred(socket);
+  return bytesOf(socket, count);
+};
+
+/** The client's greeting, answered: it must offer to go without authentication. */
+const greet = async (client: Socket): Promise<void> => {
+  const [version, count = 0] = await bytesOf(client, 2);
+  if (version !== VERSION) {
+    throw new Error(`a SOCKS${String(version)} greeting, not SOCKS5`);
+  }
+  const methods = await bytesOf(client, count);
+  if (!methods.includes(NO_AUTHENTICATION)) {
+    client.end(Buffer.from([VERSION, NO_ACCEPTABLE_METHOD]));
+    throw new Error('the client offered no way without authentication');
+  }
+  client.write(Buffer.from([VERSION, NO_AUTHENTICATION]));
+};
+
+/** Sixteen bytes as an IPv6 address's eight groups, written out whole. */
+const ipv6Of = (bytes: Buffer): string =>
+  Array.from({ length: 8 }, (_unused, group) => bytes.readUInt16BE(group * 2).toString(16)).join(
+    ':',
+  );
+
+/** The address a request names, by its type; undefined for a type SOCKS5 lacks. */
+const hostOf = async (client: Socket, type: number | undefined): Promise<string | undefined> => {
+  if (type === TYPE.ipv4) {
+    const octets = await bytesOf(client, 4);
+    return [...octets].join('.');
+  }
+  if (type === TYPE.ipv6) {
+    return ipv6Of(await bytesOf(client, 16));
+  }
+  if (type === TYPE.name) {
+    const [length = 0] = await bytesOf(client, 1);
+    const name = await bytesOf(client, length);
+    return name.toString('latin1');
+  }
+  return undefined;
+};
+
+/** The destination of the client's CONNECT; any other command, or address type, is refused. */
+const destinationOf = async (client: Socket): Promise<Destination> => {
+  const [, command, , type] = await bytesOf(client, 4);
+  if (command !== CONNECT) {
+    client.end(reply(REPLY.commandUnsupported));
+    throw new Error(`SOCKS command ${String(command)}, which this server doesn't serve`);
+  }
+  const host = await hostOf(client, type);
+  if (host === undefined) {
+    client.end(reply(REPLY.addressUnsupported));
+    throw new Error(`SOCKS address type ${String(type)}`);
+  }
+  const port = await bytesOf(client, 2);
+  return { host, port: port.readUInt16BE(0) };
+};
+
+/** The reply for a connection that failed, by its error's code. */
+const failureOf = (error: unknown): number => {
+  const code = codeOf(error);
+  if (code === 'ECONNREFUSED') {
+    return REPLY.refused;
+  }
+  if (code === 'ENETUNREACH') {
+    return REPLY.networkUnreachable;
+  }
+  return code === 'EHOSTUNREACH' || code === 'ENOTFOUND' ? REPLY.hostUnreachable : REPLY.failed;
+};
+
+/** Each side's end ends the other's writing, through the pipes, and a side closed or broken
+ *  closes the other, so neither outlives its pair. */
+const joined = (client: Socket, upstream: Socket): void => {
+  for (const [one, other] of [
+    [client, upstream],
+    [upstream, client],
+  ] as const) {
+    const end = (): void => {
+      other.destroy();
+    };
+    one.on('error', end).on('close', end);
+  }
+  client.pipe(upstream);
+  upstream.pipe(client);
+};
+
+/** Serves one client: its greeting, its CONNECT, then its bytes both ways. */
+const serve = async (client: Socket): Promise<void> => {
+  await greet(client);
+  const destination = routeOf(await destinationOf(client));
+  const upstream = connect({ port: destination.port, host: destination.host, allowHalfOpen: true });
+  // A browser that gives up first leaves no connection waiting on the operating system's timeout.
+  client.once('close', () => {
+    upstream.destroy();
+  });
+  try {
+    await once(upstream, 'connect');
+  } catch (error) {
+    client.end(reply(failureOf(error)));
+    return;
+  }
+  client.write(reply(REPLY.succeeded));
+  joined(client, upstream);
+};
+
+export interface Socks extends Service {
+  /** The port it listens on, at the address it was given. */
+  readonly port: number;
+}
+
+/** A SOCKS5 server on `host`, serving only clients from `peer`, the browsers' own address: any
+ *  other is closed unanswered, as it may reach the host's loopback through it. */
+export const startSocks = async ({
+  host,
+  peer,
+}: {
+  readonly host: string;
+  readonly peer: string;
+}): Promise<Socks> => {
+  const open = new Set<Socket>();
+  // Half open, so a side that has said all it will still hears the other's answer.
+  const server = createServer({ allowHalfOpen: true }, (client) => {
+    if (client.remoteAddress !== peer) {
+      client.destroy();
+      return;
+    }
+    open.add(client);
+    // A client that resets part way is closed, never an error the host's process throws.
+    client
+      .on('error', () => {
+        client.destroy();
+      })
+      .once('close', () => {
+        open.delete(client);
+      });
+    // A broken greeting or a client gone part way ends that client alone.
+    serve(client).catch(() => {
+      client.destroy();
+    });
+  });
+  server.listen(0, host);
+  await once(server, 'listening');
+  const address = server.address();
+  const port = typeof address === 'object' && address !== null ? address.port : 0;
+  return {
+    port,
+    stop: async () => {
+      for (const client of open) {
+        client.destroy();
+      }
+      server.close();
+      await once(server, 'close');
+    },
+  };
+};