serverless-ircd 0.1.0

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

@@ -0,0 +1,512 @@
+import { Effect } from '@serverless-ircd/irc-core';
+import type { ChannelDelta, ConnId, RawLine } from '@serverless-ircd/irc-core';
+import { describe, expect, it } from 'vitest';
+import { dispatch } from '../src/dispatch';
+import type { IrcRuntime } from '../src/runtime';
+
+interface RecordedCall {
+  method: string;
+  args: unknown[];
+}
+
+function fakeRuntime(calls: RecordedCall[]): IrcRuntime {
+  return {
+    async send(to, lines) {
+      calls.push({ method: 'send', args: [to, lines] });
+    },
+    async broadcast(chan, lines, except) {
+      calls.push({ method: 'broadcast', args: [chan, lines, except] });
+    },
+    async disconnect(conn, reason) {
+      calls.push({ method: 'disconnect', args: [conn, reason] });
+    },
+    async sendToNick(nick, sender, lines, notFoundLines) {
+      calls.push({ method: 'sendToNick', args: [nick, sender, lines, notFoundLines] });
+    },
+    async reserveNick(nick, conn) {
+      calls.push({ method: 'reserveNick', args: [nick, conn] });
+      return { ok: true };
+    },
+    async changeNick(conn, oldNick, newNick) {
+      calls.push({ method: 'changeNick', args: [conn, oldNick, newNick] });
+      return true;
+    },
+    async releaseNick(nick) {
+      calls.push({ method: 'releaseNick', args: [nick] });
+    },
+    async applyChannelDelta(chan, delta) {
+      calls.push({ method: 'applyChannelDelta', args: [chan, delta] });
+    },
+    async lookupNick(nick) {
+      calls.push({ method: 'lookupNick', args: [nick] });
+      return null;
+    },
+    async getConnectionInfo(conn) {
+      calls.push({ method: 'getConnectionInfo', args: [conn] });
+      return null;
+    },
+    async getConnection(conn) {
+      calls.push({ method: 'getConnection', args: [conn] });
+      return null;
+    },
+    async getChannelSnapshot(chan) {
+      calls.push({ method: 'getChannelSnapshot', args: [chan] });
+      return null;
+    },
+    async getChannelConnections() {
+      return new Map();
+    },
+    async listChannels() {
+      return [];
+    },
+  };
+}
+
+const L = (text: string): RawLine => ({ text });
+
+describe('dispatch', () => {
+  it('processes a mixed sequence of effects in order', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch(
+      [
+        Effect.send('c1', [L('PONG :tok')]),
+        Effect.broadcast('#foo', [L('hi')], 'c1'),
+        Effect.disconnect('c2', 'excess flood'),
+      ],
+      fakeRuntime(calls),
+    );
+    expect(calls).toEqual<RecordedCall[]>([
+      { method: 'send', args: ['c1', [{ text: 'PONG :tok' }]] },
+      { method: 'broadcast', args: ['#foo', [{ text: 'hi' }], 'c1'] },
+      { method: 'disconnect', args: ['c2', 'excess flood'] },
+    ]);
+  });
+
+  it('returns synchronously when the effect list is empty', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch([], fakeRuntime(calls));
+    expect(calls).toEqual([]);
+  });
+
+  it('routes Send with no lines verbatim to the runtime', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch([Effect.send('c1', [])], fakeRuntime(calls));
+    expect(calls).toEqual([{ method: 'send', args: ['c1', []] }]);
+  });
+
+  it('routes Broadcast without except (undefined is preserved)', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch([Effect.broadcast('#x', [L('m')])], fakeRuntime(calls));
+    expect(calls[0]).toEqual({ method: 'broadcast', args: ['#x', [{ text: 'm' }], undefined] });
+  });
+
+  it('routes Disconnect without reason (undefined is preserved)', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch([Effect.disconnect('c1')], fakeRuntime(calls));
+    expect(calls[0]).toEqual({ method: 'disconnect', args: ['c1', undefined] });
+  });
+
+  it('routes SendToNick with all four arguments in order', async () => {
+    const calls: RecordedCall[] = [];
+    const notFound = [L('401')];
+    await dispatch([Effect.sendToNick('bob', 'c1', [L('hi')], notFound)], fakeRuntime(calls));
+    expect(calls[0]).toEqual({
+      method: 'sendToNick',
+      args: ['bob', 'c1', [{ text: 'hi' }], notFound],
+    });
+  });
+
+  it('routes SendToNick preserving undefined notFoundLines', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch([Effect.sendToNick('bob', 'c1', [L('hi')])], fakeRuntime(calls));
+    expect(calls[0]).toEqual({
+      method: 'sendToNick',
+      args: ['bob', 'c1', [{ text: 'hi' }], undefined],
+    });
+  });
+
+  it('calls reserveNick, changeNick, releaseNick in order', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch(
+      [
+        Effect.reserveNick('alice', 'c1'),
+        Effect.changeNick('c1', 'alice', 'bob'),
+        Effect.releaseNick('alice'),
+      ],
+      fakeRuntime(calls),
+    );
+    expect(calls.map((c) => c.method)).toEqual(['reserveNick', 'changeNick', 'releaseNick']);
+  });
+
+  it('calls applyChannelDelta with the supplied delta', async () => {
+    const calls: RecordedCall[] = [];
+    const delta: ChannelDelta = { memberships: [{ type: 'remove', conn: 'c1' }] };
+    await dispatch([Effect.applyChannelDelta('#foo', delta)], fakeRuntime(calls));
+    expect(calls[0]).toEqual({ method: 'applyChannelDelta', args: ['#foo', delta] });
+  });
+
+  it('invokes lookupNick, getConnectionInfo, getChannelSnapshot lookups', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch(
+      [
+        Effect.lookupNick('alice'),
+        Effect.getConnectionInfo('c1'),
+        Effect.getChannelSnapshot('#foo'),
+      ],
+      fakeRuntime(calls),
+    );
+    expect(calls.map((c) => c.method)).toEqual([
+      'lookupNick',
+      'getConnectionInfo',
+      'getChannelSnapshot',
+    ]);
+  });
+
+  it('awaits each effect in sequence (one fails, the rest after it do not run)', async () => {
+    const calls: RecordedCall[] = [];
+    const failing: IrcRuntime = {
+      ...fakeRuntime(calls),
+      async send() {
+        calls.push({ method: 'send', args: [] });
+        throw new Error('boom');
+      },
+    };
+    await expect(
+      dispatch([Effect.send('c1', []), Effect.disconnect('c1')], failing),
+    ).rejects.toThrow('boom');
+    expect(calls.map((c) => c.method)).toEqual(['send']);
+  });
+
+  it('deduplicates consecutive identical Send effects to the same target', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch(
+      [Effect.send('c1', [L('hi')]), Effect.send('c1', [L('hi')])],
+      fakeRuntime(calls),
+    );
+    expect(calls).toHaveLength(1);
+    expect(calls[0]).toEqual({ method: 'send', args: ['c1', [{ text: 'hi' }]] });
+  });
+
+  it('does not deduplicate Sends with different targets or different content', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch(
+      [Effect.send('c1', [L('hi')]), Effect.send('c2', [L('hi')]), Effect.send('c1', [L('bye')])],
+      fakeRuntime(calls),
+    );
+    expect(calls).toHaveLength(3);
+  });
+
+  it('does not deduplicate Sends to the same target with different line counts', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch(
+      [Effect.send('c1', [L('hi')]), Effect.send('c1', [L('hi'), L('bye')])],
+      fakeRuntime(calls),
+    );
+    expect(calls).toHaveLength(2);
+  });
+
+  it('does not deduplicate Sends with same line count but different text', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch(
+      [Effect.send('c1', [L('hi')]), Effect.send('c1', [L('bye')])],
+      fakeRuntime(calls),
+    );
+    expect(calls).toHaveLength(2);
+  });
+
+  it('does not deduplicate non-Send effects even if identical', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch(
+      [Effect.disconnect('c1', 'x'), Effect.disconnect('c1', 'x')],
+      fakeRuntime(calls),
+    );
+    expect(calls).toHaveLength(2);
+    expect(calls.map((c) => c.method)).toEqual(['disconnect', 'disconnect']);
+  });
+});
+
+// ============================================================================
+// Broadcast cap filtering (cap / capLines)
+//
+// IRCv3 capabilities like `extended-join` and `chghost` need per-recipient
+// delivery: which line a peer sees depends on the caps THEY negotiated. The
+// reducer annotates the Broadcast effect with `cap` (and optionally
+// `capLines`); dispatch resolves each member's caps via `getConnectionInfo`
+// and routes per-recipient with `send`.
+//
+//   - cap unset                          → lines to everyone (fast path).
+//   - cap set, capLines set (split)      → capLines to cap-enabled peers,
+//                                           lines to everyone else.
+//   - cap set, capLines unset (cap-only) → lines ONLY to cap-enabled peers.
+// ============================================================================
+
+interface MemberInfo {
+  caps: ReadonlySet<string>;
+}
+
+/**
+ * Builds a fake runtime whose `getChannelSnapshot` returns the given roster
+ * and whose `getConnectionInfo` returns each member's caps. Records `send`
+ * and `broadcast` calls so tests can assert per-recipient delivery.
+ */
+function capAwareRuntime(members: ReadonlyMap<ConnId, MemberInfo>): {
+  runtime: IrcRuntime;
+  sends: { to: ConnId; lines: RawLine[] }[];
+  broadcasts: { chan: string; lines: RawLine[]; except?: ConnId | undefined }[];
+} {
+  const sends: { to: ConnId; lines: RawLine[] }[] = [];
+  const broadcasts: { chan: string; lines: RawLine[]; except?: ConnId | undefined }[] = [];
+  const runtime: IrcRuntime = {
+    async send(to, lines) {
+      sends.push({ to, lines });
+    },
+    async broadcast(chan, lines, except) {
+      broadcasts.push({ chan, lines, except });
+    },
+    async disconnect() {},
+    async sendToNick() {},
+    async reserveNick() {
+      return { ok: true };
+    },
+    async changeNick() {
+      return true;
+    },
+    async releaseNick() {},
+    async applyChannelDelta() {},
+    async lookupNick() {
+      return null;
+    },
+    async getConnectionInfo(conn) {
+      const info = members.get(conn);
+      if (info === undefined) return null;
+      return {
+        id: conn,
+        registration: 'registered',
+        caps: info.caps,
+        joinedChannels: new Set<string>(),
+        userModes: { invisible: false, oper: false, wallops: false, serverNotices: false },
+        lastSeen: 0,
+        connectedSince: 0,
+      };
+    },
+    async getConnection() {
+      return null;
+    },
+    async getChannelSnapshot(chan) {
+      const roster = new Map();
+      for (const connId of members.keys()) {
+        roster.set(connId, { conn: connId, nick: connId, op: false, voice: false });
+      }
+      return {
+        name: chan,
+        nameLower: chan.toLowerCase(),
+        modes: {
+          inviteOnly: false,
+          topicLock: false,
+          noExternal: false,
+          moderated: false,
+          secret: false,
+          private: false,
+        },
+        banMasks: new Set<string>(),
+        members: roster,
+        pendingInvites: new Set<string>(),
+        createdAt: 0,
+      };
+    },
+    async getChannelConnections() {
+      return new Map();
+    },
+    async listChannels() {
+      return [];
+    },
+  };
+  return { runtime, sends, broadcasts };
+}
+
+function memberMap(entries: ReadonlyArray<[ConnId, MemberInfo]>): ReadonlyMap<ConnId, MemberInfo> {
+  return new Map(entries);
+}
+
+describe('dispatch — Broadcast cap / capLines', () => {
+  it('takes the runtime.broadcast fast path when cap is unset', async () => {
+    const members = memberMap([['c1', { caps: new Set<string>() }]]);
+    const { runtime, sends, broadcasts } = capAwareRuntime(members);
+
+    await dispatch([Effect.broadcast('#foo', [L('hi')])], runtime);
+
+    expect(broadcasts).toEqual([{ chan: '#foo', lines: [L('hi')], except: undefined }]);
+    expect(sends).toHaveLength(0);
+  });
+
+  it('delivers capLines to cap-enabled members and lines to others (split mode)', async () => {
+    const members = memberMap([
+      ['c1', { caps: new Set(['extended-join']) }],
+      ['c2', { caps: new Set<string>() }],
+    ]);
+    const { runtime, sends, broadcasts } = capAwareRuntime(members);
+
+    await dispatch(
+      [
+        Effect.broadcast('#foo', [L(':a JOIN #foo')], undefined, 'extended-join', [
+          L(':a JOIN #foo acct :real'),
+        ]),
+      ],
+      runtime,
+    );
+
+    // No fast-path broadcast call: dispatch routes per-recipient.
+    expect(broadcasts).toHaveLength(0);
+    const toC1 = sends.find((s) => s.to === 'c1');
+    const toC2 = sends.find((s) => s.to === 'c2');
+    expect(toC1?.lines).toEqual([L(':a JOIN #foo acct :real')]); // extended
+    expect(toC2?.lines).toEqual([L(':a JOIN #foo')]); // legacy
+  });
+
+  it('delivers lines ONLY to cap-enabled members when capLines is unset (cap-only mode)', async () => {
+    const members = memberMap([
+      ['c1', { caps: new Set(['chghost']) }],
+      ['c2', { caps: new Set<string>() }],
+    ]);
+    const { runtime, sends } = capAwareRuntime(members);
+
+    await dispatch(
+      [Effect.broadcast('#foo', [L(':a CHGHOST u :h')], undefined, 'chghost')],
+      runtime,
+    );
+
+    expect(sends.map((s) => s.to)).toEqual(['c1']);
+    expect(sends[0]?.lines).toEqual([L(':a CHGHOST u :h')]);
+  });
+
+  it('honors `except` alongside cap filters (excepted member never receives)', async () => {
+    const members = memberMap([
+      ['c1', { caps: new Set(['chghost']) }], // the changing user
+      ['c2', { caps: new Set(['chghost']) }],
+    ]);
+    const { runtime, sends } = capAwareRuntime(members);
+
+    await dispatch([Effect.broadcast('#foo', [L(':a CHGHOST u :h')], 'c1', 'chghost')], runtime);
+
+    expect(sends.map((s) => s.to)).toEqual(['c2']);
+  });
+
+  it('is a no-op when the channel snapshot is null (channel does not exist)', async () => {
+    const sends: { to: ConnId; lines: RawLine[] }[] = [];
+    const runtime: IrcRuntime = {
+      async send(to, lines) {
+        sends.push({ to, lines });
+      },
+      async broadcast() {},
+      async disconnect() {},
+      async sendToNick() {},
+      async reserveNick() {
+        return { ok: true };
+      },
+      async changeNick() {
+        return true;
+      },
+      async releaseNick() {},
+      async applyChannelDelta() {},
+      async lookupNick() {
+        return null;
+      },
+      async getConnectionInfo() {
+        return null;
+      },
+      async getConnection() {
+        return null;
+      },
+      async getChannelSnapshot() {
+        return null;
+      },
+      async getChannelConnections() {
+        return new Map();
+      },
+      async listChannels() {
+        return [];
+      },
+    };
+
+    await dispatch([Effect.broadcast('#nope', [L('x')], undefined, 'chghost')], runtime);
+
+    expect(sends).toHaveLength(0);
+  });
+
+  it('treats a member with unavailable connection info as lacking the cap', async () => {
+    // c2 is on the roster but getConnectionInfo returns null for it (gone).
+    const sends: { to: ConnId; lines: RawLine[] }[] = [];
+    const runtime: IrcRuntime = {
+      async send(to, lines) {
+        sends.push({ to, lines });
+      },
+      async broadcast() {},
+      async disconnect() {},
+      async sendToNick() {},
+      async reserveNick() {
+        return { ok: true };
+      },
+      async changeNick() {
+        return true;
+      },
+      async releaseNick() {},
+      async applyChannelDelta() {},
+      async lookupNick() {
+        return null;
+      },
+      async getConnectionInfo(conn) {
+        if (conn === 'c1') {
+          return {
+            id: 'c1',
+            registration: 'registered',
+            caps: new Set(['chghost']),
+            joinedChannels: new Set<string>(),
+            userModes: { invisible: false, oper: false, wallops: false, serverNotices: false },
+            lastSeen: 0,
+            connectedSince: 0,
+          };
+        }
+        return null; // c2 gone
+      },
+      async getConnection() {
+        return null;
+      },
+      async getChannelSnapshot(chan) {
+        const roster = new Map([
+          ['c1', { conn: 'c1', nick: 'c1', op: false, voice: false }],
+          ['c2', { conn: 'c2', nick: 'c2', op: false, voice: false }],
+        ]);
+        return {
+          name: chan,
+          nameLower: chan.toLowerCase(),
+          modes: {
+            inviteOnly: false,
+            topicLock: false,
+            noExternal: false,
+            moderated: false,
+            secret: false,
+            private: false,
+          },
+          banMasks: new Set<string>(),
+          members: roster,
+          pendingInvites: new Set<string>(),
+          createdAt: 0,
+        };
+      },
+      async getChannelConnections() {
+        return new Map();
+      },
+      async listChannels() {
+        return [];
+      },
+    };
+
+    await dispatch(
+      [Effect.broadcast('#foo', [L(':a CHGHOST u :h')], undefined, 'chghost')],
+      runtime,
+    );
+
+    // c2 gone → no caps → skipped by the cap-only filter.
+    expect(sends.map((s) => s.to)).toEqual(['c1']);
+  });
+});

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

@@ -0,0 +1,52 @@
+import { describe, expect, it } from 'vitest';
+import type { IrcRuntime } from '../src/runtime';
+
+describe('IrcRuntime contract', () => {
+  it('is satisfied by a minimal object implementing every method', () => {
+    const runtime: IrcRuntime = {
+      async send() {},
+      async broadcast() {},
+      async disconnect() {},
+      async sendToNick() {},
+      async reserveNick() {
+        return { ok: true };
+      },
+      async changeNick() {
+        return true;
+      },
+      async releaseNick() {},
+      async applyChannelDelta() {},
+      async lookupNick() {
+        return null;
+      },
+      async getConnectionInfo() {
+        return null;
+      },
+      async getConnection() {
+        return null;
+      },
+      async getChannelSnapshot() {
+        return null;
+      },
+      async getChannelConnections() {
+        return new Map();
+      },
+      async listChannels() {
+        return [];
+      },
+    };
+    expect(runtime).toBeDefined();
+    expect(typeof runtime.send).toBe('function');
+    expect(typeof runtime.broadcast).toBe('function');
+    expect(typeof runtime.disconnect).toBe('function');
+    expect(typeof runtime.sendToNick).toBe('function');
+    expect(typeof runtime.reserveNick).toBe('function');
+    expect(typeof runtime.changeNick).toBe('function');
+    expect(typeof runtime.releaseNick).toBe('function');
+    expect(typeof runtime.applyChannelDelta).toBe('function');
+    expect(typeof runtime.lookupNick).toBe('function');
+    expect(typeof runtime.getConnectionInfo).toBe('function');
+    expect(typeof runtime.getConnection).toBe('function');
+    expect(typeof runtime.getChannelSnapshot).toBe('function');
+  });
+});

package/packages/irc-server/tsconfig.build.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "tsBuildInfoFile": "./.tsbuildinfo",
+    "types": []
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "tests", "**/*.test.ts"],
+  "references": [{ "path": "../irc-core/tsconfig.build.json" }]
+}

package/packages/irc-server/tsconfig.test.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": [],
+    "composite": false
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"],
+  "exclude": ["dist"],
+  "references": [{ "path": "../irc-core/tsconfig.build.json" }]
+}

package/packages/irc-server/vitest.config.ts

@@ -0,0 +1,21 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/**/*.test.ts'],
+    coverage: {
+      provider: 'v8',
+      all: false,
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/index.ts'],
+      reporter: ['text', 'html', 'json-summary'],
+      thresholds: {
+        lines: 100,
+        functions: 100,
+        branches: 100,
+        statements: 100,
+      },
+    },
+  },
+});

package/pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+packages:
+  - "packages/*"
+  - "apps/*"
+  - "tools/*"

package/tools/tcp-ws-forwarder/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@serverless-ircd/tcp-ws-forwarder",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Local TCP to ws/wss forwarder so standard IRC clients can reach the WebSocket-only ServerlessIRCd transport",
+  "license": "BSD-3-Clause",
+  "type": "module",
+  "main": "./dist/forwarder.js",
+  "bin": {
+    "tcp-ws-forwarder": "./dist/main.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.test.json --noEmit",
+    "start": "node --enable-source-maps ./dist/main.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "clean": "rimraf dist coverage .tsbuildinfo .turbo"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.1",
+    "@types/ws": "^8.5.13",
+    "@vitest/coverage-v8": "^4.1.0",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.0"
+  }
+}