serverless-ircd 0.4.0 → 0.5.0

package/packages/irc-core/src/commands/setname.ts

@@ -0,0 +1,109 @@
+/**
+ * Pure reducer for the IRC `SETNAME` command (RFC 2812 §4.1.7).
+ *
+ * PLAN §2.1 location-of-authority: SETNAME runs in the Connection entity.
+ * The reducer mutates `state.realname` (the GECOS field originally set by
+ * the `USER` reducer) and performs no IO.
+ *
+ * Wire format:
+ *   - `SETNAME :<realname>` — replaces `state.realname`.
+ *   - `461 ERR_NEEDMOREPARAMS` when the realname is missing/empty.
+ *   - `451 ERR_NOTREGISTERED` when issued before registration completes.
+ *
+ * Broadcast decision: there is no standard IRCv3 cap for relaying a
+ * realname change (the `chghost` cap covers user/host, not realname), so
+ * v1 updates `state.realname` silently. A subsequent `WHOIS` reflects the
+ * new value in `311 RPL_WHOISUSER`. A `draft/setname` relay cap is a
+ * documented follow-up.
+ *
+ * Length cap: registration-time `USER` does not enforce a realname length
+ * cap, so this command applies its own via `serverConfig.realnameLen`
+ * (falling back to {@link DEFAULT_REALNAME_LEN}). An over-cap value is
+ * rejected with `432 ERR_ERRONEUSNICKNAME` — the same numeric registration
+ * uses for an over-length `NICK` (the codebase's only registration-time
+ * "value rejected for length" precedent). The offending value is NOT
+ * echoed back so a client cannot amplify a multi-kilobyte payload via the
+ * error reply. Truncation (as `TOPIC` does) is deliberately not used: the
+ * spec frames an over-long realname as a rejection, not a silent trim.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, Reducer } from '../types.js';
+
+/**
+ * Built-in realname length cap when `serverConfig.realnameLen` is unset.
+ * Matches the schema default and the common ircd-seven GECOS ceiling.
+ */
+const DEFAULT_REALNAME_LEN = 50;
+
+/** Fixed trailing text for `461 ERR_NEEDMOREPARAMS` (matches `USER`/`PASS`). */
+const NEEDMOREPARAMS_TRAILING = 'Not enough parameters';
+
+/** Fixed trailing text for `451 ERR_NOTREGISTERED`. */
+const NOTREGISTERED_TRAILING = 'You have not registered';
+
+/** Fixed trailing text for the over-cap `432` rejection. */
+const ERRONEOUS_REALNAME_TRAILING = 'Erroneous realname';
+
+/**
+ * Handles `SETNAME :<realname>`.
+ *
+ * Stamps `lastSeen`, enforces the registration + length gates, and on
+ * success replaces `state.realname` with no broadcast. The reducer never
+ * performs IO.
+ */
+export const setnameReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  if (state.registration !== 'registered') {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_NOTREGISTERED, NOTREGISTERED_TRAILING),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  const realname = msg.params[0];
+  if (realname === undefined || realname.length === 0) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_NEEDMOREPARAMS, NEEDMOREPARAMS_TRAILING, 'SETNAME'),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  const cap = ctx.serverConfig.realnameLen ?? DEFAULT_REALNAME_LEN;
+  if (realname.length > cap) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_ERRONEUSNICKNAME, ERRONEOUS_REALNAME_TRAILING),
+      ]),
+    );
+    return { state, effects };
+  }
+
+  state.realname = realname;
+  return { state, effects };
+};
+
+/**
+ * Builds a `:<server> <code> <nick> [:<middle>] :<trailing>` line. The nick
+ * falls back to `*` when the connection has not yet registered one, and the
+ * optional `middle` is omitted when not supplied — matching the numeric
+ * formatting used by the registration reducers.
+ */
+function numericLine(ctx: Ctx, code: number, trailing: string, middle?: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  const parts = [`:${ctx.serverName}`, codeStr, nick];
+  if (middle !== undefined) parts.push(middle);
+  parts.push(`:${trailing}`);
+  return { text: parts.join(' ') };
+}

package/packages/irc-core/src/commands/stats.ts

@@ -0,0 +1,152 @@
+/**
+ * Pure reducer for the IRC `STATS` command (RFC 2812 §4.6.3).
+ *
+ * PLAN §2.1 location-of-authority: STATS is a read-only diagnostic that
+ * reports server statistics keyed by a single-letter query. The reducer
+ * takes an already-aggregated {@link ServerStatsSnapshot} (the actor
+ * awaits a {@link ServerStats} backend before calling here). The reducer
+ * never mutates anything but the requester's `lastSeen`.
+ *
+ * Wire format (RFC 2812 §5.1 + modern practice):
+ *   - `STATS <query> [<server>]`
+ *   - `211 RPL_STATSLINKINFO` (the `l` query): per-link sendq/byte/msg
+ *     counters. Single-server deployment collapses this to one line for
+ *     the bound server.
+ *   - `242 RPL_STATSUPTIME` (the `u` query):
+ *     `:<server> 242 <nick> :Server Up <d> days, <h>:<mm>:<ss>`
+ *   - `219 RPL_ENDOFSTATS`:
+ *     `:<server> 219 <nick> <query> :End of /STATS report`
+ *   - `402 ERR_NOSUCHSERVER`:
+ *     `:<server> 402 <nick> <server> :No such server`
+ *
+ * Implemented query letters: `u` (uptime), `l` (link info). Unknown letters
+ * follow charybdis semantics: the reducer emits ONLY the `219` terminator
+ * with an empty body (no 461/401/etc). The remaining RFC letters
+ * (`k`/`K`/`q`/`g`/`x`/`z`/…) are deferred behind per-letter tests; the
+ * actor routes them here regardless so a future implementation is just
+ * another case branch.
+ *
+ * `<server>` resolves at the actor layer: a non-local name yields
+ * `402 ERR_NOSUCHSERVER` (single-server network — S2S routing is a PLAN
+ * non-goal). When the actor passes `serverTarget`, the reducer emits ONLY
+ * the 402 and nothing else.
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import type { ServerStatsSnapshot } from '../ports.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { Ctx } from '../types.js';
+
+/** Fixed text emitted for `402 ERR_NOSUCHSERVER`. */
+const NOSUCHSERVER_TRAILING_TEXT = 'No such server';
+
+/** Fixed text emitted for `219 RPL_ENDOFSTATS`. */
+const ENDOFSTATS_TRAILING_TEXT = 'End of /STATS report';
+
+/**
+ * Builds a `:<server> <code> <nick> [<middle>] :<trailing>` numeric line
+ * addressed to the requester. When `middle` is empty the middle field is
+ * still emitted as a bare space-prefixed token (matches charybdis output
+ * for STATS with no query letter).
+ */
+function numericLine(ctx: Ctx, code: number, trailing: string, middle: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  const parts = [`:${ctx.serverName}`, codeStr, nick];
+  parts.push(middle);
+  parts.push(`:${trailing}`);
+  return { text: parts.join(' ') };
+}
+
+/**
+ * Formats an uptime delta (ms) as `Server Up <d> days, <h>:<mm>:<ss>`,
+ * matching charybdis's `RPL_STATSUPTIME` text. Days and hours are not
+ * zero-padded; minutes and seconds are.
+ */
+function formatUptime(deltaMs: number): string {
+  let totalSec = Math.floor(deltaMs / 1000);
+  const days = Math.floor(totalSec / 86_400);
+  totalSec -= days * 86_400;
+  const hours = Math.floor(totalSec / 3_600);
+  totalSec -= hours * 3_600;
+  const minutes = Math.floor(totalSec / 60);
+  totalSec -= minutes * 60;
+  const seconds = totalSec;
+  const mm = minutes.toString().padStart(2, '0');
+  const ss = seconds.toString().padStart(2, '0');
+  return `Server Up ${days} days, ${hours}:${mm}:${ss}`;
+}
+
+/**
+ * Handles `STATS <query> [<server>]`.
+ *
+ * @param snapshot      The aggregated network statistics (only `uptimeStartedAt`
+ *   is consulted here; full counts are surfaced by LUSERS).
+ * @param msg           The parsed `STATS` message.
+ * @param ctx           The per-invocation context.
+ * @param serverTarget  When set, the actor determined `<server>` names a
+ *   non-local server; the reducer emits `402 ERR_NOSUCHSERVER` against this
+ *   name.
+ */
+export function statsReducer(
+  snapshot: ServerStatsSnapshot,
+  msg: { command: string; params: readonly string[] },
+  ctx: Ctx,
+  serverTarget?: string,
+): { effects: EffectType[] } {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+
+  if (serverTarget !== undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_NOSUCHSERVER, NOSUCHSERVER_TRAILING_TEXT, serverTarget),
+      ]),
+    );
+    return { effects };
+  }
+
+  // Normalise: STATS with no query letter is treated as the empty string;
+  // case is folded to lower so the terminator matches the canonical charybdis
+  // output (`STATS U` and `STATS u` both terminate with `219 <nick> u`).
+  const rawQuery = msg.params[0] ?? '';
+  const query = rawQuery.toLowerCase();
+
+  if (query === 'u') {
+    const uptimeMs = ctx.clock.now() - snapshot.uptimeStartedAt;
+    const code = Numerics.RPL_STATSUPTIME.toString().padStart(3, '0');
+    effects.push(
+      Effect.send(ctx.connId, [
+        {
+          text: `:${ctx.serverName} ${code} ${ctx.connection.nick ?? '*'} :${formatUptime(uptimeMs)}`,
+        },
+      ]),
+    );
+  } else if (query === 'l') {
+    // Single-server: one link-info line for the bound server. All sendq /
+    // byte / message counters are zero for a stateless serverless runtime
+    // (no persistent S2S link); the trailing text is the configured server
+    // version so the client sees a self-describing entry.
+    const code = Numerics.RPL_STATSLINKINFO.toString().padStart(3, '0');
+    const requester = ctx.connection.nick ?? '*';
+    const version = ctx.serverConfig.serverVersion ?? '';
+    effects.push(
+      Effect.send(ctx.connId, [
+        {
+          text: `:${ctx.serverName} ${code} ${requester} ${ctx.serverName} 0 0 0 0 0 0 :${version}`,
+        },
+      ]),
+    );
+  }
+  // Terminator always emitted, even for unknown letters (charybdis
+  // semantics: unknown STATS letters produce no body lines, just 219).
+  effects.push(
+    Effect.send(ctx.connId, [
+      numericLine(ctx, Numerics.RPL_ENDOFSTATS, ENDOFSTATS_TRAILING_TEXT, query),
+    ]),
+  );
+
+  return { effects };
+}

package/packages/irc-core/src/commands/topic.ts

@@ -35,12 +35,10 @@ function isValidChannelName(name: string, maxLen: number): boolean {
 }
 
 /** Formats a numeric error/reply line addressed to the connection's nick. */
-function numericErr(ctx: Ctx, code: number, trailing: string, middle?: string): RawLine {
+function numericErr(ctx: Ctx, code: number, trailing: string, middle: string): RawLine {
   const nick = ctx.connection.nick ?? '*';
   const codeStr = code.toString().padStart(3, '0');
-  const parts = [`:${ctx.serverName}`, codeStr, nick];
-  if (middle !== undefined) parts.push(middle);
-  parts.push(`:${trailing}`);
+  const parts = [`:${ctx.serverName}`, codeStr, nick, middle, `:${trailing}`];
   return { text: parts.join(' ') };
 }
 

package/packages/irc-core/src/commands/trace.ts

@@ -0,0 +1,137 @@
+/**
+ * Pure reducer for the IRC `TRACE` command (RFC 2812 §4.6.3).
+ *
+ * PLAN §2.1 location-of-authority: TRACE is a query-only diagnostic. The
+ * actor layer resolves the optional `<target>` and — when it is a nick —
+ * hands the resolved {@link ConnectionState} here. The reducer never
+ * mutates anything but the requester's `lastSeen`.
+ *
+ * In a single-server serverless IRCd, multi-hop routing collapses to the
+ * local server. The classic `200 RPL_TRACELINK` / `206 RPL_TRACESERVER`
+ * server-link dump is therefore trivial (one server, zero hops); modern
+ * daemons emit just the per-connection `205`/`204` lines and the
+ * terminating `262 RPL_ENDOFTRACE`. This reducer follows that convention.
+ *
+ * Wire format (RFC 2812 §4.6.3 + modern practice):
+ *   - `TRACE [<target>]`
+ *   - `205 RPL_TRACEUSER`:
+ *     `:<server> 205 <nick> User <hops> <user> <host>` (per matched conn)
+ *   - `204 RPL_TRACEOPERATOR`:
+ *     `:<server> 204 <nick> Oper <hops> <user> <host>` (oper conns only)
+ *   - `262 RPL_ENDOFTRACE`:
+ *     `:<server> 262 <nick> <target> :End of TRACE`
+ *   - `402 ERR_NOSUCHSERVER`:
+ *     `:<server> 402 <nick> <server> :No such server`
+ *
+ * Detail visibility is oper-gated:
+ *   - Non-opers see only the `262` terminator (no per-connection detail),
+ *     so a non-oper cannot use `TRACE` to enumerate online users. This
+ *     also implicitly enforces `+i` invisibility for non-opers.
+ *   - Opers see one `205`/`204` line per matched connection and bypass
+ *     the `+i` filter (RFC 2812 §4.6.3).
+ */
+
+import { Effect } from '../effects.js';
+import type { Effect as EffectType, RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx } from '../types.js';
+
+/** Fixed text emitted for `402 ERR_NOSUCHSERVER`. */
+const NOSUCHSERVER_TRAILING_TEXT = 'No such server';
+
+/** Fixed text emitted for `262 RPL_ENDOFTRACE`. */
+const ENDOFTRACE_TRAILING_TEXT = 'End of TRACE';
+
+/**
+ * Builds a `:<server> <code> <nick> <Class> <hops> <nick> <user> <host>`
+ * line for one matched connection. `<Class>` is `Oper` for an oper,
+ * otherwise `User` (matching RFC 2812 §4.6.3 + common client rendering).
+ * `<hops>` is always 0 in a single-server deployment.
+ */
+function traceDetailLine(ctx: Ctx, code: number, cls: string, target: ConnectionState): RawLine {
+  const requesterNick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  const tNick = target.nick ?? '*';
+  const tUser = target.user ?? '?';
+  const tHost = target.host ?? '?';
+  return {
+    text: `:${ctx.serverName} ${codeStr} ${requesterNick} ${cls} 0 ${tNick} ${tUser} ${tHost}`,
+  };
+}
+
+/**
+ * Builds a `:<server> <code> <nick> [<middle>] :<trailing>` numeric line
+ * addressed to the requester. When `middle` is empty the middle field is
+ * omitted entirely.
+ */
+function numericLine(ctx: Ctx, code: number, trailing: string, middle: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  const parts = [`:${ctx.serverName}`, codeStr, nick];
+  if (middle !== '') parts.push(middle);
+  parts.push(`:${trailing}`);
+  return { text: parts.join(' ') };
+}
+
+/**
+ * Handles `TRACE [<target>]`.
+ *
+ * The actor layer resolves `<target>`:
+ *   - Empty / absent / equal to the local server name → `target` is
+ *     `undefined` and `serverTarget` is unset; the reducer emits only the
+ *     terminating `262`.
+ *   - A nick that resolves → `target` is the live
+ *     {@link ConnectionState}; the reducer emits `205`/`204` (oper
+ *     requester only) then `262`.
+ *   - A nick that does not resolve → `target` is `undefined`; the reducer
+ *     emits only the `262` (carrying the requested nick).
+ *   - A name that is not the local server (treated as a remote server) →
+ *     the actor passes `serverTarget = '<name>'`; the reducer emits
+ *     `402 ERR_NOSUCHSERVER`.
+ *
+ * @param target        The resolved target connection, or `undefined`.
+ * @param msg           The parsed `TRACE` message.
+ * @param ctx           The per-invocation context.
+ * @param serverTarget  When set, the actor determined `<target>` names a
+ *   non-local server; the reducer emits `402` against this name.
+ */
+export function traceReducer(
+  target: ConnectionState | undefined,
+  msg: { command: string; params: readonly string[] },
+  ctx: Ctx,
+  serverTarget?: string,
+): { effects: EffectType[] } {
+  ctx.connection.lastSeen = ctx.clock.now();
+
+  const effects: EffectType[] = [];
+  const rawTarget = msg.params[0] ?? '';
+
+  if (serverTarget !== undefined) {
+    effects.push(
+      Effect.send(ctx.connId, [
+        numericLine(ctx, Numerics.ERR_NOSUCHSERVER, NOSUCHSERVER_TRAILING_TEXT, serverTarget),
+      ]),
+    );
+    return { effects };
+  }
+
+  const isOper = ctx.connection.userModes.oper;
+  if (target !== undefined && isOper) {
+    // Per-connection detail is oper-gated, which also implicitly enforces
+    // `+i` invisibility for non-opers (they never receive detail). Opers
+    // bypass `+i` per RFC 2812 §4.6.3 and always see the matched conn.
+    const code = target.userModes.oper ? Numerics.RPL_TRACEOPERATOR : Numerics.RPL_TRACEUSER;
+    const cls = target.userModes.oper ? 'Oper' : 'User';
+    effects.push(Effect.send(ctx.connId, [traceDetailLine(ctx, code, cls, target)]));
+  }
+
+  const endMiddle = rawTarget.length > 0 ? rawTarget : '';
+  effects.push(
+    Effect.send(ctx.connId, [
+      numericLine(ctx, Numerics.RPL_ENDOFTRACE, ENDOFTRACE_TRAILING_TEXT, endMiddle),
+    ]),
+  );
+
+  return { effects };
+}

package/packages/irc-core/src/commands/wallops.ts

@@ -0,0 +1,118 @@
+/**
+ * Pure reducer for the IRC `WALLOPS` command (oper-only global broadcast).
+ *
+ * PLAN §2.1 location-of-authority: WALLOPS runs in the Connection entity.
+ * The reducer is pure — it enforces the oper gate, validates the message,
+ * and emits a single {@link BroadcastWallopsEffect}. The bound runtime's
+ * `broadcastWallops` method owns the cross-connection enumeration that
+ * the gate cannot observe purely (it does not see which other
+ * connections carry the `+w` user mode).
+ *
+ * Wire format (RFC 2812 §4.7):
+ *   - `WALLOPS :<message>`
+ *   - `481 ERR_NOPRIVILEGES`:
+ *     `:<server> 481 <nick> :Permission Denied - You're not an IRC operator`
+ *   - `412 ERR_NOTEXTTOSEND`:
+ *     `:<server> 412 <nick> :No text to send`
+ *
+ * Behaviour:
+ *   - Non-oper sender → `481` (checked before the message is inspected, so
+ *     a non-oper cannot probe the command shape).
+ *   - Empty / missing message → `412 ERR_NOTEXTTOSEND`. We pick `412` over
+ *     `461 ERR_NEEDMOREPARAMS` to match the message-bearing commands
+ *     PRIVMSG/NOTICE, which use `412` for "no text to send". WALLOPS is a
+ *     single-param message command, so the semantically closer numeric wins.
+ *   - Otherwise emit `BroadcastWallops([:<oper> WALLOPS :<message>], sender)`
+ *     so the runtime fans the line out to every `+w` connection.
+ *
+ * Delivery / skip-self: the originator is ALWAYS passed as `except`. This
+ * matches NOTICE/PRIVMSG channel-broadcast semantics (the sender never
+ * receives their own message back) and avoids a redundant echo to the
+ * oper who just typed it. The `+w` user mode is the *recipient* gate,
+ * owned by the runtime — the sender's own `+w` is therefore irrelevant
+ * under this default. An oper who wants a delivery receipt can query
+ * logs. (RFC leaves delivery to `+w` regardless of oper; we deliberately
+ * diverge to match the rest of the codebase's broadcast primitives.)
+ *
+ * The `+w` user mode is accepted by the MODE reducer (`w → 'wallops'`)
+ * and advertised in `004 RPL_MYINFO`, but no command consumed it before
+ * this one — setting `+w` used to be a silent no-op. This reducer lights
+ * up the consumer.
+ */
+
+import { Effect } from '../effects.js';
+import type { RawLine } from '../effects.js';
+import { Numerics } from '../protocol/numerics.js';
+import { hostmaskOf } from '../state/connection.js';
+import type { ConnectionState } from '../state/connection.js';
+import type { Ctx, Reducer } from '../types.js';
+
+/** Fixed text emitted for `481 ERR_NOPRIVILEGES` (matches `kill.ts` / `mode.ts`). */
+const NOPRIVILEGES_TRAILING_TEXT = "Permission Denied - You're not an IRC operator";
+
+/** Fixed text emitted for `412 ERR_NOTEXTTOSEND` (matches `privmsg.ts`). */
+const NOTEXTTOSEND_TRAILING_TEXT = 'No text to send';
+
+/**
+ * Renders the `:<source> WALLOPS :<message>` wire line that every `+w`
+ * connection receives. `<source>` is the oper's full hostmask
+ * (`nick!user@host`), consistent with how PRIVMSG/NOTICE/QUIT attribute
+ * user-originated messages. When the hostmask is incomplete (e.g. no
+ * `user`/`host` yet, which should not happen for a registered oper but is
+ * defended against) the bare nick is used, falling back to `*` only when
+ * no nick is set at all.
+ */
+export function wallopsLine(state: ConnectionState, message: string): RawLine {
+  const source = hostmaskOf(state) ?? state.nick ?? '*';
+  return { text: `:${source} WALLOPS :${message}` };
+}
+
+/**
+ * Handles `WALLOPS :<message>`.
+ *
+ * Enforces the oper gate, stamps `lastSeen`, and on success emits a single
+ * {@link BroadcastWallopsEffect} addressed to every `+w` connection. The
+ * sender is always excluded (skip-self). The reducer never performs IO.
+ */
+export const wallopsReducer: Reducer<ConnectionState> = (state, msg, ctx) => {
+  state.lastSeen = ctx.clock.now();
+
+  if (!state.userModes.oper) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.ERR_NOPRIVILEGES, NOPRIVILEGES_TRAILING_TEXT),
+        ]),
+      ],
+    };
+  }
+
+  const message = msg.params[0];
+  if (message === undefined || message.length === 0) {
+    return {
+      state,
+      effects: [
+        Effect.send(ctx.connId, [
+          numericLine(ctx, Numerics.ERR_NOTEXTTOSEND, NOTEXTTOSEND_TRAILING_TEXT),
+        ]),
+      ],
+    };
+  }
+
+  return {
+    state,
+    effects: [Effect.broadcastWallops([wallopsLine(state, message)], ctx.connId)],
+  };
+};
+
+/**
+ * Builds a `:<server> <code> <nick> :<trailing>` line. The nick falls back
+ * to `*` when the connection has not yet registered one, matching the rest
+ * of the codebase's numeric formatting.
+ */
+function numericLine(ctx: Ctx, code: number, trailing: string): RawLine {
+  const nick = ctx.connection.nick ?? '*';
+  const codeStr = code.toString().padStart(3, '0');
+  return { text: [`:${ctx.serverName}`, codeStr, nick, `:${trailing}`].join(' ') };
+}

package/packages/irc-core/src/config.ts

@@ -256,6 +256,13 @@ export const ServerConfigSchema = z.object({
   channelLen: z.number().int().positive().default(50),
   /** Maximum topic length (advertised as `TOPICLEN=`). */
   topicLen: z.number().int().nonnegative().default(390),
+  /**
+   * Maximum realname (GECOS) length enforced by `SETNAME`. There is no
+   * standard ISUPPORT token for this; registration-time `USER` does not
+   * enforce a cap, so the knob is optional on {@link ServerConfig} and the
+   * reducer falls back to a built-in default when unset.
+   */
+  realnameLen: z.number().int().nonnegative().default(50),
   /** Default QUIT reason when the client disconnects without one. */
   quitMessage: z.string().default('Client Quit'),
 

package/packages/irc-core/src/effects.ts

@@ -89,6 +89,26 @@ export interface SendToNickEffect {
   notFoundLines?: RawLine[];
 }
 
+/**
+ * Global cross-connection fanout for `WALLOPS`. Unlike
+ * {@link BroadcastEffect} (channel-scoped via the roster), this reaches
+ * every live connection whose `+w` user mode is set, regardless of shared
+ * channel membership. `except` skips a single connection — by convention
+ * the originator, so an oper never receives their own wallops back
+ * (matching NOTICE/PRIVMSG channel-broadcast semantics).
+ *
+ * The reducer does not know which connections carry `+w`; the bound
+ * runtime's `broadcastWallops` method owns that enumeration. On the
+ * in-memory runtime that is a scan of its connection map; on CF it walks
+ * the registry shards; on AWS it scans the `Connections` table. Each
+ * adapter applies its own cost cap (documented at the method).
+ */
+export interface BroadcastWallopsEffect {
+  tag: 'BroadcastWallops';
+  lines: RawLine[];
+  except?: ConnId;
+}
+
 /** Discriminated union of every effect the dispatch interpreter knows. */
 export type Effect =
   | SendEffect
@@ -98,7 +118,8 @@ export type Effect =
   | ChangeNickEffect
   | ReleaseNickEffect
   | ApplyChannelDeltaEffect
-  | SendToNickEffect;
+  | SendToNickEffect
+  | BroadcastWallopsEffect;
 
 /** Literal string tag of every {@link Effect} variant. */
 export type EffectTag = Effect['tag'];
@@ -158,4 +179,9 @@ export const Effect = {
     if (notFoundLines !== undefined) e.notFoundLines = notFoundLines;
     return e;
   },
+  broadcastWallops(lines: RawLine[], except?: ConnId): Effect {
+    const e: BroadcastWallopsEffect = { tag: 'BroadcastWallops', lines };
+    if (except !== undefined) e.except = except;
+    return e;
+  },
 } as const;

package/packages/irc-core/src/index.ts

@@ -14,6 +14,8 @@ export * from './credential-hashing.js';
 export * from './flood-control.js';
 export * from './cloak.js';
 export * from './case-fold.js';
+export * from './ws-subprotocol.js';
+export * from './ws-framing.js';
 export * from './admission.js';
 export * from './config.js';
 export type {