serverless-ircd 0.4.0 → 0.5.0

package/packages/irc-core/tests/ws-subprotocol.test.ts

@@ -0,0 +1,111 @@
+import { describe, expect, it } from 'vitest';
+import {
+  WS_SUBPROTO_BINARY,
+  WS_SUBPROTO_TEXT,
+  type WsSubprotocol,
+  parseSecWsProtocolOffers,
+  selectSubprotocol,
+} from '../src/ws-subprotocol';
+
+// ============================================================================
+// constants & type
+// ============================================================================
+
+describe('WS subprotocol constants', () => {
+  it('exposes the IRCv3 text subprotocol name', () => {
+    expect(WS_SUBPROTO_TEXT).toBe('text.ircv3.net');
+  });
+
+  it('exposes the IRCv3 binary subprotocol name', () => {
+    expect(WS_SUBPROTO_BINARY).toBe('binary.ircv3.net');
+  });
+
+  it('the WsSubprotocol type resolves to the two literal names', () => {
+    const a: WsSubprotocol = WS_SUBPROTO_TEXT;
+    const b: WsSubprotocol = WS_SUBPROTO_BINARY;
+    expect([a, b]).toEqual([WS_SUBPROTO_TEXT, WS_SUBPROTO_BINARY]);
+  });
+});
+
+// ============================================================================
+// parseSecWsProtocolOffers — header parsing
+// ============================================================================
+
+describe('parseSecWsProtocolOffers', () => {
+  it('splits a comma-separated list into ordered offers', () => {
+    expect(parseSecWsProtocolOffers('text.ircv3.net, binary.ircv3.net')).toEqual([
+      'text.ircv3.net',
+      'binary.ircv3.net',
+    ]);
+  });
+
+  it('trims whitespace around each item', () => {
+    expect(parseSecWsProtocolOffers(' text.ircv3.net , binary.ircv3.net ')).toEqual([
+      'text.ircv3.net',
+      'binary.ircv3.net',
+    ]);
+  });
+
+  it('preserves client-preference order', () => {
+    expect(parseSecWsProtocolOffers('binary.ircv3.net, text.ircv3.net')).toEqual([
+      'binary.ircv3.net',
+      'text.ircv3.net',
+    ]);
+  });
+
+  it('returns an empty array for null', () => {
+    expect(parseSecWsProtocolOffers(null)).toEqual([]);
+  });
+
+  it('returns an empty array for undefined', () => {
+    expect(parseSecWsProtocolOffers(undefined)).toEqual([]);
+  });
+
+  it('returns an empty array for an empty string', () => {
+    expect(parseSecWsProtocolOffers('')).toEqual([]);
+  });
+
+  it('drops empty entries produced by stray commas', () => {
+    expect(parseSecWsProtocolOffers('text.ircv3.net,, ,binary.ircv3.net')).toEqual([
+      'text.ircv3.net',
+      'binary.ircv3.net',
+    ]);
+  });
+
+  it('preserves duplicate entries in order', () => {
+    expect(parseSecWsProtocolOffers('text.ircv3.net, text.ircv3.net')).toEqual([
+      'text.ircv3.net',
+      'text.ircv3.net',
+    ]);
+  });
+});
+
+// ============================================================================
+// selectSubprotocol — preference-ordered selection
+// ============================================================================
+
+describe('selectSubprotocol', () => {
+  it('returns the first supported offer in client-preference order (text first)', () => {
+    expect(selectSubprotocol(['text.ircv3.net', 'binary.ircv3.net'])).toBe('text.ircv3.net');
+  });
+
+  it('honours client preference when binary is offered first', () => {
+    expect(selectSubprotocol(['binary.ircv3.net', 'text.ircv3.net'])).toBe('binary.ircv3.net');
+  });
+
+  it('returns null when only unsupported protocols are offered', () => {
+    expect(selectSubprotocol(['foo', 'bar'])).toBeNull();
+  });
+
+  it('returns null for an empty offer list', () => {
+    expect(selectSubprotocol([])).toBeNull();
+  });
+
+  it('skips unsupported offers and selects the first supported one', () => {
+    expect(selectSubprotocol(['foo', 'binary.ircv3.net'])).toBe('binary.ircv3.net');
+  });
+
+  it('returns the first occurrence for duplicate supported offers', () => {
+    expect(selectSubprotocol(['text.ircv3.net', 'text.ircv3.net'])).toBe('text.ircv3.net');
+  });
+});

package/packages/irc-server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/irc-server",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": true,
   "description": "Orchestration layer: IrcRuntime port, dispatch interpreter, ConnectionActor",
   "license": "BSD-3-Clause",

package/packages/irc-server/src/actor.ts

@@ -46,15 +46,23 @@ import {
   Numerics,
   type RawLine,
   type ServerConfig,
+  type ServerStats,
   buildCtx,
   chathistoryReducer,
   handleJoinZero,
   isChannelTarget,
   isonReducer,
+  killReducer,
   listReducer,
+  lusersReducer,
   parse,
+  rehashLine,
+  rehashReducer,
+  statsReducer,
   toSnapshot,
+  traceReducer,
   userhostReducer,
+  wallopsReducer,
   whoReducer,
   whoisReducer,
   whowasReducer,
@@ -100,6 +108,13 @@ export interface ConnectionActorOptions {
   runtime: IrcRuntime;
   channels: ActorChannelAccess;
   serverConfig: ServerConfig;
+  /**
+   * Short label identifying the adapter's bound config source (e.g.
+   * `"KV"`, `"Secrets Manager"`, `"config file"`). Surfaced in the
+   * `382 RPL_REHASHING` reply's trailing text so the oper can see where the
+   * reload was attempted from. Defaults to `"server config"` when omitted.
+   */
+  readonly configSource?: string;
   clock: Clock;
   ids: IdFactory;
   motd?: MotdProvider;
@@ -138,6 +153,17 @@ export interface ConnectionActorOptions {
    * preserves the no-store behaviour: `WHOWAS <nick>` emits `406`+`369`.
    */
   readonly history?: NickHistoryStore;
+  /**
+   * Network-statistics source for the `LUSERS` and `STATS` commands
+   * (absent when no stats backend is wired). When bound, the actor
+   * awaits `stats.getStats()` once per LUSERS/STATS invocation and hands
+   * the resulting snapshot to the pure reducers — same pattern as
+   * `listChannels` → `listReducer`. Omitted (→ a zero-count fallback)
+   * preserves graceful behaviour for deployments/tests that have not
+   * opted in: `LUSERS` reports zero users/channels, `STATS u` reports
+   * zero uptime.
+   */
+  readonly stats?: ServerStats;
   /**
    * Structured-logger port. When omitted the actor runs
    * silently — observability is purely opt-in. When supplied, every
@@ -166,7 +192,8 @@ export class ConnectionActor {
   private readonly state: ConnectionState;
   private readonly runtime: IrcRuntime;
   private readonly channels: ActorChannelAccess;
-  private readonly serverConfig: ServerConfig;
+  private serverConfig: ServerConfig;
+  private readonly configSource: string;
   private readonly clock: Clock;
   private readonly ids: IdFactory;
   private readonly motd: MotdProvider;
@@ -174,6 +201,7 @@ export class ConnectionActor {
   private readonly accounts: AccountStore | undefined;
   private readonly mtlsIdentity: MtlsIdentityProvider | undefined;
   private readonly history: NickHistoryStore | undefined;
+  private readonly stats: ServerStats | undefined;
   private readonly reducers: RoutedReducers;
   /**
    * Line-framing seam. Turns inbound input (a WS text frame or a raw TCP
@@ -200,6 +228,7 @@ export class ConnectionActor {
     this.runtime = opts.runtime;
     this.channels = opts.channels;
     this.serverConfig = opts.serverConfig;
+    this.configSource = opts.configSource ?? 'server config';
     this.clock = opts.clock;
     this.ids = opts.ids;
     this.motd = opts.motd ?? EmptyMotdProvider;
@@ -207,6 +236,7 @@ export class ConnectionActor {
     this.accounts = opts.accounts;
     this.mtlsIdentity = opts.mtlsIdentity;
     this.history = opts.history;
+    this.stats = opts.stats;
     this.logger = opts.logger ?? NoopLoggerInstance;
     this.pinnedTraceId = opts.traceId;
     // Bind the connection id once so every record the actor emits carries
@@ -337,12 +367,16 @@ export class ConnectionActor {
         return this.reducers.motd(this.state, msg, ctx).effects;
       case 'OPER':
         return this.reducers.oper(this.state, msg, ctx).effects;
+      case 'REHASH':
+        return this.routeRehash(msg, ctx);
       case 'CAP':
         return this.reducers.cap(this.state, msg, ctx).effects;
       case 'AUTHENTICATE':
         return this.reducers.authenticate(this.state, msg, ctx).effects;
       case 'AWAY':
         return this.reducers.away(this.state, msg, ctx).effects;
+      case 'SETNAME':
+        return this.reducers.setname(this.state, msg, ctx).effects;
 
       // -------- Server-info query commands --------
       case 'VERSION':
@@ -382,6 +416,16 @@ export class ConnectionActor {
         return this.routeWhois(msg, ctx);
       case 'WHOWAS':
         return this.routeWhowas(msg, ctx);
+      case 'KILL':
+        return this.routeKill(msg, ctx);
+      case 'TRACE':
+        return this.routeTrace(msg, ctx);
+      case 'WALLOPS':
+        return this.routeWallops(msg, ctx);
+      case 'LUSERS':
+        return this.routeLusers(msg, ctx);
+      case 'STATS':
+        return this.routeStats(msg, ctx);
       case 'CHATHISTORY':
         return this.routeChathistory(msg, ctx);
 
@@ -418,14 +462,17 @@ export class ConnectionActor {
       default:
         // Remaining standard IRC verbs not yet implemented. They fall through
         // to a graceful `421 ERR_UNKNOWNCOMMAND`. Triage of remaining verbs:
-        //   - Deferred (serverless-incompatible / S2S / needs new infra):
-        //     LUSERS (needs cross-adapter getStats), KILL (oper disconnect),
-        //     REHASH (no runtime config reload), CONNECT/SQUIT (S2S, PLAN
-        //     non-goal), TRACE (complex routing info), STATS (stats backend),
-        //     WALLOPS (oper broadcast mechanism), SETNAME (CHGHOST plumbing),
-        //     LINKS (S2S server list).
-        //   - Obsolete (RFC 2812, never widely implemented): SERVICE, SUMMON,
-        //     USERS.
+        //   - Deferred (serverless-incompatible / needs new infra):
+        //     (none — LUSERS/STATS are now implemented).
+        //   - Deliberately dropped (S2S — PLAN non-goal):
+        //     CONNECT, SQUIT, LINKS. There is no server mesh to connect,
+        //     split, or list; these stay 421. Their reserved numerics
+        //     (RPL_LINKS/RPL_ENDOFLINKS/ERR_CANTKILLSERVER) were removed.
+        //   - Deliberately dropped (RFC 2812 obsolete, never widely
+        //     implemented): SERVICE, SUMMON, USERS. These
+        //     stay 421; their reserved numerics
+        //     (RPL_YOURESERVICE/ERR_NOSUCHSERVICE/ERR_SUMMONDISABLED/
+        //     ERR_USERSDISABLED) were removed.
         return [this.unknownCommandEffect(msg.command)];
     }
   }
@@ -438,6 +485,40 @@ export class ConnectionActor {
     return listReducer(snapshots, msg, ctx).effects;
   }
 
+  /**
+   * Routes `REHASH` (oper-gated config reload). The pure reducer enforces the
+   * oper gate and emits `382 RPL_REHASHING`; when the gate passes the actor
+   * re-invokes the runtime's bound config loader and swaps its live
+   * `serverConfig` reference so subsequent commands observe the refreshed
+   * value (rotated oper creds, new MOTD source, etc.).
+   *
+   * On reload failure the previous config stays in effect and a graceful
+   * error-suffixed `382` follows — the oper is NOT disconnected (per the
+   * serverless reload contract: a bad store read must never sever a live
+   * connection).
+   */
+  private async routeRehash(
+    msg: IrcMessage,
+    ctx: ReturnType<typeof buildCtx>,
+  ): Promise<EffectType[]> {
+    const result = rehashReducer(this.state, msg, ctx, this.configSource);
+    if (!result.shouldReload) {
+      return result.effects;
+    }
+    const effects = [...result.effects];
+    try {
+      this.serverConfig = await this.runtime.reloadConfig();
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      this.logger.warn('rehash.reload-failed', { reason });
+      const nick = this.state.nick ?? '*';
+      effects.push(
+        Effect.send(this.state.id, [rehashLine(ctx.serverName, nick, this.configSource, reason)]),
+      );
+    }
+    return effects;
+  }
+
   private async routeWho(msg: IrcMessage, ctx: ReturnType<typeof buildCtx>): Promise<EffectType[]> {
     const target = msg.params[0] ?? '';
     if (target.length === 0) {
@@ -474,6 +555,78 @@ export class ConnectionActor {
     return whoisReducer(target, channels, msg, ctx).effects;
   }
 
+  /**
+   * Routes `KILL <nick> <comment>` to the kill reducer. The actor resolves
+   * the target via the nick registry + a live connection fetch (mirroring
+   * {@link routeWhois}); no channel is created as a side effect. The
+   * reducer performs the oper gate and, on success, emits a
+   * {@link DisconnectEffect} for the target — the runtime's `disconnect`
+   * closes the target transport and fans QUIT out to shared-channel peers
+   * (peer fanout is the runtime's responsibility, not the reducer's).
+   */
+  private async routeKill(
+    msg: IrcMessage,
+    ctx: ReturnType<typeof buildCtx>,
+  ): Promise<EffectType[]> {
+    const targetNick = msg.params[0] ?? '';
+    let target: ConnectionState | undefined;
+    if (targetNick.length > 0) {
+      const connId = await this.runtime.lookupNick(targetNick);
+      if (connId !== null) {
+        target = (await this.runtime.getConnection(connId)) ?? undefined;
+      }
+    }
+    return killReducer(target, msg, ctx).effects;
+  }
+
+  /**
+   * Routes `TRACE [<target>]` to the trace reducer. Single-server
+   * deployment: when `<target>` is absent or equals the local server name
+   * the reducer emits only the `262 RPL_ENDOFTRACE` terminator; when
+   * `<target>` resolves to a nick the reducer emits `205`/`204` per-conn
+   * detail (oper requester only) plus `262`; any other `<target>` is
+   * treated as a non-local server and yields `402 ERR_NOSUCHSERVER`.
+   *
+   * The actor resolves the target via `lookupNick` + `getConnection`
+   * (mirroring {@link routeWhois}). The local-server check is
+   * case-insensitive against `serverConfig.serverName`. Multi-hop S2S
+   * tracing is a PLAN non-goal.
+   */
+  private async routeTrace(
+    msg: IrcMessage,
+    ctx: ReturnType<typeof buildCtx>,
+  ): Promise<EffectType[]> {
+    const rawTarget = msg.params[0] ?? '';
+    if (rawTarget.length === 0) {
+      return traceReducer(undefined, msg, ctx).effects;
+    }
+    // Local server name (case-insensitive) → collapse to the no-target path.
+    if (rawTarget.toLowerCase() === ctx.serverName.toLowerCase()) {
+      return traceReducer(undefined, msg, ctx).effects;
+    }
+    // Try to resolve as a nick.
+    const connId = await this.runtime.lookupNick(rawTarget);
+    if (connId !== null) {
+      const target = (await this.runtime.getConnection(connId)) ?? undefined;
+      return traceReducer(target, msg, ctx).effects;
+    }
+    // Unresolved: treat as a remote server → 402 ERR_NOSUCHSERVER.
+    return traceReducer(undefined, msg, ctx, rawTarget).effects;
+  }
+
+  /**
+   * Routes `WALLOPS :<message>` to the wallops reducer. The pure reducer
+   * enforces the oper gate (`481`) and the non-empty-message check
+   * (`412`); on success it emits a single {@link BroadcastWallopsEffect}
+   * that the dispatch layer interprets via the runtime's
+   * `broadcastWallops` method — a global fan-out to every `+w`
+   * connection (not channel-scoped). The originator is always excluded
+   * (skip-self, matching NOTICE/PRIVMSG broadcast semantics).
+   */
+  private routeWallops(msg: IrcMessage, ctx: ReturnType<typeof buildCtx>): EffectType[] {
+    return wallopsReducer(this.state, msg, ctx).effects;
+  }
+
   /**
    * Routes `WHOWAS <nick>{,<nick>} [<count>]` to the whowas reducer. The
    * command is query-only: it reads the bound nick-history store
@@ -488,6 +641,70 @@ export class ConnectionActor {
     return whowasReducer(this.history, msg, ctx).effects;
   }
 
+  /**
+   * Routes `LUSERS [<mask> [<server>]]` to the lusers reducer. Awaits the
+   * bound {@link ServerStats} backend (or falls back to a zero-count
+   * snapshot when no backend is wired) and hands the result to the pure
+   * reducer, which emits the `251`–`255`/`265`/`266` numerics.
+   *
+   * Single-server deployment: a `<server>` argument that does not match
+   * the local server name (case-insensitive) is treated as a remote
+   * server and yields `402 ERR_NOSUCHSERVER`. S2S aggregation is a PLAN
+   * non-goal.
+   */
+  private async routeLusers(
+    msg: IrcMessage,
+    ctx: ReturnType<typeof buildCtx>,
+  ): Promise<EffectType[]> {
+    const serverTarget = serverTargetOf(msg.params[1] ?? '', ctx.serverName);
+    const snapshot = await this.fetchStats();
+    return lusersReducer(snapshot, msg, ctx, serverTarget).effects;
+  }
+
+  /**
+   * Routes `STATS <query> [<server>]` to the stats reducer. Awaits the
+   * bound {@link ServerStats} backend (or zero-count fallback) and hands
+   * the result to the pure reducer. The reducer handles the implemented
+   * query letters (`u`, `l`), the unknown-letter charybdis-style empty
+   * body, and the `219` terminator; non-local `<server>` arguments
+   * produce `402 ERR_NOSUCHSERVER`.
+   */
+  private async routeStats(
+    msg: IrcMessage,
+    ctx: ReturnType<typeof buildCtx>,
+  ): Promise<EffectType[]> {
+    const serverTarget = serverTargetOf(msg.params[1] ?? '', ctx.serverName);
+    const snapshot = await this.fetchStats();
+    return statsReducer(snapshot, msg, ctx, serverTarget).effects;
+  }
+
+  /**
+   * Fetches the current {@link ServerStatsSnapshot} from the bound backend.
+   * When no backend is wired, returns a zero-count snapshot so LUSERS/STATS
+   * still emit a well-formed reply rather than a 421/empty stream — the
+   * uptime anchor defaults to the actor's wall clock so `STATS u` reports
+   * zero uptime instead of a negative duration.
+   */
+  private async fetchStats(): Promise<import('@serverless-ircd/irc-core').ServerStatsSnapshot> {
+    if (this.stats !== undefined) {
+      return this.stats.getStats();
+    }
+    const now = this.clock.now();
+    return {
+      users: 0,
+      invisible: 0,
+      opers: 0,
+      unknownConnections: 0,
+      channels: 0,
+      servers: 1,
+      localConns: 0,
+      globalConns: 0,
+      maxLocalConns: 0,
+      maxGlobalConns: 0,
+      uptimeStartedAt: now,
+    };
+  }
+
   /**
    * Routes `USERHOST <nick>{ <nick>}` to the userhost reducer. Resolves each
    * requested nick via the nick registry + connection lookup, passing the
@@ -500,10 +717,8 @@ export class ConnectionActor {
     ctx: ReturnType<typeof buildCtx>,
   ): Promise<EffectType[]> {
     const cap = ctx.serverConfig.maxTargetsPerCommand;
-    const nicks = msg.params.slice(0, cap);
     const resolved = new Map<string, ConnSnapshot | null>();
-    for (const nick of nicks) {
-      if (nick.length === 0) continue;
+    for (const nick of msg.params.slice(0, cap)) {
       const connId = await this.runtime.lookupNick(nick);
       if (connId === null) {
         resolved.set(nick, null);
@@ -526,13 +741,14 @@ export class ConnectionActor {
     ctx: ReturnType<typeof buildCtx>,
   ): Promise<EffectType[]> {
     const cap = ctx.serverConfig.maxTargetsPerCommand;
-    const nicks = msg.params.slice(0, cap);
     const online = new Map<string, string>();
-    for (const nick of nicks) {
-      if (nick.length === 0) continue;
+    for (const nick of msg.params.slice(0, cap)) {
       const connId = await this.runtime.lookupNick(nick);
       if (connId === null) continue;
       const conn = await this.runtime.getConnection(connId);
+      // `conn` can be null in the race where lookupNick resolved but the
+      // connection has since torn down (the nick map lags the connection
+      // map). Skip those — they are no longer online.
       if (conn?.nick !== undefined) {
         online.set(conn.nick.toLowerCase(), conn.nick);
       }
@@ -699,6 +915,20 @@ function splitCsv(param: string): string[] {
   return param.split(',').filter((p) => p.length > 0);
 }
 
+/**
+ * Resolves the `<server>` parameter shared by `LUSERS` / `STATS` (and any
+ * future single-server-aware query verb). Returns `undefined` when the
+ * argument is absent OR names the local server (case-insensitive) — the
+ * caller then proceeds with the local-server code path. Returns the raw
+ * argument verbatim when it names a non-local server, which the reducer
+ * surfaces as `402 ERR_NOSUCHSERVER`.
+ */
+function serverTargetOf(rawServer: string, localServerName: string): string | undefined {
+  if (rawServer.length === 0) return undefined;
+  if (rawServer.toLowerCase() === localServerName.toLowerCase()) return undefined;
+  return rawServer;
+}
+
 /**
  * Extracts the channel names a reducer will read for the supplied command.
  * Used by `prefetchChannelState` to refresh only the channels the upcoming
@@ -708,8 +938,11 @@ function splitCsv(param: string): string[] {
  * Commands not listed here either have no channel target (PING, NICK, …)
  * or read channel membership from `ctx.connection.joinedChannels` directly
  * (QUIT), so they don't need a prefetch.
+ *
+ * Exported so the per-command dispatch table can be unit-tested without
+ * standing up a full {@link ConnectionActor} + runtime.
  */
-function channelTargetsForMessage(msg: IrcMessage): ChanName[] {
+export function channelTargetsForMessage(msg: IrcMessage): ChanName[] {
   const cmd = msg.command;
   switch (cmd) {
     case 'JOIN':

package/packages/irc-server/src/dispatch.ts

@@ -33,6 +33,7 @@ const handlers: { [K in Effect['tag']]: Handler<Extract<Effect, { tag: K }>> } =
   ChangeNick: (e, r) => r.changeNick(e.conn, e.oldNick, e.newNick).then(noop),
   ReleaseNick: (e, r) => r.releaseNick(e.nick),
   ApplyChannelDelta: (e, r) => r.applyChannelDelta(e.chan, e.delta),
+  BroadcastWallops: (e, r) => r.broadcastWallops(e.lines, e.except),
 };
 
 function noop(): void {}

package/packages/irc-server/src/routing.ts

@@ -52,6 +52,7 @@ import {
   privmsgChannelReducer,
   privmsgUserReducer,
   quitReducer,
+  setnameReducer,
   tagmsgChannelReducer,
   tagmsgUserReducer,
   timeReducer,
@@ -80,6 +81,7 @@ export interface RoutedReducers {
   readonly cap: Reducer<ConnectionState>;
   readonly authenticate: Reducer<ConnectionState>;
   readonly away: Reducer<ConnectionState>;
+  readonly setname: Reducer<ConnectionState>;
   readonly version: Reducer<ConnectionState>;
   readonly time: Reducer<ConnectionState>;
   readonly admin: Reducer<ConnectionState>;
@@ -150,6 +152,7 @@ export function buildRoutedReducers(serverConfig: ServerConfig): RoutedReducers
     cap: wrap(capReducer),
     authenticate: wrap(authenticateReducer),
     away: wrap(awayReducer),
+    setname: wrap(setnameReducer),
     version: wrap(versionReducer),
     time: wrap(timeReducer),
     admin: wrap(adminReducer),

package/packages/irc-server/src/runtime.ts

@@ -17,6 +17,7 @@ import type {
   ConnectionState,
   Nick,
   RawLine,
+  ServerConfig,
 } from '@serverless-ircd/irc-core';
 
 export interface IrcRuntime {
@@ -35,6 +36,24 @@ export interface IrcRuntime {
     lines: RawLine[],
     notFoundLines?: RawLine[],
   ): Promise<void>;
+  /**
+   * Global cross-connection fanout for `WALLOPS`. Delivers `lines` to every
+   * live connection whose `+w` user mode is set, skipping `except` (the
+   * originator, so an oper never receives their own wallops). Unlike
+   * {@link broadcast} this is NOT channel-scoped — it reaches connections
+   * with no shared channel membership.
+   *
+   * Each adapter applies its own cost cap and enumeration strategy:
+   *   - in-memory: scans its connection map, filters `+w`.
+   *   - Cloudflare: walks the sharded registry to enumerate connIds, then
+   *     fetches each state to check `+w`. Capped to bound the fan-out RPC
+   *     count; document a ceiling for very large fleets.
+   *   - AWS: `Scan`s the `Connections` table and `PostToConnection`s each
+   *     `+w` row. DynamoDB `Scan` reads scale with table size, so this is
+   *     expensive at high connection counts — callers should bound the
+   *     oper's WALLOPS rate.
+   */
+  broadcastWallops(lines: RawLine[], except?: ConnId): Promise<void>;
 
   // nickname registry
   reserveNick(nick: Nick, conn: ConnId): Promise<{ ok: true } | { ok: false }>;
@@ -58,4 +77,16 @@ export interface IrcRuntime {
   getChannelSnapshot(chan: ChanName): Promise<ChanSnapshot | null>;
   getChannelConnections(chan: ChanName): Promise<ReadonlyMap<ConnId, ConnectionState>>;
   listChannels(): Promise<ChanSnapshot[]>;
+  /**
+   * Re-fetches the deployment's {@link ServerConfig} from the adapter's bound
+   * source (CF: KV/secret env; AWS: Secrets Manager/SSM env; local-cli: the
+   * config file/options) and returns the fresh value. The caller (the
+   * ConnectionActor's `REHASH` route) swaps its live config reference with
+   * the result; on rejection the previous config stays in effect.
+   *
+   * Modelled as a request/response runtime method — like `lookupNick` /
+   * `getConnection` — rather than a fire-and-forget `Effect`, because the
+   * refreshed value must come back to the actor.
+   */
+  reloadConfig(): Promise<ServerConfig>;
 }

package/packages/irc-server/src/transport.ts

@@ -15,6 +15,10 @@
  * parser/reducer/dispatch pipeline.
  */
 
+import { splitFrameLines } from '@serverless-ircd/irc-core';
+
+export { splitFrameLines };
+
 /**
  * The line-framing contract a {@link ConnectionActor} consumes. `feed`
  * returns the complete IRC lines terminated within `chunk`; a stateful
@@ -25,14 +29,13 @@ export interface Transport {
 }
 
 /**
- * Splits a WebSocket text frame into IRC lines. Tolerates `\r\n`, bare `\n`,
- * and a missing trailing terminator (a WS frame is a complete unit). Returns
- * each line bare (no CRLF). This is the legacy-tolerant WS contract.
+ * Splits a WebSocket text frame into IRC lines. Re-exported from
+ * `@serverless-ircd/irc-core` (`ws-framing.ts`), which owns the canonical
+ * legacy-tolerant framing so the IRCv3 spec-mode framing and this legacy
+ * behaviour never diverge. Tolerates `\r\n`, bare `\n`, and a missing
+ * trailing terminator (a WS frame is a complete unit). Returns each line
+ * bare (no CRLF). This is the legacy-tolerant WS contract.
  */
-export function splitFrameLines(text: string): string[] {
-  if (text.length === 0) return [];
-  return text.split(/\r?\n/u);
-}
 
 /**
  * Stateless WS-frame transport: one {@link feed} call per inbound text frame.