serverless-ircd 0.1.0 → 0.3.0

package/packages/aws-adapter/tests/transactions.test.ts

@@ -0,0 +1,446 @@
+/**
+ * Membership atomicity for JOIN / PART / KICK (the DynamoDB
+ * `TransactWriteItems` path).
+ *
+ * Each membership mutation must span BOTH tables in a single transaction:
+ *   - `ChannelMembers` (the authoritative roster), AND
+ *   - `Connections.joinedChannels` (the per-connection joined set used
+ *     by `$disconnect` cleanup).
+ *
+ * Without the transaction, a concurrent JOIN of two different channels
+ * by the same connection leaves `joinedChannels` missing one of them
+ * (the second `persistConnectionState` overwrites the first). The
+ * stress test below proves the transactions serialise correctly.
+ *
+ * Gated on `process.env.DDB_AVAILABLE` — needs real DynamoDB Local
+ * (TransactWriteItems semantics aren't faithfully mockable).
+ */
+
+import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
+import { GetCommand, PutCommand, QueryCommand, TransactWriteCommand } from '@aws-sdk/lib-dynamodb';
+import { type ChanName, type Nick, createConnection } from '@serverless-ircd/irc-core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { AwsRuntime, type AwsRuntimeHandlers } from '../src/aws-runtime.js';
+import { TABLE_DEFS } from '../src/cdk-table-defs.js';
+import { createDynamoDocumentClient } from '../src/dynamo.js';
+import { marshalChannelMember, marshalConnection } from '../src/serialize.js';
+import type { TablesConfig } from '../src/tables.js';
+
+const available = process.env.DDB_AVAILABLE === '1';
+const endpoint = process.env.DYNAMO_ENDPOINT;
+
+interface Fixture {
+  tables: TablesConfig;
+  client: ReturnType<typeof createDynamoDocumentClient>;
+  cleanup: () => Promise<void>;
+}
+
+let fx: Fixture | null;
+
+async function makeFixture(): Promise<Fixture> {
+  if (endpoint === undefined) throw new Error('DYNAMO_ENDPOINT missing');
+  const prefix = `x${Date.now()}-${Math.floor(Math.random() * 1e6)}-`;
+  const tables = Object.fromEntries(
+    Object.keys(TABLE_DEFS).map((name) => [name, `${prefix}${name}`]),
+  ) as TablesConfig;
+  const client = createDynamoDocumentClient({ endpoint });
+  for (const [logical, props] of Object.entries(TABLE_DEFS)) {
+    const pkName = props.partitionKey?.name;
+    const skName = props.sortKey?.name;
+    if (pkName === undefined) throw new Error(`table ${logical} missing partitionKey`);
+    const attributeDefinitions: Array<{ AttributeName: string; AttributeType: 'S' }> = [
+      { AttributeName: pkName, AttributeType: 'S' },
+    ];
+    const keySchema: Array<{ AttributeName: string; KeyType: 'HASH' | 'RANGE' }> = [
+      { AttributeName: pkName, KeyType: 'HASH' },
+    ];
+    if (skName !== undefined) {
+      attributeDefinitions.push({ AttributeName: skName, AttributeType: 'S' });
+      keySchema.push({ AttributeName: skName, KeyType: 'RANGE' });
+    }
+    await client.send(
+      new CreateTableCommand({
+        TableName: `${prefix}${logical}`,
+        AttributeDefinitions: attributeDefinitions,
+        KeySchema: keySchema,
+        BillingMode: 'PAY_PER_REQUEST',
+      }),
+    );
+  }
+  return {
+    tables,
+    client,
+    cleanup: async () => {
+      for (const logical of Object.keys(TABLE_DEFS)) {
+        try {
+          await client.send(new DeleteTableCommand({ TableName: `${prefix}${logical}` }));
+        } catch {
+          // best-effort
+        }
+      }
+    },
+  };
+}
+
+function makeRuntime(connId: string): AwsRuntime {
+  const handlers: AwsRuntimeHandlers = {
+    send: () => {},
+    disconnect: () => {},
+    snapshot: () => undefined,
+  };
+  return new AwsRuntime({
+    dynamo: fx!.client,
+    tables: fx!.tables,
+    connId,
+    handlers,
+    managementApi: null,
+  });
+}
+
+/** Persists a fresh Connections row with no joined channels. */
+async function seedConnection(connId: string, idleSince = 1_000): Promise<void> {
+  const state = createConnection({ id: connId, connectedSince: idleSince });
+  await fx!.client.send(
+    new PutCommand({
+      TableName: fx!.tables.Connections,
+      Item: marshalConnection(state, idleSince),
+    }),
+  );
+}
+
+/** Reads the raw Connections row (so we can inspect the stored shape). */
+async function readConnection(connId: string): Promise<{ joinedChannels?: unknown } | undefined> {
+  const res = await fx!.client.send(
+    new GetCommand({
+      TableName: fx!.tables.Connections,
+      Key: { connectionId: connId },
+    }),
+  );
+  return res.Item as { joinedChannels?: unknown } | undefined;
+}
+
+/** Reads every ChannelMembers row for a channel. */
+async function readMembers(channelKey: string): Promise<{ connectionId: string }[]> {
+  const res = await fx!.client.send(
+    new QueryCommand({
+      TableName: fx!.tables.ChannelMembers,
+      KeyConditionExpression: 'channelName = :k',
+      ExpressionAttributeValues: { ':k': channelKey },
+    }),
+  );
+  return (res.Items ?? []) as { connectionId: string }[];
+}
+
+/** Seeds a ChannelMembers row + reflects it on the connection's joined set. */
+async function seedMembership(connId: string, nick: string, channel: ChanName): Promise<void> {
+  const state = createConnection({ id: connId, connectedSince: 1_000 });
+  state.registration = 'registered';
+  state.nick = nick as Nick;
+  state.joinedChannels.add(channel);
+  await fx!.client.send(
+    new PutCommand({
+      TableName: fx!.tables.Connections,
+      Item: marshalConnection(state, 1_000),
+    }),
+  );
+  await fx!.client.send(
+    new PutCommand({
+      TableName: fx!.tables.ChannelMembers,
+      Item: marshalChannelMember(channel.toLowerCase(), {
+        conn: connId,
+        nick: nick as Nick,
+        op: false,
+        voice: false,
+      }),
+    }),
+  );
+}
+
+describe.skipIf(!available)('membership transactions', () => {
+  beforeEach(async () => {
+    fx = await makeFixture();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+    fx = null;
+  });
+
+  // -------------------------------------------------------------------------
+  // Atomicity: ChannelMembers ↔ Connections.joinedChannels
+  // -------------------------------------------------------------------------
+
+  it('JOIN writes both the ChannelMembers row and the channel to Connections.joinedChannels', async () => {
+    await seedConnection('c1');
+    const rt = makeRuntime('caller');
+
+    await rt.applyChannelDelta('#foo' as ChanName, {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' as Nick }],
+    });
+
+    const members = await readMembers('#foo');
+    expect(members.map((m) => m.connectionId)).toEqual(['c1']);
+
+    const row = await readConnection('c1');
+    expect(row).toBeDefined();
+    expect(row!.joinedChannels).toBeInstanceOf(Set);
+    expect((row!.joinedChannels as Set<string>).has('#foo')).toBe(true);
+  });
+
+  it('PART removes both the ChannelMembers row and the channel from joinedChannels', async () => {
+    await seedMembership('c1', 'Alice', '#foo' as ChanName);
+    const rt = makeRuntime('caller');
+
+    await rt.applyChannelDelta('#foo' as ChanName, {
+      memberships: [{ type: 'remove', conn: 'c1' }],
+    });
+
+    const members = await readMembers('#foo');
+    expect(members).toHaveLength(0);
+
+    const row = await readConnection('c1');
+    expect(row).toBeDefined();
+    expect((row!.joinedChannels as Set<string> | undefined)?.has('#foo') ?? false).toBe(false);
+  });
+
+  it('KICK (remove of a different connection) drops the target from joinedChannels', async () => {
+    await seedMembership('target', 'Bob', '#room' as ChanName);
+    const rt = makeRuntime('op');
+
+    await rt.applyChannelDelta('#room' as ChanName, {
+      memberships: [{ type: 'remove', conn: 'target' }],
+    });
+
+    const row = await readConnection('target');
+    expect((row!.joinedChannels as Set<string> | undefined)?.has('#room') ?? false).toBe(false);
+    expect(await readMembers('#room')).toHaveLength(0);
+  });
+
+  // -------------------------------------------------------------------------
+  // Stress: concurrent mutations by the same connection
+  // -------------------------------------------------------------------------
+
+  it('concurrent JOINs of different channels by the same connection leave both channels in joinedChannels', async () => {
+    await seedConnection('c1');
+    const rtA = makeRuntime('probe-a');
+    const rtB = makeRuntime('probe-b');
+
+    await Promise.all([
+      rtA.applyChannelDelta('#foo' as ChanName, {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' as Nick }],
+      }),
+      rtB.applyChannelDelta('#bar' as ChanName, {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' as Nick }],
+      }),
+    ]);
+
+    const row = await readConnection('c1');
+    const joined = row!.joinedChannels as Set<string>;
+    expect(joined.has('#foo')).toBe(true);
+    expect(joined.has('#bar')).toBe(true);
+
+    expect((await readMembers('#foo')).map((m) => m.connectionId)).toEqual(['c1']);
+    expect((await readMembers('#bar')).map((m) => m.connectionId)).toEqual(['c1']);
+  });
+
+  it('concurrent JOINs of the same channel by the same connection are idempotent (one roster row, channel listed once)', async () => {
+    await seedConnection('c1');
+    const rtA = makeRuntime('probe-a');
+    const rtB = makeRuntime('probe-b');
+
+    await expect(
+      Promise.all([
+        rtA.applyChannelDelta('#foo' as ChanName, {
+          memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' as Nick }],
+        }),
+        rtB.applyChannelDelta('#foo' as ChanName, {
+          memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' as Nick }],
+        }),
+      ]),
+    ).resolves.toBeDefined();
+
+    expect(await readMembers('#foo')).toHaveLength(1);
+    const row = await readConnection('c1');
+    const joined = row!.joinedChannels as Set<string>;
+    expect(joined.has('#foo')).toBe(true);
+    expect([...joined].filter((c) => c === '#foo')).toHaveLength(1);
+  });
+
+  it('concurrent PARTs of the same channel are idempotent (no rows left, joinedChannels empty)', async () => {
+    await seedMembership('c1', 'Alice', '#foo' as ChanName);
+    const rtA = makeRuntime('probe-a');
+    const rtB = makeRuntime('probe-b');
+
+    await expect(
+      Promise.all([
+        rtA.applyChannelDelta('#foo' as ChanName, {
+          memberships: [{ type: 'remove', conn: 'c1' }],
+        }),
+        rtB.applyChannelDelta('#foo' as ChanName, {
+          memberships: [{ type: 'remove', conn: 'c1' }],
+        }),
+      ]),
+    ).resolves.toBeDefined();
+
+    expect(await readMembers('#foo')).toHaveLength(0);
+    const row = await readConnection('c1');
+    expect((row!.joinedChannels as Set<string> | undefined)?.size ?? 0).toBe(0);
+  });
+
+  // -------------------------------------------------------------------------
+  // Sequence: JOIN then PART leaves no trace
+  // -------------------------------------------------------------------------
+
+  it('JOIN then PART on the same connection leaves joinedChannels empty and no roster row', async () => {
+    await seedConnection('c1');
+    const rt = makeRuntime('caller');
+
+    await rt.applyChannelDelta('#foo' as ChanName, {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' as Nick }],
+    });
+    await rt.applyChannelDelta('#foo' as ChanName, {
+      memberships: [{ type: 'remove', conn: 'c1' }],
+    });
+
+    expect(await readMembers('#foo')).toHaveLength(0);
+    const row = await readConnection('c1');
+    expect((row!.joinedChannels as Set<string> | undefined)?.size ?? 0).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Retry / error-classification (no DynamoDB Local required — fake client)
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal fake document client. Counts `TransactWriteCommand` invocations
+ * and throws a configurable error for the first N transact attempts so
+ * the retry loop in `AwsRuntime.sendTransactWithRetry` is exercised
+ * without needing real DynamoDB concurrency.
+ */
+class FakeDynamo {
+  transactCalls = 0;
+  otherCalls = 0;
+  constructor(
+    private readonly opts: {
+      failTransactTimes?: number;
+      error?: { name: string; CancellationReasons?: Array<{ Code?: string }> };
+    },
+  ) {}
+  async send(cmd: unknown): Promise<unknown> {
+    if (cmd instanceof TransactWriteCommand) {
+      this.transactCalls++;
+      const fail = this.opts.failTransactTimes ?? 0;
+      if (this.transactCalls <= fail) {
+        throw (
+          this.opts.error ?? {
+            name: 'TransactionCanceledException',
+            CancellationReasons: [{ Code: 'TransactionConflict' }],
+          }
+        );
+      }
+      return {};
+    }
+    this.otherCalls++;
+    // ensureMetaRow does a PutCommand (ChannelMeta); return success.
+    return {};
+  }
+}
+
+function fakeRuntime(client: FakeDynamo): AwsRuntime {
+  const handlers: AwsRuntimeHandlers = {
+    send: () => {},
+    disconnect: () => {},
+    snapshot: () => undefined,
+  };
+  return new AwsRuntime({
+    dynamo: client as unknown as ReturnType<typeof createDynamoDocumentClient>,
+    tables: {
+      Connections: 'C',
+      ChannelMeta: 'CM',
+      ChannelMembers: 'CMem',
+      Nicks: 'N',
+      Accounts: 'A',
+    },
+    connId: 'probe',
+    handlers,
+    managementApi: null,
+  });
+}
+
+describe('membership transaction retry / error classification', () => {
+  it('retries on TransactionConflict and succeeds once the conflict clears', async () => {
+    const fake = new FakeDynamo({ failTransactTimes: 2 });
+    const rt = fakeRuntime(fake);
+
+    await rt.applyChannelDelta('#foo' as ChanName, {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' as Nick }],
+    });
+
+    // 2 failed attempts + 1 successful = 3 transact calls.
+    expect(fake.transactCalls).toBe(3);
+  });
+
+  it('rethrows a non-conflict TransactionCanceledException immediately (no retry)', async () => {
+    const fake = new FakeDynamo({
+      failTransactTimes: 1,
+      error: {
+        name: 'TransactionCanceledException',
+        CancellationReasons: [{ Code: 'ConditionalCheckFailed' }],
+      },
+    });
+    const rt = fakeRuntime(fake);
+
+    await expect(
+      rt.applyChannelDelta('#foo' as ChanName, {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' as Nick }],
+      }),
+    ).rejects.toThrow();
+    expect(fake.transactCalls).toBe(1);
+  });
+
+  it('rethrows after exhausting the retry budget on persistent conflicts', async () => {
+    const fake = new FakeDynamo({ failTransactTimes: 999 });
+    const rt = fakeRuntime(fake);
+
+    await expect(
+      rt.applyChannelDelta('#foo' as ChanName, {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' as Nick }],
+      }),
+    ).rejects.toThrow();
+    // MAX_ATTEMPTS = 6.
+    expect(fake.transactCalls).toBe(6);
+  });
+
+  it('rethrows a non-transact error (e.g. ProvisionedThroughputExceeded) without retry', async () => {
+    const fake = new FakeDynamo({
+      failTransactTimes: 1,
+      error: { name: 'ProvisionedThroughputExceededException' },
+    });
+    const rt = fakeRuntime(fake);
+
+    await expect(
+      rt.applyChannelDelta('#foo' as ChanName, {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' as Nick }],
+      }),
+    ).rejects.toThrow();
+    expect(fake.transactCalls).toBe(1);
+  });
+
+  it('rejects a TransactionConflict classifier on null / non-object errors', async () => {
+    // Smoke-test the classifier's defensive branches by replaying the
+    // same fake-runtime path with a non-object error. The classifier
+    // must treat it as non-retryable and rethrow on the first attempt.
+    const fake = new FakeDynamo({
+      failTransactTimes: 1,
+      error: { name: 'TransactionCanceledException' }, // no CancellationReasons
+    });
+    const rt = fakeRuntime(fake);
+
+    await expect(
+      rt.applyChannelDelta('#foo' as ChanName, {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' as Nick }],
+      }),
+    ).rejects.toThrow();
+    expect(fake.transactCalls).toBe(1);
+  });
+});

package/packages/aws-adapter/tsconfig.build.json

@@ -0,0 +1,16 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "tsBuildInfoFile": "./.tsbuildinfo",
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["dist", "tests", "**/*.test.ts"],
+  "references": [
+    { "path": "../irc-core/tsconfig.build.json" },
+    { "path": "../irc-server/tsconfig.build.json" }
+  ]
+}

package/packages/aws-adapter/tsconfig.test.json

@@ -0,0 +1,14 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "tests/**/*.ts"],
+  "exclude": ["dist"],
+  "references": [
+    { "path": "../irc-core/tsconfig.build.json" },
+    { "path": "../irc-server/tsconfig.build.json" },
+    { "path": "../irc-test-support/tsconfig.build.json" }
+  ]
+}

package/packages/aws-adapter/vitest.config.ts

@@ -0,0 +1,23 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globalSetup: ['./tests/global-setup.ts'],
+    setupFiles: [],
+    include: ['tests/**/*.test.ts'],
+    exclude: ['dist/**', 'node_modules/**'],
+    coverage: {
+      provider: 'v8',
+      all: false,
+      include: ['src/**/*.ts'],
+      exclude: ['src/**/index.ts'],
+      reporter: ['text', 'html', 'json-summary'],
+      thresholds: {
+        lines: 90,
+        functions: 90,
+        branches: 90,
+        statements: 90,
+      },
+    },
+  },
+});

package/packages/cf-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-adapter",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "private": true,
   "description": "Cloudflare Workers adapter: Durable Objects (ConnectionDO, RegistryDO, ChannelDO) and CfRuntime implementing IrcRuntime",
   "license": "BSD-3-Clause",
@@ -30,6 +30,7 @@
     "@cloudflare/vitest-pool-workers": "0.18.6",
     "@cloudflare/workers-types": "^5.20260714.1",
     "@serverless-ircd/in-memory-runtime": "workspace:*",
+    "@serverless-ircd/irc-test-support": "workspace:*",
     "@vitest/coverage-v8": "^4.1.0",
     "rimraf": "^6.0.0",
     "typescript": "^5.6.0",

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

@@ -38,8 +38,10 @@ import {
   toSnapshot,
 } from '@serverless-ircd/irc-core';
 import type { IrcRuntime } from '@serverless-ircd/irc-server';
-import type { Env, RegistryRpc } from './env.js';
+import type { ChannelRegistryRpc, Env, RegistryRpc } from './env.js';
 import { DEFAULT_REGISTRY_SHARDS, registryKeyForNick, shardNick } from './sharding.js';
+import type { PersistedConnectionState } from './serialize.js';
+import { deserialize } from './serialize.js';
 
 /** Per-connection transport callbacks the ConnectionDO wires up. */
 export interface CfConnectionHandlers {
@@ -64,6 +66,10 @@ export interface ConnectionRpc {
   deliver(lines: RawLine[]): Promise<{ delivered: number }>;
   /** Returns a serializable snapshot of the connection state. */
   getConnSnapshot(): Promise<ConnSnapshot | null>;
+  /** Returns the full connection state as a serializable DTO. */
+  getConnState(): Promise<PersistedConnectionState | null>;
+  /** Cross-connection disconnect: closes the WebSocket and runs teardown. */
+  disconnect(reason?: string): Promise<void>;
 }
 
 /**
@@ -117,12 +123,8 @@ export class CfRuntime implements IrcRuntime {
       this.handlers.disconnect(reason);
       return;
     }
-    // Cross-connection disconnect is a teardown signal; we route it via
-    // the target's ConnectionDO RPC as well. (ConnectionDO doesn't expose
-    // a dedicated `disconnect` RPC today — the canonical teardown path is
-    // the WebSocket close, which is owned by the connection itself. We
-    // therefore no-op for cross-connection disconnects; this preserves
-    // the IrcRuntime contract without inventing a new RPC.)
+    const stub = this.env.CONNECTION_DO.get(this.env.CONNECTION_DO.idFromString(conn));
+    await (stub as unknown as ConnectionRpc).disconnect(reason);
   }
 
   async sendToNick(
@@ -232,29 +234,37 @@ export class CfRuntime implements IrcRuntime {
   }
 
   async getConnection(conn: ConnId): Promise<ConnectionState | null> {
-    // CF stores ConnectionState inside each ConnectionDO; the only
-    // authoritative view this runtime can hand out without a new RPC is
-    // the local connection's live state. Remote connections return null
-    // until a dedicated `getConnState` RPC lands alongside the broader
-    // WHOIS-over-CF work — the actor degrades to "unknown nick" for them.
     if (conn === this.connId) {
       return this.handlers.snapshot() ?? null;
     }
-    return null;
+    const stub = this.env.CONNECTION_DO.get(this.env.CONNECTION_DO.idFromString(conn));
+    const dto = await (stub as unknown as ConnectionRpc).getConnState();
+    return dto === null ? null : deserialize(dto);
   }
 
-  async getChannelConnections(_chan: ChanName): Promise<ReadonlyMap<ConnId, ConnectionState>> {
-    // CF has no single source of truth for full ConnectionStates across
-    // all ConnectionDOs. The WHO command (the only current consumer)
-    // ships in a later ticket; return an empty map until then.
-    return new Map();
+  async getChannelConnections(chan: ChanName): Promise<ReadonlyMap<ConnId, ConnectionState>> {
+    const memberIds = await this.channelRpc(chan).listMembers();
+    const out = new Map<ConnId, ConnectionState>();
+    await Promise.all(
+      memberIds.map(async (id) => {
+        const connStub = this.env.CONNECTION_DO.get(
+          this.env.CONNECTION_DO.idFromString(id),
+        );
+        const dto = await (connStub as unknown as ConnectionRpc).getConnState();
+        if (dto !== null) {
+          out.set(id, deserialize(dto));
+        }
+      }),
+    );
+    return out;
   }
 
   async listChannels(): Promise<ChanSnapshot[]> {
-    // CF has no central channel registry; each ChannelDO is independent.
-    // The LIST command (the only current consumer) ships in a later
-    // ticket; return an empty array until then.
-    return [];
+    const names = await this.channelRegistryRpc().list();
+    const snapshots = await Promise.all(
+      names.map((nameLower) => this.getChannelSnapshot(nameLower)),
+    );
+    return snapshots.filter((s): s is ChanSnapshot => s !== null);
   }
 
   // -------------------------------------------------------------------------
@@ -278,6 +288,7 @@ export class CfRuntime implements IrcRuntime {
     broadcast(lines: unknown[], except?: string): Promise<void>;
     applyChannelDelta(delta: unknown): Promise<void>;
     getChannelSnapshot(): Promise<unknown>;
+    listMembers(): Promise<string[]>;
   } {
     const lower = name.toLowerCase();
     const stub = this.env.CHANNEL_DO.get(this.env.CHANNEL_DO.idFromName(lower));
@@ -285,8 +296,17 @@ export class CfRuntime implements IrcRuntime {
       broadcast(lines: unknown[], except?: string): Promise<void>;
       applyChannelDelta(delta: unknown): Promise<void>;
       getChannelSnapshot(): Promise<unknown>;
+      listMembers(): Promise<string[]>;
     };
   }
+
+  /** Returns the channel registry DO RPC stub. */
+  private channelRegistryRpc(): ChannelRegistryRpc {
+    const stub = this.env.CHANNEL_REGISTRY_DO.get(
+      this.env.CHANNEL_REGISTRY_DO.idFromName('channels'),
+    );
+    return stub as unknown as ChannelRegistryRpc;
+  }
 }
 
 /**