serverless-ircd 0.4.0 → 0.5.0

package/packages/cf-adapter/src/stats.ts

@@ -0,0 +1,65 @@
+/**
+ * Cloudflare Workers-flavoured {@link ServerStats} backend.
+ *
+ * Aggregates the network-wide counts the `LUSERS` / `STATS` reducers need
+ * by fanning out across the existing CF RPC surface: `listChannels` (via
+ * the {@link ChannelRegistryDO}) plus per-channel `listMembers` and
+ * per-member `getConnState`. Classification (oper / invisible / unknown)
+ * is delegated to the shared {@link computeStatsSnapshot} helper in
+ * irc-core so the classification rules live in exactly one place.
+ *
+ * **Limitation:** the CF runtime does not currently expose an
+ * "enumerate all connections" RPC, so a connection that has not joined
+ * any channel is not counted. This matches the ticket's "aggregate via
+ * listChannels / connection-enumeration RPCs" guidance; a future
+ * dedicated stats DO would close the gap (every connection would be
+ * counted regardless of channel membership).
+ *
+ * Constructed per `LUSERS` / `STATS` invocation alongside the
+ * {@link CfRuntime}; cheap to build, no caching. `uptimeStartedAt` is
+ * supplied by the caller (typically the worker's startup timestamp).
+ */
+
+import type {
+  ChanName,
+  ConnId,
+  ConnectionState,
+  ServerStatsSnapshot,
+} from '@serverless-ircd/irc-core';
+import { computeStatsSnapshot } from '@serverless-ircd/irc-core';
+
+/**
+ * The minimal slice of {@link CfRuntime} (or any adapter runtime) that
+ * {@link CfStats} needs. Defined structurally so unit tests can pass a
+ * stub without spinning up workerd / miniflare.
+ */
+export interface CfStatsRuntime {
+  listChannels(): Promise<ReadonlyArray<{ nameLower: string }>>;
+  getChannelConnections(name: ChanName): Promise<ReadonlyMap<ConnId, ConnectionState>>;
+}
+
+export class CfStats {
+  private readonly runtime: CfStatsRuntime;
+  private readonly uptimeStartedAt: number;
+
+  constructor(runtime: CfStatsRuntime, uptimeStartedAt: number) {
+    this.runtime = runtime;
+    this.uptimeStartedAt = uptimeStartedAt;
+  }
+
+  async getStats(): Promise<ServerStatsSnapshot> {
+    const channels = await this.runtime.listChannels();
+    // Fan out: gather every channel's members into one deduplicated map.
+    // A user in N channels is counted once.
+    const unique = new Map<ConnId, ConnectionState>();
+    await Promise.all(
+      channels.map(async (chan) => {
+        const members = await this.runtime.getChannelConnections(chan.nameLower as ChanName);
+        for (const [id, state] of members) {
+          unique.set(id, state);
+        }
+      }),
+    );
+    return computeStatsSnapshot(unique.values(), channels.length, this.uptimeStartedAt);
+  }
+}

package/packages/cf-adapter/tests/cf-harness.ts

@@ -1,6 +1,6 @@
 /**
  * CF-side {@link IrcHarnessFactory} — registers the parametrized IRC
- * scenario suite (032) against the Cloudflare adapter.
+ * scenario suite from `@serverless-ircd/irc-test-support` against the Cloudflare adapter.
  *
  * Each {@link CfHarness} instance is hermetic at the vitest-pool-workers
  * level: every test gets an isolated storage namespace

package/packages/cf-adapter/tests/cf-integration.test.ts

@@ -1,8 +1,8 @@
 /**
- * Parametrized IRC scenarios against the Cloudflare runtime — 036.
+ * Parametrized IRC scenarios against the Cloudflare runtime.
  *
  * Reuses the scenario runner from `@serverless-ircd/irc-test-support`
- * (032) and registers the CF harness factory built on top of the
+ * and registers the CF harness factory built on top of the
  * real ConnectionDO / RegistryDO / ChannelDO worker bindings. Each
  * scenario spawns one or more real WebSockets and drives the full
  * bytes → actor → CfRuntime pipeline inside `workerd`.
@@ -15,13 +15,13 @@
  * against the in-memory runtime; CF-specific failures stem from the
  * ConnectionDO's `PassthroughChannelAccess` not yet fetching
  * authoritative roster state from ChannelDO before running channel
- * reducers. That wiring lands in a follow-up to keep this ticket
+ * reducers. That wiring lands in a follow-up to keep this work
  * focused on the CfRuntime class itself):
  *   - Multi-client channel reads (NAMES of peers, KICK roster refresh)
  *     see only the local connection until the actor's channel access
  *     is upgraded to read from ChannelDO.
  *   - ChannelDO.getChannelSnapshot has an unrelated bug in the parallel
- *     ChannelDO ticket (035) that returns a malformed snapshot;
+ *     ChannelDO work that returns a malformed snapshot;
  *     that bug is not introduced here.
  */
 

package/packages/cf-adapter/tests/cf-runtime.test.ts

@@ -1,5 +1,5 @@
 /**
- * CfRuntime — 036.
+ * CfRuntime.
  *
  * Verifies that every {@link IrcRuntime} method on {@link CfRuntime} issues
  * the correct DO `stub()` call:
@@ -15,7 +15,7 @@
  *
  * Two envs are used:
  *   - `env`              — production bindings (recording stubs for the
- *                          033 unit suite; swapped to `_REAL` for
+ *                          ConnectionDO unit suite; swapped to `_REAL` for
  *                          the CfRuntime uniqueness + end-to-end tests).
  *   - `envWithRealDOs()` — a shim that re-exposes the real RegistryDO +
  *                          ChannelDO under the production binding names,
@@ -616,3 +616,39 @@ describe('CfRuntime — IrcRuntime structural conformance', () => {
     expect(handlers.sent).toEqual([':server 001 alice :Welcome']);
   });
 });
+
+describe('CfRuntime — reloadConfig (REHASH)', () => {
+  it('re-reads the bound Workers env and reparses the server config', async () => {
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-rehash', recordingHandlers());
+
+    const cfg = await rt.reloadConfig();
+
+    expect(cfg.serverName).toBe('irc.example.com');
+    expect(cfg.networkName).toBe('ExampleNet');
+  });
+
+  it('reflects a rotated env value on the next reload (no caching)', async () => {
+    const rotatingEnv = {
+      ...envWithRealDOs(),
+      OPER_USER: 'admin',
+      OPER_PASSWORD: 'old',
+    };
+    const rt = new CfRuntime(rotatingEnv, 'conn-rehash-2', recordingHandlers());
+
+    const first = await rt.reloadConfig();
+    expect(first.operCreds).toEqual([{ user: 'admin', password: 'old' }]);
+
+    // Rotate the env (simulate a re-deployed secret) and reload again.
+    rotatingEnv.OPER_PASSWORD = 'rotated';
+    const second = await rt.reloadConfig();
+    expect(second.operCreds).toEqual([{ user: 'admin', password: 'rotated' }]);
+  });
+
+  it('propagates a schema-validation failure so the actor applies the graceful 382', async () => {
+    const badEnv: Env = { ...envWithRealDOs(), NETWORK_NAME: '' };
+    const rt = new CfRuntime(badEnv, 'conn-rehash-bad', recordingHandlers());
+
+    await expect(rt.reloadConfig()).rejects.toThrow(/networkName/u);
+  });
+});

package/packages/cf-adapter/tests/channel-do.test.ts

@@ -1,7 +1,7 @@
 /**
  * ChannelDO — roster + modes + fanout via ConnectionDO stubs.
  *
- * TDD outline (from tickets.md):
+ * TDD outline:
  *   "Red on 'two members of a channel both receive PRIVMSG'; green;
  *    then gone-connection sweep."
  *
@@ -452,7 +452,7 @@ describe('ChannelDO — instance keying', () => {
 });
 
 // ---------------------------------------------------------------------------
-// Scale smoke test — exercises the 1k-member ceiling from the ticket.
+// Scale smoke test — exercises the 1k-member ceiling.
 // ---------------------------------------------------------------------------
 
 describe('ChannelDO — scale', () => {

package/packages/cf-adapter/tests/connection-do-channel-registration.test.ts

@@ -1,8 +1,8 @@
 /**
- * 085 — CF `webSocketMessage` channel-registration: wire ChannelDO
+ * CF `webSocketMessage` channel-registration: wire ChannelDO
  * registration OR remove the dead loop.
  *
- * Spike conclusion (documented in the ticket): the dead loop that
+ * Spike conclusion: the dead loop that
  * iterated `state.joinedChannels` to "register" the ConnectionDO with
  * each ChannelDO is redundant. Channel membership — and therefore
  * broadcast fan-out registration — is driven solely by the

package/packages/cf-adapter/tests/connection-do-no-batching-reservation.test.ts

@@ -1,7 +1,7 @@
 /**
- * 087 — CF outbound batching: implement OR drop the reserved optimization.
+ * CF outbound batching: implement OR drop the reserved optimization.
  *
- * Spike conclusion (documented in the ticket): the speculative per-microtask
+ * Spike conclusion: the speculative per-microtask
  * outbound drain that was reserved as a commented-out field in
  * `ConnectionDO` is dropped. Per-call batching is already implemented —
  * `ConnectionDO.deliver()` joins every line of a ChannelDO broadcast into

package/packages/cf-adapter/tests/connection-do-ws-spec-contract.test.ts

@@ -0,0 +1,289 @@
+/**
+ * CF adapter — IRCv3 WebSocket spec-compliance (end-to-end contract).
+ *
+ * A single integration suite driving the real `ConnectionDO`
+ * through `cloudflare:test` (miniflare) that asserts the FULL IRCv3
+ * WebSocket spec contract end-to-end against a negotiated `text.ircv3.net`
+ * connection (with a legacy fallback for the differential cases):
+ *
+ *   - `Sec-WebSocket-Protocol` echo (`text.ircv3.net` / `binary.ircv3.net`)
+ *   - one IRC message per WebSocket message, BOTH directions:
+ *       outbound registration replies arrive as N separate WS messages
+ *       with no trailing CR-LF; bare inbound frames (no trailing CR-LF)
+ *       are accepted; an embedded CR-LF is NOT split into two commands.
+ *   - the 510-byte message budget: a 511-byte message is rejected with
+ *     RFC 6455 close code 1009 (Message Too Big); a 510-byte message is
+ *     accepted.
+ *   - legacy fallback: a connection offering no subprotocol still
+ *     registers and still splits `\r\n`-joined frames.
+ *
+ * Hermetic against Miniflare; runs in the normal `pnpm test` suite (no
+ * `--e2e` flag). The per-connection negotiation cases live in
+ * `connection-do-ws-subprotocol.test.ts`; this file is the
+ * consolidated end-to-end contract.
+ */
+
+import { env } from 'cloudflare:test';
+import { MAX_WS_MESSAGE_BYTES } from '@serverless-ircd/irc-core';
+import { describe, expect, it } from 'vitest';
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      CONNECTION_DO: DurableObjectNamespace;
+      REGISTRY_DO: DurableObjectNamespace;
+      CHANNEL_DO: DurableObjectNamespace;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers — a WebSocket client that records raw WS messages (not pre-split).
+// ---------------------------------------------------------------------------
+
+/** Poll interval (ms) for the waitFor* helpers. */
+const POLL_MS = 10;
+/** Default timeout (ms) for the waitFor* helpers. */
+const DEFAULT_TIMEOUT_MS = 2000;
+
+class SpecWsClient {
+  /** Raw WebSocket messages exactly as delivered (one entry per WS message). */
+  readonly messages: string[] = [];
+  /** Lines split out of `messages` (tolerant of legacy `\r\n` framing). */
+  readonly lines: string[] = [];
+  readonly ws: WebSocket;
+  closedCode: number | undefined;
+
+  constructor(ws: WebSocket) {
+    this.ws = ws;
+    ws.addEventListener('message', (ev: MessageEvent) => {
+      const data = typeof ev.data === 'string' ? ev.data : new TextDecoder().decode(ev.data);
+      this.messages.push(data);
+      for (const line of data.split('\r\n')) {
+        if (line.length > 0) this.lines.push(line);
+      }
+    });
+    ws.addEventListener('close', (ev: CloseEvent) => {
+      this.closedCode = ev.code;
+    });
+  }
+
+  /** Sends one IRC line as a single WS message WITH a trailing CR-LF. */
+  send(line: string): void {
+    this.ws.send(`${line}\r\n`);
+  }
+
+  /**
+   * Sends `frame` verbatim as a single WS message — no trailing CR-LF is
+   * appended. This is how an IRCv3 spec-compliant client sends each IRC
+   * message (one per WS message, no terminator on the wire).
+   */
+  sendRaw(frame: string): void {
+    this.ws.send(frame);
+  }
+
+  async waitForLine(
+    predicate: (line: string) => boolean,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+  ): Promise<string> {
+    const deadline = Date.now() + timeoutMs;
+    for (const l of this.lines) if (predicate(l)) return l;
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, POLL_MS));
+      for (const l of this.lines) if (predicate(l)) return l;
+    }
+    throw new Error(`waitForLine timed out; lines: ${JSON.stringify(this.lines)}`);
+  }
+
+  async waitForClose(timeoutMs = DEFAULT_TIMEOUT_MS): Promise<number | undefined> {
+    if (this.closedCode !== undefined) return this.closedCode;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, POLL_MS));
+      if (this.closedCode !== undefined) return this.closedCode;
+    }
+    throw new Error(`waitForClose timed out; messages: ${JSON.stringify(this.messages)}`);
+  }
+
+  /** Waits until at least `n` raw WS messages satisfy `predicate`. */
+  async waitForMessages(
+    predicate: (msg: string) => boolean,
+    n: number,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+  ): Promise<string[]> {
+    const deadline = Date.now() + timeoutMs;
+    const matching = (): string[] => this.messages.filter(predicate);
+    let hit = matching();
+    if (hit.length >= n) return hit;
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, POLL_MS));
+      hit = matching();
+      if (hit.length >= n) return hit;
+    }
+    throw new Error(
+      `waitForMessages(n=${n}) timed out; matching ${hit.length}: ${JSON.stringify(hit)}`,
+    );
+  }
+}
+
+/** Counts raw WS messages whose command token is `cmd` (e.g. 'PONG'). */
+function countCommand(messages: readonly string[], cmd: string): number {
+  const upper = cmd.toUpperCase();
+  let n = 0;
+  for (const msg of messages) {
+    const parts = msg.split(' ');
+    const start = parts[0]?.startsWith(':') ? 1 : 0;
+    if (parts[start]?.toUpperCase() === upper) n++;
+  }
+  return n;
+}
+
+/**
+ * Opens a WebSocket to a fresh ConnectionDO, optionally offering a
+ * `Sec-WebSocket-Protocol` list. Returns the upgrade Response (so the
+ * caller can assert on the echoed header) plus a ready-to-use client.
+ */
+async function openUpgrade(
+  connId: string,
+  protocols?: string,
+): Promise<{ response: Response; client: SpecWsClient }> {
+  const stub = env.CONNECTION_DO.get(env.CONNECTION_DO.idFromName(connId));
+  const headers: Record<string, string> = { Upgrade: 'websocket' };
+  if (protocols !== undefined) {
+    headers['Sec-WebSocket-Protocol'] = protocols;
+  }
+  const response = await stub.fetch('https://do/upgrade', { headers });
+  const ws = response.webSocket;
+  if (ws === undefined || ws === null) {
+    throw new Error('ConnectionDO.fetch did not return a WebSocket');
+  }
+  ws.accept();
+  const client = await new Promise<SpecWsClient>((resolve) => {
+    setTimeout(() => resolve(new SpecWsClient(ws as WebSocket)), 0);
+  });
+  return { response, client };
+}
+
+/** Registers a client using bare spec-style frames (no trailing CR-LF). */
+async function registerBare(client: SpecWsClient, nick: string): Promise<void> {
+  client.sendRaw(`NICK ${nick}`);
+  client.sendRaw(`USER ${nick} 0 * :${nick}`);
+  await client.waitForLine((l) => l.includes(' 001 '));
+}
+
+// ---------------------------------------------------------------------------
+// Spec contract
+// ---------------------------------------------------------------------------
+
+describe('ConnectionDO — IRCv3 WebSocket spec contract (end-to-end)', () => {
+  // --- Sec-WebSocket-Protocol echo ----------------------------------------
+
+  it('echoes text.ircv3.net and binary.ircv3.net back in the 101 response', async () => {
+    const text = await openUpgrade('conn-contract-echo-text', 'text.ircv3.net');
+    expect(text.response.status).toBe(101);
+    expect(text.response.headers.get('Sec-WebSocket-Protocol')).toBe('text.ircv3.net');
+    text.client.ws.close();
+
+    const bin = await openUpgrade('conn-contract-echo-bin', 'binary.ircv3.net');
+    expect(bin.response.status).toBe(101);
+    expect(bin.response.headers.get('Sec-WebSocket-Protocol')).toBe('binary.ircv3.net');
+    bin.client.ws.close();
+  });
+
+  // --- Outbound: one IRC line per WS message, no trailing CR-LF -----------
+
+  it('delivers each outbound IRC line as its own WS message with no trailing CR-LF (spec-text)', async () => {
+    const { client } = await openUpgrade('conn-contract-outbound', 'text.ircv3.net');
+    client.sendRaw('NICK out-bob');
+    client.sendRaw('USER out-bob 0 * :out-bob');
+    await client.waitForLine((l) => l.includes(' 001 '));
+
+    // A successful registration emits several numerics (001..005, MOTD).
+    expect(client.messages.length).toBeGreaterThan(1);
+    for (const msg of client.messages) {
+      expect(msg.endsWith('\r\n')).toBe(false);
+    }
+    client.ws.close();
+  });
+
+  // --- Inbound: one IRC message per WS message ----------------------------
+
+  it('accepts bare single-line inbound frames (no trailing CR-LF) and completes registration (spec-text)', async () => {
+    const { client } = await openUpgrade('conn-contract-inbound-bare', 'text.ircv3.net');
+    // Each command is its own WS message with NO trailing CR-LF — the
+    // spec-mandated client shape. Registration must still complete.
+    await registerBare(client, 'bare-alice');
+    expect(client.lines.some((l) => l.includes(' 001 '))).toBe(true);
+    client.ws.close();
+  });
+
+  it('treats one WS message as exactly one IRC command (embedded CR-LF is not split) in spec-text mode', async () => {
+    const { client } = await openUpgrade('conn-contract-nosplit', 'text.ircv3.net');
+    await registerBare(client, 'nosplit-alice');
+    client.messages.length = 0;
+
+    // One WS message that LOOKS like two PING lines. In spec mode the frame
+    // is a single IRC message, so exactly ONE PONG is emitted.
+    client.sendRaw('PING one\r\nPING two');
+    await client.waitForMessages((m) => countCommand([m], 'PONG') === 1, 1);
+    // Give a grace window for a (incorrect) second PONG to arrive.
+    await new Promise((r) => setTimeout(r, 100));
+    expect(countCommand(client.messages, 'PONG')).toBe(1);
+    client.ws.close();
+  });
+
+  it('splits a joined CR-LF frame into multiple commands in legacy mode', async () => {
+    const { client } = await openUpgrade('conn-contract-legacy-split');
+    await registerBare(client, 'legsplit-bob');
+    client.messages.length = 0;
+
+    // Same joined frame, but legacy framing splits on CR-LF → TWO PONGs.
+    client.sendRaw('PING one\r\nPING two');
+    await client.waitForMessages((m) => countCommand([m], 'PONG') === 1, 2);
+    expect(countCommand(client.messages, 'PONG')).toBe(2);
+    client.ws.close();
+  });
+
+  // --- 510-byte message budget -------------------------------------------
+
+  it(`accepts a ${MAX_WS_MESSAGE_BYTES}-byte message and rejects a ${MAX_WS_MESSAGE_BYTES + 1}-byte message with close 1009 (spec-text)`, async () => {
+    // Accepted: exactly the budget. A PING whose token pads the frame to
+    // MAX_WS_MESSAGE_BYTES bytes parses and is answered with a PONG.
+    const okFrame = `PING :${'a'.repeat(MAX_WS_MESSAGE_BYTES - 'PING :'.length)}`;
+    expect(okFrame.length).toBe(MAX_WS_MESSAGE_BYTES);
+    const ok = await openUpgrade('conn-contract-budget-ok', 'text.ircv3.net');
+    ok.client.sendRaw(okFrame);
+    await ok.client.waitForLine((l) => l.startsWith('PONG') || l.includes(' PONG '));
+    expect(ok.client.closedCode).toBeUndefined();
+    ok.client.ws.close();
+
+    // Rejected: one byte over the budget → RFC 6455 1009 (Message Too Big).
+    const bigFrame = `PING :${'a'.repeat(MAX_WS_MESSAGE_BYTES + 1 - 'PING :'.length)}`;
+    expect(bigFrame.length).toBe(MAX_WS_MESSAGE_BYTES + 1);
+    const big = await openUpgrade('conn-contract-budget-big', 'text.ircv3.net');
+    big.client.sendRaw(bigFrame);
+    const code = await big.client.waitForClose();
+    expect(code).toBe(1009);
+
+    // The same budget applies on a binary.ircv3.net connection (sent as a
+    // binary frame): oversize → close 1009.
+    const bin = await openUpgrade('conn-contract-budget-bin', 'binary.ircv3.net');
+    bin.client.ws.send(new TextEncoder().encode(bigFrame));
+    const binCode = await bin.client.waitForClose();
+    expect(binCode).toBe(1009);
+  });
+
+  // --- Legacy fallback ----------------------------------------------------
+
+  it('still serves a legacy (no subprotocol offer) connection end-to-end', async () => {
+    const { response, client } = await openUpgrade('conn-contract-legacy');
+    expect(response.headers.get('Sec-WebSocket-Protocol')).toBeNull();
+    // Legacy clients join several commands into one CR-LF frame; the server
+    // splits and processes both → registration completes.
+    client.send('NICK legacy-carol');
+    client.send('USER legacy-carol 0 * :legacy-carol');
+    await client.waitForLine((l) => l.includes(' 001 '));
+    expect(client.lines.some((l) => l.includes(' 001 '))).toBe(true);
+    client.ws.close();
+  });
+});

package/packages/cf-adapter/tests/connection-do-ws-subprotocol.test.ts

@@ -0,0 +1,184 @@
+/**
+ * CF adapter — IRCv3 WebSocket subprotocol negotiation + per-message framing.
+ *
+ * Drives the real `ConnectionDO` through `cloudflare:test` (miniflare) so
+ * the `Sec-WebSocket-Protocol` round-trip, hibernation tags, and frame
+ * framing behave exactly as in production. Each test gets its own
+ * isolated storage namespace.
+ */
+
+import { env } from 'cloudflare:test';
+import { describe, expect, it } from 'vitest';
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      CONNECTION_DO: DurableObjectNamespace;
+      REGISTRY_DO: DurableObjectNamespace;
+      CHANNEL_DO: DurableObjectNamespace;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers — WebSocket client that records raw WS messages (not split lines).
+// ---------------------------------------------------------------------------
+
+class SpecWsClient {
+  /** Raw WebSocket messages exactly as delivered (one entry per WS message). */
+  readonly messages: string[] = [];
+  /** Lines split out of `messages` (tolerant of legacy `\r\n` framing). */
+  readonly lines: string[] = [];
+  readonly ws: WebSocket;
+  closedCode: number | undefined;
+
+  constructor(ws: WebSocket) {
+    this.ws = ws;
+    ws.addEventListener('message', (ev: MessageEvent) => {
+      const data = typeof ev.data === 'string' ? ev.data : new TextDecoder().decode(ev.data);
+      this.messages.push(data);
+      for (const line of data.split('\r\n')) {
+        if (line.length > 0) this.lines.push(line);
+      }
+    });
+    ws.addEventListener('close', (ev: CloseEvent) => {
+      this.closedCode = ev.code;
+    });
+  }
+
+  send(line: string): void {
+    this.ws.send(`${line}\r\n`);
+  }
+
+  waitForLine(predicate: (line: string) => boolean, timeoutMs = 2000): Promise<string> {
+    return new Promise<string>((resolve, reject) => {
+      const start = Date.now();
+      const tick = (): void => {
+        const hit = this.lines.find(predicate);
+        if (hit !== undefined) {
+          resolve(hit);
+          return;
+        }
+        if (Date.now() - start > timeoutMs) {
+          reject(new Error(`timeout waiting for line; got: ${JSON.stringify(this.lines)}`));
+          return;
+        }
+        setTimeout(tick, 20);
+      };
+      tick();
+    });
+  }
+
+  waitForClose(timeoutMs = 2000): Promise<number | undefined> {
+    return new Promise<number | undefined>((resolve, reject) => {
+      if (this.closedCode !== undefined) {
+        resolve(this.closedCode);
+        return;
+      }
+      const start = Date.now();
+      const tick = (): void => {
+        if (this.closedCode !== undefined) {
+          resolve(this.closedCode);
+          return;
+        }
+        if (Date.now() - start > timeoutMs) {
+          reject(
+            new Error(`timeout waiting for close; messages: ${JSON.stringify(this.messages)}`),
+          );
+          return;
+        }
+        setTimeout(tick, 20);
+      };
+      tick();
+    });
+  }
+}
+
+/**
+ * Opens a WebSocket to a fresh ConnectionDO, optionally offering a
+ * `Sec-WebSocket-Protocol` list. Returns the upgrade Response so the
+ * caller can assert on the echoed header, plus a ready-to-use client.
+ */
+async function openUpgrade(
+  connId: string,
+  protocols?: string,
+): Promise<{ response: Response; client: SpecWsClient }> {
+  const stub = env.CONNECTION_DO.get(env.CONNECTION_DO.idFromName(connId));
+  const headers: Record<string, string> = { Upgrade: 'websocket' };
+  if (protocols !== undefined) {
+    headers['Sec-WebSocket-Protocol'] = protocols;
+  }
+  const response = await stub.fetch('https://do/upgrade', { headers });
+  const ws = response.webSocket;
+  if (ws === undefined || ws === null) {
+    throw new Error('ConnectionDO.fetch did not return a WebSocket');
+  }
+  ws.accept();
+  const client = await new Promise<SpecWsClient>((resolve) => {
+    setTimeout(() => resolve(new SpecWsClient(ws as WebSocket)), 0);
+  });
+  return { response, client };
+}
+
+async function register(client: SpecWsClient, nick: string): Promise<void> {
+  client.send(`NICK ${nick}`);
+  client.send(`USER ${nick} 0 * :${nick}`);
+  await client.waitForLine((l) => l.includes(' 001 '));
+}
+
+// ---------------------------------------------------------------------------
+// Acceptance criteria
+// ---------------------------------------------------------------------------
+
+describe('ConnectionDO — IRCv3 WebSocket subprotocol negotiation', () => {
+  it('echoes text.ircv3.net back in the 101 response Sec-WebSocket-Protocol header', async () => {
+    const { response, client } = await openUpgrade('conn-subproto-text', 'text.ircv3.net');
+    expect(response.status).toBe(101);
+    expect(response.headers.get('Sec-WebSocket-Protocol')).toBe('text.ircv3.net');
+    client.ws.close();
+  });
+
+  it('selects the first-listed supported protocol when both are offered', async () => {
+    const a = await openUpgrade('conn-subproto-order-a', 'text.ircv3.net, binary.ircv3.net');
+    expect(a.response.headers.get('Sec-WebSocket-Protocol')).toBe('text.ircv3.net');
+    a.client.ws.close();
+
+    const b = await openUpgrade('conn-subproto-order-b', 'binary.ircv3.net, text.ircv3.net');
+    expect(b.response.headers.get('Sec-WebSocket-Protocol')).toBe('binary.ircv3.net');
+    b.client.ws.close();
+  });
+
+  it('omits Sec-WebSocket-Protocol when the client offers no supported protocol', async () => {
+    const { response, client } = await openUpgrade('conn-subproto-unsupported', 'bogus.proto');
+    expect(response.status).toBe(101);
+    expect(response.headers.get('Sec-WebSocket-Protocol')).toBeNull();
+    client.ws.close();
+  });
+
+  it('connects without a subprotocol offer (legacy mode) and registers', async () => {
+    const { client } = await openUpgrade('conn-subproto-legacy');
+    await register(client, 'legacy-alice');
+    expect(client.lines.some((l) => l.includes(' 001 '))).toBe(true);
+    client.ws.close();
+  });
+
+  it('delivers registration replies as N separate WS messages with no trailing CRLF (spec-text)', async () => {
+    const { client } = await openUpgrade('conn-subproto-permsg', 'text.ircv3.net');
+    client.send('NICK spec-bob');
+    client.send('USER spec-bob 0 * :spec-bob');
+    await client.waitForLine((l) => l.includes(' 001 '));
+
+    expect(client.messages.length).toBeGreaterThan(1);
+    for (const msg of client.messages) {
+      expect(msg.endsWith('\r\n')).toBe(false);
+    }
+    client.ws.close();
+  });
+
+  it('closes with code 1003 when a binary frame arrives on a spec-text connection', async () => {
+    const { client } = await openUpgrade('conn-subproto-bin-on-text', 'text.ircv3.net');
+    client.ws.send(new Uint8Array([0x4e, 0x49, 0x43, 0x4b]).buffer);
+    const code = await client.waitForClose();
+    expect(code).toBe(1003);
+  });
+});