serverless-ircd 0.3.0 → 0.5.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/aws-adapter/tests/sweeper.test.ts

@@ -34,6 +34,11 @@ interface Fixture {
 
 let fx: Fixture | null;
 
+function requireFx(): Fixture {
+  if (!fx) throw new Error('test fixture not initialized');
+  return fx;
+}
+
 async function makeFixture(): Promise<Fixture> {
   if (endpoint === undefined) throw new Error('DYNAMO_ENDPOINT missing');
   const prefix = `s${Date.now()}-${Math.floor(Math.random() * 1e6)}-`;
@@ -81,8 +86,8 @@ async function makeFixture(): Promise<Fixture> {
 
 function params(overrides: Partial<SweepParams> = {}): SweepParams {
   return {
-    dynamo: fx!.client,
-    tables: fx!.tables,
+    dynamo: requireFx().client,
+    tables: requireFx().tables,
     ...overrides,
   };
 }
@@ -100,18 +105,18 @@ async function seedConnection(opts: {
   if (opts.nick !== undefined) {
     state.nick = opts.nick as Nick;
     state.user = opts.nick;
-    await fx!.client.send(
+    await requireFx().client.send(
       new PutCommand({
-        TableName: fx!.tables.Nicks,
+        TableName: requireFx().tables.Nicks,
         Item: marshalNick(opts.nick as Nick, opts.connId, opts.idleSince),
       }),
     );
   }
   for (const chan of opts.channels ?? []) {
     state.joinedChannels.add(chan);
-    await fx!.client.send(
+    await requireFx().client.send(
       new PutCommand({
-        TableName: fx!.tables.ChannelMembers,
+        TableName: requireFx().tables.ChannelMembers,
         Item: marshalChannelMember(chan.toLowerCase(), {
           conn: opts.connId,
           nick: (opts.nick ?? 'x') as Nick,
@@ -121,9 +126,9 @@ async function seedConnection(opts: {
       }),
     );
   }
-  await fx!.client.send(
+  await requireFx().client.send(
     new PutCommand({
-      TableName: fx!.tables.Connections,
+      TableName: requireFx().tables.Connections,
       Item: marshalConnection(state, opts.idleSince),
     }),
   );
@@ -131,16 +136,16 @@ async function seedConnection(opts: {
 
 async function connectionExists(connId: string): Promise<boolean> {
   const { GetCommand } = await import('@aws-sdk/lib-dynamodb');
-  const res = await fx!.client.send(
-    new GetCommand({ TableName: fx!.tables.Connections, Key: { connectionId: connId } }),
+  const res = await requireFx().client.send(
+    new GetCommand({ TableName: requireFx().tables.Connections, Key: { connectionId: connId } }),
   );
   return res.Item !== undefined;
 }
 
 async function membersOf(channelKey: string): Promise<{ connectionId: string }[]> {
-  const res = await fx!.client.send(
+  const res = await requireFx().client.send(
     new QueryCommand({
-      TableName: fx!.tables.ChannelMembers,
+      TableName: requireFx().tables.ChannelMembers,
       KeyConditionExpression: 'channelName = :k',
       ExpressionAttributeValues: { ':k': channelKey },
     }),
@@ -150,8 +155,8 @@ async function membersOf(channelKey: string): Promise<{ connectionId: string }[]
 
 async function nickExists(nick: string): Promise<boolean> {
   const { GetCommand } = await import('@aws-sdk/lib-dynamodb');
-  const res = await fx!.client.send(
-    new GetCommand({ TableName: fx!.tables.Nicks, Key: { nickLower: nick.toLowerCase() } }),
+  const res = await requireFx().client.send(
+    new GetCommand({ TableName: requireFx().tables.Nicks, Key: { nickLower: nick.toLowerCase() } }),
   );
   return res.Item !== undefined;
 }
@@ -281,8 +286,10 @@ describe.skipIf(!available)('gone-connection sweeper', () => {
 
   it('cleanupConnection is safe to call on a row the sweeper already removed (no throw)', async () => {
     await seedConnection({ connId: 'stale', idleSince: 0, nick: 'zed' });
-    await cleanupConnection(fx!.client, fx!.tables, 'stale', null);
-    await expect(cleanupConnection(fx!.client, fx!.tables, 'stale', null)).resolves.toBeUndefined();
+    await cleanupConnection(requireFx().client, requireFx().tables, 'stale', null);
+    await expect(
+      cleanupConnection(requireFx().client, requireFx().tables, 'stale', null),
+    ).resolves.toBeUndefined();
   });
 
   it('uses Date.now() when now is omitted (real-clock default path)', async () => {
@@ -297,9 +304,9 @@ describe.skipIf(!available)('gone-connection sweeper', () => {
 
   it('skips a row whose idleSince is not a number (defensive — corrupted row)', async () => {
     // Write a Connections row directly with a non-numeric idleSince.
-    await fx!.client.send(
+    await requireFx().client.send(
       new PutCommand({
-        TableName: fx!.tables.Connections,
+        TableName: requireFx().tables.Connections,
         Item: {
           connectionId: 'corrupt',
           registration: 'registered',

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

@@ -37,6 +37,11 @@ interface Fixture {
 
 let fx: Fixture | null;
 
+function requireFx(): Fixture {
+  if (!fx) throw new Error('test fixture not initialized');
+  return fx;
+}
+
 async function makeFixture(): Promise<Fixture> {
   if (endpoint === undefined) throw new Error('DYNAMO_ENDPOINT missing');
   const prefix = `x${Date.now()}-${Math.floor(Math.random() * 1e6)}-`;
@@ -89,8 +94,8 @@ function makeRuntime(connId: string): AwsRuntime {
     snapshot: () => undefined,
   };
   return new AwsRuntime({
-    dynamo: fx!.client,
-    tables: fx!.tables,
+    dynamo: requireFx().client,
+    tables: requireFx().tables,
     connId,
     handlers,
     managementApi: null,
@@ -100,9 +105,9 @@ function makeRuntime(connId: string): AwsRuntime {
 /** 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(
+  await requireFx().client.send(
     new PutCommand({
-      TableName: fx!.tables.Connections,
+      TableName: requireFx().tables.Connections,
       Item: marshalConnection(state, idleSince),
     }),
   );
@@ -110,9 +115,9 @@ async function seedConnection(connId: string, idleSince = 1_000): Promise<void>
 
 /** 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(
+  const res = await requireFx().client.send(
     new GetCommand({
-      TableName: fx!.tables.Connections,
+      TableName: requireFx().tables.Connections,
       Key: { connectionId: connId },
     }),
   );
@@ -121,9 +126,9 @@ async function readConnection(connId: string): Promise<{ joinedChannels?: unknow
 
 /** Reads every ChannelMembers row for a channel. */
 async function readMembers(channelKey: string): Promise<{ connectionId: string }[]> {
-  const res = await fx!.client.send(
+  const res = await requireFx().client.send(
     new QueryCommand({
-      TableName: fx!.tables.ChannelMembers,
+      TableName: requireFx().tables.ChannelMembers,
       KeyConditionExpression: 'channelName = :k',
       ExpressionAttributeValues: { ':k': channelKey },
     }),
@@ -137,15 +142,15 @@ async function seedMembership(connId: string, nick: string, channel: ChanName):
   state.registration = 'registered';
   state.nick = nick as Nick;
   state.joinedChannels.add(channel);
-  await fx!.client.send(
+  await requireFx().client.send(
     new PutCommand({
-      TableName: fx!.tables.Connections,
+      TableName: requireFx().tables.Connections,
       Item: marshalConnection(state, 1_000),
     }),
   );
-  await fx!.client.send(
+  await requireFx().client.send(
     new PutCommand({
-      TableName: fx!.tables.ChannelMembers,
+      TableName: requireFx().tables.ChannelMembers,
       Item: marshalChannelMember(channel.toLowerCase(), {
         conn: connId,
         nick: nick as Nick,
@@ -182,8 +187,8 @@ describe.skipIf(!available)('membership transactions', () => {
 
     const row = await readConnection('c1');
     expect(row).toBeDefined();
-    expect(row!.joinedChannels).toBeInstanceOf(Set);
-    expect((row!.joinedChannels as Set<string>).has('#foo')).toBe(true);
+    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 () => {
@@ -199,7 +204,7 @@ describe.skipIf(!available)('membership transactions', () => {
 
     const row = await readConnection('c1');
     expect(row).toBeDefined();
-    expect((row!.joinedChannels as Set<string> | undefined)?.has('#foo') ?? false).toBe(false);
+    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 () => {
@@ -211,7 +216,7 @@ describe.skipIf(!available)('membership transactions', () => {
     });
 
     const row = await readConnection('target');
-    expect((row!.joinedChannels as Set<string> | undefined)?.has('#room') ?? false).toBe(false);
+    expect((row?.joinedChannels as Set<string> | undefined)?.has('#room') ?? false).toBe(false);
     expect(await readMembers('#room')).toHaveLength(0);
   });
 
@@ -234,7 +239,7 @@ describe.skipIf(!available)('membership transactions', () => {
     ]);
 
     const row = await readConnection('c1');
-    const joined = row!.joinedChannels as Set<string>;
+    const joined = row?.joinedChannels as Set<string>;
     expect(joined.has('#foo')).toBe(true);
     expect(joined.has('#bar')).toBe(true);
 
@@ -260,7 +265,7 @@ describe.skipIf(!available)('membership transactions', () => {
 
     expect(await readMembers('#foo')).toHaveLength(1);
     const row = await readConnection('c1');
-    const joined = row!.joinedChannels as Set<string>;
+    const joined = row?.joinedChannels as Set<string>;
     expect(joined.has('#foo')).toBe(true);
     expect([...joined].filter((c) => c === '#foo')).toHaveLength(1);
   });
@@ -283,7 +288,7 @@ describe.skipIf(!available)('membership transactions', () => {
 
     expect(await readMembers('#foo')).toHaveLength(0);
     const row = await readConnection('c1');
-    expect((row!.joinedChannels as Set<string> | undefined)?.size ?? 0).toBe(0);
+    expect((row?.joinedChannels as Set<string> | undefined)?.size ?? 0).toBe(0);
   });
 
   // -------------------------------------------------------------------------
@@ -303,7 +308,7 @@ describe.skipIf(!available)('membership transactions', () => {
 
     expect(await readMembers('#foo')).toHaveLength(0);
     const row = await readConnection('c1');
-    expect((row!.joinedChannels as Set<string> | undefined)?.size ?? 0).toBe(0);
+    expect((row?.joinedChannels as Set<string> | undefined)?.size ?? 0).toBe(0);
   });
 });
 

package/packages/cf-adapter/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serverless-ircd/cf-adapter",
-  "version": "0.3.0",
+  "version": "0.5.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": {