serverless-ircd 0.4.0 → 0.6.0

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

@@ -0,0 +1,317 @@
+import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { type Clock, createConnection } from '@serverless-ircd/irc-core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { AwsRuntime } from '../src/aws-runtime.js';
+import type { AwsRuntimeHandlers } from '../src/aws-runtime.js';
+import { TABLE_DEFS } from '../src/cdk-table-defs.js';
+import { createDynamoDocumentClient } from '../src/dynamo.js';
+import { AwsStats } from '../src/stats.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;
+
+async function makeFixture(): Promise<Fixture> {
+  if (endpoint === undefined) throw new Error('DYNAMO_ENDPOINT missing');
+  const prefix = `t${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)) {
+        await client.send(new DeleteTableCommand({ TableName: `${prefix}${logical}` }));
+      }
+    },
+  };
+}
+
+function noopHandlers(): AwsRuntimeHandlers {
+  return {
+    send: () => {},
+    disconnect: () => {},
+    snapshot: () => undefined,
+  };
+}
+
+function makeRuntime(connId: string, clockFn: () => number = () => 1_000): AwsRuntime {
+  const clock: Clock = { now: clockFn };
+  return new AwsRuntime({
+    dynamo: fx.client,
+    tables: fx.tables,
+    connId,
+    handlers: noopHandlers(),
+    managementApi: null,
+    clock,
+  });
+}
+
+describe.skipIf(!available)('AwsStats', () => {
+  beforeEach(async () => {
+    fx = await makeFixture();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+  });
+
+  it('returns zero counts for an empty deployment', async () => {
+    const stats = new AwsStats({
+      dynamo: fx.client,
+      tables: fx.tables,
+      uptimeStartedAt: 1_000,
+    });
+    const snap = await stats.getStats();
+    expect(snap.users).toBe(0);
+    expect(snap.channels).toBe(0);
+    expect(snap.servers).toBe(1);
+    expect(snap.localConns).toBe(0);
+  });
+
+  it('counts registered connections (visible, invisible, opers)', async () => {
+    const rt = makeRuntime('self');
+    const a = createConnection({ id: 'c1', connectedSince: 0 });
+    a.nick = 'alice';
+    a.registration = 'registered';
+    const b = createConnection({ id: 'c2', connectedSince: 0 });
+    b.nick = 'bob';
+    b.registration = 'registered';
+    b.userModes.invisible = true;
+    const c = createConnection({ id: 'c3', connectedSince: 0 });
+    c.nick = 'carol';
+    c.registration = 'registered';
+    c.userModes.oper = true;
+    const d = createConnection({ id: 'c4', connectedSince: 0 });
+    d.registration = 'pre-registration';
+    await rt.persistConnectionState(a);
+    await rt.persistConnectionState(b);
+    await rt.persistConnectionState(c);
+    await rt.persistConnectionState(d);
+
+    const stats = new AwsStats({
+      dynamo: fx.client,
+      tables: fx.tables,
+      uptimeStartedAt: 1_000,
+    });
+    const snap = await stats.getStats();
+    // 3 registered (2 visible + 1 invisible), 1 oper, 1 unknown, 4 total.
+    expect(snap.users).toBe(2);
+    expect(snap.invisible).toBe(1);
+    expect(snap.opers).toBe(1);
+    expect(snap.unknownConnections).toBe(1);
+    expect(snap.localConns).toBe(4);
+  });
+
+  it('counts channels via the ChannelMeta table', async () => {
+    const rt = makeRuntime('self');
+    await rt.applyChannelDelta('#a', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' }],
+    });
+    await rt.applyChannelDelta('#b', {
+      memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' }],
+    });
+
+    const stats = new AwsStats({
+      dynamo: fx.client,
+      tables: fx.tables,
+      uptimeStartedAt: 1_000,
+    });
+    const snap = await stats.getStats();
+    expect(snap.channels).toBe(2);
+  });
+
+  it('echoes the supplied uptimeStartedAt', async () => {
+    const stats = new AwsStats({
+      dynamo: fx.client,
+      tables: fx.tables,
+      uptimeStartedAt: 7_777,
+    });
+    const snap = await stats.getStats();
+    expect(snap.uptimeStartedAt).toBe(7_777);
+  });
+
+  it('honours supplied maxLocalConns / maxGlobalConns overrides', async () => {
+    const rt = makeRuntime('self');
+    const a = createConnection({ id: 'c1', connectedSince: 0 });
+    a.nick = 'alice';
+    a.registration = 'registered';
+    await rt.persistConnectionState(a);
+
+    const stats = new AwsStats({
+      dynamo: fx.client,
+      tables: fx.tables,
+      uptimeStartedAt: 1_000,
+      maxLocalConns: 99,
+      maxGlobalConns: 88,
+    });
+    const snap = await stats.getStats();
+    expect(snap.maxLocalConns).toBe(99);
+    expect(snap.maxGlobalConns).toBe(88);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Mock-based unit tests — exercise the defensive Scan fallbacks without
+// requiring DynamoDB Local.
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds a stub DocumentClient whose `send` returns canned Scan output.
+ * Exercises the `?? []` and `?? 0` fallbacks in {@link AwsStats.getStats}
+ * that the DynamoDB-Local integration suite cannot reach (the SDK always
+ * returns defined arrays / counts there).
+ *
+ * Pass `connectionsItems: undefined` to simulate the SDK omitting the
+ * `Items` field entirely (the `?? []` fallback path).
+ */
+function stubDynamo(
+  connectionsItems: unknown[] | undefined,
+  channelCount: number | undefined,
+): DynamoDBDocumentClient {
+  const calls: { TableName: string }[] = [];
+  const stub = {
+    send: async (cmd: {
+      input?: { TableName?: string; Select?: string };
+      TableName?: string;
+      Select?: string;
+    }) => {
+      // ScanCommand exposes its input via `.input`; both shapes are tolerated.
+      const input = (cmd as { input?: { TableName?: string; Select?: string } }).input ?? cmd;
+      const tableName = input.TableName ?? '';
+      const select = input.Select;
+      calls.push({ TableName: tableName });
+      void calls;
+      // Heuristic: the Connections scan omits `Select`, the ChannelMeta
+      // scan sets `Select: 'COUNT'`.
+      if (select === 'COUNT') {
+        return { Count: channelCount };
+      }
+      // Returning `{}` (no Items key) exercises the `?? []` fallback.
+      return connectionsItems === undefined ? {} : { Items: connectionsItems };
+    },
+  };
+  // Expose calls for any future assertions.
+  (stub as { _calls?: unknown })._calls = calls;
+  return stub as unknown as DynamoDBDocumentClient;
+}
+
+describe('AwsStats — defensive Scan fallbacks (mocked client)', () => {
+  // These tests do NOT require DynamoDB Local — they exercise the
+  // `?? []` / `?? 0` fallbacks by feeding a stub client.
+  it('returns empty arrays when the Connections Scan yields no Items field', async () => {
+    const tables: TablesConfig = {
+      Connections: 'Connections',
+      ChannelMeta: 'ChannelMeta',
+      ChannelMembers: 'ChannelMembers',
+      Nicks: 'Nicks',
+      Accounts: 'Accounts',
+    };
+    // Pass `undefined` so the stub returns `{}` — no Items key — to
+    // exercise the `?? []` fallback on the Connections scan, and
+    // `undefined` for Count to exercise the `?? 0` fallback.
+    const dynamo = stubDynamo(undefined, undefined);
+    const stats = new AwsStats({ dynamo, tables, uptimeStartedAt: 1_000 });
+    const snap = await stats.getStats();
+    expect(snap.users).toBe(0);
+    expect(snap.unknownConnections).toBe(0);
+    expect(snap.channels).toBe(0);
+    expect(snap.localConns).toBe(0);
+  });
+
+  it('honours maxLocalConns / maxGlobalConns overrides via the stub client', async () => {
+    const tables: TablesConfig = {
+      Connections: 'Connections',
+      ChannelMeta: 'ChannelMeta',
+      ChannelMembers: 'ChannelMembers',
+      Nicks: 'Nicks',
+      Accounts: 'Accounts',
+    };
+    const dynamo = stubDynamo([], 0);
+    const stats = new AwsStats({
+      dynamo,
+      tables,
+      uptimeStartedAt: 1_000,
+      maxLocalConns: 42,
+      maxGlobalConns: 43,
+    });
+    const snap = await stats.getStats();
+    expect(snap.maxLocalConns).toBe(42);
+    expect(snap.maxGlobalConns).toBe(43);
+  });
+
+  it('counts connections returned by the stub client', async () => {
+    const tables: TablesConfig = {
+      Connections: 'Connections',
+      ChannelMeta: 'ChannelMeta',
+      ChannelMembers: 'ChannelMembers',
+      Nicks: 'Nicks',
+      Accounts: 'Accounts',
+    };
+    // Two registered connection rows.
+    const items = [
+      {
+        connectionId: 'c1',
+        registration: 'registered',
+        capNegotiating: false,
+        caps: [],
+        userModes: { invisible: false, oper: false, wallops: false, serverNotices: false },
+        lastSeen: 0,
+        connectedSince: 0,
+        idleSince: 0,
+        version: 1,
+      },
+      {
+        connectionId: 'c2',
+        registration: 'registered',
+        capNegotiating: false,
+        caps: [],
+        userModes: { invisible: true, oper: false, wallops: false, serverNotices: false },
+        lastSeen: 0,
+        connectedSince: 0,
+        idleSince: 0,
+        version: 1,
+      },
+    ];
+    const dynamo = stubDynamo(items, 3);
+    const stats = new AwsStats({ dynamo, tables, uptimeStartedAt: 1_000 });
+    const snap = await stats.getStats();
+    expect(snap.users).toBe(1); // 2 registered − 1 invisible
+    expect(snap.invisible).toBe(1);
+    expect(snap.channels).toBe(3);
+    expect(snap.localConns).toBe(2);
+  });
+});

package/packages/cf-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-adapter",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "private": true,
   "description": "Cloudflare Workers adapter: Durable Objects (ConnectionDO, RegistryDO, ChannelDO) and CfRuntime implementing IrcRuntime",
   "license": "BSD-3-Clause",
@@ -11,6 +11,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./accounts": {
+      "types": "./dist/d1-account-store.d.ts",
+      "import": "./dist/d1-account-store.js"
     }
   },
   "scripts": {
@@ -31,6 +35,7 @@
     "@cloudflare/workers-types": "^5.20260714.1",
     "@serverless-ircd/in-memory-runtime": "workspace:*",
     "@serverless-ircd/irc-test-support": "workspace:*",
+    "@vitest/coverage-istanbul": "^4.1.0",
     "@vitest/coverage-v8": "^4.1.0",
     "rimraf": "^6.0.0",
     "typescript": "^5.6.0",

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

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

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

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