serverless-ircd 0.4.0 → 0.6.0

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,308 @@ 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);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests — broadcastWallops (global +w fan-out across every registry shard)
+// ---------------------------------------------------------------------------
+
+/**
+ * Opens a ConnectionDO, registers it with the given nick, and optionally
+ * flips user mode `w` on via a direct state mutation (avoids driving the
+ * full MODE handshake through the actor). Returns the live WebSocket and
+ * the connection's canonical hex id.
+ */
+async function openWallopsCapableConn(
+  name: string,
+  opts: { wallops: boolean },
+): Promise<{ ws: WebSocket; hexId: string; received: string[] }> {
+  const ws = await openConnection(name);
+  await new Promise<void>((r) => setTimeout(r, 20));
+  ws.send(`NICK ${name}\r\n`);
+  ws.send(`USER ${name} 0 * :${name}\r\n`);
+  // Drain the registration numerics so they don't interfere with the
+  // assertions on wallops delivery below.
+  await new Promise<void>((r) => setTimeout(r, 100));
+
+  const hexId = await getConnectionHexId(name);
+  const received = drainSocket(ws);
+
+  if (opts.wallops) {
+    // Flip the +w mode directly on the live cached state. The DO is the
+    // authority for this state; broadcastWallops reads it back via
+    // getConnState() so what we mutate here is exactly what the fan-out
+    // will see.
+    const stub = env.CONNECTION_DO.get(env.CONNECTION_DO.idFromString(hexId));
+    await runInDurableObject(stub, async (instance: unknown) => {
+      const doi = instance as {
+        __peekState?: () => Promise<
+          import('@serverless-ircd/irc-core').ConnectionState | undefined
+        >;
+        __pokeState?: (s: import('@serverless-ircd/irc-core').ConnectionState) => void;
+      };
+      const state = await doi.__peekState?.();
+      if (state !== undefined) state.userModes.wallops = true;
+    });
+  }
+
+  // Reserve the nick in the REAL registry under its hex id so
+  // broadcastWallops' shard walk finds it.
+  await reserveNickInRealRegistry(name, hexId);
+
+  return { ws, hexId, received };
+}
+
+describe('CfRuntime — broadcastWallops', () => {
+  it('delivers to every +w connection enumerated across all registry shards', async () => {
+    const realEnv = envWithRealDOs();
+
+    const a = await openWallopsCapableConn('wallops-a', { wallops: true });
+    const b = await openWallopsCapableConn('wallops-b', { wallops: true });
+    // A connection without +w must not receive the wallops.
+    const plain = await openWallopsCapableConn('wallops-plain', { wallops: false });
+
+    const rt = new CfRuntime(realEnv, 'conn-wallops-sender', recordingHandlers());
+    await rt.broadcastWallops([{ text: ':oper!u@h WALLOPS :hi fleet' }]);
+
+    await new Promise<void>((resolve) => {
+      const deadline = Date.now() + 1500;
+      const tick = (): void => {
+        const aGot = a.received.some((l) => l.includes('hi fleet'));
+        const bGot = b.received.some((l) => l.includes('hi fleet'));
+        if (aGot && bGot && Date.now() > deadline - 1000) {
+          resolve();
+          return;
+        }
+        if (Date.now() > deadline) {
+          resolve();
+          return;
+        }
+        setTimeout(tick, 20);
+      };
+      tick();
+    });
+
+    expect(a.received.some((l) => l.includes('hi fleet'))).toBe(true);
+    expect(b.received.some((l) => l.includes('hi fleet'))).toBe(true);
+    expect(plain.received.some((l) => l.includes('hi fleet'))).toBe(false);
+
+    a.ws.close();
+    b.ws.close();
+    plain.ws.close();
+  });
+
+  it('skips the excepted originator', async () => {
+    const realEnv = envWithRealDOs();
+    const sender = await openWallopsCapableConn('wallops-except-sender', { wallops: true });
+    const other = await openWallopsCapableConn('wallops-except-other', { wallops: true });
+
+    const rt = new CfRuntime(realEnv, sender.hexId, recordingHandlers());
+    await rt.broadcastWallops([{ text: ':oper!u@h WALLOPS :except me' }], sender.hexId);
+
+    await new Promise<void>((resolve) => {
+      const deadline = Date.now() + 1000;
+      const tick = (): void => {
+        if (other.received.some((l) => l.includes('except me'))) {
+          resolve();
+          return;
+        }
+        if (Date.now() > deadline) {
+          resolve();
+          return;
+        }
+        setTimeout(tick, 20);
+      };
+      tick();
+    });
+
+    expect(other.received.some((l) => l.includes('except me'))).toBe(true);
+    expect(sender.received.some((l) => l.includes('except me'))).toBe(false);
+
+    sender.ws.close();
+    other.ws.close();
+  });
+
+  it('is a no-op when the registry has no entries', async () => {
+    const realEnv = envWithRealDOs();
+    const handlers = recordingHandlers();
+    const rt = new CfRuntime(realEnv, 'conn-wallops-empty', handlers);
+    // Fresh storage (afterEach reset); no nick reservations anywhere.
+    await expect(
+      rt.broadcastWallops([{ text: ':oper!u@h WALLOPS :nobody' }]),
+    ).resolves.toBeUndefined();
+    expect(handlers.sent).toEqual([]);
+  });
+
+  it('skips a connection whose persisted state is null without throwing', async () => {
+    // Reserve a nick pointing at a hex id whose ConnectionDO has no
+    // live state. `newUniqueId()` gives us a valid 64-hex DO id that
+    // is guaranteed not to collide with any connection we open here.
+    const realEnv = envWithRealDOs();
+    const ghostHex = env.CONNECTION_DO.newUniqueId().toString();
+    await reserveNickInRealRegistry('wallops-ghost', ghostHex);
+
+    const other = await openWallopsCapableConn('wallops-alongside-ghost', { wallops: true });
+
+    const rt = new CfRuntime(realEnv, 'conn-wallops-ghost-caller', recordingHandlers());
+    // Must not reject even though one enumerated conn reports null state.
+    await expect(
+      rt.broadcastWallops([{ text: ':oper!u@h WALLOPS :ghost friendly' }]),
+    ).resolves.toBeUndefined();
+
+    await new Promise<void>((resolve) => {
+      const deadline = Date.now() + 1000;
+      const tick = (): void => {
+        if (other.received.some((l) => l.includes('ghost friendly'))) {
+          resolve();
+          return;
+        }
+        if (Date.now() > deadline) {
+          resolve();
+          return;
+        }
+        setTimeout(tick, 20);
+      };
+      tick();
+    });
+    expect(other.received.some((l) => l.includes('ghost friendly'))).toBe(true);
+
+    other.ws.close();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests — changeNick shard routing + failure paths
+// ---------------------------------------------------------------------------
+
+describe('CfRuntime — changeNick shard routing', () => {
+  it('uses the single-shard RegistryDO.changeNick when old and new hash to the same shard', async () => {
+    // Pin registryShards to 1 so every nick routes to shard 0 — the
+    // same-shard branch in CfRuntime.changeNick is taken.
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-sameshard', recordingHandlers(), {
+      registryShards: 1,
+    });
+    expect(await rt.reserveNick('sn-old', 'conn-sameshard')).toEqual({ ok: true });
+
+    const ok = await rt.changeNick('conn-sameshard', 'sn-old', 'sn-new');
+    expect(ok).toBe(true);
+
+    // Look up under the same shard count the runtime used (1).
+    const key = registryKeyForNick('sn-new', 1);
+    const newOwner = (
+      (await env.REGISTRY_DO_REAL.get(
+        env.REGISTRY_DO_REAL.idFromName(key),
+      )) as unknown as RegistryRpc
+    ).lookupNick('sn-new');
+    expect(await newOwner).toBe('conn-sameshard');
+    const oldKey = registryKeyForNick('sn-old', 1);
+    const oldOwner = (
+      (await env.REGISTRY_DO_REAL.get(
+        env.REGISTRY_DO_REAL.idFromName(oldKey),
+      )) as unknown as RegistryRpc
+    ).lookupNick('sn-old');
+    expect(await oldOwner).toBeNull();
+  });
+
+  it('two-phase path returns false when the new nick is already taken cross-shard', async () => {
+    // Default shard count (32). Reserve `wn-taken` by another conn first,
+    // then attempt to changeNick to it from a different conn.
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-newowner', recordingHandlers());
+    expect(await rt.reserveNick('wn-current', 'conn-newowner')).toEqual({ ok: true });
+    expect(await rt.reserveNick('wn-taken', 'conn-someoneelse')).toEqual({ ok: true });
+
+    const ok = await rt.changeNick('conn-newowner', 'wn-current', 'wn-taken');
+    expect(ok).toBe(false);
+    // Old nick untouched because the reserve-new phase failed.
+    expect(await registryForNick(realEnv, 'wn-current').lookupNick('wn-current')).toBe(
+      'conn-newowner',
+    );
+    expect(await registryForNick(realEnv, 'wn-taken').lookupNick('wn-taken')).toBe(
+      'conn-someoneelse',
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests — getConnection / getChannelConnections edge cases
+// ---------------------------------------------------------------------------
+
+describe('CfRuntime — getConnection and getChannelConnections branches', () => {
+  it('getConnection(this.connId) returns the live snapshot via handlers', async () => {
+    const stubEnv = envWithChannelStub();
+    const state = createConnection({ id: 'conn-getc-self', connectedSince: 0 });
+    state.nick = 'self';
+    const handlers: CfConnectionHandlers = {
+      send: (): void => {},
+      disconnect: (): void => {},
+      snapshot: () => state,
+    };
+    const rt = new CfRuntime(stubEnv, 'conn-getc-self', handlers);
+    const conn = await rt.getConnection('conn-getc-self');
+    expect(conn).not.toBeNull();
+    expect(conn?.nick).toBe('self');
+  });
+
+  it('getConnection(this.connId) returns null when handlers.snapshot is undefined', async () => {
+    const stubEnv = envWithChannelStub();
+    const rt = new CfRuntime(stubEnv, 'conn-getc-empty', recordingHandlers());
+    expect(await rt.getConnection('conn-getc-empty')).toBeNull();
+  });
+
+  it('getChannelConnections returns every member that reports a persisted state', async () => {
+    // A channel roster with one real member; the ConnectionDO is the
+    // authority for each member's state. getChannelConnections fans out
+    // one getConnState RPC per member and collects the results.
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-gcc-caller', recordingHandlers());
+
+    const member = await openWallopsCapableConn('gcc-real', { wallops: false });
+
+    await rt.applyChannelDelta('#gcc', {
+      memberships: [{ type: 'add' as const, conn: member.hexId, nick: 'gcc-real' }],
+    });
+
+    const conns = await rt.getChannelConnections('#gcc');
+    expect(conns.size).toBe(1);
+    expect(conns.get(member.hexId)?.nick).toBe('gcc-real');
+
+    member.ws.close();
+  });
+});

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', () => {
@@ -478,3 +478,120 @@ describe('ChannelDO — scale', () => {
     expect(snapAfter?.members.length).toBe(0);
   }, 15_000);
 });
+
+// ---------------------------------------------------------------------------
+// Edge cases — empty-lines broadcast, cache reload, test hooks
+// ---------------------------------------------------------------------------
+
+describe('ChannelDO — broadcast + cache edge cases', () => {
+  it('broadcast is a no-op for an empty lines array', async () => {
+    const chan = '#empty-bcast';
+    await channel(chan.toLowerCase()).applyChannelDelta({
+      memberships: [{ type: 'add' as const, conn: 'ghost', nick: 'g' }],
+    });
+    // Must not reject and must not prune members (no fan-out attempted).
+    await expect(channel(chan.toLowerCase()).broadcast([])).resolves.toBeUndefined();
+    const snap = await channel(chan.toLowerCase()).getChannelSnapshot();
+    expect(snap?.members.length).toBe(1);
+  });
+
+  it('reloads persisted state from storage after __resetCache (deserializeChannel)', async () => {
+    // Mutate the channel, drop the in-memory cache, then read again.
+    // The read must go through deserializeChannel to rebuild Map/Set
+    // fields from the JSON-friendly persisted shape.
+    const chan = '#cache-reload';
+    const lower = chan.toLowerCase();
+    await channel(lower).applyChannelDelta({
+      memberships: [{ type: 'add' as const, conn: 'c-1', nick: 'alice' }],
+      topic: { text: 'hello topic', setter: 'alice', setAt: 100 },
+    });
+
+    // Drop the cache so the next read forces a storage reload.
+    await runInDurableObject(channelStub(lower), (instance: unknown) => {
+      const doi = instance as { __resetCache?: () => void };
+      doi.__resetCache?.();
+    });
+
+    const snap = await channel(lower).getChannelSnapshot();
+    expect(snap?.members.length).toBe(1);
+    expect(snap?.members[0]?.nick).toBe('alice');
+    expect(snap?.topic?.text).toBe('hello topic');
+  });
+
+  it('__peekState returns the live cached state before any reload', async () => {
+    const lower = '#peek-state';
+    await channel(lower).applyChannelDelta({
+      memberships: [{ type: 'add' as const, conn: 'c-peek', nick: 'peeker' }],
+    });
+    const cached = await runInDurableObject(channelStub(lower), async (instance: unknown) => {
+      const doi = instance as { __peekState?: () => Promise<unknown> };
+      return doi.__peekState?.();
+    });
+    expect(cached).toBeDefined();
+    // The cached state's members Map carries the entry we just added.
+    const members = (cached as { members: Map<string, unknown> }).members;
+    expect(members.get('c-peek')).toBeDefined();
+  });
+
+  it('__resetCache clears the in-memory cache', async () => {
+    const lower = '#reset-cache';
+    await channel(lower).applyChannelDelta({
+      memberships: [{ type: 'add' as const, conn: 'c-reset', nick: 'resetter' }],
+    });
+
+    await runInDurableObject(channelStub(lower), (instance: unknown) => {
+      const doi = instance as { __resetCache?: () => void };
+      doi.__resetCache?.();
+    });
+
+    const cached = await runInDurableObject(channelStub(lower), async (instance: unknown) => {
+      const doi = instance as { __peekState?: () => Promise<unknown> };
+      return doi.__peekState?.();
+    });
+    expect(cached).toBeUndefined();
+  });
+
+  it('broadcast with all-live members does not prune the roster', async () => {
+    // When every member has an OPEN WebSocket, deliver returns > 0 for
+    // each and the `pruned.length > 0` else branch is taken (no prune
+    // delta applied).
+    const chan = '#no-prune';
+    const alice = await connectAndRegister('conn-noprune-alice', 'alice');
+    const bob = await connectAndRegister('conn-noprune-bob', 'bob');
+
+    await channel(chan.toLowerCase()).applyChannelDelta({
+      memberships: [
+        { type: 'add', conn: alice.id, nick: 'alice' },
+        { type: 'add', conn: bob.id, nick: 'bob' },
+      ],
+    });
+
+    await channel(chan.toLowerCase()).broadcast(['PRIVMSG #no-prune :hello']);
+    await alice.client.waitForMessage((l) => l.startsWith('PRIVMSG #no-prune'));
+    await bob.client.waitForMessage((l) => l.startsWith('PRIVMSG #no-prune'));
+
+    // Both members survive — no prune occurred.
+    const snap = await channel(chan.toLowerCase()).getChannelSnapshot();
+    expect(snap?.members.length).toBe(2);
+
+    await alice.client.close();
+    await bob.client.close();
+  });
+
+  it('sweep on a channel with all-live members prunes nobody', async () => {
+    const chan = '#sweep-clean';
+    const alice = await connectAndRegister('conn-sweep-uniq-001', 'sweepop');
+
+    await channel(chan.toLowerCase()).applyChannelDelta({
+      memberships: [{ type: 'add', conn: alice.id, nick: 'alice' }],
+    });
+
+    const pruned = await channel(chan.toLowerCase()).sweep();
+    expect(pruned).toBe(0);
+
+    const snap = await channel(chan.toLowerCase()).getChannelSnapshot();
+    expect(snap?.members.length).toBe(1);
+
+    await alice.client.close();
+  });
+});

package/packages/cf-adapter/tests/config-loader.test.ts

@@ -169,3 +169,52 @@ describe('loadServerConfigFromCfEnv — failure modes', () => {
     }
   });
 });
+
+// ---------------------------------------------------------------------------
+// SASL_ACCOUNTS env parsing — malformed entries are skipped, valid ones kept.
+// ---------------------------------------------------------------------------
+
+describe('loadServerConfigFromCfEnv — SASL_ACCOUNTS parsing', () => {
+  it('skips blank lines within the seed', () => {
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      SASL_ACCOUNTS: 'alice:secret\n\nbob:password\n   \n',
+    });
+    expect(cfg.saslAccounts).toEqual([
+      { username: 'alice', password: 'secret' },
+      { username: 'bob', password: 'password' },
+    ]);
+  });
+
+  it('skips lines with no colon separator', () => {
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      SASL_ACCOUNTS: 'alice:secret\nnocolonhere\nbob:password',
+    });
+    expect(cfg.saslAccounts).toHaveLength(2);
+  });
+
+  it('skips lines where the colon is at position 0 (empty username)', () => {
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      SASL_ACCOUNTS: ':secret\nalice:valid',
+    });
+    expect(cfg.saslAccounts).toEqual([{ username: 'alice', password: 'valid' }]);
+  });
+
+  it('skips lines with an empty password after the colon', () => {
+    const cfg = loadServerConfigFromCfEnv({
+      ...baseEnv(),
+      SASL_ACCOUNTS: 'alice:\nbob:valid',
+    });
+    expect(cfg.saslAccounts).toEqual([{ username: 'bob', password: 'valid' }]);
+  });
+
+  it('passes CREATED_AT verbatim when it overflows Number precision', () => {
+    // A digit string so large that Number() produces Infinity — the
+    // parser must fall back to the raw string rather than emit Infinity.
+    const huge = '9'.repeat(400);
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), CREATED_AT: huge });
+    expect(cfg.createdAt).toBe(huge);
+  });
+});

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-pure.test.ts

@@ -0,0 +1,91 @@
+/**
+ * Pure exported helpers from `connection-do.ts`.
+ *
+ * These functions are independent of Durable Object state, so they are
+ * unit-tested directly without the workerd/miniflare DO harness.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { parseSaslAccountsEnv, wsFrameModeFromTags } from '../src/connection-do';
+
+describe('parseSaslAccountsEnv', () => {
+  it('returns an empty array for undefined input', () => {
+    expect(parseSaslAccountsEnv(undefined)).toEqual([]);
+  });
+
+  it('returns an empty array for an empty string', () => {
+    expect(parseSaslAccountsEnv('')).toEqual([]);
+  });
+
+  it('parses a single well-formed entry', () => {
+    expect(parseSaslAccountsEnv('alice:secret')).toEqual([
+      { username: 'alice', password: 'secret' },
+    ]);
+  });
+
+  it('parses multiple newline-delimited entries', () => {
+    expect(parseSaslAccountsEnv('alice:secret\nbob:pw')).toEqual([
+      { username: 'alice', password: 'secret' },
+      { username: 'bob', password: 'pw' },
+    ]);
+  });
+
+  it('skips blank lines', () => {
+    expect(parseSaslAccountsEnv('alice:secret\n\nbob:pw\n   \n')).toEqual([
+      { username: 'alice', password: 'secret' },
+      { username: 'bob', password: 'pw' },
+    ]);
+  });
+
+  it('skips lines with no colon separator', () => {
+    expect(parseSaslAccountsEnv('alice:secret\nnocolonhere\nbob:pw')).toEqual([
+      { username: 'alice', password: 'secret' },
+      { username: 'bob', password: 'pw' },
+    ]);
+  });
+
+  it('skips lines where the colon is at position 0 (empty username)', () => {
+    expect(parseSaslAccountsEnv(':secret\nalice:valid')).toEqual([
+      { username: 'alice', password: 'valid' },
+    ]);
+  });
+
+  it('skips lines with an empty password after the colon', () => {
+    expect(parseSaslAccountsEnv('alice:\nbob:valid')).toEqual([
+      { username: 'bob', password: 'valid' },
+    ]);
+  });
+
+  it('returns an empty array when every line is malformed', () => {
+    expect(parseSaslAccountsEnv('\n   \n:no-user\nuser:')).toEqual([]);
+  });
+});
+
+describe('wsFrameModeFromTags', () => {
+  it("returns 'legacy' when no tags are present", () => {
+    expect(wsFrameModeFromTags([])).toBe('legacy');
+  });
+
+  it("returns 'legacy' when no recognized tag matches", () => {
+    // Unknown tags (e.g. from an older deployment's tag scheme) fall
+    // back to the legacy-tolerant mode.
+    expect(wsFrameModeFromTags(['unknown:tag', 'another'])).toBe('legacy');
+  });
+
+  it("returns 'spec-text' when the spec-text tag is present", () => {
+    expect(wsFrameModeFromTags(['ws:spec-text'])).toBe('spec-text');
+  });
+
+  it("returns 'spec-binary' when the spec-binary tag is present", () => {
+    expect(wsFrameModeFromTags(['ws:spec-binary'])).toBe('spec-binary');
+  });
+
+  it("returns 'legacy' when the legacy tag is present", () => {
+    expect(wsFrameModeFromTags(['ws:legacy'])).toBe('legacy');
+  });
+
+  it('picks the first recognized tag when multiple are present', () => {
+    // The scan is order-sensitive; the first matching tag wins.
+    expect(wsFrameModeFromTags(['ws:spec-text', 'ws:legacy'])).toBe('spec-text');
+  });
+});