serverless-ircd 0.1.0

package/apps/local-cli/tests/e2e.test.ts

@@ -0,0 +1,346 @@
+import { EventEmitter } from 'node:events';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { WebSocket } from 'ws';
+import { type LocalServer, startLocalServer } from '../src/server';
+
+/**
+ * Minimal IRC-over-WS test client. Sends one IRC message per WS text frame
+ * (the simplest frame-per-message convention from PLAN §9) and parses
+ * incoming frames into IRC lines.
+ */
+class TestClient extends EventEmitter {
+  readonly ws: WebSocket;
+  readonly received: string[] = [];
+
+  constructor(url: string) {
+    super();
+    this.ws = new WebSocket(url);
+    this.ws.on('message', (data) => {
+      const text = data.toString('utf8');
+      for (const line of text.split(/\r?\n/u)) {
+        if (line.length > 0) {
+          this.received.push(line);
+          this.emit('line', line);
+        }
+      }
+    });
+  }
+
+  /** Resolves once the WS handshake completes. */
+  opened(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.ws.readyState === WebSocket.OPEN) resolve();
+      else {
+        this.ws.once('open', () => resolve());
+        this.ws.once('error', reject);
+      }
+    });
+  }
+
+  send(line: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ws.send(`${line}\r\n`, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  /** Waits until a received line contains `needle` (substring match). */
+  waitFor(predicate: (line: string) => boolean, timeoutMs = 1000): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => {
+        reject(new Error(`timeout waiting for line; received: ${JSON.stringify(this.received)}`));
+      }, timeoutMs);
+      const check = (line: string) => {
+        if (predicate(line)) {
+          clearTimeout(timeout);
+          this.off('line', check);
+          resolve(line);
+        }
+      };
+      // Scan already-received lines first.
+      for (const line of this.received) {
+        if (predicate(line)) {
+          clearTimeout(timeout);
+          resolve(line);
+          return;
+        }
+      }
+      this.on('line', check);
+    });
+  }
+
+  close(): Promise<void> {
+    return new Promise((resolve) => {
+      this.ws.once('close', () => resolve());
+      this.ws.close();
+    });
+  }
+}
+
+describe('local-cli e2e', () => {
+  let server: LocalServer;
+
+  beforeAll(async () => {
+    server = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('boots on the requested port and accepts a WebSocket connection', async () => {
+    expect(server.port).toBeGreaterThan(0);
+    const client = new TestClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.close();
+  });
+
+  it('completes a register → join → privmsg flow end-to-end', async () => {
+    // Two clients: alice joins #foo, bob joins #foo, alice PRIVMSGs the channel.
+    const alice = new TestClient(`ws://127.0.0.1:${server.port}/`);
+    const bob = new TestClient(`ws://127.0.0.1:${server.port}/`);
+    await alice.opened();
+    await bob.opened();
+
+    await alice.send('NICK alice');
+    await alice.send('USER alice 0 * :Alice');
+    await alice.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    await bob.send('NICK bob');
+    await bob.send('USER bob 0 * :Bob');
+    await bob.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    await alice.send('JOIN #e2e');
+    await alice.waitFor((l) => l.includes('JOIN #e2e'));
+    await alice.waitFor((l) => l.startsWith(':irc.example.com 353 '));
+
+    await bob.send('JOIN #e2e');
+    // Bob sees his own JOIN + NAMES.
+    await bob.waitFor((l) => l.includes('JOIN #e2e'));
+
+    await alice.send('PRIVMSG #e2e :hello world');
+    // Bob receives the broadcast (alice's actor excludes alice as sender).
+    await bob.waitFor((l) => l.includes('PRIVMSG #e2e :hello world'));
+
+    await alice.close();
+    await bob.close();
+  });
+
+  it('routes PING → PONG', async () => {
+    const client = new TestClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.send('NICK charlie');
+    await client.send('USER charlie 0 * :Charlie');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    await client.send('PING :tok-12345');
+    await client.waitFor((l) => l === 'PONG :tok-12345');
+
+    await client.close();
+  });
+
+  it('emits 421 for an unknown command', async () => {
+    const client = new TestClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.send('NICK dave');
+    await client.send('USER dave 0 * :Dave');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    await client.send('BOGUSCMD');
+    await client.waitFor((l) => l.includes('421') && l.includes('BOGUSCMD'));
+
+    await client.close();
+  });
+
+  it('handles QUIT cleanly (closes the socket, releases the nick)', async () => {
+    const client = new TestClient(`ws://127.0.0.1:${server.port}/`);
+    await client.opened();
+    await client.send('NICK eve');
+    await client.send('USER eve 0 * :Eve');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    await client.send('QUIT :bye');
+    // The disconnect effect should close the socket.
+    await client.close();
+    // The nick should be released so a new client can claim it.
+    const next = new TestClient(`ws://127.0.0.1:${server.port}/`);
+    await next.opened();
+    await next.send('NICK eve');
+    await next.send('USER eve 0 * :Eve2');
+    await next.waitFor((l) => l.startsWith(':irc.example.com 001 '), 2000);
+    await next.close();
+  });
+});
+
+describe('local-cli error paths', () => {
+  it('rejects startLocalServer when the port is already in use', async () => {
+    const first = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    await expect(startLocalServer({ port: first.port, hostname: '127.0.0.1' })).rejects.toThrow();
+    await first.close();
+  });
+
+  it('logs and recovers from a per-socket error without crashing the server', async () => {
+    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
+    await client.opened();
+    // Synthesize a socket-level error on the SERVER-side ws via the
+    // test-only seam. This exercises the `ws.on('error')` handler that
+    // logs + unregisters the connection.
+    expect(srv.testSockets.size).toBe(1);
+    const serverSideWs = [...srv.testSockets][0];
+    if (serverSideWs === undefined) throw new Error('no server-side socket');
+    const wsErr = new Error('synthetic socket failure');
+    // biome-ignore lint/suspicious/noExplicitAny: ws emit accepts any Error
+    (serverSideWs as any).emit('error', wsErr);
+    // Give the server a tick to process the handler.
+    await new Promise((r) => setImmediate(r));
+    // Server should still serve new connections.
+    const next = new TestClient(`ws://127.0.0.1:${srv.port}/`);
+    await next.opened();
+    await next.close();
+    await client.close();
+    await srv.close();
+  });
+
+  it('delivers configured MOTD lines on explicit MOTD command', async () => {
+    const srv = await startLocalServer({
+      port: 0,
+      hostname: '127.0.0.1',
+      motdLines: ['first line of motd', 'second line of motd'],
+    });
+    const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
+    await client.opened();
+    await client.send('NICK karl');
+    await client.send('USER karl 0 * :Karl');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    // Drain registration burst so the explicit MOTD responses below aren't
+    // confused with the placeholder MOTD emitted at registration.
+    client.received.length = 0;
+    await client.send('MOTD');
+    // Wait for end-of-MOTD so all 372 lines are buffered in `received`.
+    await client.waitFor((l) => l.startsWith(':irc.example.com 376 karl'));
+    const motdBody = client.received.filter((l) => l.startsWith(':irc.example.com 372 karl'));
+    expect(motdBody.some((l) => l.includes('first line of motd'))).toBe(true);
+    expect(motdBody.some((l) => l.includes('second line of motd'))).toBe(true);
+    await client.close();
+    await srv.close();
+  });
+
+  it('defaults hostname to 127.0.0.1 when omitted', async () => {
+    const srv = await startLocalServer({ port: 0 });
+    expect(srv.hostname).toBe('127.0.0.1');
+    // Sanity-check that the server is actually reachable on the default.
+    const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
+    await client.opened();
+    await client.close();
+    await srv.close();
+  });
+
+  it('close() forcibly closes any still-open client sockets', async () => {
+    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
+    await client.opened();
+    // Close the server WITHOUT first closing the client — exercises the
+    //srv.close cleanup loop that iterates live connections.
+    await srv.close();
+    // The client socket should have been closed by the server.
+    expect(client.ws.readyState).not.toBe(1); // not OPEN
+  });
+
+  it('close() is a no-op when no connections are live', async () => {
+    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    await srv.close();
+    // Closing again should not throw (idempotent).
+    await expect(srv.close()).resolves.toBeUndefined();
+  });
+
+  it('logs an actor failure without crashing the server (Error path)', async () => {
+    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    // Force the runtime's `send` to throw a real Error so the actor's
+    // reducer pipeline rejects with an Error instance — exercises
+    // `stringifyErr`'s `instanceof Error` branch and `logError`.
+    const original = srv.runtime.send.bind(srv.runtime);
+    srv.runtime.send = async () => {
+      throw new Error('synthetic send failure');
+    };
+
+    const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
+    await client.opened();
+    await client.send('NICK frank');
+    await client.send('USER frank 0 * :Frank');
+    // PING triggers a Send → synthetic throw → actor catch → logError.
+    await client.send('PING :will-throw');
+    // Give the server a tick to process the rejection.
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Restore and verify the server still serves new connections.
+    srv.runtime.send = original;
+    const next = new TestClient(`ws://127.0.0.1:${srv.port}/`);
+    await next.opened();
+    await next.send('NICK grace');
+    await next.send('USER grace 0 * :Grace');
+    await next.waitFor((l) => l.startsWith(':irc.example.com 001 '), 2000);
+    await next.close();
+    await client.close();
+    await srv.close();
+  });
+
+  it('logs a non-Error throw from the actor pipeline (defensive path)', async () => {
+    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const original = srv.runtime.send.bind(srv.runtime);
+    srv.runtime.send = async () => {
+      // Throw a non-Error value to exercise stringifyErr's else branch.
+      throw 'synthetic non-Error throw';
+    };
+    const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
+    await client.opened();
+    await client.send('NICK frank2');
+    await client.send('USER frank2 0 * :Frank2');
+    await client.send('PING :will-throw-non-error');
+    await new Promise((r) => setTimeout(r, 50));
+    srv.runtime.send = original;
+    await client.close();
+    await srv.close();
+  });
+
+  it('cleans up when a client terminates abruptly (server-side error path)', async () => {
+    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
+    await client.opened();
+    await client.send('NICK ivan');
+    await client.send('USER ivan 0 * :Ivan');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    const connId = await srv.runtime.lookupNick('ivan');
+    expect(connId).not.toBeNull();
+    expect(srv.runtime.hasConnection(connId as string)).toBe(true);
+
+    // Terminate the underlying socket abruptly; the server-side ws sees an
+    // 'error' followed by 'close', and the cleanup handler unregisters the
+    // connection from the runtime. (The nick itself is released by the
+    // QUIT reducer on graceful shutdown; abrupt termination leaks the nick
+    // pending a future gone-connection sweep — 041.)
+    client.ws.terminate();
+    await new Promise((r) => setTimeout(r, 100));
+    expect(srv.runtime.hasConnection(connId as string)).toBe(false);
+    await srv.close();
+  });
+
+  it('delivers an ERROR notice when a reducer supplies a disconnect reason', async () => {
+    const srv = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+    const client = new TestClient(`ws://127.0.0.1:${srv.port}/`);
+    await client.opened();
+    await client.send('NICK heidi');
+    await client.send('USER heidi 0 * :Heidi');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    // Call the runtime's disconnect directly with a reason (simulates a
+    // future flood-control / oper-kill effect). The runtime takes a ConnId;
+    // we resolve it from the nick registry.
+    const connId = await srv.runtime.lookupNick('heidi');
+    expect(connId).not.toBeNull();
+    const waitForErrorNotice = client.waitFor((l) => l.startsWith('ERROR :Closing link:'));
+    await srv.runtime.disconnect(connId as string, 'Excess Flood');
+    await expect(waitForErrorNotice).resolves.toContain('Excess Flood');
+    await client.close();
+    await srv.close();
+  });
+});

package/apps/local-cli/tests/id-factory.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from 'vitest';
+import { DEFAULT_ID_FACTORY } from '../src/server';
+
+describe('DEFAULT_ID_FACTORY', () => {
+  it('batchId returns distinct UUID-shaped strings', () => {
+    const a = DEFAULT_ID_FACTORY.batchId();
+    const b = DEFAULT_ID_FACTORY.batchId();
+    expect(a).not.toBe(b);
+    expect(a).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u);
+  });
+
+  it('nonce returns distinct UUID-shaped strings', () => {
+    const a = DEFAULT_ID_FACTORY.nonce();
+    const b = DEFAULT_ID_FACTORY.nonce();
+    expect(a).not.toBe(b);
+    expect(a).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u);
+  });
+
+  it('sessionId returns distinct UUID-shaped strings', () => {
+    const a = DEFAULT_ID_FACTORY.sessionId();
+    const b = DEFAULT_ID_FACTORY.sessionId();
+    expect(a).not.toBe(b);
+    expect(a).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u);
+  });
+});

package/apps/local-cli/tests/line-scanner.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest';
+import { LineScanner } from '../src/line-scanner';
+
+const enc = (s: string): Buffer => Buffer.from(s, 'utf8');
+
+describe('LineScanner', () => {
+  it('returns an empty array for an empty chunk', () => {
+    const sc = new LineScanner();
+    expect(sc.push(enc(''))).toEqual([]);
+  });
+
+  it('returns nothing until a line terminator arrives', () => {
+    const sc = new LineScanner();
+    expect(sc.push(enc('NICK alice'))).toEqual([]);
+  });
+
+  it('emits one complete CRLF-terminated line', () => {
+    const sc = new LineScanner();
+    expect(sc.push(enc('NICK alice\r\n'))).toEqual(['NICK alice']);
+  });
+
+  it('emits one complete LF-terminated line (bare-newline tolerated)', () => {
+    const sc = new LineScanner();
+    expect(sc.push(enc('NICK alice\n'))).toEqual(['NICK alice']);
+  });
+
+  it('reassembles a line split across two chunks (mid-token)', () => {
+    const sc = new LineScanner();
+    expect(sc.push(enc('PING :split'))).toEqual([]);
+    expect(sc.push(enc('ted\r\n'))).toEqual(['PING :splitted']);
+  });
+
+  it('emits multiple lines delivered in one chunk', () => {
+    const sc = new LineScanner();
+    expect(sc.push(enc('NICK bob\r\nUSER bob 0 * :Bob\r\n'))).toEqual([
+      'NICK bob',
+      'USER bob 0 * :Bob',
+    ]);
+  });
+
+  it('handles a mix of CRLF and bare LF in the same chunk', () => {
+    const sc = new LineScanner();
+    expect(sc.push(enc('NICK carol\r\nUSER carol 0 * :C\n'))).toEqual([
+      'NICK carol',
+      'USER carol 0 * :C',
+    ]);
+  });
+
+  it('preserves a lone CR that is not followed by LF', () => {
+    const sc = new LineScanner();
+    // `CR` mid-text is data; only LF terminates. The CR right before LF is
+    // stripped as the CRLF pair's trailing CR.
+    expect(sc.push(enc('PRIVMSG #x :a\rb\r\n'))).toEqual(['PRIVMSG #x :a\rb']);
+  });
+
+  it('emits an empty line for two consecutive terminators', () => {
+    const sc = new LineScanner();
+    expect(sc.push(enc('foo\r\n\r\n'))).toEqual(['foo', '']);
+  });
+
+  it('decodes a multi-byte UTF-8 sequence split across chunks without corruption', () => {
+    const sc = new LineScanner();
+    // 'snowman' U+2603 encodes as 3 bytes: E2 98 83. Split after byte 1.
+    const whole = enc('PRIVMSG #x :☃\r\n');
+    expect(sc.push(whole.subarray(0, 14))).toEqual([]);
+    expect(sc.push(whole.subarray(14))).toEqual(['PRIVMSG #x :☃']);
+  });
+
+  it('flush returns an unterminated tail and clears the carry', () => {
+    const sc = new LineScanner();
+    sc.push(enc('NICK dave'));
+    expect(sc.flush()).toEqual(['NICK dave']);
+    // Carry cleared: subsequent push starts fresh.
+    expect(sc.push(enc('PING :t\r\n'))).toEqual(['PING :t']);
+  });
+
+  it('flush returns an empty array when nothing is buffered', () => {
+    const sc = new LineScanner();
+    expect(sc.flush()).toEqual([]);
+  });
+});

package/apps/local-cli/tests/motd-file.test.ts

@@ -0,0 +1,71 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { loadMotdFile, parseMotdFileContent } from '../src/motd-file';
+
+describe('parseMotdFileContent', () => {
+  it('returns an empty array for the empty string', () => {
+    expect(parseMotdFileContent('')).toEqual([]);
+  });
+
+  it('parses a single bare-LF-terminated line', () => {
+    expect(parseMotdFileContent('Welcome.\n')).toEqual(['Welcome.']);
+  });
+
+  it('parses multiple LF-separated lines', () => {
+    expect(parseMotdFileContent('first\nsecond\nthird')).toEqual(['first', 'second', 'third']);
+  });
+
+  it('strips a trailing CR from CRLF pairs', () => {
+    expect(parseMotdFileContent('hi\r\nthere\r\n')).toEqual(['hi', 'there']);
+  });
+
+  it('drops a single trailing newline but preserves interior blank lines', () => {
+    expect(parseMotdFileContent('a\n\nb\n')).toEqual(['a', '', 'b']);
+  });
+
+  it('preserves a lone CR that is not followed by LF', () => {
+    expect(parseMotdFileContent('a\rb\r\n')).toEqual(['a\rb']);
+  });
+
+  it('does not synthesize a trailing empty line for content lacking a final newline', () => {
+    expect(parseMotdFileContent('only')).toEqual(['only']);
+  });
+});
+
+describe('loadMotdFile', () => {
+  let dir: string;
+
+  afterEach(() => {
+    if (dir !== undefined) rmSync(dir, { recursive: true, force: true });
+  });
+
+  function setup(): string {
+    dir = mkdtempSync(join(tmpdir(), 'local-cli-motd-'));
+    return dir;
+  }
+
+  it('reads and parses the file at the given path', () => {
+    const d = setup();
+    const path = join(d, 'motd.txt');
+    writeFileSync(path, 'line one\nline two\n');
+
+    expect(loadMotdFile(path)).toEqual(['line one', 'line two']);
+  });
+
+  it('returns an empty array for an empty file', () => {
+    const d = setup();
+    const path = join(d, 'empty.txt');
+    writeFileSync(path, '');
+
+    expect(loadMotdFile(path)).toEqual([]);
+  });
+
+  it('throws a descriptive error when the file does not exist', () => {
+    const d = setup();
+    const path = join(d, 'nope.txt');
+
+    expect(() => loadMotdFile(path)).toThrowError(/motd/i);
+  });
+});