serverless-ircd 0.2.0 → 0.4.0

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

@@ -0,0 +1,78 @@
+/**
+ * Unit tests for `handleConnect` that exercise the DynamoDB plumbing
+ * branches the integration suite cannot reach cheaply — namely the
+ * paginated `Scan COUNT` loop (a real DynamoDB Local table fits in a
+ * single page) and the `Count ?? 0` defensive fallback. A hand-rolled
+ * stub client stands in for `DynamoDBDocumentClient`; the admission
+ * policy itself is covered by `admission.test.ts`.
+ */
+
+import { type DynamoDBDocumentClient, PutCommand, ScanCommand } from '@aws-sdk/lib-dynamodb';
+import { DEFAULT_SERVER_CONFIG } from '@serverless-ircd/irc-core';
+import { describe, expect, it } from 'vitest';
+import { handleConnect } from '../src/handlers/connect.js';
+import type { TablesConfig } from '../src/tables.js';
+
+const TABLES: TablesConfig = {
+  Connections: 'Connections',
+  ChannelMeta: 'ChannelMeta',
+  ChannelMembers: 'ChannelMembers',
+  Nicks: 'Nicks',
+  Accounts: 'Accounts',
+};
+
+interface Stub {
+  dynamo: DynamoDBDocumentClient;
+  puts: number;
+}
+
+/** Builds a stub client that serves the supplied `Scan` pages in order. */
+function makeStub(pages: Array<Record<string, unknown>>): Stub {
+  let scanIdx = 0;
+  const calls = { puts: 0 };
+  const dynamo = {
+    send: async (cmd: unknown) => {
+      if (cmd instanceof ScanCommand) {
+        return pages[scanIdx++] ?? { Count: 0 };
+      }
+      if (cmd instanceof PutCommand) {
+        calls.puts++;
+        return {};
+      }
+      throw new Error('unexpected command');
+    },
+  } as unknown as DynamoDBDocumentClient;
+  return {
+    dynamo,
+    get puts() {
+      return calls.puts;
+    },
+  };
+}
+
+describe('handleConnect admission plumbing', () => {
+  it('sums Scan COUNT across pages and admits (writes the row) when below the cap', async () => {
+    const stub = makeStub([{ Count: 1, LastEvaluatedKey: { connectionId: 'page-1' } }, {}]);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-paged',
+      now: 42,
+      serverConfig: { ...DEFAULT_SERVER_CONFIG, maxClients: 5 },
+    });
+    expect(outcome).toEqual({ admitted: true });
+    expect(stub.puts).toBe(1);
+  });
+
+  it('does not write a row when the count reaches the cap', async () => {
+    const stub = makeStub([{ Count: 5 }]);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-full',
+      serverConfig: { ...DEFAULT_SERVER_CONFIG, maxClients: 5 },
+    });
+    expect(outcome).toEqual({ admitted: false, statusCode: 429, reason: 'server full' });
+    expect(stub.puts).toBe(0);
+  });
+});

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

@@ -0,0 +1,343 @@
+/**
+ * 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, type PostToConnection, cleanupConnection } from '../src/aws-runtime.js';
+import { TABLE_DEFS } from '../src/cdk-table-defs.js';
+import { createDynamoDocumentClient } from '../src/dynamo.js';
+import { handleDisconnect } from '../src/handlers/disconnect.js';
+import { type HandlerDeps, __resetHandlerCacheForTests, dispatch } from '../src/handlers/index.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;
+
+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 = `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(requireFx().client, requireFx().tables, 'a', 'alice', '#room');
+    await seedConnection(requireFx().client, requireFx().tables, 'b', 'bob', '#room');
+
+    const mgmt = new RecordingPostToConnection();
+    await handleDisconnect({
+      dynamo: requireFx().client,
+      tables: requireFx().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(requireFx().client, requireFx().tables, 'a', 'alice', '#room');
+    await handleDisconnect({
+      dynamo: requireFx().client,
+      tables: requireFx().tables,
+      connectionId: 'a',
+      managementApi: null,
+    });
+    const p = probe(requireFx().client, requireFx().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: requireFx().client,
+      tables: requireFx().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(requireFx().client, requireFx().tables, 'a', 'alice', '#room');
+    await seedConnection(requireFx().client, requireFx().tables, 'b', 'bob', '#room');
+
+    const mgmt = new RecordingPostToConnection();
+    mgmt.markGone('b');
+
+    await expect(
+      handleDisconnect({
+        dynamo: requireFx().client,
+        tables: requireFx().tables,
+        connectionId: 'a',
+        managementApi: mgmt,
+      }),
+    ).resolves.toBeUndefined();
+
+    // The gone peer b was lazily cleaned up (Connection row removed).
+    const p = probe(requireFx().client, requireFx().tables);
+    expect(await p.getConnectionInfo('b')).toBeNull();
+  });
+
+  it('cleanupConnection directly broadcasts QUIT when given a managementApi', async () => {
+    await seedConnection(requireFx().client, requireFx().tables, 'a', 'alice', '#room');
+    await seedConnection(requireFx().client, requireFx().tables, 'b', 'bob', '#room');
+
+    const mgmt = new RecordingPostToConnection();
+    await cleanupConnection(requireFx().client, requireFx().tables, 'a', mgmt);
+
+    const bobReceived = mgmt.sent.get('b') ?? [];
+    expect(bobReceived).toContain(':alice!alice@x QUIT :Client Quit');
+    const p = probe(requireFx().client, requireFx().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: requireFx().client,
+      tables: requireFx().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(requireFx().client, requireFx().tables, 'alice', 'alice', '#room');
+    await seedConnection(requireFx().client, requireFx().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: requireFx().client,
+      tables: requireFx().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(requireFx().client, requireFx().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(requireFx().client, requireFx().tables, 'a', 'alice', '#room');
+    await seedConnection(requireFx().client, requireFx().tables, 'b', 'bob', '#room');
+
+    const mgmt = new RecordingPostToConnection();
+    mgmt.markError('b', new Error('transient network failure'));
+
+    await expect(
+      handleDisconnect({
+        dynamo: requireFx().client,
+        tables: requireFx().tables,
+        connectionId: 'a',
+        managementApi: mgmt,
+      }),
+    ).rejects.toThrow('transient network failure');
+  });
+});

package/packages/aws-adapter/tests/gone-exception.test.ts

@@ -42,6 +42,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 = `g${Date.now()}-${Math.floor(Math.random() * 1e6)}-`;
@@ -136,7 +141,7 @@ describe.skipIf(!available)('GoneException cleanup', () => {
   });
 
   it('send() to a gone connection triggers cleanupConnection and deletes Connections/Nicks/Members rows', async () => {
-    await seedConnection(fx!.client, fx!.tables, 'gone', 'bob', '#room');
+    await seedConnection(requireFx().client, requireFx().tables, 'gone', 'bob', '#room');
 
     // A self-connection runtime that tries to `send` to 'gone'.
     const mgmt: PostToConnection = {
@@ -149,8 +154,8 @@ describe.skipIf(!available)('GoneException cleanup', () => {
     };
 
     const runtime = new AwsRuntime({
-      dynamo: fx!.client,
-      tables: fx!.tables,
+      dynamo: requireFx().client,
+      tables: requireFx().tables,
       connId: 'self',
       handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
       managementApi: mgmt,
@@ -159,8 +164,8 @@ describe.skipIf(!available)('GoneException cleanup', () => {
     await runtime.send('gone', [{ text: ':self PRIVMSG bob :hi' } as never]);
 
     const probe = new AwsRuntime({
-      dynamo: fx!.client,
-      tables: fx!.tables,
+      dynamo: requireFx().client,
+      tables: requireFx().tables,
       connId: '__probe__',
       handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
       managementApi: null,
@@ -172,15 +177,15 @@ describe.skipIf(!available)('GoneException cleanup', () => {
   });
 
   it('send() to a non-gone error rethrows', async () => {
-    await seedConnection(fx!.client, fx!.tables, 'present', 'carol', '#room');
+    await seedConnection(requireFx().client, requireFx().tables, 'present', 'carol', '#room');
     const mgmt: PostToConnection = {
       async postToConnection() {
         throw new Error('network down');
       },
     };
     const runtime = new AwsRuntime({
-      dynamo: fx!.client,
-      tables: fx!.tables,
+      dynamo: requireFx().client,
+      tables: requireFx().tables,
       connId: 'self',
       handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
       managementApi: mgmt,
@@ -190,8 +195,8 @@ describe.skipIf(!available)('GoneException cleanup', () => {
     ).rejects.toThrow('network down');
     // The target row should NOT have been cleaned up.
     const probe = new AwsRuntime({
-      dynamo: fx!.client,
-      tables: fx!.tables,
+      dynamo: requireFx().client,
+      tables: requireFx().tables,
       connId: '__probe__',
       handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
       managementApi: null,
@@ -200,12 +205,12 @@ describe.skipIf(!available)('GoneException cleanup', () => {
   });
 
   it('cleanupConnection is idempotent when called twice', async () => {
-    await seedConnection(fx!.client, fx!.tables, 'gone2', 'dave', '#room');
-    await cleanupConnection(fx!.client, fx!.tables, 'gone2', null);
-    await cleanupConnection(fx!.client, fx!.tables, 'gone2', null);
+    await seedConnection(requireFx().client, requireFx().tables, 'gone2', 'dave', '#room');
+    await cleanupConnection(requireFx().client, requireFx().tables, 'gone2', null);
+    await cleanupConnection(requireFx().client, requireFx().tables, 'gone2', null);
     const probe = new AwsRuntime({
-      dynamo: fx!.client,
-      tables: fx!.tables,
+      dynamo: requireFx().client,
+      tables: requireFx().tables,
       connId: '__probe__',
       handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
       managementApi: null,
@@ -215,20 +220,20 @@ describe.skipIf(!available)('GoneException cleanup', () => {
 
   it('cleanupConnection is safe when the connection row is missing', async () => {
     await expect(
-      cleanupConnection(fx!.client, fx!.tables, 'never-existed', null),
+      cleanupConnection(requireFx().client, requireFx().tables, 'never-existed', null),
     ).resolves.toBeUndefined();
   });
 
   it('broadcast() skips and cleans up gone members', async () => {
-    await seedConnection(fx!.client, fx!.tables, 'gone3', 'eve', '#room');
+    await seedConnection(requireFx().client, requireFx().tables, 'gone3', 'eve', '#room');
     const mgmt: PostToConnection = {
       async postToConnection() {
         throw new GoneException({ $metadata: {}, message: 'Gone' });
       },
     };
     const runtime = new AwsRuntime({
-      dynamo: fx!.client,
-      tables: fx!.tables,
+      dynamo: requireFx().client,
+      tables: requireFx().tables,
       connId: 'self',
       handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
       managementApi: mgmt,
@@ -236,8 +241,8 @@ describe.skipIf(!available)('GoneException cleanup', () => {
     // `broadcast` iterates ChannelMembers and skips `except`.
     await runtime.broadcast('#room' as never, [{ text: ':self PRIVMSG #room :hi' } as never]);
     const probe = new AwsRuntime({
-      dynamo: fx!.client,
-      tables: fx!.tables,
+      dynamo: requireFx().client,
+      tables: requireFx().tables,
       connId: '__probe__',
       handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
       managementApi: null,
@@ -246,18 +251,18 @@ describe.skipIf(!available)('GoneException cleanup', () => {
   });
 
   it('send() with managementApi=null is a silent no-op (no throw, no cleanup)', async () => {
-    await seedConnection(fx!.client, fx!.tables, 'present2', 'frank', '#room');
+    await seedConnection(requireFx().client, requireFx().tables, 'present2', 'frank', '#room');
     const runtime = new AwsRuntime({
-      dynamo: fx!.client,
-      tables: fx!.tables,
+      dynamo: requireFx().client,
+      tables: requireFx().tables,
       connId: 'self',
       handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
       managementApi: null,
     });
     await runtime.send('present2', [{ text: ':self PRIVMSG frank :hi' } as never]);
     const probe = new AwsRuntime({
-      dynamo: fx!.client,
-      tables: fx!.tables,
+      dynamo: requireFx().client,
+      tables: requireFx().tables,
       connId: '__probe__',
       handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
       managementApi: null,