serverless-ircd 0.4.0 → 0.5.0

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

@@ -18,6 +18,9 @@ function fakeRuntime(calls: RecordedCall[]): IrcRuntime {
     async broadcast(chan, lines, except) {
       calls.push({ method: 'broadcast', args: [chan, lines, except] });
     },
+    async broadcastWallops(lines, except) {
+      calls.push({ method: 'broadcastWallops', args: [lines, except] });
+    },
     async disconnect(conn, reason) {
       calls.push({ method: 'disconnect', args: [conn, reason] });
     },
@@ -60,6 +63,10 @@ function fakeRuntime(calls: RecordedCall[]): IrcRuntime {
     async listChannels() {
       return [];
     },
+    async reloadConfig() {
+      calls.push({ method: 'reloadConfig', args: [] });
+      throw new Error('reloadConfig not configured for this fake');
+    },
   };
 }
 
@@ -126,6 +133,24 @@ describe('dispatch', () => {
     });
   });
 
+  it('routes BroadcastWallops with lines and except', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch([Effect.broadcastWallops([L(':a WALLOPS :hi')], 'c1')], fakeRuntime(calls));
+    expect(calls[0]).toEqual({
+      method: 'broadcastWallops',
+      args: [[{ text: ':a WALLOPS :hi' }], 'c1'],
+    });
+  });
+
+  it('routes BroadcastWallops preserving undefined except', async () => {
+    const calls: RecordedCall[] = [];
+    await dispatch([Effect.broadcastWallops([L(':a WALLOPS :hi')])], fakeRuntime(calls));
+    expect(calls[0]).toEqual({
+      method: 'broadcastWallops',
+      args: [[{ text: ':a WALLOPS :hi' }], undefined],
+    });
+  });
+
   it('calls reserveNick, changeNick, releaseNick in order', async () => {
     const calls: RecordedCall[] = [];
     await dispatch(
@@ -247,6 +272,7 @@ function capAwareRuntime(members: ReadonlyMap<ConnId, MemberInfo>): {
     async broadcast(chan, lines, except) {
       broadcasts.push({ chan, lines, except });
     },
+    async broadcastWallops() {},
     async disconnect() {},
     async sendToNick() {},
     async reserveNick() {
@@ -304,6 +330,9 @@ function capAwareRuntime(members: ReadonlyMap<ConnId, MemberInfo>): {
     async listChannels() {
       return [];
     },
+    async reloadConfig() {
+      throw new Error('reloadConfig not configured for this fake');
+    },
   };
   return { runtime, sends, broadcasts };
 }
@@ -382,6 +411,7 @@ describe('dispatch — Broadcast cap / capLines', () => {
         sends.push({ to, lines });
       },
       async broadcast() {},
+      async broadcastWallops() {},
       async disconnect() {},
       async sendToNick() {},
       async reserveNick() {
@@ -410,6 +440,9 @@ describe('dispatch — Broadcast cap / capLines', () => {
       async listChannels() {
         return [];
       },
+      async reloadConfig() {
+        throw new Error('reloadConfig not configured for this fake');
+      },
     };
 
     await dispatch([Effect.broadcast('#nope', [L('x')], undefined, 'chghost')], runtime);
@@ -425,6 +458,7 @@ describe('dispatch — Broadcast cap / capLines', () => {
         sends.push({ to, lines });
       },
       async broadcast() {},
+      async broadcastWallops() {},
       async disconnect() {},
       async sendToNick() {},
       async reserveNick() {
@@ -483,6 +517,9 @@ describe('dispatch — Broadcast cap / capLines', () => {
       async listChannels() {
         return [];
       },
+      async reloadConfig() {
+        throw new Error('reloadConfig not configured for this fake');
+      },
     };
 
     await dispatch(

package/packages/irc-server/tests/raw-modules.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Ambient declaration so `?raw` imports (Vite's built-in transform that
+ * inlines a file's text at bundle time) typecheck under the strict
+ * `tsconfig.test.json`. Used by source-level regression guards that
+ * assert the actor default-branch triage stays accurate.
+ */
+declare module '*?raw' {
+  const content: string;
+  // eslint-disable-next-line import/no-default-export
+  export default content;
+}

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

@@ -131,6 +131,7 @@ describe('buildRoutedReducers', () => {
         'privmsgChannel',
         'privmsgUser',
         'quit',
+        'setname',
         'tagmsgChannel',
         'tagmsgUser',
         'time',

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

@@ -34,6 +34,10 @@ describe('IrcRuntime contract', () => {
       async listChannels() {
         return [];
       },
+      async reloadConfig() {
+        throw new Error('reloadConfig not configured for this fake');
+      },
+      async broadcastWallops() {},
     };
     expect(runtime).toBeDefined();
     expect(typeof runtime.send).toBe('function');
@@ -48,5 +52,8 @@ describe('IrcRuntime contract', () => {
     expect(typeof runtime.getConnectionInfo).toBe('function');
     expect(typeof runtime.getConnection).toBe('function');
     expect(typeof runtime.getChannelSnapshot).toBe('function');
+    expect(typeof runtime.listChannels).toBe('function');
+    expect(typeof runtime.reloadConfig).toBe('function');
+    expect(typeof runtime.broadcastWallops).toBe('function');
   });
 });

package/packages/irc-test-support/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/irc-test-support",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": true,
   "description": "Shared IRC scenario runner + harness seam used by every adapter's integration suite",
   "license": "BSD-3-Clause",

package/packages/irc-test-support/src/scenarios.ts

@@ -192,7 +192,15 @@ export function runIrcScenarios(factories: readonly IrcHarnessFactory[]): void {
         await alice.waitForLine((l) => l.includes('JOIN #bar'));
         alice.received.length = 0;
         await alice.send('JOIN 0');
-        await alice.waitForLine((l) => l.includes('PART'));
+        // The two PART echoes arrive as separate deliveries (one per
+        // channel, with an ApplyChannelDelta in between). On distributed
+        // runtimes (cf-adapter) they land in distinct WS messages with
+        // cross-DO latency between them, so waiting for the first generic
+        // PART and then snapshotting `received` races the second one.
+        // Wait for each channel's PART explicitly to make the observation
+        // deterministic across in-memory and DO-backed runtimes.
+        await alice.waitForLine((l) => l.includes('PART') && l.includes('#foo'));
+        await alice.waitForLine((l) => l.includes('PART') && l.includes('#bar'));
         const parts = alice.received.filter((l) => l.includes('PART'));
         expect(parts.length).toBe(2);
         expect(parts.some((l) => l.includes('#foo'))).toBe(true);

package/packages/irc-test-support/tests/in-memory-scenarios.test.ts

@@ -1,5 +1,5 @@
 /**
- * Parametrized IRC scenarios — 032 + 057.
+ * Parametrized IRC scenarios.
  *
  * The scenario bodies live in `src/scenarios.ts` (now re-exported as
  * `runIrcScenarios`) so adapter packages can register their own

package/pnpm-workspace.yaml

@@ -1,6 +1,7 @@
 packages:
   - "packages/*"
   - "apps/*"
+  - "tools"
   - "tools/*"
 linkWorkspacePackages: true
 allowBuilds:

package/tools/ci-hardening/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/ci-hardening",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": true,
   "description": "CI hardening helpers: coverage-gate config validator + mutation-testing driver for irc-core",
   "license": "BSD-3-Clause",

package/tools/package.json

@@ -1,4 +1,9 @@
 {
+  "name": "@serverless-ircd/tools",
   "private": true,
-  "type": "module"
+  "type": "module",
+  "dependencies": {
+    "@serverless-ircd/aws-adapter": "workspace:*",
+    "@serverless-ircd/cf-adapter": "workspace:*"
+  }
 }

package/tools/seed-cf-accounts.ts

@@ -33,7 +33,10 @@
 import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { parseArgs } from 'node:util';
-import { CREATE_ACCOUNTS_TABLE_SQL, buildAccountPutStatement } from '@serverless-ircd/cf-adapter';
+import {
+  CREATE_ACCOUNTS_TABLE_SQL,
+  buildAccountPutStatement,
+} from '@serverless-ircd/cf-adapter/accounts';
 
 const { values } = parseArgs({
   options: {

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

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/tcp-ws-forwarder",
-  "version": "0.4.0",
+  "version": "0.5.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",

package/tools/tcp-ws-forwarder/src/forwarder.ts

@@ -11,16 +11,25 @@
  *   IRC client  ──TCP──▶  forwarder  ──WS──▶  ServerlessIRCd endpoint
  *   IRC client  ◀─TCP──  forwarder  ◀─WS──  ServerlessIRCd endpoint
  *
+ * IRCv3 WebSocket subprotocol: every dial offers
+ * `['binary.ircv3.net', 'text.ircv3.net']` so a spec-capable upstream
+ * (e.g. the CF `ConnectionDO`) agrees on one-message-per-frame framing. A
+ * server that supports neither simply leaves the subprotocol unset and the
+ * bridge keeps working with its tolerant line-split framing.
+ *
  * Framing:
  *   • TCP→WS: the TCP byte stream is reassembled into IRC lines with the
  *     byte-accurate {@link LineScanner} (tolerant of CRLF and bare LF per
  *     PLAN §9). Each complete line is sent as one bare WebSocket text frame
  *     — the canonical "one message per frame" convention the server's
- *     `ConnectionActor` expects.
+ *     `ConnectionActor` expects — with any trailing CR-LF stripped by
+ *     {@link toWsMessagePayload} per the IRCv3 spec ("no trailing CR-LF on
+ *     the wire").
  *   • WS→TCP: each inbound WS frame is split on line terminators and every
  *     non-empty line is written back to the TCP socket with a trailing
- *     CRLF, normalizing whatever framing the server used (single message,
- *     `\r\n`-joined, or bare) into canonical IRC wire format.
+ *     CRLF via {@link toTcpWire}, normalizing whatever framing the server
+ *     used (single message, `\r\n`-joined, or bare) into canonical IRC wire
+ *     format.
  *
  * Lifetime: closing either side tears down the whole bridge. The forwarder
  * itself is transport-agnostic and has no `@serverless-ircd/*` dependency.
@@ -31,6 +40,16 @@ import { type RawData, WebSocket } from 'ws';
 import { LineScanner } from './line-scanner.js';
 import { ConsoleLogger, LogLevel, type Logger } from './logger.js';
 
+/**
+ * IRCv3 WebSocket subprotocols the forwarder offers when dialing the upstream
+ * IRCd, in preference order. `binary.ircv3.net` is offered first so a
+ * spec-capable server agrees on binary framing; `text.ircv3.net` is the
+ * fallback. A server that supports neither (e.g. a legacy deployment) leaves
+ * the subprotocol unset and the bridge keeps working with its tolerant
+ * line-split framing.
+ */
+export const FORWARDER_WS_SUBPROTOCOLS = ['binary.ircv3.net', 'text.ircv3.net'] as const;
+
 /** Options accepted by {@link startForwarder}. */
 export interface StartForwarderOptions {
   /** TCP port to listen on. Use 0 for an ephemeral port. */
@@ -157,7 +176,7 @@ function bridgeConnection(
   logger: Logger,
   connId: number,
 ): () => void {
-  const ws = new WebSocket(targetHref);
+  const ws = new WebSocket(targetHref, [...FORWARDER_WS_SUBPROTOCOLS]);
   const outgoing = new LineScanner();
   const pending: string[] = [];
   let wsReady = false;
@@ -167,8 +186,8 @@ function bridgeConnection(
   logger.info('bridge.accepted', { conn: connId, remote });
 
   const sendLine = (line: string): void => {
-    if (wsReady) ws.send(line);
-    else pending.push(line);
+    if (wsReady) ws.send(toWsMessagePayload(line));
+    else pending.push(toWsMessagePayload(line));
   };
 
   tcp.on('data', (chunk: Buffer) => {
@@ -191,9 +210,7 @@ function bridgeConnection(
   ws.on('message', (data: RawData) => {
     const text = toBuffer(data).toString('utf8');
     logger.debug('ws.frame', { conn: connId, frame: text });
-    for (const line of splitFrameLines(text)) {
-      if (line.length > 0) tcp.write(`${line}\r\n`);
-    }
+    for (const chunk of toTcpWire(text)) tcp.write(chunk);
   });
 
   const teardown = (reason: CloseReason): void => {
@@ -241,6 +258,37 @@ export function splitFrameLines(text: string): string[] {
   return text.split(/\r?\n/u);
 }
 
+/**
+ * Translates a TCP IRC line into the WebSocket message payload for the
+ * upstream send direction. Strips a single trailing CR-LF (or bare LF) so
+ * the WS message carries the bare IRC line, per the IRCv3 WebSocket spec
+ * ("no trailing CR-LF on the wire"). Idempotent on already-bare lines
+ * (the {@link LineScanner} output), so callers can apply it unconditionally
+ * without inspecting the line first. Exported so the CRLF-strip contract is
+ * unit-testable in isolation.
+ */
+export function toWsMessagePayload(line: string): string {
+  if (line.endsWith('\r\n')) return line.slice(0, -2);
+  if (line.endsWith('\n')) return line.slice(0, -1);
+  return line;
+}
+
+/**
+ * Translates an inbound WebSocket message payload into the CRLF-terminated
+ * TCP chunk(s) to write back to the IRC client. Each non-empty IRC line is
+ * returned as its own entry ending in CRLF, ready for `socket.write`. A
+ * single trailing CR-LF on the message (defensive against servers that emit
+ * one) is collapsed rather than doubled. Exported so the CRLF-re-append
+ * contract is unit-testable in isolation.
+ */
+export function toTcpWire(text: string): string[] {
+  const out: string[] = [];
+  for (const line of splitFrameLines(text)) {
+    if (line.length > 0) out.push(`${line}\r\n`);
+  }
+  return out;
+}
+
 /**
  * Normalizes a `ws` `RawData` payload into a single UTF-8 `Buffer`. Exported
  * so the `ArrayBuffer` / `Uint8Array` / `Buffer[]` variants — which ws only

package/tools/tcp-ws-forwarder/tests/forwarder.test.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events';
-import http from 'node:http';
+import http, { type IncomingHttpHeaders } from 'node:http';
 import { type Socket, createConnection, createServer as createNetServer } from 'node:net';
 import type { AddressInfo } from 'node:net';
 import { afterEach, describe, expect, it, vi } from 'vitest';
@@ -51,6 +51,12 @@ interface Target {
   readonly frames: string[];
   readonly connections: WebSocket[];
   waitForConnection(): Promise<WebSocket>;
+  /**
+   * Resolves the next inbound upgrade request, in arrival order. Used to
+   * assert headers the forwarder sends during the WS handshake (e.g. the
+   * offered `Sec-WebSocket-Protocol`).
+   */
+  waitForUpgradeRequest(): Promise<{ headers: IncomingHttpHeaders }>;
   close(): Promise<void>;
 }
 
@@ -69,8 +75,14 @@ function startDelayedTarget(delayMs: number): Promise<Target> {
   // arrival order; queue waiters that resolve one-for-one as connections land.
   const waiters: Array<(ws: WebSocket) => void> = [];
   let waitForCount = 0;
+  // Likewise for upgrade requests, captured before the WS is handed off so
+  // headers can be asserted even when the caller never awaits a connection.
+  const upgradeReqWaiters: Array<(req: { headers: IncomingHttpHeaders }) => void> = [];
 
   server.on('upgrade', (req, socket, head) => {
+    const captured = { headers: req.headers };
+    const waiter = upgradeReqWaiters.shift();
+    if (waiter) waiter(captured);
     const finish = () => {
       wss.handleUpgrade(req, socket, head, (ws) => {
         connections.push(ws);
@@ -97,6 +109,10 @@ function startDelayedTarget(delayMs: number): Promise<Target> {
             if (connections.length > want) res(connections[want] as WebSocket);
             else waiters.push(res);
           }),
+        waitForUpgradeRequest: () =>
+          new Promise((res) => {
+            upgradeReqWaiters.push(res);
+          }),
         close: () =>
           new Promise<void>((r) => {
             for (const ws of connections) ws.close();
@@ -260,6 +276,23 @@ describe('startForwarder — lifecycle', () => {
     openServers.push(fwd);
     expect(fwd.targetUrl).toBe('wss://example.invalid/');
   });
+
+  it('offers binary.ircv3.net and text.ircv3.net in the upstream WS handshake', async () => {
+    const target = await startTarget();
+    openServers.push(target);
+    const fwd = await startForwarder({ listenPort: 0, targetUrl: `ws://127.0.0.1:${target.port}` });
+    openServers.push(fwd);
+
+    const client = new TcpClient(fwd.listenPort);
+    openClients.push(client);
+    await client.opened();
+
+    const req = await target.waitForUpgradeRequest();
+    const offered = req.headers['sec-websocket-protocol'];
+    expect(typeof offered).toBe('string');
+    const list = (offered as string).split(',').map((s) => s.trim());
+    expect(list).toEqual(['binary.ircv3.net', 'text.ircv3.net']);
+  });
 });
 
 describe('forwarder — TCP→WS framing', () => {

package/tools/tcp-ws-forwarder/tests/framing.test.ts

@@ -1,6 +1,12 @@
 import { describe, expect, it } from 'vitest';
 import type { RawData } from 'ws';
-import { splitFrameLines, toBuffer } from '../src/forwarder';
+import {
+  FORWARDER_WS_SUBPROTOCOLS,
+  splitFrameLines,
+  toBuffer,
+  toTcpWire,
+  toWsMessagePayload,
+} from '../src/forwarder';
 
 /**
  * Pure-function unit tests for the WS-side framing helpers. These edges
@@ -49,3 +55,61 @@ describe('toBuffer', () => {
     expect(toBuffer(src as RawData).toString('utf8')).toBe('ABC');
   });
 });
+
+describe('FORWARDER_WS_SUBPROTOCOLS', () => {
+  it('offers binary.ircv3.net first (preferred)', () => {
+    expect(FORWARDER_WS_SUBPROTOCOLS[0]).toBe('binary.ircv3.net');
+  });
+
+  it('offers text.ircv3.net as the fallback', () => {
+    expect(FORWARDER_WS_SUBPROTOCOLS).toContain('text.ircv3.net');
+  });
+
+  it('offers exactly the two IRCv3 subprotocols', () => {
+    expect([...FORWARDER_WS_SUBPROTOCOLS].sort()).toEqual(['binary.ircv3.net', 'text.ircv3.net']);
+  });
+});
+
+describe('toWsMessagePayload — TCP line → WS message (CRLF stripped)', () => {
+  it('strips a trailing CRLF from a TCP IRC line', () => {
+    expect(toWsMessagePayload('PING :tok\r\n')).toBe('PING :tok');
+  });
+
+  it('strips a trailing bare LF', () => {
+    expect(toWsMessagePayload('PING :bare\n')).toBe('PING :bare');
+  });
+
+  it('leaves an already-bare line unchanged (idempotent on LineScanner output)', () => {
+    expect(toWsMessagePayload('NICK alice')).toBe('NICK alice');
+  });
+
+  it('strips only one trailing terminator, keeping embedded content', () => {
+    expect(toWsMessagePayload('PRIVMSG #foo :a\r\nb\r\n')).toBe('PRIVMSG #foo :a\r\nb');
+  });
+
+  it('returns the empty string unchanged', () => {
+    expect(toWsMessagePayload('')).toBe('');
+  });
+});
+
+describe('toTcpWire — WS message → TCP bytes (CRLF re-appended)', () => {
+  it('appends CRLF to a bare spec-mode WS message', () => {
+    expect(toTcpWire(':srv 001 nick :Welcome')).toEqual([':srv 001 nick :Welcome\r\n']);
+  });
+
+  it('collapses a single trailing CRLF instead of doubling it', () => {
+    expect(toTcpWire(':srv 001 nick :Hi\r\n')).toEqual([':srv 001 nick :Hi\r\n']);
+  });
+
+  it('emits no bytes for an empty WS message', () => {
+    expect(toTcpWire('')).toEqual([]);
+  });
+
+  it('emits no bytes for a message that is only a terminator', () => {
+    expect(toTcpWire('\r\n')).toEqual([]);
+  });
+
+  it('re-appends CRLF to each line of a legacy joined multi-message frame', () => {
+    expect(toTcpWire(':srv 001\r\n:srv 376')).toEqual([':srv 001\r\n', ':srv 376\r\n']);
+  });
+});