serverless-ircd 0.4.0 → 0.5.0

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

@@ -35,9 +35,12 @@ import {
   type Nick,
   type RawLine,
   type RosterEntry,
+  type ServerConfig,
   toSnapshot,
 } from '@serverless-ircd/irc-core';
 import type { IrcRuntime } from '@serverless-ircd/irc-server';
+import type { CfConfigEnv } from './config-loader.js';
+import { loadServerConfigFromCfEnv } from './config-loader.js';
 import type { ChannelRegistryRpc, Env, RegistryRpc } from './env.js';
 import type { PersistedConnectionState } from './serialize.js';
 import { deserialize } from './serialize.js';
@@ -144,6 +147,48 @@ export class CfRuntime implements IrcRuntime {
     }
   }
 
+  /**
+   * Global cross-connection fan-out for `WALLOPS`. Enumerates every registry
+   * shard to collect all live connection ids, fetches each connection's
+   * state to honour the `+w` recipient gate, and delivers via the
+   * ConnectionDO `deliver` RPC. `except` (the originator) is skipped, as is
+   * the bound connection's own live state shortcut.
+   *
+   * Cost: this is N shard RPCs + one `getConnState` per online connection +
+   * one `deliver` per `+w` recipient. At very high connection counts the
+   * per-WALLOPS cost grows linearly with the fleet; deployments should bound
+   * the oper's WALLOPS rate (an oper flooding WALLOPS is a self-DoS). The
+   * shard walk is parallelised via `Promise.all` so wall-clock stays near one
+   * round-trip for the enumeration phase.
+   */
+  async broadcastWallops(lines: RawLine[], except?: ConnId): Promise<void> {
+    // Phase 1 — enumerate every connId across all registry shards.
+    const shardEntries = await Promise.all(
+      Array.from({ length: this.registryShards }, (_, i) => this.registryShardRpc(i).listEntries()),
+    );
+    const seen = new Set<ConnId>();
+    for (const entries of shardEntries) {
+      for (const [, connId] of entries) {
+        seen.add(connId);
+      }
+    }
+
+    // Phase 2 — fetch each candidate's state, filter +w, deliver.
+    // Bound the per-call fan-out by skipping the excepted/bound connection
+    // up front (the bound connection's own +w never needs a self-RPC).
+    await Promise.all(
+      Array.from(seen, async (connId) => {
+        if (connId === except || connId === this.connId) return;
+        const stub = this.env.CONNECTION_DO.get(this.env.CONNECTION_DO.idFromString(connId));
+        const dto = await (stub as unknown as ConnectionRpc).getConnState();
+        if (dto === null) return;
+        const state = deserialize(dto);
+        if (!state.userModes.wallops) return;
+        await (stub as unknown as ConnectionRpc).deliver(lines);
+      }),
+    );
+  }
+
   // -------------------------------------------------------------------------
   // Nick registry
   // -------------------------------------------------------------------------
@@ -265,6 +310,16 @@ export class CfRuntime implements IrcRuntime {
     return snapshots.filter((s): s is ChanSnapshot => s !== null);
   }
 
+  /**
+   * Re-reads the bound Workers env (vars + secrets, the config source for
+   * Cloudflare deployments) and reparses it through the shared schema. The
+   * actor swaps its live config with the result; a rejection leaves the
+   * previous config in effect.
+   */
+  async reloadConfig(): Promise<ServerConfig> {
+    return loadServerConfigFromCfEnv(this.env as unknown as CfConfigEnv);
+  }
+
   // -------------------------------------------------------------------------
   // Internal
   // -------------------------------------------------------------------------
@@ -281,6 +336,16 @@ export class CfRuntime implements IrcRuntime {
     return stub as unknown as RegistryRpc;
   }
 
+  /**
+   * Returns the registry DO RPC stub for shard index `i` (`0 <= i < shards`).
+   * Used by global fan-out paths (WALLOPS) that must enumerate every shard
+   * rather than address the one owning a specific nick.
+   */
+  private registryShardRpc(i: number): RegistryRpc {
+    const stub = this.env.REGISTRY_DO.get(this.env.REGISTRY_DO.idFromName(`s${i}`));
+    return stub as unknown as RegistryRpc;
+  }
+
   /** Returns the channel DO RPC stub for `name` (keyed by lowercased name). */
   private channelRpc(name: ChanName): {
     broadcast(lines: unknown[], except?: string): Promise<void>;
@@ -319,7 +384,7 @@ export function makeCfRuntime(
   handlers: CfConnectionHandlers,
 ): IrcRuntime {
   // `_registryKey` is ignored — the production CfRuntime always shards the
-  // registry by nick (the prior per-conn key was a 033 scaffolding
+  // registry by nick (the prior per-conn key was a scaffolding
   // convention that the real RegistryDO does not use).
   void _registryKey;
   return new CfRuntime(env, connId, handlers);

package/packages/cf-adapter/src/channel-do.ts

@@ -30,7 +30,7 @@
  * RPC return-type note: snapshot reads return the JSON-friendly
  * {@link ChannelSnapshotDto} (members/banMasks/pendingInvites as
  * arrays) so they survive the DO RPC boundary without relying on
- * structured-clone of `Map`/`Set`. The CfRuntime (036)
+ * structured-clone of `Map`/`Set`. The CfRuntime
  * rehydrates these into a full {@link ChanSnapshot} at the call site.
  */
 
@@ -89,7 +89,7 @@ export interface ConnectionDeliveryRpc {
  * JSON-friendly snapshot DTO returned by `getChannelSnapshot`. Maps and
  * Sets are flattened to arrays so the value survives the DO RPC
  * boundary in both production and the test pool. The CfRuntime
- * (036) rehydrates this into a {@link ChanSnapshot} at the
+ * rehydrates this into a {@link ChanSnapshot} at the
  * call site.
  */
 export interface ChannelSnapshotDto {

package/packages/cf-adapter/src/connection-do.ts

@@ -16,9 +16,8 @@
  *   - `alarm()`                       PING sweep; missing PONG disconnects.
  *
  * Cross-DO coordination:
- *   - `REGISTRY_DO` — sharded nick registry (034).
- *   - `CHANNEL_DO` per lowercased channel — authoritative roster/modes
- *     (035).
+ *   - `REGISTRY_DO` — sharded nick registry.
+ *   - `CHANNEL_DO` per lowercased channel — authoritative roster/modes.
  *
  * The actor's `ActorChannelAccess` is a passthrough that returns
  * throwaway {@link ChannelState} objects — reducers mutate the local
@@ -52,35 +51,40 @@ import {
   type ServerConfig,
   SystemClock,
   UuidIdFactory,
+  type WsFrameMode,
   createChannel,
   createConnection,
+  frameToLines,
+  isWithinWsByteBudget,
+  parseSecWsProtocolOffers,
+  sanitizeForTextMode,
+  selectSubprotocol,
   toSnapshot,
+  wsFrameModeFor,
 } from '@serverless-ircd/irc-core';
-import { ConnectionActor } from '@serverless-ircd/irc-server';
+import { ConnectionActor, type Transport } from '@serverless-ircd/irc-server';
 import { makeCfRuntime } from './cf-runtime.js';
 import type { CfConnectionHandlers } from './cf-runtime.js';
+import { loadServerConfigFromCfEnv } from './config-loader.js';
 import { resolveAccountStore } from './d1-account-store.js';
 import type { Env } from './env.js';
 import { STATE_STORAGE_KEY, deserialize, serialize } from './serialize.js';
 import type { PersistedConnectionState } from './serialize.js';
+import { CfStats } from './stats.js';
 
 /** Default PING cadence (ms) — tuned for typical IRC client behavior. */
 export const DEFAULT_PING_INTERVAL_MS = 60_000;
 /** Default no-PONG disconnect threshold (ms). */
 export const DEFAULT_PONG_TIMEOUT_MS = 90_000;
 
-/** Server config defaults; production deployments override via env. */
-const DEFAULT_SERVER_CONFIG: ServerConfig = {
-  serverName: 'irc.example.com',
-  networkName: 'ServerlessIRCd',
-  maxChannelsPerUser: 30,
-  maxTargetsPerCommand: 10,
-  maxListEntries: 50,
-  nickLen: 30,
-  channelLen: 50,
-  topicLen: 390,
-  quitMessage: 'Client Quit',
-};
+/**
+ * Wall-clock timestamp captured at this worker isolate's first module load
+ * (cold start). Used as the `uptimeStartedAt` anchor for {@link CfStats} so
+ * `STATS u` reports uptime for the current isolate. A dedicated stats DO
+ * would supply a deployment-wide uptime (future work); for now each
+ * isolate reports its own.
+ */
+const WORKER_STARTUP_AT = Date.now();
 
 /**
  * ConnectionDO instance.
@@ -91,6 +95,13 @@ const DEFAULT_SERVER_CONFIG: ServerConfig = {
 export class ConnectionDO extends DurableObject<Env> {
   /** Cached connection state; reloaded from storage after hibernation. */
   private cached: ConnectionState | undefined;
+  /**
+   * Cached reducer-facing server config. Parsed once from `this.env`
+   * (bindings are stable for the DO's lifetime) so the schema-validated
+   * `loadServerConfigFromCfEnv` runs a single time rather than on every
+   * WebSocket frame.
+   */
+  private cachedServerConfig: ServerConfig | undefined;
   /**
    * Per-instance channel-state cache. Reused across every WebSocket frame
    * the connection handles (within a single hibernation cycle) so that
@@ -150,15 +161,17 @@ export class ConnectionDO extends DurableObject<Env> {
   private readonly ids: IdFactory = new UuidIdFactory();
   private readonly pingIntervalMs: number = DEFAULT_PING_INTERVAL_MS;
   private readonly pongTimeoutMs: number = DEFAULT_PONG_TIMEOUT_MS;
-  // Outbound lines are batched per call, not via a reserved instance
-  // field: `deliver()` joins every line of a ChannelDO broadcast into a
-  // single `WebSocket.send()`, and the actor `send` handler in
-  // `buildActor` does the same for one frame's response. Cross-call
-  // per-microtask coalescing (the optimization previously reserved here)
-  // was dropped — it would add a drain queue and ordering hazards between
-  // independent fan-out calls for no measured benefit (see ADR-003 and
-  // the CF adapter load-test report). Revisit only if WS round-trips
-  // become a demonstrated bottleneck.
+  // Outbound lines are batched per call (legacy mode), not via a reserved
+  // instance field: a legacy `deliver()` joins every line of a ChannelDO
+  // broadcast into a single `WebSocket.send()`, and the legacy actor `send`
+  // handler in `buildActor` does the same for one frame's response. An
+  // IRCv3 spec-mode connection instead sends one line per WS message with
+  // no trailing CR-LF (see `sendOutbound`). Cross-call per-microtask
+  // coalescing (the optimization previously reserved here) was dropped — it
+  // would add a drain queue and ordering hazards between independent
+  // fan-out calls for no measured benefit (see ADR-003 and the CF adapter
+  // load-test report). Revisit only if WS round-trips become a demonstrated
+  // bottleneck.
 
   // -------------------------------------------------------------------------
   // WebSocket upgrade
@@ -180,12 +193,23 @@ export class ConnectionDO extends DurableObject<Env> {
     if (cf !== undefined && typeof cf.tlsClientAuthCertSubject === 'string') {
       this.mtlsCertSubject = cf.tlsClientAuthCertSubject;
     }
+    // IRCv3 WebSocket subprotocol negotiation: read the offered
+    // `Sec-WebSocket-Protocol` list, select the first supported entry, and
+    // echo it back when one was agreed. The negotiated frame mode is tagged
+    // onto the hibernated socket so it survives eviction and can be
+    // recovered in every event handler (webSocketMessage / deliver / alarm).
+    const offerHeader = request.headers.get('Sec-WebSocket-Protocol');
+    const chosen = selectSubprotocol(parseSecWsProtocolOffers(offerHeader));
+    const mode = wsFrameModeFor(chosen ?? undefined);
     // Hibernation: `acceptWebSocket` accepts the server side implicitly.
-    // Calling `server.accept()` first throws "already accepted".
-    this.ctx.acceptWebSocket(server);
+    // Calling `server.accept()` first throws "already accepted". The tag
+    // records the negotiated frame mode for the outbound + inbound paths.
+    this.ctx.acceptWebSocket(server, [`ws:${mode}`]);
     // Schedule the first PING sweep.
     await this.ctx.storage.setAlarm(Date.now() + this.pingIntervalMs);
-    return new Response(null, { status: 101, webSocket: client });
+    const headers = new Headers();
+    if (chosen !== null) headers.set('Sec-WebSocket-Protocol', chosen);
+    return new Response(null, { status: 101, webSocket: client, headers });
   }
 
   // -------------------------------------------------------------------------
@@ -194,12 +218,33 @@ export class ConnectionDO extends DurableObject<Env> {
 
   /** Frame → actor → dispatch → persist. */
   override async webSocketMessage(ws: WebSocket, message: string | ArrayBuffer): Promise<void> {
-    const text = typeof message === 'string' ? message : new TextDecoder().decode(message);
+    const mode = this.wsFrameMode(ws);
+    // text.ircv3.net is a text-only subprotocol: a binary frame on such a
+    // connection is a protocol violation. RFC 6455 close code 1003 (unsupported
+    // data) is the spec-mandated response.
+    if (mode === 'spec-text' && typeof message !== 'string') {
+      ws.close(1003, 'binary frame not permitted on text.ircv3.net');
+      return;
+    }
+    const raw = typeof message === 'string' ? message : new TextDecoder().decode(message);
+    // IRCv3 WebSocket spec: a single message MUST fit the 510-byte budget
+    // (the 512-byte IRC line limit minus the omitted trailing CR-LF). An
+    // oversize message is a protocol violation; RFC 6455 close code 1009
+    // (Message Too Big) is the spec-mandated response. Legacy connections
+    // keep the parser's existing 512-byte line cap, so the budget is
+    // enforced for negotiated spec modes only.
+    if ((mode === 'spec-text' || mode === 'spec-binary') && !isWithinWsByteBudget(raw)) {
+      ws.close(1009, 'Message Too Big');
+      return;
+    }
+    // text.ircv3.net frames are UTF-8 text; lone surrogates have no valid
+    // encoding and are substituted with U+FFFD before framing.
+    const text = mode === 'spec-text' ? sanitizeForTextMode(raw) : raw;
     const state = await this.loadState();
     const beforeNick = state.nick;
 
     await this.loadAccountStore();
-    const actor = this.buildActor(ws, state);
+    const actor = this.buildActor(ws, state, mode);
     try {
       await actor.receiveTextFrame(text);
     } finally {
@@ -242,7 +287,7 @@ export class ConnectionDO extends DurableObject<Env> {
    * been idle past the PONG timeout, closes it.
    *
    * PLAN §6.1 — DO alarms are the canonical PING/idle mechanism on CF;
-   * equivalent to EventBridge Scheduler on AWS (042).
+   * equivalent to EventBridge Scheduler on AWS.
    */
   override async alarm(): Promise<void> {
     const state = await this.loadState();
@@ -260,7 +305,8 @@ export class ConnectionDO extends DurableObject<Env> {
     // Send PING. PONG replies update lastSeen via the actor.
     const token = this.ids.nonce();
     for (const ws of this.ctx.getWebSockets()) {
-      (ws as WebSocket).send(`PING :${token}\r\n`);
+      const socket = ws as WebSocket;
+      this.sendOutbound(socket, [{ text: `PING :${token}` }], this.wsFrameMode(socket));
     }
     await this.ctx.storage.setAlarm(now + this.pingIntervalMs);
   }
@@ -291,14 +337,11 @@ export class ConnectionDO extends DurableObject<Env> {
    */
   async deliver(lines: RawLine[]): Promise<{ delivered: number }> {
     let delivered = 0;
-    let text: string | undefined;
-    if (lines.length > 0) {
-      text = `${lines.map((l) => l.text).join('\r\n')}\r\n`;
-    }
     for (const ws of this.ctx.getWebSockets()) {
       const socket = ws as WebSocket;
       if (socket.readyState !== WebSocket.OPEN) continue;
-      if (text !== undefined) socket.send(text);
+      const mode = this.wsFrameMode(socket);
+      this.sendOutbound(socket, lines, mode);
       delivered++;
     }
     return { delivered };
@@ -308,6 +351,44 @@ export class ConnectionDO extends DurableObject<Env> {
   // Internal helpers
   // -------------------------------------------------------------------------
 
+  /**
+   * Recovers the negotiated WebSocket frame mode for `ws` from its
+   * hibernation tag. The tag is written once in `fetch` and survives DO
+   * eviction, so this returns the correct mode on every wake. Defaults to
+   * the legacy-tolerant mode when no tag is present (e.g. a socket accepted
+   * before subprotocol negotiation existed).
+   */
+  private wsFrameMode(ws: WebSocket): WsFrameMode {
+    return wsFrameModeFromTags(this.ctx.getTags(ws));
+  }
+
+  /**
+   * Writes `lines` to `ws` according to `mode`:
+   *   - `spec-text`   — one `ws.send` per line, no trailing CR-LF, lone
+   *                     surrogates substituted with U+FFFD (UTF-8 safety).
+   *   - `spec-binary` — one `ws.send` per line as a UTF-8 binary frame,
+   *                     no trailing CR-LF.
+   *   - `legacy`      — all lines joined with `\r\n` plus a trailing
+   *                     `\r\n`, sent as a single WebSocket message.
+   *
+   * No-ops when the socket is closed or `lines` is empty (preserving the
+   * empty-payload probe contract of {@link deliver}).
+   */
+  private sendOutbound(ws: WebSocket, lines: RawLine[], mode: WsFrameMode): void {
+    if (ws.readyState !== WebSocket.OPEN) return;
+    if (lines.length === 0) return;
+    if (mode === 'spec-text') {
+      for (const line of lines) ws.send(sanitizeForTextMode(line.text));
+      return;
+    }
+    if (mode === 'spec-binary') {
+      const enc = new TextEncoder();
+      for (const line of lines) ws.send(enc.encode(line.text));
+      return;
+    }
+    ws.send(`${lines.map((l) => l.text).join('\r\n')}\r\n`);
+  }
+
   /** Loads the connection state from storage, caching for the event. */
   private async loadState(): Promise<ConnectionState> {
     if (this.cached !== undefined) return this.cached;
@@ -330,27 +411,28 @@ export class ConnectionDO extends DurableObject<Env> {
   }
 
   /**
-   * Constructs an actor wired to this DO's CfRuntime.
+   * Constructs an actor wired to this DO's CfRuntime. `mode` drives both the
+   * inbound line-framing transport (spec mode: one IRC message per frame,
+   * never split; legacy: split on `\r\n`) and the outbound delivery shape
+   * (spec mode: one `WebSocket.send` per line, no trailing CR-LF; legacy:
+   * batched into a single `\r\n`-joined frame).
    */
-  private buildActor(ws: WebSocket, state: ConnectionState): ConnectionActor {
+  private buildActor(ws: WebSocket, state: ConnectionState, mode: WsFrameMode): ConnectionActor {
     const serverConfig = this.serverConfig();
     const motd = this.motdProvider();
     const handlers = {
       send: (lines: RawLine[]): void => {
-        if (ws.readyState === WebSocket.OPEN) {
-          const text = `${lines.map((l) => l.text).join('\r\n')}\r\n`;
-          ws.send(text);
-        }
+        this.sendOutbound(ws, lines, mode);
       },
       disconnect: (reason?: string): void => {
-        if (reason !== undefined && ws.readyState === WebSocket.OPEN) {
-          ws.send(`ERROR :Closing link: (${reason})\r\n`);
+        if (reason !== undefined) {
+          this.sendOutbound(ws, [{ text: `ERROR :Closing link: (${reason})` }], mode);
         }
         ws.close();
       },
       snapshot: (): ConnectionState | undefined => this.cached,
     };
-    // The CfRuntime shards the registry by nick (034); the per-connection
+    // The CfRuntime shards the registry by nick; the per-connection
     // key passed here is ignored by `makeCfRuntime` (kept in the signature
     // for call-site stability).
     const registryKey = this.ctx.id.toString();
@@ -372,11 +454,18 @@ export class ConnectionDO extends DurableObject<Env> {
       runtime,
       channels: this.channelAccess,
       serverConfig,
+      configSource: 'KV',
       clock: this.clock,
       ids: this.ids,
       motd,
       messages: this.messageStore(),
       history: this.historyStore(),
+      // CfStats fans out across the channel + connection RPCs the runtime
+      // already exposes. `uptimeStartedAt` is captured at the worker's
+      // module load (cold start); a dedicated stats DO would give a
+      // deployment-wide uptime, tracked as future work.
+      stats: new CfStats(runtime, WORKER_STARTUP_AT),
+      transport: makeWsFrameTransport(mode),
       ...(accounts !== undefined ? { accounts } : {}),
       ...(mtlsIdentity !== undefined ? { mtlsIdentity } : {}),
       logger,
@@ -387,7 +476,7 @@ export class ConnectionDO extends DurableObject<Env> {
   private async tearDown(ws: WebSocket): Promise<void> {
     const state = await this.loadState();
     await this.loadAccountStore();
-    const actor = this.buildActor(ws, state);
+    const actor = this.buildActor(ws, state, this.wsFrameMode(ws));
     // Drive QUIT through the actor so the same effect pipeline handles
     // fanout as during normal operation.
     await actor.receiveTextFrame('QUIT\r\n');
@@ -415,13 +504,17 @@ export class ConnectionDO extends DurableObject<Env> {
   }
 
   private serverConfig(): ServerConfig {
-    return {
-      ...DEFAULT_SERVER_CONFIG,
-      ...(this.env.SERVER_NAME !== undefined ? { serverName: this.env.SERVER_NAME } : {}),
-      ...(this.env.NETWORK_NAME !== undefined ? { networkName: this.env.NETWORK_NAME } : {}),
-      ...(this.env.SERVER_VERSION !== undefined ? { serverVersion: this.env.SERVER_VERSION } : {}),
-      ...(this.env.CREATED_AT !== undefined ? { createdAt: this.env.CREATED_AT } : {}),
-    };
+    // Single source of truth: delegate to the schema-validated loader so
+    // every reducer-facing field (operCreds, serverPassword, motdLines,
+    // limit knobs, …) is populated from `this.env` exactly as the shared
+    // `ServerConfigSchema` prescribes. The previous hand-rolled literal
+    // silently dropped fields like operCreds, which left OPER unable to
+    // authenticate (491 ERR_NOOPERHOST) even when OPER_USER/OPER_PASSWORD
+    // were bound. See config-loader.ts and config.ts.
+    if (this.cachedServerConfig === undefined) {
+      this.cachedServerConfig = loadServerConfigFromCfEnv(this.env);
+    }
+    return this.cachedServerConfig;
   }
 
   private motdProvider(): MotdProvider {
@@ -522,6 +615,7 @@ export class ConnectionDO extends DurableObject<Env> {
       runtime,
       channels: this.channelAccess,
       serverConfig: this.serverConfig(),
+      configSource: 'KV',
       clock: this.clock,
       ids: this.ids,
       motd: this.motdProvider(),
@@ -724,3 +818,37 @@ export function parseSaslAccountsEnv(raw: string | undefined): SaslAccountCreden
   }
   return out;
 }
+
+/**
+ * Hibernation-tag prefixes written by {@link ConnectionDO.fetch}. Each tag
+ * encodes the negotiated {@link WsFrameMode} so it survives DO eviction and
+ * can be recovered in every WebSocket event handler via `ctx.getTags(ws)`.
+ */
+const WS_TAG_LEGACY = 'ws:legacy';
+const WS_TAG_SPEC_TEXT = 'ws:spec-text';
+const WS_TAG_SPEC_BINARY = 'ws:spec-binary';
+
+/**
+ * Recovers the {@link WsFrameMode} from a hibernated socket's tags.
+ * Defaults to the legacy-tolerant mode when no recognized tag is present.
+ */
+export function wsFrameModeFromTags(tags: readonly string[]): WsFrameMode {
+  for (const tag of tags) {
+    if (tag === WS_TAG_SPEC_TEXT) return 'spec-text';
+    if (tag === WS_TAG_SPEC_BINARY) return 'spec-binary';
+    if (tag === WS_TAG_LEGACY) return 'legacy';
+  }
+  return 'legacy';
+}
+
+/**
+ * Builds the inbound line-framing {@link Transport} for `mode`. Spec modes
+ * treat one WebSocket message as exactly one IRC line (a single trailing
+ * CR-LF is stripped and the frame is never split); legacy mode splits the
+ * frame on `\r\n` so older clients that concatenate messages keep working.
+ */
+export function makeWsFrameTransport(mode: WsFrameMode): Transport {
+  return {
+    feed: (chunk: string): string[] => frameToLines(chunk, mode),
+  };
+}

package/packages/cf-adapter/src/env.ts

@@ -9,9 +9,9 @@
 /**
  * The production {@link Env} for `apps/cf-worker`. ConnectionDO uses the
  * four DO namespaces below to coordinate with the registry, channel, and
- * channel-registry authorities. The CfRuntime (036) wires them together
+ * channel-registry authorities. The CfRuntime wires them together
  * behind the platform-agnostic {@link IrcRuntime} port; ConnectionDO
- * (033) only needs `CONNECTION_DO` itself plus the three collaborator
+ * only needs `CONNECTION_DO` itself plus the three collaborator
  * namespaces.
  *
  * RPC method shapes on {@link RegistryRpc} and {@link ChannelRpc} are
@@ -23,7 +23,7 @@ export interface Env {
   CONNECTION_DO: DurableObjectNamespace;
   /**
    * Nick registry authority. RPC: reserveNick / changeNick / releaseNick /
-   * lookupNick. Backed by the sharded {@link RegistryDO} (034), which keys
+   * lookupNick. Backed by the sharded {@link RegistryDO}, which keys
    * instances by `hash(nick) % N` so the single-threaded DO gives the nick
    * uniqueness invariant for free.
    *
@@ -34,7 +34,7 @@ export interface Env {
   /**
    * Channel authority, keyed by lowercased channel name. RPC: broadcast /
    * applyChannelDelta / getChannelSnapshot / listMembers. Backed by the
-   * {@link ChannelDO} (035), which owns the authoritative roster, modes,
+   * {@link ChannelDO}, which owns the authoritative roster, modes,
    * topic, and ban list and fans out broadcasts to each member's
    * ConnectionDO.
    */
@@ -77,22 +77,41 @@ export interface Env {
    * end-to-end. Empty/undefined disables SASL account verification.
    */
   SASL_ACCOUNTS?: string;
+  /**
+   * IRC operator name consulted by the `OPER` reducer. Pair with
+   * {@link OPER_PASSWORD}; when either is set the connection-do threads
+   * both into the reducer-facing `ServerConfig.operCreds` via
+   * `loadServerConfigFromCfEnv`.
+   */
+  OPER_USER?: string;
+  /**
+   * IRC operator password paired with {@link OPER_USER}. Treat as a
+   * Cloudflare secret (never a plaintext `[vars]` entry) in production.
+   */
+  OPER_PASSWORD?: string;
 }
 
 /**
  * RPC contract ConnectionDO expects from the registry. The real
- * RegistryDO (034) and the test stub both implement this.
+ * RegistryDO and the test stub both implement this.
  */
 export interface RegistryRpc {
   reserveNick(nick: string, conn: string): Promise<{ ok: true } | { ok: false }>;
   changeNick(conn: string, oldNick: string, newNick: string): Promise<boolean>;
   releaseNick(nick: string): Promise<void>;
   lookupNick(nick: string): Promise<string | null>;
+  /**
+   * Enumerates every `(nickLower, connectionId)` entry in this shard. Used
+   * by global fan-out paths (e.g. `WALLOPS`) that need to reach connections
+   * regardless of shared channel membership. Returns a plain array so the
+   * RPC marshals cleanly across the DO boundary.
+   */
+  listEntries(): Promise<Array<[nickLower: string, connId: string]>>;
 }
 
 /**
  * RPC contract ConnectionDO expects from each channel instance. The real
- * ChannelDO (035) and the test stub both implement this.
+ * ChannelDO and the test stub both implement this.
  *
  * Note: `broadcast` accepts already-formatted raw line texts (no
  * `RawLine` wrapper) because that's what `cf-runtime.broadcast`

package/packages/cf-adapter/src/index.ts

@@ -23,6 +23,8 @@ export {
 } from './sharding.js';
 export { makeCfRuntime } from './cf-runtime.js';
 export type { CfConnectionHandlers } from './cf-runtime.js';
+export { CfStats } from './stats.js';
+export type { CfStatsRuntime } from './stats.js';
 export type { ChannelRpc, ChannelRegistryRpc, Env, RegistryRpc } from './env.js';
 export {
   CREATE_ACCOUNTS_TABLE_SQL,

package/packages/cf-adapter/src/registry-do.ts

@@ -23,8 +23,8 @@
  * and the second sees the new owner and fails.
  *
  * RPC surface — implements {@link RegistryRpc}, the same shape the
- * stub `RecordingRegistryDO` exposed for 033. Consumers
- * (`CfRuntime`, 036) call these methods via `env.REGISTRY_DO`
+ * stub `RecordingRegistryDO` exposed for the connection tests. Consumers
+ * (`CfRuntime`) call these methods via `env.REGISTRY_DO`
  * after computing the shard key with {@link registryKeyForNick}.
  */
 
@@ -85,7 +85,7 @@ export class RegistryDO extends DurableObject implements RegistryRpc {
    *     `oldNick` after this conn abandoned it (defence in depth).
    *
    * Cross-shard changes (old and new hash to different shards) are
-   * orchestrated by `CfRuntime` in 036 as a two-phase
+   * orchestrated by `CfRuntime` as a two-phase
    * reserve-new-then-release-old. This DO only sees single-shard
    * changes and crash-recovery paths (where `oldNick` may not be
    * present); the latter is why the conditional delete is a soft check.
@@ -127,4 +127,23 @@ export class RegistryDO extends DurableObject implements RegistryRpc {
     const owner = await this.ctx.storage.get<string>(nickKey(nick.toLowerCase()));
     return owner ?? null;
   }
+
+  /**
+   * Enumerates every `(nickLower, connectionId)` pair in this shard.
+   * Backs the global WALLOPS fan-out: the caller scans every shard, collects
+   * all connection ids, and delivers to those carrying the `+w` mode. The
+   * walk is a single `list` over the `nick:` prefix; cost is proportional to
+   * the slice's live nick count (sharded, so bounded per DO).
+   */
+  async listEntries(): Promise<Array<[nickLower: string, connId: string]>> {
+    const out: Array<[nickLower: string, connId: string]> = [];
+    // `storage.list` resolves to a Map of `key → value` for the prefix.
+    // Each key is `nick:<lower>`; we strip the prefix to recover the nick.
+    const entries = await this.ctx.storage.list<string>({ prefix: NICK_KEY_PREFIX });
+    for (const [key, connId] of entries) {
+      const nickLower = key.slice(NICK_KEY_PREFIX.length);
+      out.push([nickLower, connId]);
+    }
+    return out;
+  }
 }

package/packages/cf-adapter/src/sharding.ts

@@ -22,8 +22,7 @@
  * `N` defaults to {@link DEFAULT_REGISTRY_SHARDS} (32) and is
  * configurable per deployment via the worker env. Changing N after
  * production traffic requires a migration (re-sharding every existing
- * nick→conn mapping); document this in `docs/deployment-cf.md`
- * (038).
+ * nick→conn mapping); document this in `docs/deployment-cf.md`.
  */
 
 /**