serverless-ircd 0.4.0 → 0.5.0

package/apps/local-cli/src/server.ts

@@ -8,6 +8,11 @@
  *   • a `ws.WebSocketServer` on {@link StartServerOptions.port} — the
  *     original WebSocket transport (one IRC message per text frame, or N
  *     `\r\n`-joined messages per frame). Programmatic test clients use this.
+ *     When a client negotiates an IRCv3 subprotocol
+ *     (`text.ircv3.net` / `binary.ircv3.net`) the connection switches to
+ *     spec framing: one IRC message per WebSocket message with no trailing
+ *     CR-LF, a 510-byte inbound budget, and (for text) lone-surrogate
+ *     sanitization. Un-negotiated clients keep the legacy framing.
  *   • an optional `node:net` TCP server on {@link StartServerOptions.tcpPort}
  *     — the RFC-style byte stream that real IRC clients (WeeChat, HexChat,
  *     IRCCloud) speak. The TCP path uses {@link LineScanner} to reassemble
@@ -41,9 +46,19 @@ import {
   type MessageStore,
   type NickHistoryStore,
   type RawLine,
+  type ServerConfig,
+  WS_SUBPROTO_BINARY,
+  WS_SUBPROTO_TEXT,
+  type WsFrameMode,
+  type WsSubprotocol,
   createConnection,
+  frameToLines,
+  isWithinWsByteBudget,
+  sanitizeForTextMode,
+  selectSubprotocol,
+  wsFrameModeFor,
 } from '@serverless-ircd/irc-core';
-import { ConnectionActor } from '@serverless-ircd/irc-server';
+import { ConnectionActor, type Transport } from '@serverless-ircd/irc-server';
 import { WebSocket, WebSocketServer } from 'ws';
 import { loadServerConfigFromCliArgs } from './config-loader.js';
 import { LineScanner } from './line-scanner.js';
@@ -73,6 +88,28 @@ type ResolvedServerConfig = Omit<
     | 'saslAccounts'
   >;
 
+/**
+ * Builds the reducer-facing {@link ServerConfig} from the resolved local-cli
+ * config. Shared by {@link attachConnection} (initial config) and the
+ * `InMemoryRuntime` reload source (REHASH) so a reload returns the same
+ * shape the actor was bootstrapped with — keeping the two paths consistent.
+ */
+function serverConfigFromResolved(cfg: ResolvedServerConfig): ServerConfig {
+  return {
+    serverName: cfg.serverName,
+    networkName: cfg.networkName,
+    maxChannelsPerUser: cfg.maxChannelsPerUser,
+    maxTargetsPerCommand: cfg.maxTargetsPerCommand,
+    maxListEntries: cfg.maxListEntries,
+    nickLen: cfg.nickLen,
+    channelLen: cfg.channelLen,
+    topicLen: cfg.topicLen,
+    quitMessage: cfg.quitMessage,
+    ...(cfg.serverPassword !== undefined ? { serverPassword: cfg.serverPassword } : {}),
+    ...(cfg.cloaking !== undefined ? { cloaking: cfg.cloaking } : {}),
+  };
+}
+
 /** Default per-IP / per-user caps used when callers don't override. */
 const DEFAULT_MAX_CONNECTIONS_PER_IP = 10;
 const DEFAULT_MAX_CONNECTIONS_PER_USER = 5;
@@ -216,7 +253,7 @@ const DEFAULT_CONFIG: Omit<
  * the three generators once at module load, not per-connection. No reducer in
  * the current codebase actually invokes `batchId` / `nonce` / `sessionId`;
  * they are forward-looking seams for SASL / BATCH / context-restoration
- * tickets and are exercised by irc-core's own unit tests via test fakes.
+ * and are exercised by irc-core's own unit tests via test fakes.
  *
  * Exported so `apps/local-cli` can ship a focused unit test asserting each
  * generator returns a fresh UUID-shaped string (defending against future
@@ -312,6 +349,10 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
   const runtime = new InMemoryRuntime({
     clock: { now: () => Date.now() },
     ...(admission !== undefined ? { admission } : {}),
+    // REHASH reload source: re-derive the live ServerConfig from the
+    // resolved config so an oper's `REHASH` re-fetches the latest values
+    // (rotated oper creds, MOTD, limits) without restarting the process.
+    configLoader: async () => serverConfigFromResolved(cfg),
   });
 
   // Per-process chat-history store: one ring buffer shared by every
@@ -333,8 +374,23 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
       ? new InMemoryAccountStore(cfg.saslAccounts)
       : undefined;
 
-  const wss = new WebSocketServer({ port: opts.port, host: hostname });
+  const wss = new WebSocketServer({
+    port: opts.port,
+    host: hostname,
+    // IRCv3 WebSocket subprotocol negotiation: select the first supported
+    // offer in client-preference order (core selector), or fall through to
+    // legacy framing when none match. The `ws` library only invokes this
+    // when the client offered protocols; returning the selected name echoes
+    // it, returning false completes the handshake with no
+    // Sec-WebSocket-Protocol header (legacy) — it never rejects.
+    handleProtocols: (protocols: Set<string>): string | false =>
+      selectSubprotocol([...protocols]) ?? false,
+  });
   const wsConnections = new Map<WebSocket, ConnectionBindings>();
+  // Per-connection negotiated IRCv3 subprotocol registry (null = legacy
+  // framing). Mirrors the selection made in `handleProtocols`; the resolved
+  // frame mode is also captured in the per-connection handlers below.
+  const wsModes = new Map<WebSocket, WsSubprotocol | null>();
 
   wss.on('connection', (ws, req) => {
     // Admission gate: refuse the connection BEFORE we attach an actor / emit
@@ -350,18 +406,50 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     const admissionRecordId = decision.recordId;
     runtime.commitAdmission(ip, undefined, admissionRecordId);
 
+    // Resolve the negotiated IRCv3 subprotocol (echoed by handleProtocols)
+    // and derive the frame mode. `ws.protocol` is '' when none negotiated.
+    const subproto: WsSubprotocol | null =
+      ws.protocol === WS_SUBPROTO_TEXT || ws.protocol === WS_SUBPROTO_BINARY
+        ? (ws.protocol as WsSubprotocol)
+        : null;
+    wsModes.set(ws, subproto);
+    const frameMode = wsFrameModeFor(subproto ?? undefined);
+
     const { state, actor } = attachConnection(runtime, cfg, messages, accounts, history, {
       sendText: (text) => {
-        if (ws.readyState === WebSocket.OPEN) ws.send(text);
+        if (ws.readyState !== WebSocket.OPEN) return;
+        // binary.ircv3.net connections exchange binary WebSocket frames;
+        // text/legacy connections send UTF-8 text frames.
+        ws.send(frameMode === 'spec-binary' ? Buffer.from(text, 'utf8') : text);
       },
       closeTransport: () => ws.close(),
       admissionRecordId,
       sourceHost: ip,
+      frameMode,
+      // Spec-mode framing: one IRC message per WS message (strip a single
+      // trailing CR-LF, never split on an embedded line break). Legacy
+      // connections fall through to the actor's default WsTextFrameTransport.
+      ...(frameMode === 'legacy'
+        ? {}
+        : { actorTransport: { feed: (chunk: string) => frameToLines(chunk, frameMode) } }),
     });
     wsConnections.set(ws, { state, actor });
 
     ws.on('message', (data) => {
       const text = data.toString('utf8');
+      // Spec-mode inbound: enforce the IRCv3 510-byte message budget and
+      // sanitize lone surrogates for text frames before framing. Legacy
+      // frames pass through unchanged (the 512-byte line cap is enforced in
+      // the parser, as before).
+      if (frameMode === 'spec-text' || frameMode === 'spec-binary') {
+        if (!isWithinWsByteBudget(text)) {
+          ws.close(1009, 'Message Too Big');
+          return;
+        }
+        const inbound = frameMode === 'spec-text' ? sanitizeForTextMode(text) : text;
+        actor.receiveTextFrame(inbound).catch((err) => logError('actor failure', err));
+        return;
+      }
       // Fire-and-forget: the actor's reducer pipeline is synchronous through
       // to dispatch, and dispatch awaits each runtime call in order. Errors
       // propagate to the catch here and are logged (never crash the server).
@@ -376,6 +464,7 @@ export function startLocalServer(opts: StartServerOptions): Promise<LocalServer>
     // admission record (if any) so per-IP / per-user counters stay accurate.
     const cleanup = (): void => {
       wsConnections.delete(ws);
+      wsModes.delete(ws);
       runtime.unregisterConnection(state.id);
     };
     ws.on('close', cleanup);
@@ -527,6 +616,20 @@ function attachConnection(
     closeTransport: () => void;
     admissionRecordId?: string;
     sourceHost?: string;
+    /**
+     * Negotiated IRCv3 WebSocket frame mode for this connection. Spec modes
+     * (`spec-text` / `spec-binary`) switch outbound delivery to one WS
+     * message per IRC line with no trailing CR-LF (and surrogate
+     * sanitization for text). `undefined` / `legacy` keeps the original
+     * `\r\n`-joined batch. TCP connections never set this.
+     */
+    frameMode?: WsFrameMode;
+    /**
+     * Inbound line-framing seam forwarded to the actor's `Transport`. Only
+     * set for spec-mode WebSocket connections (one IRC line per frame);
+     * when omitted the actor defaults to its WS-text-frame transport.
+     */
+    actorTransport?: Transport;
   },
 ): ConnectionBindings {
   const id = randomUUID();
@@ -547,19 +650,8 @@ function attachConnection(
     state,
     runtime,
     channels: runtime,
-    serverConfig: {
-      serverName: cfg.serverName,
-      networkName: cfg.networkName,
-      maxChannelsPerUser: cfg.maxChannelsPerUser,
-      maxTargetsPerCommand: cfg.maxTargetsPerCommand,
-      maxListEntries: cfg.maxListEntries,
-      nickLen: cfg.nickLen,
-      channelLen: cfg.channelLen,
-      topicLen: cfg.topicLen,
-      quitMessage: cfg.quitMessage,
-      ...(cfg.serverPassword !== undefined ? { serverPassword: cfg.serverPassword } : {}),
-      ...(cfg.cloaking !== undefined ? { cloaking: cfg.cloaking } : {}),
-    },
+    serverConfig: serverConfigFromResolved(cfg),
+    configSource: 'config file',
     clock: { now: () => Date.now() },
     ids: DEFAULT_ID_FACTORY,
     motd: { lines: () => cfg.motdLines },
@@ -567,21 +659,37 @@ function attachConnection(
     ...(accounts !== undefined ? { accounts } : {}),
     history,
     logger,
+    ...(transport.actorTransport !== undefined ? { transport: transport.actorTransport } : {}),
   });
 
   runtime.registerConnection(
     state,
     {
       send: (lines: RawLine[]) => {
-        const text = `${lines.map((l) => l.text).join('\r\n')}\r\n`;
-        transport.sendText(text);
+        const fm = transport.frameMode;
+        if (fm === 'spec-text' || fm === 'spec-binary') {
+          // Spec mode: one WebSocket message per IRC line, no trailing
+          // CR-LF. Sanitize lone surrogates for text frames (they have no
+          // valid UTF-8 encoding); binary frames pass through verbatim.
+          for (const l of lines) {
+            transport.sendText(fm === 'spec-text' ? sanitizeForTextMode(l.text) : l.text);
+          }
+        } else {
+          const text = `${lines.map((l) => l.text).join('\r\n')}\r\n`;
+          transport.sendText(text);
+        }
       },
       disconnect: (reason?: string) => {
         // If a reason was supplied, send the RFC-style ERROR notice before
         // closing. (QUIT does not supply one; future paths like flood
-        // control will.)
+        // control will.) In spec mode the notice is its own message with no
+        // trailing CR-LF.
         if (reason !== undefined) {
-          transport.sendText(`ERROR :Closing link: (${reason})\r\n`);
+          const line = `ERROR :Closing link: (${reason})`;
+          const fm = transport.frameMode;
+          if (fm === 'spec-text') transport.sendText(sanitizeForTextMode(line));
+          else if (fm === 'spec-binary') transport.sendText(line);
+          else transport.sendText(`${line}\r\n`);
         }
         transport.closeTransport();
       },

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

@@ -330,7 +330,7 @@ describe('local-cli error paths', () => {
     // '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.)
+    // pending a future gone-connection sweep.)
     client.ws.terminate();
     await new Promise((r) => setTimeout(r, 100));
     expect(srv.runtime.hasConnection(connId as string)).toBe(false);

package/apps/local-cli/tests/ws-subprotocol.test.ts

@@ -0,0 +1,257 @@
+import { EventEmitter } from 'node:events';
+import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { WebSocket } from 'ws';
+import { type LocalServer, startLocalServer } from '../src/server';
+
+/**
+ * IRCv3 WebSocket subprotocol negotiation + per-message framing e2e.
+ *
+ * A spec-mode (`text.ircv3.net` / `binary.ircv3.net`) connection MUST:
+ *   - have its offered subprotocol echoed back in the handshake;
+ *   - exchange exactly one IRC message per WebSocket message, with NO
+ *     trailing CR-LF on either direction.
+ *
+ * A legacy (un-negotiated) connection keeps the original `\r\n`-batched
+ * framing, so the existing integration suite stays green.
+ */
+
+/** A spec-mode client: one IRC line per WS message, no trailing CRLF. */
+class SpecClient extends EventEmitter {
+  readonly ws: WebSocket;
+  readonly received: string[] = [];
+
+  constructor(url: string, protocols: string | string[]) {
+    super();
+    this.ws = new WebSocket(url, protocols);
+    // Each inbound WS message is exactly one IRC line in spec mode (no CRLF).
+    this.ws.on('message', (data) => {
+      const line = data.toString('utf8');
+      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);
+      }
+    });
+  }
+
+  /** Sends one bare IRC line as its own WS message (no trailing CRLF). */
+  send(line: string): Promise<void> {
+    return new Promise((resolve, reject) => {
+      this.ws.send(line, (err) => (err ? reject(err) : resolve()));
+    });
+  }
+
+  /** Waits until a received line satisfies `predicate` (substring match). */
+  waitFor(predicate: (line: string) => boolean, timeoutMs = 1000): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(
+        () => reject(new Error(`timeout; received: ${JSON.stringify(this.received)}`)),
+        timeoutMs,
+      );
+      const check = (line: string) => {
+        if (predicate(line)) {
+          clearTimeout(timeout);
+          this.off('line', check);
+          resolve(line);
+        }
+      };
+      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) => {
+      if (this.ws.readyState === WebSocket.CLOSED) {
+        resolve();
+        return;
+      }
+      this.ws.once('close', () => resolve());
+      this.ws.close();
+    });
+  }
+}
+
+describe('local-cli IRCv3 WebSocket subprotocol', () => {
+  let server: LocalServer;
+
+  beforeAll(async () => {
+    server = await startLocalServer({ port: 0, hostname: '127.0.0.1' });
+  });
+
+  afterAll(async () => {
+    await server.close();
+  });
+
+  it('echoes text.ircv3.net when offered', async () => {
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    expect(client.ws.protocol).toBe('text.ircv3.net');
+    await client.close();
+  });
+
+  it('echoes binary.ircv3.net when offered', async () => {
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'binary.ircv3.net');
+    await client.opened();
+    expect(client.ws.protocol).toBe('binary.ircv3.net');
+    await client.close();
+  });
+
+  it('completes a full session over binary.ircv3.net (binary frames)', async () => {
+    // binary.ircv3.net exchanges binary WebSocket frames. The server emits
+    // binary outbound frames (Buffer) and decodes inbound as UTF-8; the
+    // round-trip must decode to valid IRC lines with no trailing CRLF.
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'binary.ircv3.net');
+    await client.opened();
+    await client.send('NICK spec-bin');
+    await client.send('USER spec-bin 0 * :Spec Bin');
+    const welcome = await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    expect(welcome).toContain('spec-bin');
+
+    await client.send('PING :bin-tok');
+    const pong = await client.waitFor((l) => l === 'PONG :bin-tok');
+    expect(pong).toBe('PONG :bin-tok');
+
+    // Every decoded outbound message is a single bare IRC line.
+    for (const line of client.received) {
+      expect(line.includes('\r')).toBe(false);
+      expect(line.includes('\n')).toBe(false);
+    }
+    await client.close();
+  });
+
+  it('selects the first-listed supported subprotocol (client preference)', async () => {
+    // Client prefers binary over text; server honours the order.
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, [
+      'binary.ircv3.net',
+      'text.ircv3.net',
+    ]);
+    await client.opened();
+    expect(client.ws.protocol).toBe('binary.ircv3.net');
+    await client.close();
+  });
+
+  it('ignores unsupported offers and still selects a supported one', async () => {
+    // Client lists an unsupported protocol first, then a supported one. The
+    // server MUST select the supported entry, not blindly echo the first.
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, ['chat', 'text.ircv3.net']);
+    await client.opened();
+    expect(client.ws.protocol).toBe('text.ircv3.net');
+    await client.close();
+  });
+
+  it('connects in legacy mode when no subprotocol is offered', async () => {
+    // A plain client (no Sec-WebSocket-Protocol) is the legacy path: the
+    // server does not negotiate and the existing integration suite keeps
+    // working unchanged.
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, []);
+    await client.opened();
+    expect(client.ws.protocol).toBe('');
+    await client.close();
+  });
+
+  it('completes registration with one IRC message per WebSocket message (text mode)', async () => {
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    // One bare line per WS message (no trailing CRLF).
+    await client.send('NICK spec-alice');
+    await client.send('USER spec-alice 0 * :Spec Alice');
+    const welcome = await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+    expect(welcome).toContain('spec-alice');
+
+    // Every received message must be a single IRC line with no trailing CRLF
+    // and no embedded line break (one IRC message per WS message).
+    for (const line of client.received) {
+      expect(line.includes('\r')).toBe(false);
+      expect(line.includes('\n')).toBe(false);
+    }
+    await client.close();
+  });
+
+  it('delivers each outbound line as a distinct WebSocket message in spec mode', async () => {
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    await client.send('NICK spec-bob');
+    await client.send('USER spec-bob 0 * :Spec Bob');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    // The welcome sequence is many numerics (001..005, 375/372/376). In spec
+    // mode each arrives as its own WS message; a legacy batch would have
+    // concatenated them with CRLF inside one message. Assert we observed
+    // several distinct messages.
+    expect(client.received.length).toBeGreaterThan(1);
+    await client.close();
+  });
+
+  it('routes PING → PONG as a single-message frame in spec mode', async () => {
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    await client.send('NICK spec-ping');
+    await client.send('USER spec-ping 0 * :Spec Ping');
+    await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+    await client.send('PING :spec-tok');
+    const pong = await client.waitFor((l) => l === 'PONG :spec-tok');
+    expect(pong).toBe('PONG :spec-tok');
+    await client.close();
+  });
+
+  it('rejects an inbound message exceeding the 510-byte budget in spec mode', async () => {
+    const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, 'text.ircv3.net');
+    await client.opened();
+    await client.send('NICK spec-budget');
+    await client.send('USER spec-budget 0 * :Spec Budget');
+    // Drain the entire registration burst (001..376) so delayed numerics
+    // don't pollute the post-overlong-message assertion below.
+    await client.waitFor((l) => l.startsWith(':irc.example.com 376 '));
+
+    client.received.length = 0;
+    // 511-byte payload: `PRIVMSG #x :` (12 bytes) + 499 chars = 511 total.
+    const overlong = `PRIVMSG #x :${'a'.repeat(499)}`;
+    expect(overlong.length).toBe(511);
+    await client.send(overlong);
+    // Give the server a moment to process + close. An over-budget message
+    // MUST NOT produce a PRIVMSG broadcast or numeric reply.
+    await new Promise((r) => setTimeout(r, 80));
+    expect(client.received.length).toBe(0);
+    await client.close();
+  });
+
+  // A reducer-driven disconnect with a reason (e.g. flood control / oper
+  // kill) emits the RFC-style ERROR notice. In spec mode it MUST arrive as
+  // its own WebSocket message with no trailing CR-LF, for both text and
+  // binary negotiated connections.
+  for (const subproto of ['text.ircv3.net', 'binary.ircv3.net'] as const) {
+    it(`delivers the ERROR notice as a single message on a ${subproto} connection`, async () => {
+      const nick = subproto === 'text.ircv3.net' ? 'spec-disc-text' : 'spec-disc-bin';
+      const client = new SpecClient(`ws://127.0.0.1:${server.port}/`, subproto);
+      await client.opened();
+      await client.send(`NICK ${nick}`);
+      await client.send(`USER ${nick} 0 * :Spec Disc`);
+      await client.waitFor((l) => l.startsWith(':irc.example.com 001 '));
+
+      const connId = await server.runtime.lookupNick(nick);
+      expect(connId).not.toBeNull();
+      await server.runtime.disconnect(connId as string, 'Excess Flood');
+      const notice = await client.waitFor((l) => l.startsWith('ERROR :Closing link:'));
+      expect(notice).toBe('ERROR :Closing link: (Excess Flood)');
+      await client.close();
+    });
+  }
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "serverless-ircd",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Serverless IRC daemon with a platform-agnostic core and Cloudflare Workers + AWS adapters",
   "license": "BSD-3-Clause",
@@ -17,7 +17,7 @@
     "typescript": "^5.9.3",
     "vite": "^7.3.6",
     "vitest": "^4.1.10",
-    "@serverless-ircd/aws-adapter": "0.4.0"
+    "@serverless-ircd/aws-adapter": "0.5.0"
   },
   "scripts": {
     "build": "turbo run build",

package/packages/aws-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/aws-adapter",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": true,
   "description": "AWS Lambda + DynamoDB adapter: AwsRuntime implementing IrcRuntime + $connect/$disconnect/$default handlers",
   "license": "BSD-3-Clause",

package/packages/aws-adapter/src/aws-runtime.ts

@@ -51,6 +51,7 @@ import {
   type Nick,
   type RawLine,
   type RosterEntry,
+  type ServerConfig,
   SystemClock,
   emptyModes,
   toSnapshot as toConnSnapshot,
@@ -119,6 +120,14 @@ export interface AwsRuntimeOptions {
    */
   managementApi: ApiGatewayManagementApi | PostToConnection | null;
   clock?: Clock;
+  /**
+   * Config-reload source for `REHASH`. The Lambda handler binds this to a
+   * closure that re-invokes {@link loadServerConfigFromLambdaEnv} against the
+   * invocation env (Secrets Manager / SSM / env vars). When omitted
+   * `reloadConfig` rejects so the actor applies a graceful error-suffixed
+   * `382` and retains the prior config.
+   */
+  readonly configLoader?: () => Promise<ServerConfig>;
 }
 
 /**
@@ -133,6 +142,7 @@ export class AwsRuntime implements IrcRuntime {
   private readonly handlers: AwsRuntimeHandlers;
   private readonly managementApi: ApiGatewayManagementApi | PostToConnection | null;
   private readonly clock: Clock;
+  private readonly configLoader: (() => Promise<ServerConfig>) | undefined;
 
   constructor(opts: AwsRuntimeOptions) {
     this.dynamo = opts.dynamo;
@@ -141,6 +151,7 @@ export class AwsRuntime implements IrcRuntime {
     this.handlers = opts.handlers;
     this.managementApi = opts.managementApi;
     this.clock = opts.clock ?? SystemClock;
+    this.configLoader = opts.configLoader;
   }
 
   // -------------------------------------------------------------------------
@@ -210,6 +221,51 @@ export class AwsRuntime implements IrcRuntime {
     }
   }
 
+  /**
+   * Global cross-connection fan-out for `WALLOPS`. `Scan`s the `Connections`
+   * table filtered to rows whose `userModes.wallops` is `true`, then
+   * `PostToConnection`s each one (skipping `except`). The bound connection's
+   * own delivery goes through the in-process handlers (no APIGW round-trip),
+   * mirroring `send`.
+   *
+   * Cost: a DynamoDB `Scan` reads the ENTIRE table (chargeable per row read,
+   * not per match), so this is expensive at high connection counts. A fleet
+   * of 10k connections costs one full scan per WALLOPS plus one
+   * `PostToConnection` per `+w` recipient. Deployments should bound the
+   * oper's WALLOPS rate; a projected GSI on `userModes.wallops` would lift
+   * the scan to a targeted query (documented follow-up). The scan uses
+   * `FilterExpression` so only `+w` rows survive to the `PostToConnection`
+   * phase — the APIGW call count is bounded by the genuine recipient set.
+   */
+  async broadcastWallops(lines: RawLine[], except?: ConnId): Promise<void> {
+    let startKey: Record<string, NativeAttributeValue> | undefined;
+    // Paginate the scan: DynamoDB caps a single Scan at 1 MB. Loop until
+    // no `LastEvaluatedKey` remains so every +w connection is reached.
+    do {
+      const result = await this.dynamo.send(
+        new ScanCommand({
+          TableName: this.tables.Connections,
+          FilterExpression: 'userModes.#m = :true',
+          ExpressionAttributeNames: { '#m': 'wallops' },
+          ExpressionAttributeValues: { ':true': true },
+          ...(startKey !== undefined ? { ExclusiveStartKey: startKey } : {}),
+        }),
+      );
+      const items = (result.Items ?? []) as unknown as MarshalledConnection[];
+      for (const row of items) {
+        const connId = row.connectionId;
+        if (connId === except) continue;
+        // `send` short-cuts the bound connection through the in-process
+        // handlers and catches GoneException so vanished sockets are
+        // cleaned up rather than aborting the fan-out mid-loop.
+        if (row.userModes.wallops) {
+          await this.send(connId, lines);
+        }
+      }
+      startKey = result.LastEvaluatedKey as Record<string, NativeAttributeValue> | undefined;
+    } while (startKey !== undefined);
+  }
+
   // -------------------------------------------------------------------------
   // Nick registry
   // -------------------------------------------------------------------------
@@ -365,6 +421,19 @@ export class AwsRuntime implements IrcRuntime {
     return out;
   }
 
+  /**
+   * Re-invokes the bound config loader (Secrets Manager / SSM / env) and
+   * returns the fresh {@link ServerConfig}. The Lambda handler binds the
+   * loader at construction; when no loader was supplied this rejects so the
+   * actor's graceful failure path applies.
+   */
+  async reloadConfig(): Promise<ServerConfig> {
+    if (this.configLoader === undefined) {
+      throw new Error('no config loader bound to AwsRuntime');
+    }
+    return this.configLoader();
+  }
+
   // -------------------------------------------------------------------------
   // Public helpers (re-exported surface)
   // -------------------------------------------------------------------------