serverless-ircd 0.1.0

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

@@ -0,0 +1,542 @@
+/**
+ * `ConnectionDO` — Cloudflare Durable Object that owns one IRC
+ * connection's socket + authoritative state.
+ *
+ * PLAN §6.1 — uses {@link DurableObjectState}'s
+ * `HibernatingWebSocketHandler` so idle WebSocket connections cost
+ * nothing between messages. When a message arrives the DO wakes, replays
+ * the persisted {@link ConnectionState} from `state.storage`, runs the
+ * frame through {@link ConnectionActor} with a stub {@link CfRuntime},
+ * and persists the updated state back.
+ *
+ * Lifecycle:
+ *   - `fetch()`                       WebSocket upgrade; `acceptWebSocket`.
+ *   - `webSocketMessage()`            Frame → actor → dispatch → persist.
+ *   - `webSocketClose()`/`Error()`    QUIT fanout + nick release.
+ *   - `alarm()`                       PING sweep; missing PONG disconnects.
+ *
+ * Cross-DO coordination:
+ *   - `REGISTRY_DO` (RPC stub today, real in 034).
+ *   - `CHANNEL_DO` per lowercased channel (stub today, real in 035).
+ *
+ * The actor's `ActorChannelAccess` is a passthrough that returns
+ * throwaway {@link ChannelState} objects — reducers mutate the local
+ * view and emit `ApplyChannelDelta` effects that the CfRuntime forwards
+ * to the authoritative ChannelDO. Sufficient for connection-authority
+ * commands and JOIN/QUIT fan-out; richer channel reads (NAMES of remote
+ * state) ship in 036.
+ */
+
+import { DurableObject } from 'cloudflare:workers';
+import {
+  type ChanName,
+  type ChannelState,
+  type Clock,
+  type ConnId,
+  type ConnectionState,
+  type IdFactory,
+  type MotdProvider,
+  type RawLine,
+  type ServerConfig,
+  SystemClock,
+  UuidIdFactory,
+  applyChannelDelta,
+  createChannel,
+  createConnection,
+  toSnapshot,
+} from '@serverless-ircd/irc-core';
+import { ConnectionActor } from '@serverless-ircd/irc-server';
+import { makeCfRuntime } from './cf-runtime.js';
+import type { CfConnectionHandlers } from './cf-runtime.js';
+import type { Env } from './env.js';
+import { PERSISTED_STATE_VERSION, STATE_STORAGE_KEY, deserialize, serialize } from './serialize.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',
+};
+
+/**
+ * ConnectionDO instance.
+ *
+ * The class is exported as the binding target in `wrangler.toml`; the
+ * Workers runtime instantiates it with `(ctx, env)` per DO id.
+ */
+export class ConnectionDO extends DurableObject<Env> {
+  /** Cached connection state; reloaded from storage after hibernation. */
+  private cached: ConnectionState | undefined;
+  /**
+   * Per-instance channel-state cache. Reused across every WebSocket frame
+   * the connection handles (within a single hibernation cycle) so that
+   * reducers see the roster mutations they performed on prior frames —
+   * e.g. JOIN in frame 1, then PART/TOPIC/MODE in later frames all
+   * share the same ChannelState. Authoritative state still lives in the
+   * ChannelDO; this cache only mirrors the local connection's view.
+   *
+   * Created lazily because `clock.now()` advances and the first frame
+   * should seed `createdAt` with its receive time.
+   */
+  private channelAccess: PassthroughChannelAccess | undefined;
+  private readonly clock: Clock = SystemClock;
+  private readonly ids: IdFactory = new UuidIdFactory();
+  private readonly pingIntervalMs: number = DEFAULT_PING_INTERVAL_MS;
+  private readonly pongTimeoutMs: number = DEFAULT_PONG_TIMEOUT_MS;
+  /** Outstanding outbound lines, drained when the WS sends complete. */
+  // (Reserved for a future batching optimization; kept off until 036.)
+
+  // -------------------------------------------------------------------------
+  // WebSocket upgrade
+  // -------------------------------------------------------------------------
+
+  /** Standard WebSocket upgrade handler. */
+  override async fetch(request: Request): Promise<Response> {
+    if (request.headers.get('Upgrade') !== 'websocket') {
+      return new Response('Expected WebSocket', { status: 426 });
+    }
+    const pair = new WebSocketPair();
+    const server = pair[0];
+    const client = pair[1];
+    // Hibernation: `acceptWebSocket` accepts the server side implicitly.
+    // Calling `server.accept()` first throws "already accepted".
+    this.ctx.acceptWebSocket(server);
+    // Schedule the first PING sweep.
+    await this.ctx.storage.setAlarm(Date.now() + this.pingIntervalMs);
+    return new Response(null, { status: 101, webSocket: client });
+  }
+
+  // -------------------------------------------------------------------------
+  // Hibernating WebSocket event handlers
+  // -------------------------------------------------------------------------
+
+  /** 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 state = await this.loadState();
+    const before = new Set(state.joinedChannels);
+    const beforeNick = state.nick;
+
+    const actor = this.buildActor(ws, state);
+    try {
+      await actor.receiveTextFrame(text);
+    } finally {
+      // Persist any mutations even if dispatch threw partway through.
+      await this.persistState(state);
+    }
+
+    // If registration completed this frame, schedule a PING alarm.
+    if (beforeNick === undefined && state.nick !== undefined) {
+      await this.ctx.storage.setAlarm(Date.now() + this.pingIntervalMs);
+    }
+    // Detect newly joined channels so we can register them with the
+    // channel DO — necessary for the close handler to fan out QUIT to
+    // them. The stub channel DO records the call; the real ChannelDO
+    // (035) maintains authoritative roster state.
+    for (const chan of state.joinedChannels) {
+      if (!before.has(chan)) {
+        // joinReducer already emitted an ApplyChannelDelta; the stub
+        // ChannelDO records it. No extra work needed here for 033.
+        void chan;
+      }
+    }
+  }
+
+  /** QUIT fanout + nick release. RFC 1459: a missing close is a QUIT. */
+  override async webSocketClose(
+    ws: WebSocket,
+    _code: number,
+    _reason: string,
+    _wasClean: boolean,
+  ): Promise<void> {
+    await this.tearDown(ws);
+  }
+
+  /** Same teardown as close. */
+  override async webSocketError(ws: WebSocket, _error: unknown): Promise<void> {
+    await this.tearDown(ws);
+  }
+
+  // -------------------------------------------------------------------------
+  // Alarms (PING / idle sweeps)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Fires on the scheduled alarm. Sends a PING; if the connection has
+   * 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).
+   */
+  override async alarm(): Promise<void> {
+    const state = await this.loadState();
+    const now = this.clock.now();
+    if (state.lastSeen + this.pongTimeoutMs < now) {
+      // Idle past the PONG threshold: tear down.
+      const sockets = this.ctx.getWebSockets();
+      if (sockets.length > 0) {
+        await this.tearDown(sockets[0] as WebSocket);
+      } else {
+        await this.releaseAndPersist(state);
+      }
+      return;
+    }
+    // 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`);
+    }
+    await this.ctx.storage.setAlarm(now + this.pingIntervalMs);
+  }
+
+  // -------------------------------------------------------------------------
+  // RPC — cross-DO fan-out (called by ChannelDO)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Pushes `lines` to every WebSocket attached to this connection. This
+   * is the fan-out target used by {@link ChannelDO}: one broadcast to
+   * a channel becomes N `deliver` calls, one per member's
+   * ConnectionDO.
+   *
+   * Returns `{ delivered: number }` — the number of WebSockets the
+   * lines were written to. Zero signals "no live connection"; callers
+   * (ChannelDO.broadcast / sweep) use that to prune dead roster
+   * entries lazily.
+   *
+   * Hibernation note: `state.getWebSockets()` returns the live set
+   * even after the DO has been evicted and woken back up, because the
+   * runtime tracks them out-of-process. A connection that closed
+   * unilaterally reports an empty list and is pruned on the next
+   * broadcast.
+   *
+   * Empty payload (`lines === []`) is a probe — returns the live
+   * socket count without sending anything. Used by ChannelDO.sweep.
+   */
+  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);
+      delivered++;
+    }
+    return { delivered };
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal helpers
+  // -------------------------------------------------------------------------
+
+  /** Loads the connection state from storage, caching for the event. */
+  private async loadState(): Promise<ConnectionState> {
+    if (this.cached !== undefined) return this.cached;
+    const record = await this.ctx.storage.get(STATE_STORAGE_KEY);
+    if (record === undefined) {
+      this.cached = createConnection({
+        id: this.ctx.id.toString(),
+        connectedSince: this.clock.now(),
+      });
+    } else {
+      this.cached = deserialize(record);
+    }
+    return this.cached;
+  }
+
+  /** Persists the connection state to storage. */
+  private async persistState(state: ConnectionState): Promise<void> {
+    this.cached = state;
+    await this.ctx.storage.put(STATE_STORAGE_KEY, serialize(state));
+  }
+
+  /**
+   * Constructs an actor wired to this DO's CfRuntime.
+   */
+  private buildActor(ws: WebSocket, state: ConnectionState): 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);
+        }
+      },
+      disconnect: (reason?: string): void => {
+        if (reason !== undefined && ws.readyState === WebSocket.OPEN) {
+          ws.send(`ERROR :Closing link: (${reason})\r\n`);
+        }
+        ws.close();
+      },
+      snapshot: (): ConnectionState | undefined => this.cached,
+    };
+    // For 033 stub routing we look up the per-connection registry
+    // stub by the DO instance's hex id. Production (034) shards the
+    // registry by nick instead, at which point `registryKey` is unused.
+    const registryKey = this.ctx.id.toString();
+    const runtime = makeCfRuntime(this.env, state.id, registryKey, handlers);
+    if (this.channelAccess === undefined) {
+      this.channelAccess = new PassthroughChannelAccess(this.clock.now(), this.env);
+    }
+    return new ConnectionActor({
+      state,
+      runtime,
+      channels: this.channelAccess,
+      serverConfig,
+      clock: this.clock,
+      ids: this.ids,
+      motd,
+    });
+  }
+
+  /** Tears down a connection: emit QUIT effects, release nick, close WS. */
+  private async tearDown(ws: WebSocket): Promise<void> {
+    const state = await this.loadState();
+    const actor = this.buildActor(ws, state);
+    // Drive QUIT through the actor so the same effect pipeline handles
+    // fanout as during normal operation.
+    await actor.receiveTextFrame('QUIT\r\n');
+    await this.releaseAndPersist(state);
+    if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
+      ws.close();
+    }
+    try {
+      await this.ctx.storage.deleteAlarm();
+    } catch {
+      // Already cleared; ignore.
+    }
+  }
+
+  /** Releases the nick via the registry and persists the (possibly mutated) state. */
+  private async releaseAndPersist(state: ConnectionState): Promise<void> {
+    if (state.nick !== undefined) {
+      const registryKey = this.ctx.id.toString();
+      const stub = this.env.REGISTRY_DO.get(this.env.REGISTRY_DO.idFromName(registryKey));
+      await (stub as unknown as { releaseNick: (n: string) => Promise<void> }).releaseNick(
+        state.nick,
+      );
+    }
+    await this.persistState(state);
+  }
+
+  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 } : {}),
+    };
+  }
+
+  private motdProvider(): MotdProvider {
+    const raw = this.env.MOTD_LINES;
+    if (raw === undefined || raw.length === 0) {
+      return { lines: () => DEFAULT_MOTD };
+    }
+    // MOTD_LINES is a newline-delimited env var.
+    return { lines: () => raw.split('\n') };
+  }
+
+  // -------------------------------------------------------------------------
+  // Test hooks (only invoked from `runInDurableObject` in tests)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Test hook: explicitly invokes the close-teardown path. Useful when
+   * the test framework does not propagate the WebSocket close event to
+   * hibernated sockets synchronously enough for assertions.
+   */
+  public async __triggerClose(): Promise<void> {
+    const sockets = this.ctx.getWebSockets();
+    const ws = sockets[0];
+    if (ws === undefined) {
+      // No socket attached; run cleanup without it.
+      const state = await this.loadState();
+      await this.tearDownNoSocket(state);
+      return;
+    }
+    await this.tearDown(ws as WebSocket);
+  }
+
+  /** Like {@link tearDown} but without a live WebSocket reference. */
+  private async tearDownNoSocket(state: ConnectionState): Promise<void> {
+    // Emit QUIT effects without dispatching transport calls (the socket
+    // is already gone). The cross-DO fanout still runs.
+    const noOpHandlers: CfConnectionHandlers = {
+      send: (): void => {},
+      disconnect: (): void => {},
+      snapshot: (): ConnectionState | undefined => this.cached,
+    };
+    const registryKey = this.ctx.id.toString();
+    const runtime = makeCfRuntime(this.env, state.id, registryKey, noOpHandlers);
+    if (this.channelAccess === undefined) {
+      this.channelAccess = new PassthroughChannelAccess(this.clock.now(), this.env);
+    }
+    const actor = new ConnectionActor({
+      state,
+      runtime,
+      channels: this.channelAccess,
+      serverConfig: this.serverConfig(),
+      clock: this.clock,
+      ids: this.ids,
+      motd: this.motdProvider(),
+    });
+    await actor.receiveTextFrame('QUIT\r\n');
+    await this.releaseAndPersist(state);
+    try {
+      await this.ctx.storage.deleteAlarm();
+    } catch {
+      // Already cleared.
+    }
+  }
+
+  /** Drops the in-memory state cache, simulating wake-from-hibernation. */
+  public __resetCache(): void {
+    this.cached = undefined;
+  }
+
+  /** Returns the live cached state (without forcing a storage read). */
+  public async __peekState(): Promise<ConnectionState | undefined> {
+    return this.cached;
+  }
+
+  /** Backdates `lastSeen` to test the alarm-driven disconnect path. */
+  public async __backdateLastSeen(deltaMs: number): Promise<void> {
+    const state = await this.loadState();
+    state.lastSeen = this.clock.now() - deltaMs;
+    await this.persistState(state);
+  }
+
+  /** Returns this DO's hex id — the canonical ConnId used in RPC routing. */
+  public __peekHexId(): string {
+    return this.ctx.id.toString();
+  }
+
+  /**
+   * Cross-connection RPC: returns a snapshot of this connection's state.
+   * Called by another connection's {@link CfRuntime} when a
+   * `GetConnectionInfo` effect targets this connection. Loads from storage
+   * on demand (safe to call after hibernation).
+   */
+  public async getConnSnapshot(): Promise<import('@serverless-ircd/irc-core').ConnSnapshot | null> {
+    const state = await this.loadState();
+    return toSnapshot(state);
+  }
+}
+
+/** Default MOTD when no `MOTD_LINES` env is supplied. */
+const DEFAULT_MOTD: string[] = ['Welcome to the ServerlessIRCd Cloudflare adapter.'];
+
+/**
+ * `ActorChannelAccess` backed by a per-instance cache that is refreshed
+ * from the authoritative ChannelDO before each reducer that needs to
+ * observe channel state. The cache is seeded lazily by `getOrCreateChannel`
+ * (for commands like JOIN that create a brand-new channel) and overwritten
+ * by `refreshChannel` (for commands that read existing state: NAMES, MODE,
+ * KICK, PART, TOPIC, PRIVMSG fan-out checks, …).
+ *
+ * The `env` reference lets `refreshChannel` issue a `getChannelSnapshot`
+ * RPC to the right ChannelDO instance. The DTO returned across the RPC
+ * boundary is rehydrated into a proper {@link ChannelState} so the
+ * synchronous reducers can mutate `members` (a Map) and `banMasks` /
+ * `pendingInvites` (Sets) in place.
+ */
+class PassthroughChannelAccess {
+  private readonly cache = new Map<string, ChannelState>();
+  constructor(
+    private readonly now: number,
+    private readonly env: Env,
+  ) {}
+
+  getOrCreateChannel(name: ChanName): ChannelState {
+    const key = name.toLowerCase();
+    const existing = this.cache.get(key);
+    if (existing !== undefined) return existing;
+    const created = createChannel({
+      name,
+      nameLower: key,
+      createdAt: this.now,
+    });
+    this.cache.set(key, created);
+    return created;
+  }
+
+  /**
+   * Pulls the authoritative snapshot for `name` from the ChannelDO and
+   * replaces the local cache entry. No-op if the channel does not exist
+   * remotely (the caller will fall through to `getOrCreateChannel` which
+   * lazily seeds an empty entry).
+   *
+   * Safe to call on a channel the connection has not joined: the snapshot
+   * is read-only and the local cache entry is only consulted by the
+   * reducer running this frame.
+   *
+   * The caller-supplied `name` is preserved verbatim in the rebuilt state
+   * (rather than trusting `dto.name`, which can default to a hex DO id on
+   * channels that were lazily initialised by ChannelDO but never received
+   * an `applyChannelDelta`).
+   */
+  async refreshChannel(name: ChanName): Promise<void> {
+    const key = name.toLowerCase();
+    const id = this.env.CHANNEL_DO.idFromName(key);
+    const stub = this.env.CHANNEL_DO.get(id);
+    const dto = (await (
+      stub as unknown as {
+        getChannelSnapshot: () => Promise<unknown>;
+      }
+    ).getChannelSnapshot()) as {
+      modes: ChannelState['modes'];
+      banMasks: string[];
+      topic?: ChannelState['topic'];
+      members: Array<{ conn: ConnId; nick: string; op: boolean; voice: boolean }>;
+      pendingInvites: string[];
+      createdAt: number;
+    } | null;
+    if (dto === null) return;
+    // Don't replace the cache with an empty snapshot — the channel
+    // effectively doesn't exist yet, and the local reducer should lazily
+    // seed it via getOrCreateChannel. This also avoids clobbering the
+    // local cache with ChannelDO's "name unknown" default state.
+    if (dto.members.length === 0) return;
+    const members = new Map<ConnId, { conn: ConnId; nick: string; op: boolean; voice: boolean }>();
+    for (const entry of dto.members) {
+      members.set(entry.conn, {
+        conn: entry.conn,
+        nick: entry.nick,
+        op: entry.op,
+        voice: entry.voice,
+      });
+    }
+    const rebuilt: ChannelState = {
+      name,
+      nameLower: key,
+      modes: { ...dto.modes },
+      banMasks: new Set(dto.banMasks),
+      ...(dto.topic !== undefined ? { topic: dto.topic } : {}),
+      members,
+      pendingInvites: new Set(dto.pendingInvites),
+      createdAt: dto.createdAt,
+    };
+    this.cache.set(key, rebuilt);
+  }
+}
+
+// Reference `applyChannelDelta` to ensure the import is used downstream by
+// tests that exercise state migrations; harmless if the symbol is unused
+// in production today. (Removed from the ConnectionDO path because the
+// authoritative delta application lives in the ChannelDO stub today.)
+export { applyChannelDelta, PERSISTED_STATE_VERSION };

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

@@ -0,0 +1,67 @@
+/**
+ * Cloudflare Workers environment bindings for the cf-adapter.
+ *
+ * Each binding corresponds to a Durable Object namespace declared in
+ * `wrangler.toml`. The same shape is used in production and tests;
+ * tests register stub implementations in `wrangler.test.toml`.
+ */
+
+/**
+ * The production {@link Env} for `apps/cf-worker`. ConnectionDO uses the
+ * three DO namespaces below to coordinate with the registry and channel
+ * authorities. 036 (CfRuntime) is where the full wiring lives;
+ * 033 (ConnectionDO) only needs `CONNECTION_DO` itself plus the
+ * two collaborator namespaces.
+ *
+ * RPC method shapes on {@link RegistryRpc} and {@link ChannelRpc} are
+ * implemented by both the production DOs and the test stubs in
+ * `tests/worker/stubs/`.
+ */
+export interface Env {
+  /** Per-connection authority: socket + ConnectionState. */
+  CONNECTION_DO: DurableObjectNamespace;
+  /**
+   * Nick registry authority. RPC: reserveNick / changeNick / releaseNick /
+   * lookupNick. Stubbed now (033); real impl in 034.
+   *
+   * Note: the production DO class is what's brand-typed; here we keep the
+   * namespace unparameterized and cast to the RPC surface at the call
+   * site. The full type plumbing lands with 034.
+   */
+  REGISTRY_DO: DurableObjectNamespace;
+  /**
+   * Channel authority, keyed by lowercased channel name. RPC: broadcast /
+   * applyChannelDelta / getChannelSnapshot. Stubbed now; real in 035.
+   */
+  CHANNEL_DO: DurableObjectNamespace;
+  /** Server-level config knobs (name, MOTD lines, limits). */
+  SERVER_NAME: string;
+  NETWORK_NAME: string;
+  MOTD_LINES: string;
+}
+
+/**
+ * RPC contract ConnectionDO expects from the registry. The real
+ * RegistryDO (034) 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>;
+}
+
+/**
+ * RPC contract ConnectionDO expects from each channel instance. The real
+ * ChannelDO (035) 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`
+ * forwards after unwrapping the pure-core `RawLine[]`. The ChannelDO
+ * re-wraps them when calling `ConnectionDO.deliver`.
+ */
+export interface ChannelRpc {
+  broadcast(lines: unknown[], except?: string): Promise<void>;
+  applyChannelDelta(delta: unknown): Promise<void>;
+  getChannelSnapshot(): Promise<unknown>;
+}

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

@@ -0,0 +1,38 @@
+/**
+ * @serverless-ircd/cf-adapter
+ *
+ * Cloudflare Workers adapter for ServerlessIRCd. Implements the three
+ * Durable Objects (ConnectionDO, RegistryDO, ChannelDO) and a
+ * CfRuntime that bridges them behind the platform-agnostic
+ * {@link IrcRuntime} port.
+ *
+ * 033 shipped the {@link ConnectionDO} + a stub CfRuntime.
+ * 034 ships the {@link RegistryDO} (real nick registry with
+ * sharding). The {@link ChannelDO} (roster + modes + fanout) ships
+ * here. The full CfRuntime lands in 036.
+ */
+
+export {
+  ConnectionDO,
+  DEFAULT_PING_INTERVAL_MS,
+  DEFAULT_PONG_TIMEOUT_MS,
+} from './connection-do.js';
+export { RegistryDO } from './registry-do.js';
+export { ChannelDO } from './channel-do.js';
+export type { DeliverResult, ConnectionDeliveryRpc } from './channel-do.js';
+export {
+  DEFAULT_REGISTRY_SHARDS,
+  registryKeyForNick,
+  shardNick,
+} from './sharding.js';
+export { makeCfRuntime } from './cf-runtime.js';
+export type { CfConnectionHandlers } from './cf-runtime.js';
+export type { ChannelRpc, Env, RegistryRpc } from './env.js';
+export {
+  PERSISTED_STATE_VERSION,
+  STATE_STORAGE_KEY,
+  deserialize,
+  migrate,
+  serialize,
+} from './serialize.js';
+export type { PersistedConnectionState } from './serialize.js';