serverless-ircd 0.1.0

package/packages/irc-server/tests/actor.test.ts

@@ -0,0 +1,816 @@
+import {
+  type ChanName,
+  type ChanSnapshot,
+  type ChannelDelta,
+  type ChannelState,
+  type ConnId,
+  type ConnSnapshot,
+  type ConnectionState,
+  EmptyMotdProvider,
+  FakeClock,
+  type Nick,
+  Numerics,
+  type RawLine,
+  SequentialIdFactory,
+  applyChannelDelta as applyDelta,
+  createChannel,
+  createConnection,
+  isChannelTarget,
+  toChannelSnapshot,
+} from '@serverless-ircd/irc-core';
+import { describe, expect, it } from 'vitest';
+import { ConnectionActor } from '../src/actor';
+import type { IrcRuntime } from '../src/runtime';
+
+// ---------------------------------------------------------------------------
+// Fakes
+// ---------------------------------------------------------------------------
+
+interface RecordedCall {
+  method: string;
+  args: unknown[];
+}
+
+class FakeRuntime implements IrcRuntime {
+  readonly calls: RecordedCall[] = [];
+  private readonly channels = new Map<string, ChannelState>();
+  private readonly testConnections = new Map<ConnId, ConnectionState>();
+  private readonly nicks = new Map<string, ConnId>();
+
+  constructor(private readonly clock: { now(): number }) {}
+
+  addConnection(state: ConnectionState): void {
+    this.testConnections.set(state.id, state);
+    if (state.nick !== undefined) {
+      this.nicks.set(state.nick.toLowerCase(), state.id);
+    }
+  }
+
+  // Channel-state access (used by the actor's `channels` dep).
+  getOrCreateChannel(name: ChanName): ChannelState {
+    const key = name.toLowerCase();
+    const existing = this.channels.get(key);
+    if (existing) return existing;
+    const chan = createChannel({ name, nameLower: key, createdAt: this.clock.now() });
+    this.channels.set(key, chan);
+    return chan;
+  }
+
+  async send(to: ConnId, lines: RawLine[]): Promise<void> {
+    this.calls.push({ method: 'send', args: [to, lines] });
+  }
+  async broadcast(chan: ChanName, lines: RawLine[], except?: ConnId): Promise<void> {
+    this.calls.push({ method: 'broadcast', args: [chan, lines, except] });
+  }
+  async disconnect(conn: ConnId, reason?: string): Promise<void> {
+    this.calls.push({ method: 'disconnect', args: [conn, reason] });
+  }
+  async sendToNick(
+    nick: Nick,
+    sender: ConnId,
+    lines: RawLine[],
+    notFoundLines?: RawLine[],
+  ): Promise<void> {
+    this.calls.push({ method: 'sendToNick', args: [nick, sender, lines, notFoundLines] });
+  }
+  async reserveNick(nick: Nick, conn: ConnId): Promise<{ ok: true } | { ok: false }> {
+    this.calls.push({ method: 'reserveNick', args: [nick, conn] });
+    return { ok: true };
+  }
+  async changeNick(conn: ConnId, oldNick: Nick, newNick: Nick): Promise<boolean> {
+    this.calls.push({ method: 'changeNick', args: [conn, oldNick, newNick] });
+    return true;
+  }
+  async releaseNick(nick: Nick): Promise<void> {
+    this.calls.push({ method: 'releaseNick', args: [nick] });
+  }
+  async applyChannelDelta(chan: ChanName, delta: ChannelDelta): Promise<void> {
+    this.calls.push({ method: 'applyChannelDelta', args: [chan, delta] });
+    // Actually mutate the stored channel so subsequent getOrCreateChannel
+    // calls observe the new state. The actor's setup relies on this.
+    const key = chan.toLowerCase();
+    const current = this.channels.get(key);
+    const next = current
+      ? applyDelta(current, delta)
+      : applyDelta(
+          createChannel({ name: chan, nameLower: key, createdAt: this.clock.now() }),
+          delta,
+        );
+    this.channels.set(key, next);
+  }
+  async lookupNick(nick: Nick): Promise<ConnId | null> {
+    this.calls.push({ method: 'lookupNick', args: [nick] });
+    return this.nicks.get(nick.toLowerCase()) ?? null;
+  }
+  async getConnectionInfo(conn: ConnId): Promise<ConnSnapshot | null> {
+    this.calls.push({ method: 'getConnectionInfo', args: [conn] });
+    return null;
+  }
+  async getConnection(conn: ConnId): Promise<ConnectionState | null> {
+    this.calls.push({ method: 'getConnection', args: [conn] });
+    return this.testConnections.get(conn) ?? null;
+  }
+  async getChannelSnapshot(chan: ChanName): Promise<ChanSnapshot | null> {
+    this.calls.push({ method: 'getChannelSnapshot', args: [chan] });
+    const key = chan.toLowerCase();
+    const channel = this.channels.get(key);
+    return channel === undefined ? null : toChannelSnapshot(channel);
+  }
+  async listChannels(): Promise<ChanSnapshot[]> {
+    this.calls.push({ method: 'listChannels', args: [] });
+    return Array.from(this.channels.values(), (c) => toChannelSnapshot(c));
+  }
+
+  async getChannelConnections(chan: ChanName): Promise<ReadonlyMap<ConnId, ConnectionState>> {
+    this.calls.push({ method: 'getChannelConnections', args: [chan] });
+    const key = chan.toLowerCase();
+    const channel = this.channels.get(key);
+    const out = new Map<ConnId, ConnectionState>();
+    if (channel === undefined) return out;
+    for (const connId of channel.members.keys()) {
+      const state = this.testConnections.get(connId);
+      if (state !== undefined) out.set(connId, state);
+    }
+    return out;
+  }
+}
+
+function makeActor(opts: {
+  conn?: Partial<ConnectionState>;
+  clock?: FakeClock;
+}): { actor: ConnectionActor; runtime: FakeRuntime; conn: ConnectionState } {
+  const clock = opts.clock ?? new FakeClock(1_000);
+  const conn = createConnection({ id: 'c1', connectedSince: 0 });
+  conn.nick = 'alice';
+  conn.user = 'alice';
+  conn.host = 'example.com';
+  conn.realname = 'Alice';
+  conn.registration = 'registered';
+  if (opts.conn) Object.assign(conn, opts.conn);
+
+  const runtime = new FakeRuntime(clock);
+  const actor = new ConnectionActor({
+    state: conn,
+    runtime,
+    channels: runtime,
+    serverConfig: {
+      serverName: 'irc.example.com',
+      networkName: 'ExampleNet',
+      maxChannelsPerUser: 30,
+      maxTargetsPerCommand: 10,
+      maxListEntries: 50,
+      nickLen: 30,
+      channelLen: 50,
+      topicLen: 390,
+      quitMessage: 'Client Quit',
+    },
+    clock,
+    ids: new SequentialIdFactory(),
+    motd: EmptyMotdProvider,
+  });
+  return { actor, runtime, conn };
+}
+
+// Lazy import to keep the unused-warning suppression tidy for `isChannelTarget`.
+void isChannelTarget;
+
+describe('ConnectionActor — framing', () => {
+  it('processes one PRIVMSG in a single text frame into one broadcast', async () => {
+    const { actor, runtime } = makeActor({});
+    // Pre-add the connection to the channel so the broadcast excludes the sender.
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('PRIVMSG #foo :hello\r\n');
+
+    const broadcasts = runtime.calls.filter((c) => c.method === 'broadcast');
+    expect(broadcasts).toHaveLength(1);
+    expect(broadcasts[0]?.args[0]).toBe('#foo');
+    expect(broadcasts[0]?.args[2]).toBe('c1'); // except sender
+    const lines = broadcasts[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toBe(':alice!alice@example.com PRIVMSG #foo :hello');
+  });
+
+  it('tolerates a frame without a trailing CRLF', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('PING :tok');
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toBe('PONG :tok');
+  });
+
+  it('splits a joined frame with N CRLF-delimited messages into N invocations in order', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('PING :a\r\nPING :b\r\nPING :c\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(3);
+    expect((sends[0]?.args[1] as RawLine[])[0]?.text).toBe('PONG :a');
+    expect((sends[1]?.args[1] as RawLine[])[0]?.text).toBe('PONG :b');
+    expect((sends[2]?.args[1] as RawLine[])[0]?.text).toBe('PONG :c');
+  });
+
+  it('tolerates bare LF line endings in a joined frame', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('PING :a\nPING :b\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(2);
+  });
+
+  it('ignores empty lines between messages', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('PING :a\r\n\r\nPING :b\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(2);
+  });
+});
+
+describe('ConnectionActor — malformed input', () => {
+  it('emits 421 for an unparseable line and continues processing the rest', async () => {
+    const { actor, runtime } = makeActor({});
+    // First token starts with a digit but is not exactly 3 digits → parser rejects.
+    await actor.receiveTextFrame('12345\r\nPING :tok\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(2);
+    const firstLines = sends[0]?.args[1] as RawLine[];
+    expect(firstLines[0]?.text).toContain(Numerics.ERR_UNKNOWNCOMMAND.toString().padStart(3, '0'));
+    const secondLines = sends[1]?.args[1] as RawLine[];
+    expect(secondLines[0]?.text).toBe('PONG :tok');
+  });
+
+  it('emits 421 for an unknown command and continues', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('BOGUS arg\r\nPING :tok\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    // First send carries the 421, second carries the PONG.
+    expect(sends).toHaveLength(2);
+    const firstLines = sends[0]?.args[1] as RawLine[];
+    expect(firstLines[0]?.text).toContain('421');
+    expect(firstLines[0]?.text).toContain('BOGUS');
+  });
+
+  it('does not crash when the frame is an empty string', async () => {
+    const { actor, runtime } = makeActor({});
+    await expect(actor.receiveTextFrame('')).resolves.toBeUndefined();
+    expect(runtime.calls).toHaveLength(0);
+  });
+
+  it('does not crash when the frame has only whitespace', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('\r\n\r\n');
+    expect(runtime.calls).toHaveLength(0);
+  });
+});
+
+describe('ConnectionActor — routing', () => {
+  it('routes PRIVMSG to a nick through sendToNick', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('PRIVMSG bob :hi\r\n');
+
+    const sendsToNick = runtime.calls.filter((c) => c.method === 'sendToNick');
+    expect(sendsToNick).toHaveLength(1);
+    expect(sendsToNick[0]?.args[0]).toBe('bob');
+  });
+
+  it('routes JOIN to the channel authority (mutates roster + broadcasts)', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('JOIN #foo\r\n');
+
+    // JOIN emits a cap-aware broadcast (extended-join); dispatch routes the
+    // legacy JOIN line per-recipient via send rather than the broadcast
+    // fast path (the connection here lacks the extended-join cap).
+    const joinSends = runtime.calls.filter(
+      (c) =>
+        c.method === 'send' && (c.args[1] as RawLine[]).some((l) => l.text.includes('JOIN #foo')),
+    );
+    expect(joinSends).toHaveLength(1);
+    const lines = joinSends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain('JOIN #foo');
+  });
+
+  it('routes QUIT through disconnect + releaseNick effects', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    conn.nick = 'alice';
+    await actor.receiveTextFrame('QUIT :bye\r\n');
+
+    const methods = runtime.calls.map((c) => c.method);
+    expect(methods).toContain('releaseNick');
+    expect(methods).toContain('disconnect');
+  });
+
+  it('routes NICK through reserveNick effect', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    conn.registration = 'pre-registration';
+    // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes
+    delete conn.nick;
+    await actor.receiveTextFrame('NICK alice\r\n');
+
+    const reserves = runtime.calls.filter((c) => c.method === 'reserveNick');
+    expect(reserves).toHaveLength(1);
+    expect(reserves[0]?.args[0]).toBe('alice');
+  });
+});
+
+describe('ConnectionActor — additional routing', () => {
+  it('routes PART through routeMultiChannel (one channel per invocation)', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    await runtime.applyChannelDelta('#bar', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('PART #foo,#bar :bye\r\n');
+
+    const broadcasts = runtime.calls.filter((c) => c.method === 'broadcast');
+    expect(broadcasts).toHaveLength(2);
+  });
+
+  it('routes TOPIC through routeSingleChannel', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice', op: true }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('TOPIC #foo :hello topic\r\n');
+    // The TOPIC reducer emits either a Broadcast (on set) or a Send (on read).
+    const methods = runtime.calls.map((c) => c.method);
+    expect(methods).toContain('broadcast');
+  });
+
+  it('routes NAMES through routeSingleChannel', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('NAMES #foo\r\n');
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThan(0);
+  });
+
+  it('routes KICK through routeSingleChannel', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [
+        { type: 'add', conn: 'c1', nick: 'alice', op: true },
+        { type: 'add', conn: 'c2', nick: 'bob' },
+      ],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('KICK #foo bob :bye\r\n');
+    const broadcasts = runtime.calls.filter((c) => c.method === 'broadcast');
+    expect(broadcasts).toHaveLength(1);
+  });
+
+  it('routes INVITE through routeSingleChannel', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice', op: true }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('INVITE bob #foo\r\n');
+    // INVITE emits a Send (341 to inviter) + SendToNick (the INVITE notice).
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThan(0);
+  });
+
+  it('routes MODE #chan through channelModeReducer', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice', op: true }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('MODE #foo +t\r\n');
+    const broadcasts = runtime.calls.filter((c) => c.method === 'broadcast');
+    expect(broadcasts).toHaveLength(1);
+  });
+
+  it('routes MODE <nick> through userModeReducer (connection authority)', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('MODE alice +i\r\n');
+    // User-mode changes don't broadcast; they echo via Send to the user.
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThan(0);
+  });
+
+  it('routes JOIN 0 to handleJoinZero (parts every channel)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    conn.joinedChannels.add('#foo');
+    conn.joinedChannels.add('#bar');
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('JOIN 0\r\n');
+    const broadcasts = runtime.calls.filter((c) => c.method === 'broadcast');
+    expect(broadcasts).toHaveLength(2);
+    const deltas = runtime.calls.filter((c) => c.method === 'applyChannelDelta');
+    expect(deltas).toHaveLength(2);
+  });
+
+  it('routes JOIN with multiple channels and keys', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('JOIN #a,#b ka,kb\r\n');
+    // Two cap-aware JOIN broadcasts (one per channel); dispatch delivers
+    // each legacy JOIN line per-recipient via send.
+    const joinSends = runtime.calls.filter(
+      (c) => c.method === 'send' && (c.args[1] as RawLine[]).some((l) => l.text.includes('JOIN')),
+    );
+    expect(joinSends).toHaveLength(2);
+  });
+
+  it('routes NOTICE to a channel target', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+    await actor.receiveTextFrame('NOTICE #foo :note\r\n');
+    expect(runtime.calls.filter((c) => c.method === 'broadcast')).toHaveLength(1);
+  });
+
+  it('routes PRIVMSG with mixed targets (#chan,nick) into 2 invocations', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+    await actor.receiveTextFrame('PRIVMSG #foo,bob :hi\r\n');
+    // One broadcast (channel) + one sendToNick (user).
+    expect(runtime.calls.filter((c) => c.method === 'broadcast')).toHaveLength(1);
+    expect(runtime.calls.filter((c) => c.method === 'sendToNick')).toHaveLength(1);
+  });
+
+  it('routes CAP through the connection-authority capReducer', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('CAP LS\r\n');
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThan(0);
+  });
+
+  it('routes MOTD through motdReducer (empty MOTD → 422)', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('MOTD\r\n');
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain('422');
+  });
+
+  it('routes USER post-registration to a 462 error Send', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('USER alice 0 * :Alice\r\n');
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain('462');
+  });
+
+  it('routes PASS to passReducer (stashes the attempt)', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('PASS sekrat\r\n');
+    // passReducer on an already-registered conn emits a 462 Send.
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+  });
+
+  it('routes PONG to pongReducer (no effects, lastSeen refreshed)', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('PONG :tok\r\n');
+    expect(runtime.calls).toHaveLength(0);
+  });
+
+  it('emits 421 with no command token for an entirely non-token parse failure', async () => {
+    const { actor, runtime } = makeActor({});
+    // Parser throws "missing command" when the line is just `@tags`. The
+    // first-token extractor returns the whole `@foo=bar` run; we just
+    // assert the 421 numeric was emitted.
+    await actor.receiveTextFrame('@foo=bar\r\n');
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const line = (sends[0]?.args[1] as RawLine[])[0]?.text ?? '';
+    expect(line).toContain('421');
+  });
+
+  it('emits 421 for PART with no channel argument', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('PART\r\n');
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+  });
+
+  it('routes WHOIS of a registered user through whoisReducer (311 + 318, never 421)', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    // Register a second connection `bob` so lookupNick + getConnection resolve.
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.user = 'bob';
+    bobState.host = 'example.com';
+    bobState.realname = 'Bob';
+    bobState.registration = 'registered';
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WHOIS bob\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    // whoisReducer emits the 311/312/317 batch, then the 318 end marker.
+    expect(sends.length).toBeGreaterThanOrEqual(2);
+    const firstBatch = sends[0]?.args[1] as RawLine[];
+    expect(firstBatch[0]?.text).toContain(' 311 ');
+    expect(firstBatch[0]?.text).toContain(' bob ');
+    const endBatch = sends[sends.length - 1]?.args[1] as RawLine[];
+    expect(endBatch[0]?.text).toContain(' 318 ');
+    // Critical: never 421 for WHOIS.
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('routes WHOIS of an unknown nick to 401 then 318 (never 421)', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WHOIS ghost\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(2);
+    const notFound = sends[0]?.args[1] as RawLine[];
+    expect(notFound[0]?.text).toContain(' 401 ');
+    expect(notFound[0]?.text).toContain(' ghost ');
+    const end = sends[1]?.args[1] as RawLine[];
+    expect(end[0]?.text).toContain(' 318 ');
+    for (const s of sends) {
+      for (const line of s.args[1] as RawLine[]) {
+        expect(line.text).not.toContain(' 421 ');
+      }
+    }
+  });
+
+  it('emits 421 with empty command when routeSingleChannel gets no channel (TOPIC)', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('TOPIC\r\n');
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain('421');
+    expect(lines[0]?.text).toContain('TOPIC');
+  });
+
+  it('emits 421 with no command token when the line starts with whitespace', async () => {
+    const { actor, runtime } = makeActor({});
+    // Leading space: firstToken(' foo') returns '' (the `^\S+` match fails),
+    // exercising the empty-command branch of `unknownCommandEffect`.
+    await actor.receiveTextFrame(' foo\r\n');
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toBe(':irc.example.com 421 alice :Unknown command');
+  });
+
+  it('covers JOIN with no params (splitCsv("") → [])', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('JOIN\r\n');
+    // joinReducer with no channel emits a 461 ERR_NEEDMOREPARAMS via Send.
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThan(0);
+  });
+
+  it('covers PRIVMSG with no params (splitCsv("") → [])', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('PRIVMSG\r\n');
+    // privmsgUserReducer with no recipient emits a 411 ERR_NORECIPIENT Send.
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThan(0);
+  });
+
+  it('uses "*" as the nick in 421 when the connection has no nick yet', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes
+    delete conn.nick;
+    await actor.receiveTextFrame('BOGUS\r\n');
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain('421 * BOGUS');
+  });
+
+  it('covers MODE with no params (routes to user-mode reducer)', async () => {
+    const { actor, runtime } = makeActor({});
+    await actor.receiveTextFrame('MODE\r\n');
+    // userModeReducer with no params emits a Send (numeric error or empty mode).
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends.length).toBeGreaterThan(0);
+  });
+
+  it('uses the EmptyMotdProvider default when no motd is supplied', async () => {
+    const clock = new FakeClock(1_000);
+    const conn = createConnection({ id: 'c1', connectedSince: 0 });
+    conn.nick = 'alice';
+    conn.user = 'alice';
+    conn.host = 'example.com';
+    conn.realname = 'Alice';
+    conn.registration = 'registered';
+    const runtime = new FakeRuntime(clock);
+    // No `motd` option → defaults to EmptyMotdProvider.
+    const actor = new ConnectionActor({
+      state: conn,
+      runtime,
+      channels: runtime,
+      serverConfig: {
+        serverName: 'irc.example.com',
+        networkName: 'ExampleNet',
+        maxChannelsPerUser: 30,
+        maxTargetsPerCommand: 10,
+        maxListEntries: 50,
+        nickLen: 30,
+        channelLen: 50,
+        topicLen: 390,
+        quitMessage: 'Client Quit',
+      },
+      clock,
+      ids: new SequentialIdFactory(),
+    });
+    await actor.receiveTextFrame('MOTD\r\n');
+    // Empty MOTD → 422 ERR_NOMOTD via Send.
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toContain('422');
+  });
+});
+
+describe('ConnectionActor — LIST', () => {
+  it('LIST with no args emits 321, one 322 per visible channel, then 323', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c2', nick: 'bob' }],
+    });
+    await runtime.applyChannelDelta('#bar', {
+      memberships: [{ type: 'add', conn: 'c3', nick: 'carol' }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('LIST\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(3);
+    const startLines = sends[0]?.args[1] as RawLine[];
+    expect(startLines[0]?.text).toBe(':irc.example.com 321 alice Channel :Users  Name');
+    const listLines = sends[1]?.args[1] as RawLine[];
+    expect(listLines).toHaveLength(2);
+    expect(listLines[0]?.text).toBe(':irc.example.com 322 alice #foo 1 :');
+    expect(listLines[1]?.text).toBe(':irc.example.com 322 alice #bar 1 :');
+    const endLines = sends[2]?.args[1] as RawLine[];
+    expect(endLines[0]?.text).toBe(':irc.example.com 323 alice :End of /LIST');
+  });
+
+  it('LIST <chan> narrows to the requested channel', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c2', nick: 'bob' }],
+    });
+    await runtime.applyChannelDelta('#bar', {
+      memberships: [{ type: 'add', conn: 'c3', nick: 'carol' }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('LIST #foo\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(3);
+    const listLines = sends[1]?.args[1] as RawLine[];
+    expect(listLines).toHaveLength(1);
+    expect(listLines[0]?.text).toBe(':irc.example.com 322 alice #foo 1 :');
+  });
+
+  it('LIST for a non-existent channel emits 321 then 323 with no 322', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c2', nick: 'bob' }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('LIST #nope\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(2);
+    const startLines = sends[0]?.args[1] as RawLine[];
+    expect(startLines[0]?.text).toBe(':irc.example.com 321 alice Channel :Users  Name');
+    const endLines = sends[1]?.args[1] as RawLine[];
+    expect(endLines[0]?.text).toBe(':irc.example.com 323 alice :End of /LIST');
+  });
+
+  it('LIST hides secret channels from non-members', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c2', nick: 'bob' }],
+    });
+    await runtime.applyChannelDelta('#secret', {
+      memberships: [{ type: 'add', conn: 'c3', nick: 'carol' }],
+      modeChanges: [{ mode: 'secret', set: true }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('LIST\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    const listLines = sends[1]?.args[1] as RawLine[];
+    expect(listLines).toHaveLength(1);
+    expect(listLines[0]?.text).toBe(':irc.example.com 322 alice #foo 1 :');
+  });
+});
+
+describe('ConnectionActor — WHO', () => {
+  it('WHO with no args emits only 315 End of /WHO', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WHO\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines).toHaveLength(1);
+    expect(lines[0]?.text).toBe(':irc.example.com 315 alice :End of /WHO list');
+  });
+
+  it('WHO #chan with no connections emits only 315', async () => {
+    const { actor, runtime } = makeActor({});
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'alice' }],
+    });
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WHO #foo\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines).toHaveLength(1);
+    expect(lines[0]?.text).toBe(':irc.example.com 315 alice #foo :End of /WHO list');
+  });
+
+  it('WHO #chan with members emits one 352 per member then 315', async () => {
+    const { actor, runtime, conn } = makeActor({});
+    const bobState = createConnection({ id: 'c2', connectedSince: 0 });
+    bobState.nick = 'bob';
+    bobState.user = 'bob';
+    bobState.host = 'example.com';
+    bobState.realname = 'Bob';
+    bobState.registration = 'registered';
+
+    await runtime.applyChannelDelta('#foo', {
+      memberships: [
+        { type: 'add', conn: 'c1', nick: 'alice' },
+        { type: 'add', conn: 'c2', nick: 'bob' },
+      ],
+    });
+    runtime.addConnection(conn);
+    runtime.addConnection(bobState);
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WHO #foo\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(2);
+    const replyLines = sends[0]?.args[1] as RawLine[];
+    expect(replyLines).toHaveLength(2);
+    expect(replyLines[0]?.text).toBe(
+      ':irc.example.com 352 alice #foo alice example.com irc.example.com alice H :0 Alice',
+    );
+    expect(replyLines[1]?.text).toBe(
+      ':irc.example.com 352 alice #foo bob example.com irc.example.com bob H :0 Bob',
+    );
+    const endLines = sends[1]?.args[1] as RawLine[];
+    expect(endLines[0]?.text).toBe(':irc.example.com 315 alice #foo :End of /WHO list');
+  });
+
+  it('WHO on an invalid channel name emits 403 ERR_NOSUCHCHANNEL', async () => {
+    const { actor, runtime } = makeActor({});
+    runtime.calls.length = 0;
+
+    await actor.receiveTextFrame('WHO badname\r\n');
+
+    const sends = runtime.calls.filter((c) => c.method === 'send');
+    expect(sends).toHaveLength(1);
+    const lines = sends[0]?.args[1] as RawLine[];
+    expect(lines[0]?.text).toBe(':irc.example.com 403 alice badname :No such channel');
+  });
+});