serverless-ircd 0.4.0 → 0.6.0

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

@@ -27,34 +27,57 @@
 
 import {
   type AccountStore,
+  type AwayStore,
   type ChanName,
   type ChannelState,
   type Clock,
   type ConnSnapshot,
   type ConnectionState,
+  DEFAULT_MONITOR_LIMIT,
+  DEFAULT_MULTILINE_MAX_BYTES,
   Effect,
   type Effect as EffectType,
   EmptyMotdProvider,
   type IdFactory,
   type IrcMessage,
+  LABELED_RESPONSE_CAP_NAME,
   type Logger,
   type MessageStore,
+  type MonitorStore,
   type MotdProvider,
   type MtlsIdentityProvider,
+  type MultilineEntry,
   type NickHistoryStore,
   NoopLoggerInstance,
   Numerics,
   type RawLine,
+  type ReadMarkerStore,
   type ServerConfig,
+  type ServerStats,
+  applyLabelToEffects,
   buildCtx,
+  buildMultilineFanout,
   chathistoryReducer,
+  extractLabel,
+  finalizeMultilineBatch,
   handleJoinZero,
+  hostmaskOf,
   isChannelTarget,
   isonReducer,
+  killReducer,
   listReducer,
+  lusersReducer,
+  monitorReducer,
+  multilineByteLength,
   parse,
+  recordMultilineMessage,
+  rehashLine,
+  rehashReducer,
+  statsReducer,
   toSnapshot,
+  traceReducer,
   userhostReducer,
+  wallopsReducer,
   whoReducer,
   whoisReducer,
   whowasReducer,
@@ -100,6 +123,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 +168,53 @@ export interface ConnectionActorOptions {
    * preserves the no-store behaviour: `WHOWAS <nick>` emits `406`+`369`.
    */
   readonly history?: NickHistoryStore;
+  /**
+   * Read-marker persistence source for IRCv3 `draft/read-marker` (absent
+   * when the deployment does not persist read markers). When bound,
+   * `ctx.readMarkers` is defined so a `+draft/read-marker=<msgid>` TAGMSG
+   * from an identified, cap-enabled client updates the per-`(account,
+   * channel)` marker, and SASL identify seeds the connection's
+   * `lastReadMarkers` from the stored values. Omitted (→ `ctx.readMarkers`
+   * undefined) preserves the session-only marker behaviour: the connection
+   * still tracks its own read position via chathistory playback, but the
+   * marker is not shared across connections or restored on reconnect.
+   */
+  readonly readMarkers?: ReadMarkerStore;
+  /**
+   * Away-status persistence source for IRCv3 `draft/pre-away` (absent
+   * when the deployment does not persist away reasons). When bound,
+   * `ctx.away` is defined so a set/clear of `AWAY` from an identified
+   * connection mirrors the change into the per-`account` record, and
+   * SASL identify replays the stored reason onto the connection (emitting
+   * `306 RPL_NOWAWAY`) so a reconnect restores the user's away state.
+   * Omitted (→ `ctx.away` undefined) preserves the session-only
+   * behaviour: the connection still tracks its own `AWAY` but the reason
+   * is not shared across connections or restored on reconnect.
+   */
+  readonly away?: AwayStore;
+  /**
+   * Monitor-subscription registry for the IRCv3 `MONITOR` command (absent
+   * when MONITOR push notifications are disabled). When bound, the actor
+   * syncs each connection's watchlist into the store and the store's
+   * online/offline hooks fan `730`/`731` lines out to subscribed watchers.
+   * Omitted (→ no push notifications) preserves the existing behaviour
+   * for callers that have not opted in: `MONITOR +nick` still works
+   * synchronously (the reducer resolves online/offline status against
+   * the store's `onlineNicks` snapshot) but no async push fires when a
+   * watched nick later connects or quits.
+   */
+  readonly monitor?: MonitorStore;
+  /**
+   * 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
@@ -160,13 +237,24 @@ export interface ConnectionActorOptions {
    * pipeline is shared unchanged across both transports.
    */
   readonly transport?: Transport;
+  /**
+   * Transport-level TLS fact (PLAN §5 / docs/PlanExtensions.md "user mode
+   * `S`"). Set to `true` when the connection arrived over TLS — a `wss://`
+   * WebSocket or an `irc+tls://` raw TCP connection. The actor stamps it
+   * onto `state.secure` at construction; the registration reducer then
+   * surfaces it as read-only user mode `S` (visible in `221`/`WHOIS`,
+   * rejected by the `MODE` parser with `501`). Defaults to `false` so
+   * plain-transport tests and deployments keep the pre-TLS-mode behaviour.
+   */
+  readonly secure?: boolean;
 }
 
 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 +262,10 @@ export class ConnectionActor {
   private readonly accounts: AccountStore | undefined;
   private readonly mtlsIdentity: MtlsIdentityProvider | undefined;
   private readonly history: NickHistoryStore | undefined;
+  private readonly readMarkers: ReadMarkerStore | undefined;
+  private readonly away: AwayStore | undefined;
+  private readonly monitor: MonitorStore | undefined;
+  private readonly stats: ServerStats | undefined;
   private readonly reducers: RoutedReducers;
   /**
    * Line-framing seam. Turns inbound input (a WS text frame or a raw TCP
@@ -194,12 +286,29 @@ export class ConnectionActor {
    * that need a non-undefined id in test assertions.
    */
   private readonly pinnedTraceId: string | undefined;
+  /**
+   * In-progress IRCv3 `draft/multiline` batch, if any. Set when the client
+   * sends `BATCH +id draft/multiline :<target>` (and the connection
+   * negotiated the cap), populated by each intervening `PRIVMSG`/`NOTICE`,
+   * and cleared when the closing `BATCH -id` is finalized. While set, the
+   * actor diverts `PRIVMSG`/`NOTICE` into the accumulator instead of
+   * running the normal channel/user reducers.
+   */
+  private openMultilineBatch:
+    | {
+        readonly id: string;
+        readonly target: string;
+        command: 'PRIVMSG' | 'NOTICE';
+        readonly entries: MultilineEntry[];
+      }
+    | undefined;
 
   constructor(opts: ConnectionActorOptions) {
     this.state = opts.state;
     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 +316,10 @@ export class ConnectionActor {
     this.accounts = opts.accounts;
     this.mtlsIdentity = opts.mtlsIdentity;
     this.history = opts.history;
+    this.readMarkers = opts.readMarkers;
+    this.away = opts.away;
+    this.monitor = opts.monitor;
+    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
@@ -221,6 +334,15 @@ export class ConnectionActor {
     // regardless of which authority owns the command's state.
     this.reducers = buildRoutedReducers(opts.serverConfig);
     this.transport = opts.transport ?? new WsTextFrameTransport();
+    // Surface the transport's TLS fact on the connection state so the
+    // registration reducer can stamp read-only user mode `S` from it.
+    // Only stamped when the caller explicitly asserts the fact; adapters
+    // that reconstruct the actor from persisted state (where `secure` was
+    // already written at construction time) omit the option so the
+    // deserialized value survives untouched.
+    if (opts.secure !== undefined) {
+      this.state.secure = opts.secure;
+    }
   }
 
   /**
@@ -285,12 +407,75 @@ export class ConnectionActor {
     // the channel authority (e.g. CF ChannelDO). Done before `route` so the
     // synchronous reducers observe up-to-date rosters / modes / topics.
     await this.prefetchChannelState(msg);
-    const effects = await this.route(msg);
+    const label = extractLabel(msg.tags);
+    const effects = await this.route(msg, label);
+    const labeled = this.applyLabel(effects, label);
+    await dispatch(labeled, this.runtime, this.dispatchOpts(log, traceId));
+    // After dispatch completes the bound MonitorStore (if any) may have
+    // enqueued `730`/`731` pushes for ReserveNick/ChangeNick/ReleaseNick
+    // transitions; turn each into one `Send` effect and dispatch them in a
+    // follow-up pass. Kept separate from the original effects array so the
+    // reducer's outputs continue to dedupe against themselves, not against
+    // fan-out sends.
+    await this.drainMonitorPushes(log, traceId);
+  }
+
+  /**
+   * Drains pending {@link MonitorPush}es from the bound {@link MonitorStore}
+   * and dispatches one `Send` effect per push. The watcher's nick is
+   * resolved via the live {@link ConnectionState} so the wire line carries
+   * the canonical spelling (`*` placeholder when the watcher is no longer
+   * registered — the runtime drops the send in that case anyway).
+   */
+  private async drainMonitorPushes(log: Logger, traceId: string): Promise<void> {
+    if (this.monitor === undefined) return;
+    const pushes = this.monitor.drainPushes();
+    if (pushes.length === 0) return;
+    const effects: EffectType[] = [];
+    for (const push of pushes) {
+      const watcher = await this.runtime.getConnection(push.connId);
+      const watcherNick = watcher?.nick ?? '*';
+      const code = push.status === 'online' ? Numerics.RPL_MONONLINE : Numerics.RPL_MONOFFLINE;
+      const codeStr = code.toString().padStart(3, '0');
+      effects.push(
+        Effect.send(push.connId, [
+          { text: `:${this.serverConfig.serverName} ${codeStr} ${watcherNick} :${push.display}` },
+        ]),
+      );
+    }
+    // `effects` has one entry per push; pushes was non-empty (early
+    // return above), so the second dispatch always has work to do.
     await dispatch(effects, this.runtime, this.dispatchOpts(log, traceId));
   }
 
   private dispatchOpts(log: Logger, traceId: string): DispatchOptions {
-    return { logger: log, traceId, connectionId: this.state.id };
+    return {
+      logger: log,
+      traceId,
+      connectionId: this.state.id,
+      ...(this.monitor !== undefined ? { monitor: this.monitor } : {}),
+    };
+  }
+
+  /**
+   * IRCv3 `labeled-response` wrapping.
+   *
+   * When the inbound message carried a `+label` client tag AND the requester
+   * negotiated both `batch` and `labeled-response`, every `Send`-to-self the
+   * reducer emitted is gathered into one `BATCH +label labeled-response …
+   * -label` frame (and an empty batch is emitted when there was no reply).
+   * Otherwise the effect list is returned unchanged.
+   *
+   * The label is read back from {@link Ctx.label} (plumbed through `route`)
+   * so the correlation is attributable to the same per-invocation context the
+   * reducers observed.
+   */
+  private applyLabel(effects: EffectType[], label: string | undefined): EffectType[] {
+    if (label === undefined) return effects;
+    if (!this.state.caps.has('batch') || !this.state.caps.has(LABELED_RESPONSE_CAP_NAME)) {
+      return effects;
+    }
+    return applyLabelToEffects(effects, { label, connId: this.state.id });
   }
 
   /**
@@ -306,7 +491,7 @@ export class ConnectionActor {
     await Promise.all(targets.map((name) => refresh.call(this.channels, name)));
   }
 
-  private async route(msg: IrcMessage): Promise<EffectType[]> {
+  private async route(msg: IrcMessage, label: string | undefined): Promise<EffectType[]> {
     const ctx = buildCtx({
       serverConfig: this.serverConfig,
       clock: this.clock,
@@ -317,8 +502,21 @@ export class ConnectionActor {
       ...(this.accounts !== undefined ? { accounts: this.accounts } : {}),
       ...(this.mtlsIdentity !== undefined ? { mtlsIdentity: this.mtlsIdentity } : {}),
       ...(this.history !== undefined ? { history: this.history } : {}),
+      ...(this.readMarkers !== undefined ? { readMarkers: this.readMarkers } : {}),
+      ...(this.away !== undefined ? { away: this.away } : {}),
+      ...(label !== undefined ? { label } : {}),
     });
 
+    // While a `draft/multiline` batch is open, intervening PRIVMSG/NOTICE
+    // lines are accumulated into the batch instead of being delivered
+    // immediately. The closing BATCH -id finalizes and fans the batch out.
+    if (
+      this.openMultilineBatch !== undefined &&
+      (msg.command === 'PRIVMSG' || msg.command === 'NOTICE')
+    ) {
+      return this.accumulateMultilineLine(msg);
+    }
+
     switch (msg.command) {
       // -------- Connection-authority commands --------
       case 'PING':
@@ -337,12 +535,18 @@ 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 'BATCH':
+        return this.routeBatch(msg, ctx);
       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':
@@ -357,6 +561,8 @@ export class ConnectionActor {
         return this.routeUserhost(msg, ctx);
       case 'ISON':
         return this.routeIson(msg, ctx);
+      case 'MONITOR':
+        return this.routeMonitor(msg, ctx);
 
       // -------- Channel-authority commands --------
       case 'JOIN':
@@ -382,6 +588,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 +634,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 +657,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 +727,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 +813,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 +889,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 +913,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);
       }
@@ -540,6 +928,74 @@ export class ConnectionActor {
     return isonReducer(online, msg, ctx).effects;
   }
 
+  /**
+   * Routes `MONITOR <sub> [<nicks>]` to the monitor reducer. Resolves the
+   * currently-online nicks (folded → display) via the nick registry so the
+   * reducer can emit `730`/`731` synchronously. The reducer also updates
+   * `state.monitorList`; the actor then forwards adds/removes to the bound
+   * {@link MonitorStore} (when present) so future online/offline
+   * transitions push `730`/`731` to the watcher.
+   */
+  private async routeMonitor(
+    msg: IrcMessage,
+    ctx: ReturnType<typeof buildCtx>,
+  ): Promise<EffectType[]> {
+    // Resolve every nick the reducer might consult — the union of the
+    // existing watchlist and any newly-requested targets — so the reducer
+    // can emit `730`/`731` synchronously without an O(N) lookupNick call
+    // per nick inside its own loop. Mirrors the routeIson pattern.
+    const requested =
+      msg.params[1] !== undefined
+        ? msg.params[1]
+            .split(',')
+            .map((s) => s.trim())
+            .filter((s) => s.length > 0)
+        : [];
+    const candidates = new Set<string>(ctx.connection.monitorList ?? []);
+    for (const n of requested) candidates.add(n);
+    const online = await this.resolveOnlineMap(candidates);
+
+    const before = new Set(ctx.connection.monitorList ?? []);
+    const effects = monitorReducer(online, DEFAULT_MONITOR_LIMIT, msg, ctx).effects;
+    // Sync the watchlist delta (if any) into the bound MonitorStore so
+    // later ReserveNick / ReleaseNick dispatches can fire push effects.
+    if (this.monitor !== undefined) {
+      const after = ctx.connection.monitorList ?? new Set<string>();
+      this.monitor.sync(ctx.connId, before, after);
+      // Remove the connection's subscription entirely when its watchlist
+      // becomes empty — keeps the reverse index tidy.
+      if (after.size === 0) {
+        this.monitor.unsubscribe(ctx.connId);
+      }
+    }
+    return effects;
+  }
+
+  /**
+   * Resolves each candidate nick via the runtime's nick registry and
+   * returns a folded-keyed → display-spelling map of the online subset.
+   * Mirrors {@link routeIson}'s per-nick lookup loop.
+   */
+  private async resolveOnlineMap(candidates: Iterable<string>): Promise<Map<string, string>> {
+    const online = new Map<string, string>();
+    for (const nick of candidates) {
+      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). When the connection is alive its nick is defined (the
+      // registry only resolves nicks that have been reserved, which sets
+      // `nick` on the state), so the optional chain is purely defensive
+      // against that race.
+      const display = conn?.nick;
+      if (display !== undefined) {
+        online.set(display.toLowerCase(), display);
+      }
+    }
+    return online;
+  }
+
   /**
    * Routes `CHATHISTORY <sub> <target> [<args>...]` to the chathistory
    * reducer. The command is query-only and must NOT create a channel as a
@@ -553,6 +1009,213 @@ export class ConnectionActor {
    * Cap-gating, param validation, and batch framing all live in the pure
    * reducer — this method only resolves the channel and delegates.
    */
+  /**
+   * Routes an inbound `BATCH +id …` / `BATCH -id` frame. The only
+   * client-initiated batch type this server honours is `draft/multiline`
+   * (and only when the connection negotiated both `batch` and
+   * `draft/multiline`); every other form falls through to
+   * {@link unknownCommandEffect} (`421`), preserving the pre-batch behaviour.
+   *
+   * On `+id draft/multiline :<target>` the actor opens the accumulator
+   * ({@link openMultilineBatch}); intervening PRIVMSG/NOTICE frames populate
+   * it ({@link accumulateMultilineLine}); `BATCH -id` finalizes the batch
+   * via the pure {@link finalizeMultilineBatch} reducer (channel target) or
+   * the actor-side per-recipient path (nick target) and returns its fanout
+   * effects.
+   */
+  private async routeBatch(
+    msg: IrcMessage,
+    ctx: ReturnType<typeof buildCtx>,
+  ): Promise<EffectType[]> {
+    const marker = msg.params[0] ?? '';
+    // `+<id>` opens a batch; `-<id>` closes one. Anything else is malformed.
+    if (marker.startsWith('+')) {
+      return this.beginMultilineBatch(marker.slice(1), msg, ctx);
+    }
+    if (marker.startsWith('-')) {
+      return this.closeMultilineBatch(marker.slice(1), ctx);
+    }
+    return [this.unknownCommandEffect(msg.command)];
+  }
+
+  /**
+   * Opens a `draft/multiline` accumulator. Requires the connection to have
+   * negotiated both `batch` and `draft/multiline`; otherwise the open is
+   * rejected as an unknown command (the client cannot legally send the
+   * frame without the caps).
+   */
+  private beginMultilineBatch(
+    id: string,
+    msg: IrcMessage,
+    _ctx: ReturnType<typeof buildCtx>,
+  ): EffectType[] {
+    // Cap gate: the client must have negotiated both caps to use the frame.
+    if (!this.state.caps.has('batch') || !this.state.caps.has('draft/multiline')) {
+      return [this.unknownCommandEffect(msg.command)];
+    }
+    // Only the `draft/multiline` batch type is supported client→server.
+    const type = msg.params[1];
+    const target = msg.params[2];
+    if (type !== 'draft/multiline' || target === undefined || target.length === 0) {
+      return [this.unknownCommandEffect(msg.command)];
+    }
+    // Reject re-open while another batch is mid-flight: the IRCv3 batch spec
+    // forbids reusing a ref id while one is open. Surface as 421 so the
+    // client does not silently lose the first batch's lines.
+    if (this.openMultilineBatch !== undefined) {
+      return [this.unknownCommandEffect(msg.command)];
+    }
+    this.openMultilineBatch = { id, target, command: 'PRIVMSG', entries: [] };
+    // The open marker itself produces no server→client reply.
+    return [];
+  }
+
+  /**
+   * Accumulates one intervening PRIVMSG/NOTICE line into the open
+   * `draft/multiline` batch. The inner line's target must match the batch
+   * target and (after the first line) its command must match too; a
+   * mismatch aborts the batch with a `FAIL` and clears the accumulator.
+   */
+  private accumulateMultilineLine(msg: IrcMessage): EffectType[] {
+    const open = this.openMultilineBatch;
+    if (open === undefined) return [];
+    const target = msg.params[0];
+    const text = msg.params[1] ?? '';
+    // Target mismatch: the spec requires every inner line to address the
+    // batch's target. Abort the batch.
+    if (target !== open.target) {
+      this.openMultilineBatch = undefined;
+      return [
+        Effect.send(this.state.id, [
+          {
+            text: `:${this.serverConfig.serverName} FAIL BATCH MULTILINE_INVALID_TARGET ${open.target} :Inner line target does not match the batch target`,
+          },
+        ]),
+      ];
+    }
+    const command = msg.command as 'PRIVMSG' | 'NOTICE';
+    // The first inner line pins the command; subsequent lines must match.
+    if (open.entries.length === 0) {
+      open.command = command;
+    } else if (command !== open.command) {
+      this.openMultilineBatch = undefined;
+      return [
+        Effect.send(this.state.id, [
+          {
+            text: `:${this.serverConfig.serverName} FAIL BATCH MULTILINE_MIXED_COMMANDS ${open.target} :Multi-line batch mixes PRIVMSG and NOTICE`,
+          },
+        ]),
+      ];
+    }
+    open.entries.push({ text });
+    return [];
+  }
+
+  /**
+   * Finalizes an open `draft/multiline` batch on `BATCH -id`. Channel targets
+   * delegate to the pure {@link finalizeMultilineBatch} reducer (cap-split
+   * Broadcast). Nick targets use the actor-side per-recipient path
+   * ({@link closeMultilineBatchToNick}) because the recipient is a single
+   * connection whose caps must be resolved before delivery. An unknown /
+   * mismatched id, or a close with no batch open, falls through to `421`.
+   */
+  private async closeMultilineBatch(
+    id: string,
+    ctx: ReturnType<typeof buildCtx>,
+  ): Promise<EffectType[]> {
+    const open = this.openMultilineBatch;
+    if (open === undefined || open.id !== id) {
+      return [this.unknownCommandEffect('BATCH')];
+    }
+    this.openMultilineBatch = undefined;
+    const maxBytes = this.serverConfig.multilineMaxBytes ?? DEFAULT_MULTILINE_MAX_BYTES;
+    if (isChannelTarget(open.target)) {
+      const result = finalizeMultilineBatch(open.target, open.command, open.entries, maxBytes, ctx);
+      return result.effects;
+    }
+    return this.closeMultilineBatchToNick(open, maxBytes, ctx);
+  }
+
+  /**
+   * Finalizes a nick-target multi-line batch. Resolves the single recipient
+   * via the nick registry, inspects their caps, and delivers the appropriate
+   * wire form: the batched replay to `draft/multiline`+`batch` peers, the
+   * tagged joined PRIVMSG to `message-tags` peers, or the bare joined
+   * PRIVMSG to legacy peers. PRIVMSG surfaces `401 ERR_NOSUCHNICK` when the
+   * recipient is offline; NOTICE is silently dropped (RFC: NOTICE MUST NOT
+   * generate numerics).
+   */
+  private async closeMultilineBatchToNick(
+    open: {
+      readonly id: string;
+      readonly target: string;
+      readonly command: 'PRIVMSG' | 'NOTICE';
+      readonly entries: readonly MultilineEntry[];
+    },
+    maxBytes: number,
+    ctx: ReturnType<typeof buildCtx>,
+  ): Promise<EffectType[]> {
+    if (open.entries.length === 0) {
+      return [];
+    }
+
+    const bytes = multilineByteLength(open.entries);
+    if (bytes > maxBytes) {
+      return [
+        Effect.send(ctx.connId, [
+          {
+            text: `:${ctx.serverName} FAIL BATCH MULTILINE_MAX_BYTES ${open.target} :Multi-line batch exceeds the ${maxBytes} byte limit`,
+          },
+        ]),
+      ];
+    }
+
+    const recipientConnId = await this.runtime.lookupNick(open.target);
+    if (recipientConnId === null) {
+      return this.nickNotFoundEffects(open, ctx);
+    }
+    const recipient = await this.runtime.getConnection(recipientConnId);
+    if (recipient === null) {
+      return this.nickNotFoundEffects(open, ctx);
+    }
+
+    const hostmask = hostmaskOf(this.state) ?? '?';
+    const batchId = ctx.ids.batchId();
+    const fanout = buildMultilineFanout(open.target, open.command, open.entries, hostmask, batchId);
+    const msgid = ctx.ids.nonce();
+    recordMultilineMessage(ctx, open.target, open.command, fanout.joined, msgid);
+
+    let lines: RawLine[];
+    if (recipient.caps.has('draft/multiline') && recipient.caps.has('batch')) {
+      lines = [...fanout.batchedReplay];
+    } else if (recipient.caps.has('message-tags')) {
+      lines = [fanout.taggedJoined];
+    } else {
+      lines = [fanout.bareJoined];
+    }
+
+    return [Effect.send(recipientConnId, lines)];
+  }
+
+  /**
+   * Builds the `401 ERR_NOSUCHNICK` effect for an offline nick-target batch
+   * close. PRIVMSG surfaces the error; NOTICE returns nothing (the RFC
+   * forbids numerics in response to NOTICE).
+   */
+  private nickNotFoundEffects(
+    open: { readonly target: string; readonly command: 'PRIVMSG' | 'NOTICE' },
+    ctx: ReturnType<typeof buildCtx>,
+  ): EffectType[] {
+    if (open.command === 'NOTICE') return [];
+    const nick = ctx.connection.nick ?? '*';
+    const code = Numerics.ERR_NOSUCHNICK.toString().padStart(3, '0');
+    return [
+      Effect.send(ctx.connId, [
+        { text: `:${ctx.serverName} ${code} ${nick} ${open.target} :No such nick/channel` },
+      ]),
+    ];
+  }
+
   private async routeChathistory(
     msg: IrcMessage,
     ctx: ReturnType<typeof buildCtx>,
@@ -699,6 +1362,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 +1385,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':