serverless-ircd 0.2.0 → 0.4.0

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

@@ -2,14 +2,9 @@
  * @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.
+ * Durable Objects (ConnectionDO, RegistryDO, ChannelDO), the
+ * ChannelRegistryDO index, and a CfRuntime that bridges them behind the
+ * platform-agnostic {@link IrcRuntime} port.
  */
 
 export {
@@ -19,6 +14,7 @@ export {
 } from './connection-do.js';
 export { RegistryDO } from './registry-do.js';
 export { ChannelDO } from './channel-do.js';
+export { ChannelRegistryDO } from './channel-registry-do.js';
 export type { DeliverResult, ConnectionDeliveryRpc } from './channel-do.js';
 export {
   DEFAULT_REGISTRY_SHARDS,
@@ -27,7 +23,13 @@ export {
 } 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 type { ChannelRpc, ChannelRegistryRpc, Env, RegistryRpc } from './env.js';
+export {
+  CREATE_ACCOUNTS_TABLE_SQL,
+  loadD1AccountStore,
+  putAccountCredential,
+  resolveAccountStore,
+} from './d1-account-store.js';
 export {
   PERSISTED_STATE_VERSION,
   STATE_STORAGE_KEY,

package/packages/cf-adapter/tests/cf-harness.ts

@@ -65,7 +65,8 @@ export interface CfHarnessEnv {
  */
 export function makeCfHarnessFactory(opts: CfHarnessFactoryOptions): IrcHarnessFactory {
   return Object.freeze({
-    name: 'cf',
+    name: 'cf+ws',
+    transport: 'ws',
     async create() {
       return new CfHarness(opts);
     },
@@ -204,6 +205,15 @@ class CfClientHandle implements ClientHarness {
     this.ws.send(`${line}\r\n`);
   }
 
+  async feed(chunk: string): Promise<void> {
+    if (this.closed) return;
+    // The CF harness speaks the WebSocket transport end-to-end (a real WS
+    // to a ConnectionDO), so one feed() is one text frame — identical to
+    // send() minus the framing. A CF+tcp factory (Spectrum + container
+    // origin) would route this through a TCP byte stream.
+    this.ws.send(chunk);
+  }
+
   async waitForLine(
     predicate: (line: string) => boolean,
     timeoutMs: number = DEFAULT_TIMEOUT_MS,

package/packages/cf-adapter/tests/cf-integration.test.ts

@@ -62,7 +62,8 @@ afterAll(async () => {
 // guaranteed to be initialized.
 runIrcScenarios([
   {
-    name: 'cf',
+    name: 'cf+ws',
+    transport: 'ws',
     async create() {
       if (factory === undefined) {
         factory = makeCfHarnessFactory({ env });

package/packages/cf-adapter/tests/cf-runtime.test.ts

@@ -44,6 +44,7 @@ declare global {
       CHANNEL_DO: DurableObjectNamespace;
       CHANNEL_DO_REAL: DurableObjectNamespace;
       CHANNEL_DO_STUB: DurableObjectNamespace;
+      CHANNEL_REGISTRY_DO: DurableObjectNamespace;
     }
   }
 }
@@ -62,6 +63,7 @@ function envWithRealDOs(): Env {
     CONNECTION_DO: env.CONNECTION_DO,
     REGISTRY_DO: env.REGISTRY_DO_REAL,
     CHANNEL_DO: env.CHANNEL_DO_REAL,
+    CHANNEL_REGISTRY_DO: env.CHANNEL_REGISTRY_DO,
     SERVER_NAME: 'irc.example.com',
     NETWORK_NAME: 'ExampleNet',
     MOTD_LINES: '',
@@ -78,6 +80,7 @@ function envWithChannelStub(): Env {
     CONNECTION_DO: env.CONNECTION_DO,
     REGISTRY_DO: env.REGISTRY_DO_REAL,
     CHANNEL_DO: env.CHANNEL_DO_STUB,
+    CHANNEL_REGISTRY_DO: env.CHANNEL_REGISTRY_DO,
     SERVER_NAME: 'irc.example.com',
     NETWORK_NAME: 'ExampleNet',
     MOTD_LINES: '',
@@ -484,6 +487,94 @@ describe('CfRuntime — cross-connection RPC via ConnectionDO', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Tests — cross-connection getConnection / getChannelConnections / listChannels / disconnect
+// ---------------------------------------------------------------------------
+
+describe('CfRuntime — cross-connection lookups and disconnect', () => {
+  it('getConnection(remoteConnId) returns the remote connection state via RPC', async () => {
+    const targetName = 'conn-get-target';
+    const ws = await openConnection(targetName);
+    await new Promise<void>((r) => setTimeout(r, 20));
+    ws.send('NICK carol\r\n');
+    ws.send('USER carol 0 * :Carol\r\n');
+    await new Promise<void>((r) => setTimeout(r, 100));
+
+    const targetHexId = await getConnectionHexId(targetName);
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-get-caller', recordingHandlers());
+    const conn = await rt.getConnection(targetHexId);
+    expect(conn).not.toBeNull();
+    expect(conn?.nick).toBe('carol');
+    expect(conn?.id).toBe(targetHexId);
+
+    ws.close();
+  });
+
+  it('getChannelConnections(chan) returns the ConnectionStates of all members', async () => {
+    const memberName = 'conn-who-target';
+    const ws = await openConnection(memberName);
+    await new Promise<void>((r) => setTimeout(r, 20));
+    ws.send('NICK dave\r\n');
+    ws.send('USER dave 0 * :Dave\r\n');
+    await new Promise<void>((r) => setTimeout(r, 100));
+
+    const memberHexId = await getConnectionHexId(memberName);
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-who-caller', recordingHandlers());
+
+    await rt.applyChannelDelta('#whochan', {
+      memberships: [{ type: 'add' as const, conn: memberHexId, nick: 'dave' }],
+    });
+
+    const conns = await rt.getChannelConnections('#whochan');
+    expect(conns.size).toBe(1);
+    expect(conns.get(memberHexId)?.nick).toBe('dave');
+
+    ws.close();
+  });
+
+  it('listChannels returns channels registered in the registry', async () => {
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-list', recordingHandlers());
+
+    await rt.applyChannelDelta('#listchan', {
+      memberships: [{ type: 'add' as const, conn: 'conn-list', nick: 'eve' }],
+    });
+
+    const channels = await rt.listChannels();
+    expect(channels.length).toBeGreaterThan(0);
+    expect(channels.some((c) => c.nameLower === '#listchan')).toBe(true);
+  });
+
+  it('listChannels returns empty array when no channels exist', async () => {
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-list-empty', recordingHandlers());
+    const channels = await rt.listChannels();
+    expect(channels).toEqual([]);
+  });
+
+  it('disconnect(remoteConn) closes the target connection', async () => {
+    const targetName = 'conn-disc-target';
+    const ws = await openConnection(targetName);
+    await new Promise<void>((r) => setTimeout(r, 20));
+
+    const targetHexId = await getConnectionHexId(targetName);
+    const realEnv = envWithRealDOs();
+    const rt = new CfRuntime(realEnv, 'conn-disc-caller', recordingHandlers());
+
+    const closed = new Promise<void>((resolve) => {
+      ws.addEventListener('close', () => resolve());
+      setTimeout(resolve, 2000);
+    });
+
+    await rt.disconnect(targetHexId, 'Kicked');
+    await closed;
+
+    expect([WebSocket.CLOSING, WebSocket.CLOSED]).toContain(ws.readyState);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // Tests — implements IrcRuntime
 // ---------------------------------------------------------------------------

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

@@ -101,6 +101,28 @@ describe('loadServerConfigFromCfEnv — valid env', () => {
     });
     expect(cfg.quitMessage).toBe('Bye from CF');
   });
+
+  it('threads SERVER_VERSION into serverVersion', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), SERVER_VERSION: '1.2.3' });
+    expect(cfg.serverVersion).toBe('1.2.3');
+  });
+
+  it('passes CREATED_AT verbatim when it is non-numeric', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), CREATED_AT: '2024-06-01' });
+    expect(cfg.createdAt).toBe('2024-06-01');
+  });
+
+  it('parses a numeric CREATED_AT string into an epoch-ms number', () => {
+    const cfg = loadServerConfigFromCfEnv({ ...baseEnv(), CREATED_AT: '1700000000000' });
+    expect(cfg.createdAt).toBe(1_700_000_000_000);
+  });
+
+  it('applies the schema defaults for serverVersion/createdAt when unset', () => {
+    const cfg = loadServerConfigFromCfEnv(baseEnv());
+    expect(typeof cfg.serverVersion).toBe('string');
+    expect(cfg.serverVersion.length).toBeGreaterThan(0);
+    expect(cfg.createdAt).toBeDefined();
+  });
 });
 
 describe('loadServerConfigFromCfEnv — failure modes', () => {

package/packages/cf-adapter/tests/connection-do-channel-registration.test.ts

@@ -0,0 +1,37 @@
+/**
+ * 085 — CF `webSocketMessage` channel-registration: wire ChannelDO
+ * registration OR remove the dead loop.
+ *
+ * Spike conclusion (documented in the ticket): the dead loop that
+ * iterated `state.joinedChannels` to "register" the ConnectionDO with
+ * each ChannelDO is redundant. Channel membership — and therefore
+ * broadcast fan-out registration — is driven solely by the
+ * `ApplyChannelDelta` effect the joinReducer emits. The CfRuntime
+ * forwards that effect to the authoritative ChannelDO
+ * (`cf-runtime.ts` → `channel-do.ts#applyChannelDelta`), whose roster
+ * is the single source of truth used by `ChannelDO.broadcast`. The
+ * `connection-do.test.ts` "QUIT fanout to each joined channel" test
+ * proves this end-to-end (alice JOINs, closes, and bob observes the
+ * QUIT that only the ChannelDO roster could have routed).
+ *
+ * Because the removed loop was a no-op (`void chan;`), there is no
+ * behaviour to assert — these are source-level regression guards that
+ * prevent the redundant registration loop from creeping back in.
+ */
+
+import { describe, expect, it } from 'vitest';
+import connectionDoSource from '../src/connection-do.ts?raw';
+
+describe('ConnectionDO — no redundant channel-registration loop', () => {
+  it('webSocketMessage contains no dead `void chan` no-op registration body', () => {
+    // The joinReducer's `ApplyChannelDelta` effect is the sole channel
+    // registration path; a per-ConnectionDO loop here is dead code.
+    expect(connectionDoSource).not.toContain('void chan');
+  });
+
+  it('documents that no explicit per-ConnectionDO registration step is needed', () => {
+    // The absence of the loop must be explained so it is not mistaken
+    // for a missing feature.
+    expect(connectionDoSource).toContain('No per-ConnectionDO channel-registration step is needed');
+  });
+});

package/packages/cf-adapter/tests/connection-do-no-batching-reservation.test.ts

@@ -0,0 +1,52 @@
+/**
+ * 087 — CF outbound batching: implement OR drop the reserved optimization.
+ *
+ * Spike conclusion (documented in the ticket): the speculative per-microtask
+ * outbound drain that was reserved as a commented-out field in
+ * `ConnectionDO` is dropped. Per-call batching is already implemented —
+ * `ConnectionDO.deliver()` joins every line of a ChannelDO broadcast into
+ * a single `WebSocket.send()`, and the actor `send` handler
+ * (`buildActor`) joins every line of one frame's response the same way.
+ * What the reservation speculated about was *cross-call* coalescing —
+ * queueing lines emitted by independent `deliver` / `send` invocations
+ * within the same microtask and flushing them in one write. That adds a
+ * drain queue, a `queueMicrotask` scheduler, and ordering hazards between
+ * independent fan-out calls, in exchange for no measured benefit: nothing
+ * in the load-test report or the ChannelDO fan-out path shows WS
+ * round-trips as a bottleneck. The AWS adapter batches at a
+ * different layer (per-invocation `outbound: string[]` accumulated then
+ * posted once), so there is no shared abstraction worth extracting.
+ *
+ * Because the removed reservation was a comment with no runtime
+ * behaviour, these are source-level regression guards (mirroring the
+ * pattern used for other dropped reservations) that prevent the
+ * speculative field from creeping back in and keep the deferral
+ * documented at the point a reader would otherwise expect the batching
+ * hook.
+ */
+
+import { describe, expect, it } from 'vitest';
+import connectionDoSource from '../src/connection-do.ts?raw';
+
+describe('ConnectionDO — no reserved outbound-batching field', () => {
+  it('does not contain the deferred "Reserved for a future batching optimization" comment', () => {
+    // The reservation is dropped; per-call batching in `deliver()` and
+    // the actor `send` handler is the implemented strategy.
+    expect(connectionDoSource).not.toContain('Reserved for a future batching optimization');
+  });
+
+  it('does not reintroduce a speculative outbound-drain field declaration', () => {
+    // Guards against any variant of the commented-out reservation. The
+    // implemented batching is per-call (join lines then `send` once);
+    // there is no instance-level drain queue.
+    expect(connectionDoSource).not.toContain('Outstanding outbound lines');
+    expect(connectionDoSource).not.toContain('drop the reservation');
+  });
+
+  it('documents the deferral decision at the point the reservation used to live', () => {
+    // The absence of the field must be explained so it is not mistaken
+    // for a missing feature, and a reader is pointed at the perf ADR.
+    expect(connectionDoSource).toContain('batched per call');
+    expect(connectionDoSource).toContain('ADR-003');
+  });
+});

package/packages/cf-adapter/tests/connection-do-sasl-d1.test.ts

@@ -0,0 +1,166 @@
+/**
+ * End-to-end SASL PLAIN through ConnectionDO with D1-backed accounts.
+ *
+ * Verifies the full precedence matrix:
+ *   - D1 has rows → table is authoritative (900/903 for seeded account,
+ *     904 for the env-seed account which the table shadows).
+ *   - D1 empty → the `SASL_ACCOUNTS` env-var seed still works (fallback).
+ *
+ * Each test file gets its own isolated D1 database from miniflare, so the
+ * table state set up here does not leak into `connection-do.test.ts`.
+ */
+
+import { env } from 'cloudflare:test';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { CREATE_ACCOUNTS_TABLE_SQL, putAccountCredential } from '../src/d1-account-store';
+
+declare global {
+  namespace Cloudflare {
+    interface Env {
+      CONNECTION_DO: DurableObjectNamespace;
+      REGISTRY_DO: DurableObjectNamespace;
+      CHANNEL_DO: DurableObjectNamespace;
+      ACCOUNTS_DB: D1Database;
+    }
+  }
+}
+
+class IrcWsClient {
+  readonly received: string[] = [];
+  readonly ws: WebSocket;
+
+  constructor(ws: WebSocket) {
+    this.ws = ws;
+    ws.addEventListener('message', (ev: MessageEvent) => {
+      const d = ev.data as string;
+      for (const line of d.split('\r\n')) {
+        if (line.length > 0) this.received.push(line);
+      }
+    });
+  }
+
+  send(line: string): void {
+    this.ws.send(line);
+  }
+
+  waitForMessage(predicate: (line: string) => boolean, timeoutMs = 2000): Promise<string> {
+    return new Promise<string>((resolve, reject) => {
+      const start = Date.now();
+      const tick = (): void => {
+        const hit = this.received.find(predicate);
+        if (hit !== undefined) {
+          resolve(hit);
+          return;
+        }
+        if (Date.now() - start > timeoutMs) {
+          reject(new Error(`timeout waiting for message; got: ${JSON.stringify(this.received)}`));
+          return;
+        }
+        setTimeout(tick, 20);
+      };
+      tick();
+    });
+  }
+
+  close(): Promise<void> {
+    return new Promise<void>((resolve) => {
+      this.ws.addEventListener('close', () => resolve());
+      this.ws.close();
+    });
+  }
+}
+
+async function connect(connId: string): Promise<IrcWsClient> {
+  const doId = env.CONNECTION_DO.idFromName(connId);
+  const stub = env.CONNECTION_DO.get(doId);
+  const response = await stub.fetch('https://do/upgrade', {
+    headers: { Upgrade: 'websocket' },
+  });
+  const ws = response.webSocket;
+  if (ws === undefined || ws === null) {
+    throw new Error('ConnectionDO.fetch did not return a WebSocket');
+  }
+  ws.accept();
+  return new Promise<IrcWsClient>((resolve) => {
+    setTimeout(() => resolve(new IrcWsClient(ws as WebSocket)), 0);
+  });
+}
+
+/** base64(`\0authcid\0password`) — the PLAIN payload format. */
+function plainB64(authcid: string, password: string): string {
+  const raw = `\0${authcid}\0${password}`;
+  let latin1 = '';
+  for (let i = 0; i < raw.length; i++) latin1 += String.fromCharCode(raw.charCodeAt(i));
+  return (globalThis as unknown as { btoa: (s: string) => string }).btoa(latin1);
+}
+
+/** Negotiates `CAP sasl` and sends an AUTHENTICATE PLAIN payload. */
+async function authenticatePlain(
+  client: IrcWsClient,
+  authcid: string,
+  password: string,
+): Promise<void> {
+  client.send('CAP REQ :sasl\r\n');
+  await client.waitForMessage((l) => / CAP \S+ ACK :sasl/.test(l));
+  client.send('AUTHENTICATE PLAIN\r\n');
+  await client.waitForMessage((l) => l === 'AUTHENTICATE +');
+  client.send(`AUTHENTICATE ${plainB64(authcid, password)}\r\n`);
+}
+
+describe('ConnectionDO — SASL PLAIN with D1-backed accounts', () => {
+  beforeEach(async () => {
+    await env.ACCOUNTS_DB.exec(CREATE_ACCOUNTS_TABLE_SQL);
+  });
+  afterEach(async () => {
+    await env.ACCOUNTS_DB.exec('DROP TABLE IF EXISTS accounts');
+  });
+
+  it('completes SASL PLAIN with 900/903 for a D1-seeded account', async () => {
+    await putAccountCredential(env.ACCOUNTS_DB, 'd1-alice', 'd1-s3cret');
+    const client = await connect('conn-d1-sasl-1');
+    await authenticatePlain(client, 'd1-alice', 'd1-s3cret');
+    await client.waitForMessage((l) => l.includes(' 900 '));
+    const success = await client.waitForMessage((l) => l.includes(' 903 '));
+    expect(success).toContain(' 903 ');
+    await client.close();
+  });
+
+  it('rejects SASL PLAIN with 904 for a wrong password (D1 account)', async () => {
+    await putAccountCredential(env.ACCOUNTS_DB, 'd1-alice', 'd1-s3cret');
+    const client = await connect('conn-d1-sasl-2');
+    await authenticatePlain(client, 'd1-alice', 'wrong');
+    const fail = await client.waitForMessage((l) => l.includes(' 904 '));
+    expect(fail).toContain(' 904 ');
+    await client.close();
+  });
+
+  it('table shadows the env-seed account (table wins)', async () => {
+    // SASL_ACCOUNTS env seeds "cf-sasl:s3cret" but D1 has no such row.
+    await putAccountCredential(env.ACCOUNTS_DB, 'd1-alice', 'd1-s3cret');
+    const client = await connect('conn-d1-sasl-3');
+    // env-seed account does NOT verify (table is authoritative).
+    await authenticatePlain(client, 'cf-sasl', 's3cret');
+    const fail = await client.waitForMessage((l) => l.includes(' 904 '));
+    expect(fail).toContain(' 904 ');
+    await client.close();
+  });
+});
+
+describe('ConnectionDO — SASL PLAIN in-memory fallback (D1 empty)', () => {
+  // The table exists but has zero rows → resolver falls back to SASL_ACCOUNTS.
+  beforeEach(async () => {
+    await env.ACCOUNTS_DB.exec(CREATE_ACCOUNTS_TABLE_SQL);
+  });
+  afterEach(async () => {
+    await env.ACCOUNTS_DB.exec('DROP TABLE IF EXISTS accounts');
+  });
+
+  it('falls back to SASL_ACCOUNTS seed when D1 is empty', async () => {
+    const client = await connect('conn-d1-sasl-fallback');
+    await authenticatePlain(client, 'cf-sasl', 's3cret');
+    await client.waitForMessage((l) => l.includes(' 900 '));
+    const success = await client.waitForMessage((l) => l.includes(' 903 '));
+    expect(success).toContain(' 903 ');
+    await client.close();
+  });
+});

package/packages/cf-adapter/tests/connection-do.test.ts

@@ -366,6 +366,46 @@ describe('ConnectionDO — chathistory end-to-end', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// SASL PLAIN end-to-end (AccountStore plumbing)
+// ---------------------------------------------------------------------------
+
+describe('ConnectionDO — SASL PLAIN end-to-end', () => {
+  /** base64(`\0authcid\0password`) — the PLAIN payload format. */
+  function plainB64(authcid: string, password: string): string {
+    // workerd has no `Buffer`; use btoa on a Latin1-encoded string.
+    const raw = `\0${authcid}\0${password}`;
+    let latin1 = '';
+    for (let i = 0; i < raw.length; i++) latin1 += String.fromCharCode(raw.charCodeAt(i));
+    return (globalThis as unknown as { btoa: (s: string) => string }).btoa(latin1);
+  }
+
+  it('completes SASL PLAIN with 900/903 for valid seeded creds', async () => {
+    const client = await connect('conn-sasl-1');
+    client.send('CAP REQ :sasl\r\n');
+    await client.waitForMessage((l) => / CAP \S+ ACK :sasl/.test(l));
+    client.send('AUTHENTICATE PLAIN\r\n');
+    await client.waitForMessage((l) => l === 'AUTHENTICATE +');
+    client.send(`AUTHENTICATE ${plainB64('cf-sasl', 's3cret')}\r\n`);
+    await client.waitForMessage((l) => l.includes(' 900 '));
+    const success = await client.waitForMessage((l) => l.includes(' 903 '));
+    expect(success).toContain(' 903 ');
+    client.ws.close();
+  });
+
+  it('rejects SASL PLAIN with 904 for invalid creds', async () => {
+    const client = await connect('conn-sasl-2');
+    client.send('CAP REQ :sasl\r\n');
+    await client.waitForMessage((l) => / CAP \S+ ACK :sasl/.test(l));
+    client.send('AUTHENTICATE PLAIN\r\n');
+    await client.waitForMessage((l) => l === 'AUTHENTICATE +');
+    client.send(`AUTHENTICATE ${plainB64('cf-sasl', 'wrong')}\r\n`);
+    const fail = await client.waitForMessage((l) => l.includes(' 904 '));
+    expect(fail).toContain(' 904 ');
+    client.ws.close();
+  });
+});
+
 // ---------------------------------------------------------------------------
 // End of file
 // ---------------------------------------------------------------------------