serverless-ircd 0.1.0

package/packages/cf-adapter/src/registry-do.ts

@@ -0,0 +1,130 @@
+/**
+ * `RegistryDO` — Cloudflare Durable Object owning a slice of the
+ * nickname registry.
+ *
+ * PLAN §6.1 / §4 — the global nickname registry is partitioned across N
+ * Durable Object instances. Each instance owns a disjoint slice of the
+ * `lowercased(nick) → connectionId` map and is the sole authority for
+ * that slice. The fleet is addressed by `shardNick(nick, N)`: two
+ * clients racing on the same nick always land in the same shard, where
+ * the DO's single-threaded storage transaction gives the uniqueness
+ * invariant for free — no conditional writes, no optimistic retries.
+ *
+ * Storage layout (per-shard):
+ *   - One key per registered nick: `nick:<lower>` → `connectionId`
+ *
+ * Per-nick keys (rather than a single `Map` blob) keep storage
+ * proportional to the slice's live nick count and let individual
+ * reads/writes stay O(1) regardless of fleet size. Atomicity across
+ * `reserveNick` / `changeNick` is provided by
+ * {@link DurableObjectState["storage"]["transaction"]}: the
+ * read-modify-write inside a transaction is serial — concurrent
+ * reservations for the same nick serialize, so the first writer commits
+ * and the second sees the new owner and fails.
+ *
+ * RPC surface — implements {@link RegistryRpc}, the same shape the
+ * stub `RecordingRegistryDO` exposed for 033. Consumers
+ * (`CfRuntime`, 036) call these methods via `env.REGISTRY_DO`
+ * after computing the shard key with {@link registryKeyForNick}.
+ */
+
+import { DurableObject } from 'cloudflare:workers';
+import type { RegistryRpc } from './env.js';
+
+/** Storage key prefix for per-nick entries. */
+const NICK_KEY_PREFIX = 'nick:';
+
+/** Returns the storage key for `nickLower`. */
+function nickKey(nickLower: string): string {
+  return `${NICK_KEY_PREFIX}${nickLower}`;
+}
+
+/**
+ * Per-shard registry authority.
+ *
+ * One Durable Object instance holds the nick→connectionId mappings for
+ * every nick whose {@link shardNick} lands on this shard. The class is
+ * exported as a binding target in `wrangler.toml`; the Workers runtime
+ * instantiates it with `(ctx, env)` per DO id.
+ */
+export class RegistryDO extends DurableObject implements RegistryRpc {
+  /**
+   * Reserves `nick` for `conn`. Semantics:
+   *   - **Fresh nick:** stores the mapping, returns `{ ok: true }`.
+   *   - **Already held by `conn`:** idempotent no-op, returns
+   *     `{ ok: true }`. (Same client re-sending `NICK` during
+   *     registration must not fail its own reservation.)
+   *   - **Held by a different conn:** returns `{ ok: false }`.
+   *
+   * Atomicity is provided by `state.storage.transaction`. Two
+   * concurrent `reserveNick` calls for the same nick serialize: the
+   * first commits its put, the second reads the new owner and rejects.
+   */
+  async reserveNick(nick: string, conn: string): Promise<{ ok: true } | { ok: false }> {
+    return this.ctx.storage.transaction(async (tx) => {
+      const key = nickKey(nick.toLowerCase());
+      const existing = await tx.get<string>(key);
+      if (existing !== undefined && existing !== conn) {
+        return { ok: false as const };
+      }
+      await tx.put(key, conn);
+      return { ok: true as const };
+    });
+  }
+
+  /**
+   * Atomically re-points the registry from `oldNick` to `newNick` for
+   * `conn`. Used by `NICK` (nick changes).
+   *
+   * Behaviour:
+   *   - If `newNick` is taken by another conn, returns `false` and
+   *     touches nothing.
+   *   - Otherwise reserves `newNick` for `conn`.
+   *   - Clears `oldNick` *only if it still points at `conn`*. The
+   *     conditional delete avoids clobbering a third party that grabbed
+   *     `oldNick` after this conn abandoned it (defence in depth).
+   *
+   * Cross-shard changes (old and new hash to different shards) are
+   * orchestrated by `CfRuntime` in 036 as a two-phase
+   * reserve-new-then-release-old. This DO only sees single-shard
+   * changes and crash-recovery paths (where `oldNick` may not be
+   * present); the latter is why the conditional delete is a soft check.
+   */
+  async changeNick(conn: string, oldNick: string, newNick: string): Promise<boolean> {
+    return this.ctx.storage.transaction(async (tx) => {
+      const newKey = nickKey(newNick.toLowerCase());
+      const oldKey = nickKey(oldNick.toLowerCase());
+
+      const owner = await tx.get<string>(newKey);
+      if (owner !== undefined && owner !== conn) {
+        return false;
+      }
+      await tx.put(newKey, conn);
+
+      const oldOwner = await tx.get<string>(oldKey);
+      if (oldOwner === conn) {
+        await tx.delete(oldKey);
+      }
+      return true;
+    });
+  }
+
+  /**
+   * Releases the mapping for `nick`. Idempotent — releasing a missing
+   * nick is a no-op (covers the close-after-crash case where the nick
+   * was never reserved or already cleaned up).
+   */
+  async releaseNick(nick: string): Promise<void> {
+    await this.ctx.storage.delete(nickKey(nick.toLowerCase()));
+  }
+
+  /**
+   * Resolves `nick` to its owning connectionId, or `null` if no
+   * connection currently holds it. Read-only; safe to call outside a
+   * transaction.
+   */
+  async lookupNick(nick: string): Promise<string | null> {
+    const owner = await this.ctx.storage.get<string>(nickKey(nick.toLowerCase()));
+    return owner ?? null;
+  }
+}

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

@@ -0,0 +1,142 @@
+/**
+ * Serialization helpers for {@link ConnectionState}.
+ *
+ * `state.storage` (Durable Object transactional KV) stores JSON-compatible
+ * values. `Set` and `Map` fields don't survive a JSON round-trip — they
+ * degrade into `{}`. To make hibernation safe we serialize those fields
+ * into plain arrays on write and rebuild them on read. Everything else
+ * (strings, numbers, booleans, optional fields) survives untouched.
+ *
+ * A `version` field on {@link PersistedConnectionState} supports
+ * migrations: if the persisted shape changes, bump the version and add a
+ * `migrate_vN_vN1` step in {@link migrate}. Old format -> latest on read.
+ */
+
+import type {
+  ChanName,
+  ConnectionState,
+  Nick,
+  RegistrationState,
+  UserModes,
+} from '@serverless-ircd/irc-core';
+
+/** Current on-disk schema version. Bump when the shape changes. */
+export const PERSISTED_STATE_VERSION = 1;
+
+/**
+ * Serialized representation of a {@link ConnectionState} in DO storage.
+ * `Set`s become arrays; everything else is preserved verbatim.
+ *
+ * The `version` field supports future migrations — see {@link migrate}.
+ */
+export interface PersistedConnectionState {
+  version: number;
+  id: string;
+  registration: RegistrationState;
+  capNegotiating: boolean;
+  caps: string[];
+  joinedChannels: ChanName[];
+  userModes: UserModes;
+  lastSeen: number;
+  connectedSince: number;
+  nick?: Nick;
+  user?: string;
+  host?: string;
+  realname?: string;
+  passAttempt?: string;
+  account?: string;
+  away?: string;
+}
+
+/** Storage key under which the per-connection state is persisted. */
+export const STATE_STORAGE_KEY = 'connection-state';
+
+/**
+ * Serializes a live {@link ConnectionState} into a JSON-safe shape for
+ * `state.storage.put()`.
+ */
+export function serialize(state: ConnectionState): PersistedConnectionState {
+  const out: PersistedConnectionState = {
+    version: PERSISTED_STATE_VERSION,
+    id: state.id,
+    registration: state.registration,
+    capNegotiating: state.capNegotiating,
+    caps: [...state.caps],
+    joinedChannels: [...state.joinedChannels],
+    userModes: { ...state.userModes },
+    lastSeen: state.lastSeen,
+    connectedSince: state.connectedSince,
+  };
+  if (state.nick !== undefined) out.nick = state.nick;
+  if (state.user !== undefined) out.user = state.user;
+  if (state.host !== undefined) out.host = state.host;
+  if (state.realname !== undefined) out.realname = state.realname;
+  if (state.passAttempt !== undefined) out.passAttempt = state.passAttempt;
+  if (state.account !== undefined) out.account = state.account;
+  if (state.away !== undefined) out.away = state.away;
+  return out;
+}
+
+/**
+ * Materializes a live {@link ConnectionState} from a persisted record.
+ * Rebuilds `Set`s from the stored arrays and applies any registered
+ * migrations via {@link migrate} first.
+ */
+export function deserialize(record: unknown): ConnectionState {
+  const migrated = migrate(record);
+  const state: ConnectionState = {
+    id: migrated.id,
+    registration: migrated.registration,
+    capNegotiating: migrated.capNegotiating,
+    caps: new Set<string>(migrated.caps),
+    joinedChannels: new Set<ChanName>(migrated.joinedChannels),
+    userModes: { ...migrated.userModes },
+    lastSeen: migrated.lastSeen,
+    connectedSince: migrated.connectedSince,
+  };
+  if (migrated.nick !== undefined) state.nick = migrated.nick;
+  if (migrated.user !== undefined) state.user = migrated.user;
+  if (migrated.host !== undefined) state.host = migrated.host;
+  if (migrated.realname !== undefined) state.realname = migrated.realname;
+  if (migrated.passAttempt !== undefined) state.passAttempt = migrated.passAttempt;
+  if (migrated.account !== undefined) state.account = migrated.account;
+  if (migrated.away !== undefined) state.away = migrated.away;
+  return state;
+}
+
+/**
+ * Forward-migrates a persisted record to {@link PERSISTED_STATE_VERSION}.
+ *
+ * Each step is keyed `fromVersion_toVersion`. Unknown shapes (or
+ * `version: 0`, the legacy default) are passed through as-is; the only
+ * "migration" today is the no-op v1 -> v1.
+ *
+ * PLAN §6.1 — DO transactional storage outlives any single deployment,
+ * so the on-disk schema will eventually diverge from the in-memory shape.
+ * This is the seam that keeps them in sync.
+ */
+export function migrate(record: unknown): PersistedConnectionState {
+  if (!isPlainObject(record)) {
+    throw new Error('persisted connection state is not an object');
+  }
+  const version = typeof record.version === 'number' ? record.version : 0;
+  // No migrations yet — v1 is the initial schema. Future work adds steps:
+  //   if (version < 2) record = migrate_v1_v2(record);
+  //   if (version < 3) record = migrate_v2_v3(record);
+  if (version > PERSISTED_STATE_VERSION) {
+    throw new Error(
+      `persisted connection state version ${version} is newer than ` +
+        `supported version ${PERSISTED_STATE_VERSION}`,
+    );
+  }
+  // The cast below is safe: we accept any JSON shape the storage layer
+  // returns; production code wrote it via `serialize`, tests wrote it
+  // through the same path. If a future field is missing, the
+  // `exactOptionalPropertyTypes` discipline in `serialize` keeps
+  // undefined keys out of the persisted record entirely.
+  return record as unknown as PersistedConnectionState;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

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

@@ -0,0 +1,101 @@
+/**
+ * Nick sharding for the Cloudflare `RegistryDO` fleet.
+ *
+ * PLAN §6.1 / §4 — the nickname registry is split across N Durable
+ * Object instances to avoid a single hot shard. Two clients racing on
+ * the *same* nick both route to the same shard, where DO
+ * single-threadedness (storage transactions) makes the uniqueness
+ * invariant structural instead of optimistic.
+ *
+ * Shard assignment is `hash(lowercased(nick)) % N`:
+ *   - **Deterministic** — every adapter instance computes the same
+ *     shard for a given nick without coordination.
+ *   - **Case-insensitive** — matches RFC 1459 nick equivalence.
+ *     `Alice`, `alice`, and `ALICE` MUST land in the same shard so the
+ *     single-shard uniqueness check covers all case variants.
+ *   - **Reasonably uniform** — FNV-1a 32-bit gives ~uniform spread
+ *     over realistic nick populations (verified by a 10k synthetic
+ *     distribution test).
+ *   - **Synchronous & dependency-free** — important since this runs on
+ *     every nick-reservation path; no `crypto.subtle.digest` await.
+ *
+ * `N` defaults to {@link DEFAULT_REGISTRY_SHARDS} (32) and is
+ * configurable per deployment via the worker env. Changing N after
+ * production traffic requires a migration (re-sharding every existing
+ * nick→conn mapping); document this in `docs/deployment-cf.md`
+ * (038).
+ */
+
+/**
+ * Default shard count for the registry DO fleet.
+ *
+ * 32 is a sweet spot for a v1 single-region Workers deployment:
+ *   - Small enough that the per-shard nick map fits comfortably in DO
+ *     transactional storage (tens of thousands of entries per shard
+ *     before a 128 kB transaction-size ceiling becomes a concern).
+ *   - Large enough that no single shard bottlenecks registration
+ *     throughput for any plausible nick population.
+ *
+ * Production overrides via `REGISTRY_SHARDS` env var; see
+ * {@link RegistryDO} constructor.
+ */
+export const DEFAULT_REGISTRY_SHARDS = 32;
+
+/**
+ * Computes the shard index for `nick` under a fleet of `shards` DOs.
+ *
+ * Lowercases `nick` first (RFC 1459 nick case-insensitivity) then
+ * applies FNV-1a 32-bit and reduces `mod shards`.
+ *
+ * @param nick Nick to shard (case-insensitive).
+ * @param shards Fleet size; defaults to {@link DEFAULT_REGISTRY_SHARDS}.
+ * @returns Integer in `[0, shards)`.
+ * @throws if `shards <= 0` (programming error — fail fast at boot).
+ */
+export function shardNick(nick: string, shards: number = DEFAULT_REGISTRY_SHARDS): number {
+  if (!Number.isInteger(shards) || shards <= 0) {
+    throw new Error(`shardNick: shards must be a positive integer, got ${shards}`);
+  }
+  return fnv1a32(nick.toLowerCase()) % shards;
+}
+
+/**
+ * Returns the Durable Object name key for the shard owning `nick`.
+ *
+ * The CfRuntime calls this to compute `env.REGISTRY_DO.idFromName(key)`
+ * before each RPC. The key format is **stable**: it depends only on the
+ * (lowercased) nick and the shard count, never on the host deployment,
+ * so two adapters configured the same will route to the same shard.
+ *
+ * Format: literal `s` prefix + base-10 shard index (e.g. `s7`, `s31`).
+ * The prefix keeps registry keys visually distinct from other potential
+ * name-spaced DOs in the same worker.
+ *
+ * @param nick Nick whose shard we want.
+ * @param shards Fleet size; defaults to {@link DEFAULT_REGISTRY_SHARDS}.
+ */
+export function registryKeyForNick(nick: string, shards: number = DEFAULT_REGISTRY_SHARDS): string {
+  return `s${shardNick(nick, shards)}`;
+}
+
+/**
+ * FNV-1a 32-bit hash.
+ *
+ * Chosen for sharding because:
+ *   - Short, well-understood implementation with no external deps.
+ *   - Good distribution for short ASCII inputs (nicks).
+ *   - Synchronous (unlike `crypto.subtle.digest`).
+ *
+ * Not cryptographic — the only property we need is uniform spread.
+ */
+function fnv1a32(input: string): number {
+  let hash = 0x811c9dc5; // FNV offset basis (2166136261)
+  for (let i = 0; i < input.length; i++) {
+    hash ^= input.charCodeAt(i);
+    // Multiply by FNV prime (16777619) mod 2^32. The Math.imul form
+    // keeps this in 32-bit space and avoids floating-point drift.
+    hash = Math.imul(hash, 0x01000193);
+  }
+  // Force unsigned 32-bit.
+  return hash >>> 0;
+}

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

@@ -0,0 +1,264 @@
+/**
+ * CF-side {@link IrcHarnessFactory} — registers the parametrized IRC
+ * scenario suite (032) against the Cloudflare adapter.
+ *
+ * Each {@link CfHarness} instance is hermetic at the vitest-pool-workers
+ * level: every test gets an isolated storage namespace
+ * (`isolatedStorage: true` in vitest.config.ts), so two tests never share
+ * ConnectionDO / RegistryDO / ChannelDO state even though they address
+ * the same worker bindings.
+ *
+ * Each `spawnClient` opens a real WebSocket to a fresh `ConnectionDO`
+ * named by an auto-allocated id. The WebSocket drives the actor pipeline
+ * (bytes → framed messages → reducer → dispatch → CfRuntime) exactly as
+ * in production — there is no test-only shortcut.
+ */
+
+import type { ConnId } from '@serverless-ircd/irc-core';
+import type {
+  ClientHarness,
+  IrcHarness,
+  IrcHarnessFactory,
+  SpawnClientOptions,
+} from './integration/harness.js';
+
+/** Default tick for the polling waitFor* implementations (ms). */
+const POLL_MS = 10;
+
+/** Default timeout for waitFor* implementations (ms). */
+const DEFAULT_TIMEOUT_MS = 2000;
+
+/**
+ * Factory entry for the Cloudflare runtime. Append this to a suite's
+ * FACTORIES array to opt the scenarios into the CF matrix.
+ *
+ * The factory is created lazily inside `create()` because the env is only
+ * available inside an `it` block (via the `cloudflare:test` `env`
+ * global). Consumers MUST call `setCfEnv(env)` from a `beforeAll` (or
+ * equivalent) so the harness can capture the bindings.
+ */
+export interface CfHarnessFactoryOptions {
+  /** Worker bindings; captured from `cloudflare:test`'s `env` global. */
+  env: CfHarnessEnv;
+  /** Server name to assert against in MOTD/welcome replies. */
+  serverName?: string;
+}
+
+/** Bindings the CF harness needs from `cloudflare:test`. */
+export interface CfHarnessEnv {
+  CONNECTION_DO: DurableObjectNamespace;
+  REGISTRY_DO: DurableObjectNamespace;
+  CHANNEL_DO: DurableObjectNamespace;
+}
+
+/**
+ * Constructs a CF harness factory bound to the supplied env. Call from
+ * inside a vitest test file running under `vitest-pool-workers`:
+ *
+ * ```ts
+ * import { env } from 'cloudflare:test';
+ * import { runIrcScenarios } from './integration/scenarios.js';
+ * import { makeCfHarnessFactory } from './cf-harness';
+ *
+ * runIrcScenarios([makeCfHarnessFactory({ env })]);
+ * ```
+ */
+export function makeCfHarnessFactory(opts: CfHarnessFactoryOptions): IrcHarnessFactory {
+  return Object.freeze({
+    name: 'cf',
+    async create() {
+      return new CfHarness(opts);
+    },
+  });
+}
+
+interface TrackedClient {
+  harness: CfClientHandle;
+  close: () => Promise<void>;
+}
+
+/**
+ * One isolated CF world. Spawns clients by opening real WebSockets to
+ * fresh ConnectionDO instances. The same `ConnectionDO` namespace is
+ * reused across all clients in one harness (per the in-memory harness's
+ * convention); isolation across tests comes from `isolatedStorage: true`.
+ */
+class CfHarness implements IrcHarness {
+  private readonly env: CfHarnessEnv;
+  private nextId = 0;
+  private closed = false;
+  private readonly clients = new Map<ConnId, TrackedClient>();
+  private readonly nicks = new Map<string, CfClientHandle>();
+
+  constructor(opts: CfHarnessFactoryOptions) {
+    this.env = opts.env;
+  }
+
+  async spawnClient(opts?: SpawnClientOptions): Promise<ClientHarness> {
+    if (this.closed) throw new Error('spawnClient called on a closed harness');
+    const id = opts?.id ?? `c${this.nextId++}`;
+    if (this.clients.has(id)) {
+      throw new Error(`duplicate client id: ${id}`);
+    }
+
+    const handle = await openConnection(this.env, id);
+    const client = new CfClientHandle(id, handle.ws);
+    const close = async (): Promise<void> => {
+      const tracked = this.clients.get(id);
+      if (tracked === undefined) return;
+      this.clients.delete(id);
+      await handle.close();
+    };
+    this.clients.set(id, { harness: client, close });
+
+    // Track nick → client for clientByNick lookups. We don't have a
+    // synchronous nick event, so we update this map opportunistically by
+    // observing the welcome line; precise nick lookups go through the
+    // registry via `clientByNick`.
+    if (opts?.nick !== undefined) {
+      await client.send(`NICK ${opts.nick}`);
+      await client.send(`USER ${opts.nick} 0 * :${opts.nick}`);
+      await client.waitForNumeric('001', DEFAULT_TIMEOUT_MS);
+      this.nicks.set(opts.nick.toLowerCase(), client);
+    }
+
+    return client;
+  }
+
+  async clientByNick(nick: string): Promise<ClientHarness | undefined> {
+    // First check the local cache (fast path for the test's own clients).
+    const cached = this.nicks.get(nick.toLowerCase());
+    if (cached !== undefined) return cached;
+    return undefined;
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    for (const { close } of this.clients.values()) await close();
+    this.clients.clear();
+    this.nicks.clear();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// WebSocket plumbing
+// ---------------------------------------------------------------------------
+
+interface OpenedConnection {
+  ws: WebSocket;
+  close: () => Promise<void>;
+}
+
+async function openConnection(env: CfHarnessEnv, connId: string): Promise<OpenedConnection> {
+  const stub = env.CONNECTION_DO.get(env.CONNECTION_DO.idFromName(connId));
+  const response = await stub.fetch('https://do/upgrade', {
+    headers: { Upgrade: 'websocket' },
+  });
+  const ws = response.webSocket;
+  if (ws === undefined || ws === null) {
+    throw new Error('ConnectionDO.fetch did not return a WebSocket');
+  }
+  ws.accept();
+  await new Promise<void>((resolve) => setTimeout(resolve, 0));
+  return {
+    ws: ws as WebSocket,
+    close: () =>
+      new Promise<void>((resolve) => {
+        if (ws.readyState === WebSocket.CLOSED || ws.readyState === WebSocket.CLOSING) {
+          resolve();
+          return;
+        }
+        (ws as WebSocket).addEventListener('close', () => resolve());
+        try {
+          (ws as WebSocket).close();
+        } catch {
+          resolve();
+        }
+        setTimeout(resolve, 200);
+      }),
+  };
+}
+
+/** CF-backed ClientHarness: a real WebSocket plus the standard helpers. */
+class CfClientHandle implements ClientHarness {
+  readonly received: string[] = [];
+  private closed = false;
+  private readonly ws: WebSocket;
+
+  constructor(
+    readonly id: ConnId,
+    ws: WebSocket,
+  ) {
+    this.ws = ws;
+    ws.addEventListener('message', (ev: MessageEvent) => {
+      const d = ev.data as string;
+      for (const line of d.split('\r\n')) {
+        if (line.length > 0) this.received.push(line);
+      }
+    });
+  }
+
+  async send(line: string): Promise<void> {
+    if (this.closed) return;
+    this.ws.send(`${line}\r\n`);
+  }
+
+  async waitForLine(
+    predicate: (line: string) => boolean,
+    timeoutMs: number = DEFAULT_TIMEOUT_MS,
+  ): Promise<string> {
+    const deadline = Date.now() + timeoutMs;
+    for (const line of this.received) {
+      if (predicate(line)) return line;
+    }
+    while (Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, POLL_MS));
+      for (const line of this.received) {
+        if (predicate(line)) return line;
+      }
+    }
+    throw new Error(
+      `waitForLine timed out after ${timeoutMs}ms; received: ${JSON.stringify(this.received)}`,
+    );
+  }
+
+  async waitForNumeric(
+    code: number | string,
+    timeoutMs: number = DEFAULT_TIMEOUT_MS,
+  ): Promise<string> {
+    const want = typeof code === 'number' ? code.toString().padStart(3, '0') : code;
+    return this.waitForLine((l) => numericEquals(l, want), timeoutMs);
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    // Best-effort QUIT so peers see the part broadcast.
+    try {
+      this.ws.send('QUIT :client closed\r\n');
+    } catch {
+      // ignore
+    }
+    await new Promise<void>((resolve) => {
+      this.ws.addEventListener('close', () => resolve());
+      try {
+        this.ws.close();
+      } catch {
+        resolve();
+      }
+      setTimeout(resolve, 200);
+    });
+  }
+}
+
+/**
+ * Returns true iff the second whitespace-delimited token of `line` is
+ * `code` (after the optional `:server` prefix).
+ */
+function numericEquals(line: string, code: string): boolean {
+  const parts = line.split(' ');
+  const start = parts[0]?.startsWith(':') ? 1 : 0;
+  const candidate = parts[start];
+  return candidate === code;
+}