serverless-ircd 0.1.0 → 0.2.0

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

@@ -0,0 +1,420 @@
+/**
+ * Gone-connection sweeper — a Lambda on a fixed EventBridge schedule
+ * that scans `Connections` for rows whose `idleSince` is older than a
+ * TTL threshold and runs {@link cleanupConnection} on each.
+ *
+ * Catches the case where a client vanished without APIGW ever emitting
+ * `$disconnect` (TCP RST behind a flaky NAT, mobile backgrounding,
+ * etc.). The DynamoDB TTL on `idleSince` eventually reaps the row too,
+ * but TTL expiry is eventual (up to ~48h) and does NOT clean up the
+ * matching `ChannelMembers` / `Nicks` rows — the sweeper does.
+ *
+ * Gated on `process.env.DDB_AVAILABLE` (real DynamoDB Local).
+ */
+
+import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
+import { PutCommand, QueryCommand } 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 { cleanupConnection } from '../src/aws-runtime.js';
+import { TABLE_DEFS } from '../src/cdk-table-defs.js';
+import { createDynamoDocumentClient } from '../src/dynamo.js';
+import { type SweepParams, type SweepResult, handleSweep } from '../src/handlers/sweeper.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;
+
+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 = `s${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 params(overrides: Partial<SweepParams> = {}): SweepParams {
+  return {
+    dynamo: fx!.client,
+    tables: fx!.tables,
+    ...overrides,
+  };
+}
+
+/** Seeds a connection row with the supplied idleSince + optional nick + memberships. */
+async function seedConnection(opts: {
+  connId: string;
+  idleSince: number;
+  nick?: string;
+  channels?: ChanName[];
+}): Promise<void> {
+  const state = createConnection({ id: opts.connId, connectedSince: opts.idleSince });
+  state.registration = 'registered';
+  state.lastSeen = opts.idleSince;
+  if (opts.nick !== undefined) {
+    state.nick = opts.nick as Nick;
+    state.user = opts.nick;
+    await fx!.client.send(
+      new PutCommand({
+        TableName: fx!.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(
+      new PutCommand({
+        TableName: fx!.tables.ChannelMembers,
+        Item: marshalChannelMember(chan.toLowerCase(), {
+          conn: opts.connId,
+          nick: (opts.nick ?? 'x') as Nick,
+          op: false,
+          voice: false,
+        }),
+      }),
+    );
+  }
+  await fx!.client.send(
+    new PutCommand({
+      TableName: fx!.tables.Connections,
+      Item: marshalConnection(state, opts.idleSince),
+    }),
+  );
+}
+
+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 } }),
+  );
+  return res.Item !== undefined;
+}
+
+async function membersOf(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 }[];
+}
+
+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() } }),
+  );
+  return res.Item !== undefined;
+}
+
+describe.skipIf(!available)('gone-connection sweeper', () => {
+  beforeEach(async () => {
+    fx = await makeFixture();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+    fx = null;
+  });
+
+  it('removes a Connections row whose idleSince is older than the threshold', async () => {
+    const now = 10_000;
+    await seedConnection({ connId: 'stale', idleSince: 0 }); // very old
+    await seedConnection({ connId: 'fresh', idleSince: now }); // current
+
+    const result: SweepResult = await handleSweep(params({ now, staleAfterMs: 1_000 }));
+
+    expect(result.scanned).toBe(2);
+    expect(result.swept).toBe(1);
+    expect(await connectionExists('stale')).toBe(false);
+    expect(await connectionExists('fresh')).toBe(true);
+  });
+
+  it('keeps a fresh connection that is exactly at the boundary (not swept)', async () => {
+    const now = 5_000;
+    const staleAfterMs = 1_000;
+    // idleSince == now - staleAfterMs is the cutoff; strictly older is swept.
+    await seedConnection({ connId: 'boundary', idleSince: now - staleAfterMs });
+    await seedConnection({ connId: 'oneBefore', idleSince: now - staleAfterMs - 1 });
+
+    const result = await handleSweep(params({ now, staleAfterMs }));
+
+    expect(result.swept).toBe(1);
+    expect(await connectionExists('boundary')).toBe(true);
+    expect(await connectionExists('oneBefore')).toBe(false);
+  });
+
+  it('removes the swept connection’s ChannelMembers rows', async () => {
+    const now = 10_000;
+    await seedConnection({
+      connId: 'stale',
+      idleSince: 0,
+      nick: 'alice',
+      channels: ['#foo' as ChanName, '#bar' as ChanName],
+    });
+
+    await handleSweep(params({ now, staleAfterMs: 1_000 }));
+
+    expect(await membersOf('#foo')).toHaveLength(0);
+    expect(await membersOf('#bar')).toHaveLength(0);
+  });
+
+  it('releases the swept connection’s nick', async () => {
+    const now = 10_000;
+    await seedConnection({ connId: 'stale', idleSince: 0, nick: 'alice' });
+
+    await handleSweep(params({ now, staleAfterMs: 1_000 }));
+
+    expect(await nickExists('alice')).toBe(false);
+  });
+
+  it('leaves a fresh connection’s memberships and nick intact', async () => {
+    const now = 10_000;
+    await seedConnection({
+      connId: 'fresh',
+      idleSince: now,
+      nick: 'bob',
+      channels: ['#room' as ChanName],
+    });
+
+    await handleSweep(params({ now, staleAfterMs: 1_000 }));
+
+    expect(await connectionExists('fresh')).toBe(true);
+    expect(await nickExists('bob')).toBe(true);
+    expect(await membersOf('#room')).toHaveLength(1);
+  });
+
+  it('is idempotent — running twice does not throw and sweeps 0 the second time', async () => {
+    const now = 10_000;
+    await seedConnection({ connId: 'stale', idleSince: 0 });
+
+    const first = await handleSweep(params({ now, staleAfterMs: 1_000 }));
+    const second = await handleSweep(params({ now, staleAfterMs: 1_000 }));
+
+    expect(first.swept).toBe(1);
+    expect(second.swept).toBe(0);
+  });
+
+  it('reports scanned=0 / swept=0 on an empty table', async () => {
+    const result = await handleSweep(params({ now: 1_000, staleAfterMs: 1 }));
+    expect(result.scanned).toBe(0);
+    expect(result.swept).toBe(0);
+  });
+
+  it('uses a sensible default threshold when staleAfterMs is omitted', async () => {
+    // Two-hour-old row should be swept by the default (2h) threshold.
+    const HOUR = 60 * 60 * 1000;
+    const now = 10 * HOUR;
+    await seedConnection({ connId: 'twoHoursOld', idleSince: now - 2 * HOUR - 1 });
+    await seedConnection({ connId: 'recent', idleSince: now - 30 * 60 * 1000 });
+
+    const result = await handleSweep(params({ now }));
+
+    expect(result.swept).toBe(1);
+    expect(await connectionExists('twoHoursOld')).toBe(false);
+    expect(await connectionExists('recent')).toBe(true);
+  });
+
+  it('sweeps multiple stale connections in one pass', async () => {
+    const now = 10_000;
+    await seedConnection({ connId: 's1', idleSince: 0 });
+    await seedConnection({ connId: 's2', idleSince: 0 });
+    await seedConnection({ connId: 's3', idleSince: 0 });
+    await seedConnection({ connId: 'live', idleSince: now });
+
+    const result = await handleSweep(params({ now, staleAfterMs: 1_000 }));
+
+    expect(result.swept).toBe(3);
+    expect(await connectionExists('s1')).toBe(false);
+    expect(await connectionExists('s2')).toBe(false);
+    expect(await connectionExists('s3')).toBe(false);
+    expect(await connectionExists('live')).toBe(true);
+  });
+
+  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();
+  });
+
+  it('uses Date.now() when now is omitted (real-clock default path)', async () => {
+    // Seed a connection idle far in the past relative to the real clock.
+    await seedConnection({ connId: 'ancient', idleSince: 0 });
+    const before = Date.now();
+    const result = await handleSweep(params({ staleAfterMs: 1_000 }));
+    // At least one second has elapsed since epoch 0 under any clock.
+    expect(result.swept).toBeGreaterThanOrEqual(1);
+    expect(before).toBeGreaterThan(1_000);
+  });
+
+  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(
+      new PutCommand({
+        TableName: fx!.tables.Connections,
+        Item: {
+          connectionId: 'corrupt',
+          registration: 'registered',
+          capNegotiating: false,
+          caps: [],
+          userModes: {},
+          lastSeen: 0,
+          connectedSince: 0,
+          idleSince: 'not-a-number',
+          version: 1,
+        },
+      }),
+    );
+
+    const result = await handleSweep(params({ now: 10_000, staleAfterMs: 1 }));
+    expect(result.scanned).toBe(1);
+    expect(result.swept).toBe(0);
+    expect(await connectionExists('corrupt')).toBe(true);
+  });
+
+  it('paginates: sweeps across multiple Scan pages (forces a small page size via repeated scans)', async () => {
+    // Seed 3 stale connections. handleSweep paginates while
+    // LastEvaluatedKey is set; with so few rows DynamoDB Local returns
+    // a single page, but the do/while still exercises the loop's
+    // "lastKey === undefined" exit branch.
+    await seedConnection({ connId: 'p1', idleSince: 0 });
+    await seedConnection({ connId: 'p2', idleSince: 0 });
+    const result = await handleSweep(params({ now: 10_000, staleAfterMs: 1 }));
+    expect(result.swept).toBe(2);
+    expect(result.scanned).toBe(2);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scan-response edge cases (no DynamoDB Local — fake client)
+// ---------------------------------------------------------------------------
+
+import { type DynamoDBDocumentClient, ScanCommand } from '@aws-sdk/lib-dynamodb';
+
+/**
+ * Scripted page for the fake Scan client.
+ * - `items` left unset  -> response omits the `Items` field entirely
+ *   (exercises the sweeper's `?? []` defensive branch).
+ * - `items` set to `[]` -> response has `Items: []`.
+ * - `lastKey` set       -> response carries `LastEvaluatedKey`, forcing
+ *   another scan iteration (pagination branch).
+ */
+interface ScriptedPage {
+  items?: unknown[];
+  lastKey?: unknown;
+}
+
+/**
+ * Fake document client that returns scripted `ScanCommand` pages and
+ * empty success for every other command (cleanupConnection's Get/Delete
+ * are no-ops). Lets the sweeper's pagination + defensive branches run
+ * without real DynamoDB.
+ */
+class FakeScanDynamo {
+  constructor(private readonly pages: ScriptedPage[]) {}
+  async send(cmd: unknown): Promise<unknown> {
+    if (cmd instanceof ScanCommand) {
+      const page = this.pages.shift() ?? {};
+      const resp: Record<string, unknown> = {};
+      if (page.items !== undefined) {
+        resp.Items = page.items;
+      }
+      if (page.lastKey !== undefined) {
+        resp.LastEvaluatedKey = page.lastKey;
+      }
+      return resp;
+    }
+    // Get / Delete / Put — return empty success.
+    return {};
+  }
+}
+
+function fakeSweepParams(client: FakeScanDynamo): SweepParams {
+  return {
+    dynamo: client as unknown as DynamoDBDocumentClient,
+    tables: {
+      Connections: 'C',
+      ChannelMeta: 'CM',
+      ChannelMembers: 'CMem',
+      Nicks: 'N',
+      Accounts: 'A',
+    },
+    now: 10_000,
+    staleAfterMs: 1_000,
+  };
+}
+
+describe('gone-connection sweeper — scan edge cases', () => {
+  it('paginates across multiple Scan pages (ExclusiveStartKey carried between calls)', async () => {
+    const client = new FakeScanDynamo([
+      { items: [{ connectionId: 'a', idleSince: 0 }], lastKey: { connectionId: 'a' } },
+      { items: [{ connectionId: 'b', idleSince: 0 }], lastKey: { connectionId: 'b' } },
+      { items: [{ connectionId: 'c', idleSince: 0 }] },
+    ]);
+    const result = await handleSweep(fakeSweepParams(client));
+    expect(result.scanned).toBe(3);
+    expect(result.swept).toBe(3);
+  });
+
+  it('treats a missing Items field as an empty page (defensive)', async () => {
+    const client = new FakeScanDynamo([{}]);
+    const result = await handleSweep(fakeSweepParams(client));
+    expect(result.scanned).toBe(0);
+    expect(result.swept).toBe(0);
+  });
+
+  it('skips a row whose connectionId is not a string (defensive)', async () => {
+    const client = new FakeScanDynamo([{ items: [{ connectionId: 12345, idleSince: 0 }] }]);
+    const result = await handleSweep(fakeSweepParams(client));
+    expect(result.scanned).toBe(1);
+    expect(result.swept).toBe(0);
+  });
+});

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

@@ -0,0 +1,74 @@
+/**
+ * Unit tests for the runtime-safe table metadata in `src/tables.ts`.
+ *
+ * Pure-function tests; no DynamoDB needed.
+ */
+
+import { describe, expect, it } from 'vitest';
+import {
+  TABLE_KEYS,
+  TABLE_NAMES,
+  type TablesConfig,
+  tablesConfigFromNames,
+} from '../src/tables.js';
+
+describe('TABLE_NAMES', () => {
+  it('contains exactly the five canonical logical names', () => {
+    expect(TABLE_NAMES).toEqual([
+      'Connections',
+      'ChannelMeta',
+      'ChannelMembers',
+      'Nicks',
+      'Accounts',
+    ]);
+  });
+});
+
+describe('TABLE_KEYS', () => {
+  it('exposes the connectionId PK for Connections', () => {
+    expect(TABLE_KEYS.Connections.pk).toBe('connectionId');
+  });
+
+  it('exposes the channelName PK for ChannelMeta', () => {
+    expect(TABLE_KEYS.ChannelMeta.pk).toBe('channelName');
+  });
+
+  it('exposes both PK and SK for ChannelMembers', () => {
+    expect(TABLE_KEYS.ChannelMembers.pk).toBe('channelName');
+    expect(TABLE_KEYS.ChannelMembers.sk).toBe('connectionId');
+  });
+
+  it('exposes the nickLower PK for Nicks', () => {
+    expect(TABLE_KEYS.Nicks.pk).toBe('nickLower');
+  });
+
+  it('exposes the account PK for Accounts', () => {
+    expect(TABLE_KEYS.Accounts.pk).toBe('account');
+  });
+});
+
+describe('tablesConfigFromNames', () => {
+  it('round-trips each name', () => {
+    const names: TablesConfig = {
+      Connections: 'p-Connections',
+      ChannelMeta: 'p-ChannelMeta',
+      ChannelMembers: 'p-ChannelMembers',
+      Nicks: 'p-Nicks',
+      Accounts: 'p-Accounts',
+    };
+    expect(tablesConfigFromNames(names)).toEqual(names);
+  });
+
+  it('returns a new object (does not alias the input)', () => {
+    const names: TablesConfig = {
+      Connections: 'c',
+      ChannelMeta: 'cm',
+      ChannelMembers: 'cml',
+      Nicks: 'n',
+      Accounts: 'a',
+    };
+    const out = tablesConfigFromNames(names);
+    expect(out).not.toBe(names);
+    expect(out).toEqual(names);
+  });
+});