serverless-ircd 0.2.0 → 0.3.0

package/packages/aws-adapter/tests/config-loader.test.ts

@@ -75,6 +75,49 @@ describe('buildLambdaConfigInput', () => {
   it('passes QUIT_MESSAGE through', () => {
     expect(buildLambdaConfigInput({ QUIT_MESSAGE: 'bye' }).quitMessage).toBe('bye');
   });
+
+  it('parses SASL_ACCOUNTS newline-delimited username:password pairs', () => {
+    const out = buildLambdaConfigInput({ SASL_ACCOUNTS: 'alice:secret\nbob:b-pass' });
+    expect(out.saslAccounts).toEqual([
+      { username: 'alice', password: 'secret' },
+      { username: 'bob', password: 'b-pass' },
+    ]);
+  });
+
+  it('omits saslAccounts when SASL_ACCOUNTS is empty', () => {
+    expect('saslAccounts' in buildLambdaConfigInput({ SASL_ACCOUNTS: '' })).toBe(false);
+  });
+
+  it('omits saslAccounts when SASL_ACCOUNTS is undefined', () => {
+    expect('saslAccounts' in buildLambdaConfigInput({})).toBe(false);
+  });
+
+  it('skips blank lines in SASL_ACCOUNTS (trailing newline tolerance)', () => {
+    const out = buildLambdaConfigInput({ SASL_ACCOUNTS: 'alice:secret\n\n   \n' });
+    expect(out.saslAccounts).toEqual([{ username: 'alice', password: 'secret' }]);
+  });
+
+  it('skips SASL_ACCOUNTS entries with no colon separator', () => {
+    const out = buildLambdaConfigInput({ SASL_ACCOUNTS: 'nopass\nalice:secret' });
+    expect(out.saslAccounts).toEqual([{ username: 'alice', password: 'secret' }]);
+  });
+
+  it('skips SASL_ACCOUNTS entries with an empty username (leading colon)', () => {
+    const out = buildLambdaConfigInput({ SASL_ACCOUNTS: ':onlypass\nalice:secret' });
+    expect(out.saslAccounts).toEqual([{ username: 'alice', password: 'secret' }]);
+  });
+
+  it('skips SASL_ACCOUNTS entries with an empty password', () => {
+    const out = buildLambdaConfigInput({ SASL_ACCOUNTS: 'alice:\nbob:real' });
+    expect(out.saslAccounts).toEqual([{ username: 'bob', password: 'real' }]);
+  });
+
+  it('trims whole SASL_ACCOUNTS lines but preserves fields around the colon', () => {
+    // Only the line is trimmed; whitespace adjacent to ':' is kept (so a
+    // stray space does not silently change the stored username/password).
+    const out = buildLambdaConfigInput({ SASL_ACCOUNTS: '  alice:secret  ' });
+    expect(out.saslAccounts).toEqual([{ username: 'alice', password: 'secret' }]);
+  });
 });
 
 describe('loadServerConfigFromLambdaEnv', () => {
@@ -155,4 +198,16 @@ describe('loadServerConfigFromLambdaEnv', () => {
     });
     expect(cfg.quitMessage).toBe('goodbye');
   });
+
+  it('round-trips SASL_ACCOUNTS into cfg.saslAccounts end-to-end', () => {
+    const cfg = loadServerConfigFromLambdaEnv({
+      SERVER_NAME: 's',
+      NETWORK_NAME: 'n',
+      SASL_ACCOUNTS: 'alice:secret\nbob:b-pass',
+    });
+    expect(cfg.saslAccounts).toEqual([
+      { username: 'alice', password: 'secret' },
+      { username: 'bob', password: 'b-pass' },
+    ]);
+  });
 });

package/packages/aws-adapter/tests/disconnect-fanout.test.ts

@@ -0,0 +1,336 @@
+/**
+ * Integration tests for QUIT fanout on `$disconnect` (and on the
+ * `GoneException` cleanup path).
+ *
+ * Verifies that when connection A tears down, every peer sharing a
+ * channel with A receives the canonical `:A QUIT :reason` line via
+ * `managementApi.postToConnection`, and that a gone peer during fanout
+ * triggers lazy cleanup instead of crashing.
+ */
+
+import { GoneException } from '@aws-sdk/client-apigatewaymanagementapi';
+import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
+import { PutCommand } from '@aws-sdk/lib-dynamodb';
+import {
+  DEFAULT_SERVER_CONFIG,
+  type Nick,
+  type ParsedServerConfig,
+  StaticMotdProvider,
+  createConnection,
+} from '@serverless-ircd/irc-core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { AwsRuntime, cleanupConnection, type PostToConnection } from '../src/aws-runtime.js';
+import { handleDisconnect } from '../src/handlers/disconnect.js';
+import {
+  type HandlerDeps,
+  __resetHandlerCacheForTests,
+  dispatch,
+} from '../src/handlers/index.js';
+import { TABLE_DEFS } from '../src/cdk-table-defs.js';
+import { createDynamoDocumentClient } from '../src/dynamo.js';
+import { marshalChannelMember, marshalConnection, marshalNick } from '../src/serialize.js';
+import type { TablesConfig } from '../src/tables.js';
+
+const available = process.env.DDB_AVAILABLE === '1';
+const endpoint = process.env.DYNAMO_ENDPOINT;
+
+const SERVER_CONFIG: ParsedServerConfig = {
+  ...DEFAULT_SERVER_CONFIG,
+  serverName: 'irc.example.com',
+  networkName: 'ExampleNet',
+  motdLines: [],
+};
+
+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 = `q${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
+        }
+      }
+    },
+  };
+}
+
+/** Seed a registered connection with nick/user/host and a channel membership. */
+async function seedConnection(
+  client: ReturnType<typeof createDynamoDocumentClient>,
+  tables: TablesConfig,
+  connId: string,
+  nick: string,
+  channel: string,
+): Promise<void> {
+  const now = Date.now();
+  const state = createConnection({ id: connId, connectedSince: now });
+  state.registration = 'registered';
+  state.nick = nick as Nick;
+  state.user = nick;
+  state.host = 'x';
+  state.realname = nick;
+  state.joinedChannels = new Set([channel as never]);
+  state.lastSeen = now;
+  await client.send(
+    new PutCommand({ TableName: tables.Connections, Item: marshalConnection(state, now) }),
+  );
+  await client.send(
+    new PutCommand({
+      TableName: tables.Nicks,
+      Item: marshalNick(nick as Nick, connId, now),
+    }),
+  );
+  await client.send(
+    new PutCommand({
+      TableName: tables.ChannelMembers,
+      Item: marshalChannelMember(channel, {
+        conn: connId,
+        nick: nick as Nick,
+        op: false,
+        voice: false,
+      }),
+    }),
+  );
+}
+
+/** Records every `postToConnection` call keyed by ConnectionId. */
+class RecordingPostToConnection implements PostToConnection {
+  readonly sent = new Map<string, string[]>();
+  private readonly gone = new Set<string>();
+  private readonly errorPeers = new Map<string, Error>();
+  async postToConnection(input: { ConnectionId: string; Data: string }): Promise<unknown> {
+    const custom = this.errorPeers.get(input.ConnectionId);
+    if (custom !== undefined) throw custom;
+    if (this.gone.has(input.ConnectionId)) {
+      throw new GoneException({ $metadata: {}, message: 'Gone' });
+    }
+    const list = this.sent.get(input.ConnectionId) ?? [];
+    for (const line of input.Data.split('\r\n')) {
+      if (line.length > 0) list.push(line);
+    }
+    this.sent.set(input.ConnectionId, list);
+    return {};
+  }
+  markGone(connId: string): void {
+    this.gone.add(connId);
+  }
+  markError(connId: string, err: Error): void {
+    this.errorPeers.set(connId, err);
+  }
+}
+
+function probe(
+  client: ReturnType<typeof createDynamoDocumentClient>,
+  tables: TablesConfig,
+): AwsRuntime {
+  return new AwsRuntime({
+    dynamo: client,
+    tables,
+    connId: '__probe__',
+    handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+    managementApi: null,
+  });
+}
+
+describe.skipIf(!available)('$disconnect QUIT fanout', () => {
+  beforeEach(async () => {
+    fx = await makeFixture();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+    fx = null;
+  });
+
+  it('handleDisconnect fans the QUIT line out to every other channel member', async () => {
+    await seedConnection(fx!.client, fx!.tables, 'a', 'alice', '#room');
+    await seedConnection(fx!.client, fx!.tables, 'b', 'bob', '#room');
+
+    const mgmt = new RecordingPostToConnection();
+    await handleDisconnect({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connectionId: 'a',
+      managementApi: mgmt,
+    });
+
+    // Peer b received the QUIT line for alice.
+    const bobReceived = mgmt.sent.get('b') ?? [];
+    expect(bobReceived).toContain(':alice!alice@x QUIT :Client Quit');
+    // The disconnecting connection never receives its own QUIT.
+    expect(mgmt.sent.has('a')).toBe(false);
+  });
+
+  it('handleDisconnect without a managementApi performs no fanout but still cleans up', async () => {
+    await seedConnection(fx!.client, fx!.tables, 'a', 'alice', '#room');
+    await handleDisconnect({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connectionId: 'a',
+      managementApi: null,
+    });
+    const p = probe(fx!.client, fx!.tables);
+    expect(await p.getConnectionInfo('a')).toBeNull();
+    expect(await p.lookupNick('alice' as Nick)).toBeNull();
+  });
+
+  it('a never-registered connection disconnects without fanout (no nick)', async () => {
+    const mgmt = new RecordingPostToConnection();
+    await handleDisconnect({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connectionId: 'nobody',
+      managementApi: mgmt,
+    });
+    expect(mgmt.sent.size).toBe(0);
+  });
+
+  it('fanout to a gone peer triggers lazy cleanup instead of crashing', async () => {
+    await seedConnection(fx!.client, fx!.tables, 'a', 'alice', '#room');
+    await seedConnection(fx!.client, fx!.tables, 'b', 'bob', '#room');
+
+    const mgmt = new RecordingPostToConnection();
+    mgmt.markGone('b');
+
+    await expect(
+      handleDisconnect({
+        dynamo: fx!.client,
+        tables: fx!.tables,
+        connectionId: 'a',
+        managementApi: mgmt,
+      }),
+    ).resolves.toBeUndefined();
+
+    // The gone peer b was lazily cleaned up (Connection row removed).
+    const p = probe(fx!.client, fx!.tables);
+    expect(await p.getConnectionInfo('b')).toBeNull();
+  });
+
+  it('cleanupConnection directly broadcasts QUIT when given a managementApi', async () => {
+    await seedConnection(fx!.client, fx!.tables, 'a', 'alice', '#room');
+    await seedConnection(fx!.client, fx!.tables, 'b', 'bob', '#room');
+
+    const mgmt = new RecordingPostToConnection();
+    await cleanupConnection(fx!.client, fx!.tables, 'a', mgmt);
+
+    const bobReceived = mgmt.sent.get('b') ?? [];
+    expect(bobReceived).toContain(':alice!alice@x QUIT :Client Quit');
+    const p = probe(fx!.client, fx!.tables);
+    expect(await p.getConnectionInfo('a')).toBeNull();
+  });
+
+  it('the $disconnect dispatch route fans QUIT out to peers via the management API', async () => {
+    const deps: HandlerDeps = {
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: new StaticMotdProvider([]),
+      messages: { record() {}, query: () => Promise.resolve([]) } as never,
+      managementApi: null,
+    };
+    // Register alice + bob into the same channel via $default frames.
+    const mgmt = new RecordingPostToConnection();
+    deps.managementApi = mgmt as never;
+    await dispatch({ requestContext: { routeKey: '$connect', connectionId: 'a' } }, deps);
+    await dispatch({ requestContext: { routeKey: '$connect', connectionId: 'b' } }, deps);
+    await dispatch(
+      { requestContext: { routeKey: '$default', connectionId: 'a' }, body: 'NICK alice\r\nUSER alice 0 * :Alice\r\nJOIN #room\r\n' },
+      deps,
+    );
+    await dispatch(
+      { requestContext: { routeKey: '$default', connectionId: 'b' }, body: 'NICK bob\r\nUSER bob 0 * :Bob\r\nJOIN #room\r\n' },
+      deps,
+    );
+    mgmt.sent.clear();
+
+    // alice disconnects.
+    await dispatch({ requestContext: { routeKey: '$disconnect', connectionId: 'a' } }, deps);
+
+    const bobReceived = mgmt.sent.get('b') ?? [];
+    expect(bobReceived.some((l) => /^:alice!alice\S* QUIT :/.test(l))).toBe(true);
+  });
+
+  it('the send() GoneException cleanup path also broadcasts QUIT to the gone peer\'s channels', async () => {
+    // alice and carol share #room; bob shares a different channel with carol.
+    await seedConnection(fx!.client, fx!.tables, 'alice', 'alice', '#room');
+    await seedConnection(fx!.client, fx!.tables, 'carol', 'carol', '#room');
+
+    // A management double where alice is "gone" (raises GoneException).
+    const mgmt = new RecordingPostToConnection();
+    mgmt.markGone('alice');
+
+    const runtime = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connId: 'carol',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: mgmt,
+    });
+
+    // carol sends to alice → GoneException → cleanupConnection(alice)
+    // → alice's QUIT fans out to carol (the other #room member).
+    await runtime.send('alice', [{ text: ':carol!carol@x PRIVMSG alice :hi' } as never]);
+
+    const carolReceived = mgmt.sent.get('carol') ?? [];
+    expect(carolReceived.some((l) => l.startsWith(':alice!alice@x QUIT :'))).toBe(true);
+    // alice was cleaned up.
+    const p = probe(fx!.client, fx!.tables);
+    expect(await p.getConnectionInfo('alice')).toBeNull();
+  });
+
+  it('fanout to a peer that throws a non-Gone error rethrows (no silent swallow)', async () => {
+    await seedConnection(fx!.client, fx!.tables, 'a', 'alice', '#room');
+    await seedConnection(fx!.client, fx!.tables, 'b', 'bob', '#room');
+
+    const mgmt = new RecordingPostToConnection();
+    mgmt.markError('b', new Error('transient network failure'));
+
+    await expect(
+      handleDisconnect({
+        dynamo: fx!.client,
+        tables: fx!.tables,
+        connectionId: 'a',
+        managementApi: mgmt,
+      }),
+    ).rejects.toThrow('transient network failure');
+  });
+});

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

@@ -9,6 +9,7 @@
 import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
 import {
   DEFAULT_SERVER_CONFIG,
+  InMemoryAccountStore,
   type ParsedServerConfig,
   StaticMotdProvider,
 } from '@serverless-ircd/irc-core';
@@ -383,6 +384,51 @@ describe.skipIf(!available)('handlers', () => {
       expect(replay).toBeDefined();
     });
 
+    it('completes SASL PLAIN with 900/903 when an AccountStore is bound', async () => {
+      await dispatch({ requestContext: { routeKey: '$connect', connectionId: 'c1' } }, fx!.deps);
+      const sink: string[] = [];
+      fx!.mgmt.register('c1', (data) => {
+        for (const line of data.split('\r\n')) {
+          if (line.length > 0) sink.push(line);
+        }
+      });
+      // Swap in a deps with a seeded AccountStore for this dispatch.
+      const depsWithAccounts: HandlerDeps = {
+        ...fx!.deps,
+        accounts: new InMemoryAccountStore([{ username: 'aws-sasl', password: 's3cret' }]),
+      };
+      const payload = Buffer.from('\0aws-sasl\0s3cret', 'utf8').toString('base64');
+      await dispatch(
+        {
+          requestContext: { routeKey: '$default', connectionId: 'c1' },
+          body: `CAP REQ :sasl\r\nAUTHENTICATE PLAIN\r\nAUTHENTICATE ${payload}\r\n`,
+        },
+        depsWithAccounts,
+      );
+      expect(sink.some((l) => l.includes(' 900 '))).toBe(true);
+      expect(sink.some((l) => l.includes(' 903 '))).toBe(true);
+      expect(sink.some((l) => l.includes(' 904 '))).toBe(false);
+    });
+
+    it('emits 904 when no AccountStore is bound (regression guard)', async () => {
+      await dispatch({ requestContext: { routeKey: '$connect', connectionId: 'c2' } }, fx!.deps);
+      const sink: string[] = [];
+      fx!.mgmt.register('c2', (data) => {
+        for (const line of data.split('\r\n')) {
+          if (line.length > 0) sink.push(line);
+        }
+      });
+      const payload = Buffer.from('\0aws-sasl\0s3cret', 'utf8').toString('base64');
+      await dispatch(
+        {
+          requestContext: { routeKey: '$default', connectionId: 'c2' },
+          body: `CAP REQ :sasl\r\nAUTHENTICATE PLAIN\r\nAUTHENTICATE ${payload}\r\n`,
+        },
+        fx!.deps,
+      );
+      expect(sink.some((l) => l.includes(' 904 '))).toBe(true);
+    });
+
     it('returns 500 when unmarshalConnection throws on a corrupted row (caught by Lambda)', async () => {
       // Skip: the catch in handleDefault wraps `actor.receiveTextFrame`,
       // not `unmarshalConnection`. A corrupted-row test would exercise

package/packages/cf-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-adapter",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true,
   "description": "Cloudflare Workers adapter: Durable Objects (ConnectionDO, RegistryDO, ChannelDO) and CfRuntime implementing IrcRuntime",
   "license": "BSD-3-Clause",

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;
+  }
 }
 
 /**

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

@@ -46,7 +46,7 @@ import {
   createChannel,
   toSnapshot,
 } from '@serverless-ircd/irc-core';
-import type { Env } from './env.js';
+import type { ChannelRegistryRpc, Env } from './env.js';
 
 /** Storage key under which the per-channel state is persisted. */
 const STATE_STORAGE_KEY = 'channel-state';
@@ -129,8 +129,10 @@ export class ChannelDO extends DurableObject<Env> {
    */
   async applyChannelDelta(delta: ChannelDelta): Promise<void> {
     const state = await this.loadState();
+    const wasEmpty = state.members.size === 0;
     const next = applyChannelDelta(state, delta);
     await this.persistState(next);
+    await this.syncRegistry(wasEmpty, next);
   }
 
   // -------------------------------------------------------------------------
@@ -160,10 +162,12 @@ export class ChannelDO extends DurableObject<Env> {
     const payload = lines.map((text) => ({ text }));
     const pruned = await this.fanoutAndCollect(state, payload, except);
     if (pruned.length > 0) {
+      const wasEmpty = false;
       const next = applyChannelDelta(state, {
         memberships: pruned.map((conn) => ({ type: 'remove' as const, conn })),
       });
       await this.persistState(next);
+      await this.syncRegistry(wasEmpty, next);
     }
   }
 
@@ -182,10 +186,12 @@ export class ChannelDO extends DurableObject<Env> {
     // OPEN-socket count without sending bytes).
     const pruned = await this.fanoutAndCollect(state, [], undefined);
     if (pruned.length > 0) {
+      const wasEmpty = false;
       const next = applyChannelDelta(state, {
         memberships: pruned.map((conn) => ({ type: 'remove' as const, conn })),
       });
       await this.persistState(next);
+      await this.syncRegistry(wasEmpty, next);
     }
     return pruned.length;
   }
@@ -206,6 +212,16 @@ export class ChannelDO extends DurableObject<Env> {
     return toDto(state);
   }
 
+  /**
+   * Returns the ConnIds of every member of this channel. Used by
+   * {@link CfRuntime.getChannelConnections} to enumerate the
+   * ConnectionStates of all members (for WHO).
+   */
+  async listMembers(): Promise<string[]> {
+    const state = await this.loadState();
+    return Array.from(state.members.keys());
+  }
+
   // -------------------------------------------------------------------------
   // Internal helpers
   // -------------------------------------------------------------------------
@@ -289,6 +305,29 @@ export class ChannelDO extends DurableObject<Env> {
     }
   }
 
+  /**
+   * Keeps the channel registry in sync: registers the channel when it
+   * transitions from empty to non-empty, unregisters on the reverse
+   * transition. Called after every membership-mutating path so the
+   * registry always reflects the live channel set.
+   */
+  private async syncRegistry(wasEmpty: boolean, next: ChannelState): Promise<void> {
+    const isEmpty = next.members.size === 0;
+    if (wasEmpty && !isEmpty) {
+      await this.channelRegistry().register(next.nameLower);
+    } else if (!wasEmpty && isEmpty) {
+      await this.channelRegistry().unregister(next.nameLower);
+    }
+  }
+
+  /** Returns the channel registry DO RPC stub. */
+  private channelRegistry(): ChannelRegistryRpc {
+    const stub = this.env.CHANNEL_REGISTRY_DO.get(
+      this.env.CHANNEL_REGISTRY_DO.idFromName('channels'),
+    );
+    return stub as unknown as ChannelRegistryRpc;
+  }
+
   // -------------------------------------------------------------------------
   // Test hooks (only invoked from `runInDurableObject` in tests)
   // -------------------------------------------------------------------------