serverless-ircd 0.1.0

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

@@ -0,0 +1,495 @@
+/**
+ * Reusable IRC scenario runner — exported so adapter packages (cf-adapter,
+ * aws-stack) can register their own {@link IrcHarnessFactory} and re-run
+ * the exact same scenario suite under their native runtime.
+ *
+ * Each scenario is written once against the {@link IrcHarness} seam. The
+ * runner takes a list of factories and produces one `describe` block per
+ * factory, mirroring the parametrized matrix called for in PLAN §8
+ * ("Runtime contract: vitest parametrized over IrcRuntime. Same scenarios
+ * pass in-memory + CF + AWS.").
+ */
+
+import { describe, expect, it } from 'vitest';
+import type { IrcHarness, IrcHarnessFactory } from './harness.js';
+
+/**
+ * Runs the full IRC scenario suite against every factory in `factories`.
+ *
+ * Adapter packages call this from their own vitest config:
+ *
+ * ```ts
+ * import { describe } from 'vitest';
+ * import { runIrcScenarios } from './scenarios.js';
+ * import { cfHarnessFactory } from './cf-harness.js';
+ *
+ * runIrcScenarios([cfHarnessFactory]);
+ * ```
+ *
+ * The function defines the `describe`/`it` tree at module load time so
+ * vitest discovers them like any other test file.
+ */
+export function runIrcScenarios(factories: readonly IrcHarnessFactory[]): void {
+  /** Finds the first numeric in an IRC line (`:srv 001 nick ...` → `"001"`). */
+  function numericOf(line: string): string | undefined {
+    const parts = line.split(' ');
+    for (const p of parts) {
+      if (/^\d{3}$/u.test(p)) return p;
+    }
+    return undefined;
+  }
+
+  /**
+   * Synchronization helper: alice (already in #chan) waits until she sees
+   * bob's JOIN broadcast. By the time this resolves, the runtime has also
+   * finished updating the roster and pushing the 353 NAMES list to bob.
+   */
+  type ClientWaitFor = (
+    predicate: (line: string) => boolean,
+    timeoutMs?: number,
+  ) => Promise<string>;
+
+  async function untilAliceSeesBobJoin(
+    alice: { waitForLine: ClientWaitFor },
+    channel: string,
+  ): Promise<void> {
+    await alice.waitForLine((l) => l.includes('JOIN') && l.includes(channel) && l.includes('bob!'));
+  }
+
+  for (const factory of factories) {
+    describe(`IrcRuntime contract — ${factory.name}`, () => {
+      let harness: IrcHarness;
+
+      it('scenario 01: NICK + USER produces the welcome 001..005 + MOTD block', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient();
+        await alice.send('NICK alice');
+        await alice.send('USER alice 0 * :Alice In Wonderland');
+        await alice.waitForNumeric('001');
+        const codes = alice.received.map(numericOf).filter((c): c is string => c !== undefined);
+        expect(codes.slice(0, 4)).toEqual(['001', '002', '003', '004']);
+        expect(codes).toContain('005');
+        expect(codes).toContain('375');
+        expect(codes).toContain('372');
+        expect(codes).toContain('376');
+        await harness.close();
+      });
+
+      it('scenario 02: CAP LS returns the server capability list', async () => {
+        harness = await factory.create();
+        const c = await harness.spawnClient();
+        await c.send('CAP LS');
+        await c.waitForLine((l) => l.includes(' CAP * LS :'));
+        await harness.close();
+      });
+
+      it('scenario 03: CAP REQ for a supported cap is ACKed', async () => {
+        harness = await factory.create();
+        const c = await harness.spawnClient();
+        await c.send('CAP LS');
+        await c.waitForLine((l) => l.includes(' CAP * LS :'));
+        await c.send('CAP REQ :echo-message');
+        await c.waitForLine((l) => l.includes(' CAP * ACK :echo-message'));
+        await harness.close();
+      });
+
+      it('scenario 04: CAP END completes registration when NICK and USER are set', async () => {
+        harness = await factory.create();
+        const c = await harness.spawnClient();
+        await c.send('CAP LS');
+        await c.send('NICK bob');
+        await c.send('USER bob 0 * :Bob');
+        expect(c.received.some((l) => numericOf(l) === '001')).toBe(false);
+        await c.send('CAP END');
+        await c.waitForNumeric('001');
+        await harness.close();
+      });
+
+      it('scenario 05: invalid nick grammar → 432 ERR_ERRONEUSNICKNAME', async () => {
+        harness = await factory.create();
+        const c = await harness.spawnClient();
+        await c.send('NICK 1bad');
+        await c.waitForNumeric('432');
+        await harness.close();
+      });
+
+      it('scenario 06: channel MODE +t (topic-lock) gates topic changes to ops (482)', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        const bob = await harness.spawnClient({ nick: 'bob' });
+        await bob.waitForNumeric('001');
+        await alice.send('JOIN #lock');
+        await alice.waitForNumeric('366');
+        await bob.send('JOIN #lock');
+        await untilAliceSeesBobJoin(alice, '#lock');
+        await alice.send('MODE #lock +t');
+        await alice.waitForLine((l) => l.includes('MODE #lock +t'));
+        await bob.send('TOPIC #lock :bob should not be able to set this');
+        await bob.waitForNumeric('482');
+        await harness.close();
+      });
+
+      it('scenario 07: USER after registration → 462 ERR_ALREADYREGISTRED', async () => {
+        harness = await factory.create();
+        const c = await harness.spawnClient({ nick: 'alice' });
+        await c.waitForNumeric('001');
+        await c.send('USER alice 0 * :Alice');
+        await c.waitForNumeric('462');
+        await harness.close();
+      });
+
+      it('scenario 08: PING <token> → PONG <token>', async () => {
+        harness = await factory.create();
+        const c = await harness.spawnClient({ nick: 'alice' });
+        await c.waitForNumeric('001');
+        await c.send('PING :abc-123');
+        await c.waitForLine((l) => l === 'PONG :abc-123');
+        await harness.close();
+      });
+
+      it('scenario 09: JOIN #chan → self sees JOIN + 353 NAMES + 366 end-of-names', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        await alice.send('JOIN #foo');
+        await alice.waitForLine((l) => l.includes('JOIN #foo'));
+        await alice.waitForNumeric('353');
+        await alice.waitForNumeric('366');
+        const namesLine = alice.received.find((l) => numericOf(l) === '353');
+        expect(namesLine).toBeDefined();
+        expect(namesLine ?? '').toContain('@alice');
+        await harness.close();
+      });
+
+      it('scenario 10: JOIN #a,#b joins both channels', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        await alice.send('JOIN #a,#b');
+        await alice.waitForLine((l) => l.includes('JOIN #a'));
+        await alice.waitForLine((l) => l.includes('JOIN #b'));
+        const endNames = alice.received.filter((l) => numericOf(l) === '366');
+        expect(endNames.length).toBe(2);
+        await harness.close();
+      });
+
+      it('scenario 11: JOIN 0 parts all previously joined channels', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        await alice.send('JOIN #foo,#bar');
+        await alice.waitForLine((l) => l.includes('JOIN #foo'));
+        await alice.waitForLine((l) => l.includes('JOIN #bar'));
+        alice.received.length = 0;
+        await alice.send('JOIN 0');
+        await alice.waitForLine((l) => l.includes('PART'));
+        const parts = alice.received.filter((l) => l.includes('PART'));
+        expect(parts.length).toBe(2);
+        expect(parts.some((l) => l.includes('#foo'))).toBe(true);
+        expect(parts.some((l) => l.includes('#bar'))).toBe(true);
+        await harness.close();
+      });
+
+      it('scenario 12: PART #chan broadcasts PART and removes the user', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        const bob = await harness.spawnClient({ nick: 'bob' });
+        await bob.waitForNumeric('001');
+        await alice.send('JOIN #room');
+        await bob.send('JOIN #room');
+        await untilAliceSeesBobJoin(alice, '#room');
+        await alice.send('PART #room :leaving');
+        await bob.waitForLine((l) => l.includes('PART #room') && l.includes('leaving'));
+        await harness.close();
+      });
+
+      it('scenario 13: channel PRIVMSG broadcasts to other members, not the sender', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        const bob = await harness.spawnClient({ nick: 'bob' });
+        await bob.waitForNumeric('001');
+        await alice.send('JOIN #room');
+        await bob.send('JOIN #room');
+        await untilAliceSeesBobJoin(alice, '#room');
+        alice.received.length = 0;
+        bob.received.length = 0;
+        await alice.send('PRIVMSG #room :hello team');
+        await bob.waitForLine((l) => l.includes('PRIVMSG #room :hello team'));
+        expect(alice.received.some((l) => l.includes('PRIVMSG #room :hello team'))).toBe(false);
+        await harness.close();
+      });
+
+      it('scenario 14: private PRIVMSG to another user is delivered to recipient only', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        const bob = await harness.spawnClient({ nick: 'bob' });
+        await bob.waitForNumeric('001');
+        bob.received.length = 0;
+        await alice.send('PRIVMSG bob :hey');
+        await bob.waitForLine((l) => l.includes('PRIVMSG bob :hey') && l.startsWith(':alice'));
+        await harness.close();
+      });
+
+      it('scenario 15: PRIVMSG to an offline nick → 401 ERR_NOSUCHNICK', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        await alice.send('PRIVMSG ghost :hello?');
+        await alice.waitForNumeric('401');
+        await harness.close();
+      });
+
+      it('scenario 16: TOPIC set then read', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        await alice.send('JOIN #topic');
+        await alice.waitForNumeric('366');
+        alice.received.length = 0;
+        await alice.send('TOPIC #topic :Welcome to the topic');
+        await alice.waitForLine((l) => l.includes('TOPIC #topic'));
+        alice.received.length = 0;
+        await alice.send('TOPIC #topic');
+        await alice.waitForNumeric('332');
+        await alice.waitForNumeric('333');
+        await harness.close();
+      });
+
+      it('scenario 17: NAMES #chan → 353 list + 366 end', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        await alice.send('JOIN #names');
+        await alice.waitForNumeric('366');
+        const bob = await harness.spawnClient({ nick: 'bob' });
+        await bob.waitForNumeric('001');
+        await bob.send('JOIN #names');
+        await untilAliceSeesBobJoin(alice, '#names');
+        alice.received.length = 0;
+        await alice.send('NAMES #names');
+        const namesLine = await alice.waitForNumeric('353');
+        expect(namesLine).toContain('alice');
+        expect(namesLine).toContain('bob');
+        await alice.waitForNumeric('366');
+        await harness.close();
+      });
+
+      it('scenario 18: MOTD on a configured server emits 375 + 372×N + 376', async () => {
+        harness = await factory.create();
+        const c = await harness.spawnClient({ nick: 'alice' });
+        await c.waitForNumeric('001');
+        c.received.length = 0;
+        await c.send('MOTD');
+        await c.waitForNumeric('375');
+        const body = await c.waitForNumeric('372');
+        expect(body).toContain('ServerlessIRCd integration-test harness');
+        await c.waitForNumeric('376');
+        await harness.close();
+      });
+
+      it('scenario 19: channel MODE +t by op is broadcast to the channel', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        const bob = await harness.spawnClient({ nick: 'bob' });
+        await bob.waitForNumeric('001');
+        await alice.send('JOIN #mode');
+        await bob.send('JOIN #mode');
+        await untilAliceSeesBobJoin(alice, '#mode');
+        bob.received.length = 0;
+        await alice.send('MODE #mode +t');
+        await bob.waitForLine((l) => l.includes('MODE #mode +t'));
+        await harness.close();
+      });
+
+      it('scenario 20: user MODE +i echoes back to the user', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        alice.received.length = 0;
+        await alice.send('MODE alice +i');
+        await alice.waitForLine((l) => l.includes('MODE alice +i'));
+        await harness.close();
+      });
+
+      it('scenario 21: KICK by op broadcasts to channel peers and removes the target', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        const bob = await harness.spawnClient({ nick: 'bob' });
+        await bob.waitForNumeric('001');
+        await alice.send('JOIN #kick');
+        await bob.send('JOIN #kick');
+        await untilAliceSeesBobJoin(alice, '#kick');
+        alice.received.length = 0;
+        await alice.send('KICK #kick bob :shape up');
+        await alice.waitForLine((l) => l.includes('KICK #kick bob') && l.includes('shape up'));
+        alice.received.length = 0;
+        await alice.send('NAMES #kick');
+        const namesLine = await alice.waitForNumeric('353');
+        expect(namesLine).toContain('alice');
+        expect(namesLine).not.toContain('bob');
+        await harness.close();
+      });
+
+      it('scenario 22: channel MODE +i (invite-only) rejects a fresh JOIN with 473', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        const bob = await harness.spawnClient({ nick: 'bob' });
+        await bob.waitForNumeric('001');
+        await alice.send('JOIN #inviteonly');
+        await alice.waitForNumeric('366');
+        await alice.send('MODE #inviteonly +i');
+        await alice.waitForLine((l) => l.includes('MODE #inviteonly +i'));
+        await bob.send('JOIN #inviteonly');
+        await bob.waitForNumeric('473');
+        await harness.close();
+      });
+
+      it('scenario 23: QUIT broadcasts to channel peers and releases the nick', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        const bob = await harness.spawnClient({ nick: 'bob' });
+        await bob.waitForNumeric('001');
+        await alice.send('JOIN #quit');
+        await bob.send('JOIN #quit');
+        await untilAliceSeesBobJoin(alice, '#quit');
+        bob.received.length = 0;
+        await alice.send('QUIT :goodbye');
+        await bob.waitForLine((l) => l.includes('QUIT') && l.includes('goodbye'));
+        const aliceAgain = await harness.spawnClient();
+        await aliceAgain.send('NICK alice');
+        await aliceAgain.send('USER alice 0 * :Alice Again');
+        await aliceAgain.waitForNumeric('001');
+        await harness.close();
+      });
+
+      it('scenario 24: second joiner sees the first member in the NAMES list', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        const bob = await harness.spawnClient({ nick: 'bob' });
+        await bob.waitForNumeric('001');
+        bob.received.length = 0;
+        await alice.send('JOIN #shared');
+        await alice.waitForNumeric('366');
+        await bob.send('JOIN #shared');
+        const namesLine = await bob.waitForNumeric('353');
+        expect(namesLine).toContain('alice');
+        expect(namesLine).toContain('bob');
+        await harness.close();
+      });
+
+      it('scenario 25: PRIVMSG by an echo-message client is reflected back to the sender', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient();
+        await alice.send('CAP LS');
+        await alice.waitForLine((l) => l.includes(' CAP * LS :'));
+        await alice.send('CAP REQ :echo-message');
+        await alice.waitForLine((l) => l.includes(' CAP * ACK :echo-message'));
+        await alice.send('NICK alice');
+        await alice.send('USER alice 0 * :Alice');
+        await alice.send('CAP END');
+        await alice.waitForNumeric('001');
+        const bob = await harness.spawnClient({ nick: 'bob' });
+        await bob.waitForNumeric('001');
+        await alice.send('JOIN #echo');
+        await bob.send('JOIN #echo');
+        await untilAliceSeesBobJoin(alice, '#echo');
+        alice.received.length = 0;
+        bob.received.length = 0;
+        await alice.send('PRIVMSG #echo :mirrored');
+        await alice.waitForLine(
+          (l) => l.startsWith(':alice') && l.includes('PRIVMSG #echo :mirrored'),
+        );
+        await bob.waitForLine((l) => l.includes('PRIVMSG #echo :mirrored'));
+        await harness.close();
+      });
+
+      it('scenario 26: NOTICE to a channel never produces a numeric error', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        const bob = await harness.spawnClient({ nick: 'bob' });
+        await bob.waitForNumeric('001');
+        await alice.send('JOIN #notice');
+        await bob.send('JOIN #notice');
+        await untilAliceSeesBobJoin(alice, '#notice');
+        alice.received.length = 0;
+        bob.received.length = 0;
+        await alice.send('NOTICE #notice :quiet note');
+        await bob.waitForLine((l) => l.includes('NOTICE #notice :quiet note'));
+        const numericAfterNotice = alice.received.some((l) => numericOf(l) !== undefined);
+        expect(numericAfterNotice).toBe(false);
+        await harness.close();
+      });
+
+      it('scenario 27: PASS after registration is rejected with 462', async () => {
+        harness = await factory.create();
+        const c = await harness.spawnClient({ nick: 'alice' });
+        await c.waitForNumeric('001');
+        c.received.length = 0;
+        await c.send('PASS hunter2');
+        await c.waitForNumeric('462');
+        await harness.close();
+      });
+
+      it('scenario 28: joined frame with multiple commands processes each in order', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        alice.received.length = 0;
+        await alice.send('PING :a\r\nPING :b\r\nPING :c');
+        await alice.waitForLine((l) => l === 'PONG :c');
+        const pongs = alice.received.filter((l) => l.startsWith('PONG :'));
+        expect(pongs).toEqual(['PONG :a', 'PONG :b', 'PONG :c']);
+        await harness.close();
+      });
+
+      it('scenario 29: unparseable line emits 421 and the actor stays alive', async () => {
+        harness = await factory.create();
+        const c = await harness.spawnClient({ nick: 'alice' });
+        await c.waitForNumeric('001');
+        c.received.length = 0;
+        await c.send('12345');
+        await c.waitForNumeric('421');
+        await c.send('PING :still-alive');
+        await c.waitForLine((l) => l === 'PONG :still-alive');
+        await harness.close();
+      });
+
+      it('scenario 30: channel MODE +o grants op and broadcasts the change', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        const bob = await harness.spawnClient({ nick: 'bob' });
+        await bob.waitForNumeric('001');
+        await alice.send('JOIN #op');
+        await bob.send('JOIN #op');
+        await untilAliceSeesBobJoin(alice, '#op');
+        alice.received.length = 0;
+        bob.received.length = 0;
+        await alice.send('MODE #op +o bob');
+        await bob.waitForLine((l) => l.includes('MODE #op +o bob'));
+        await alice.waitForLine((l) => l.includes('MODE #op +o bob'));
+        await harness.close();
+      });
+
+      it('scenario 31: NICK change post-registration echoes :old NICK new', async () => {
+        harness = await factory.create();
+        const alice = await harness.spawnClient({ nick: 'alice' });
+        await alice.waitForNumeric('001');
+        alice.received.length = 0;
+        await alice.send('NICK alice2');
+        await alice.waitForLine((l) => l.startsWith(':alice!') && l.includes('NICK alice2'));
+        await harness.close();
+      });
+    });
+  }
+}