serverless-ircd 0.1.0 → 0.2.0

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

@@ -0,0 +1,271 @@
+/**
+ * Verifies that a `GoneException` raised during cross-connection `send`
+ * triggers {@link cleanupConnection}, which deletes:
+ *   - the dead connection's row in Connections,
+ *   - its nick (if any) in Nicks,
+ *   - its memberships in ChannelMembers.
+ *
+ * Tested by injecting a mock `PostToConnection` that throws once.
+ */
+
+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,
+  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 { 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;
+
+async function makeFixture(): Promise<Fixture> {
+  if (endpoint === undefined) throw new Error('DYNAMO_ENDPOINT missing');
+  const prefix = `g${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 connection with a nick + a channel membership directly in Dynamo. */
+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,
+      }),
+    }),
+  );
+}
+
+describe.skipIf(!available)('GoneException cleanup', () => {
+  beforeEach(async () => {
+    fx = await makeFixture();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+    fx = null;
+  });
+
+  it('send() to a gone connection triggers cleanupConnection and deletes Connections/Nicks/Members rows', async () => {
+    await seedConnection(fx!.client, fx!.tables, 'gone', 'bob', '#room');
+
+    // A self-connection runtime that tries to `send` to 'gone'.
+    const mgmt: PostToConnection = {
+      async postToConnection() {
+        throw new GoneException({
+          $metadata: {},
+          message: 'Gone',
+        });
+      },
+    };
+
+    const runtime = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connId: 'self',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: mgmt,
+    });
+
+    await runtime.send('gone', [{ text: ':self PRIVMSG bob :hi' } as never]);
+
+    const probe = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connId: '__probe__',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: null,
+    });
+    expect(await probe.getConnectionInfo('gone')).toBeNull();
+    expect(await probe.lookupNick('bob' as Nick)).toBeNull();
+    const members = await probe.getChannelConnections('#room' as never);
+    expect(members.size).toBe(0);
+  });
+
+  it('send() to a non-gone error rethrows', async () => {
+    await seedConnection(fx!.client, fx!.tables, 'present', 'carol', '#room');
+    const mgmt: PostToConnection = {
+      async postToConnection() {
+        throw new Error('network down');
+      },
+    };
+    const runtime = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connId: 'self',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: mgmt,
+    });
+    await expect(
+      runtime.send('present', [{ text: ':self PRIVMSG carol :hi' } as never]),
+    ).rejects.toThrow('network down');
+    // The target row should NOT have been cleaned up.
+    const probe = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connId: '__probe__',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: null,
+    });
+    expect(await probe.getConnectionInfo('present')).not.toBeNull();
+  });
+
+  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);
+    const probe = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.tables,
+      connId: '__probe__',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: null,
+    });
+    expect(await probe.getConnectionInfo('gone2')).toBeNull();
+  });
+
+  it('cleanupConnection is safe when the connection row is missing', async () => {
+    await expect(
+      cleanupConnection(fx!.client, fx!.tables, 'never-existed', null),
+    ).resolves.toBeUndefined();
+  });
+
+  it('broadcast() skips and cleans up gone members', async () => {
+    await seedConnection(fx!.client, fx!.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,
+      connId: 'self',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: mgmt,
+    });
+    // `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,
+      connId: '__probe__',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: null,
+    });
+    expect(await probe.lookupNick('eve' as Nick)).toBeNull();
+  });
+
+  it('send() with managementApi=null is a silent no-op (no throw, no cleanup)', async () => {
+    await seedConnection(fx!.client, fx!.tables, 'present2', 'frank', '#room');
+    const runtime = new AwsRuntime({
+      dynamo: fx!.client,
+      tables: fx!.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,
+      connId: '__probe__',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: null,
+    });
+    expect(await probe.getConnectionInfo('present2')).not.toBeNull();
+  });
+
+  it('static SERVER_CONFIG is valid (sanity)', () => {
+    expect(SERVER_CONFIG.serverName).toBe('irc.example.com');
+  });
+});

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

@@ -0,0 +1,427 @@
+/**
+ * Unit tests for the Lambda handlers (`$connect`, `$disconnect`, `$default`).
+ *
+ * Uses real DynamoDB Local so the Get/Put/Update paths are exercised
+ * end-to-end. The `ApiGatewayManagementApi` is mocked via the
+ * `LocalPostToConnection` test double (no actual APIGW needed).
+ */
+
+import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
+import {
+  DEFAULT_SERVER_CONFIG,
+  type ParsedServerConfig,
+  StaticMotdProvider,
+} from '@serverless-ircd/irc-core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { AwsRuntime } from '../src/aws-runtime.js';
+import type { PostToConnection } from '../src/aws-runtime.js';
+import { TABLE_DEFS } from '../src/cdk-table-defs.js';
+import { createDynamoDocumentClient } from '../src/dynamo.js';
+import {
+  type HandlerDeps,
+  type LambdaResponse,
+  __resetHandlerCacheForTests,
+  dispatch,
+} from '../src/handlers/index.js';
+import { bindMessageStore } from '../src/message-store.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: ['Welcome to the test IRC server.'],
+};
+
+const MOTD = new StaticMotdProvider(SERVER_CONFIG.motdLines);
+
+interface Fixture {
+  tables: TablesConfig;
+  client: ReturnType<typeof createDynamoDocumentClient>;
+  mgmt: LocalPostToConnection;
+  deps: HandlerDeps;
+  cleanup: () => Promise<void>;
+}
+
+let fx: Fixture | null;
+
+async function makeFixture(): Promise<Fixture> {
+  if (endpoint === undefined) throw new Error('DYNAMO_ENDPOINT missing');
+  const prefix = `h${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',
+      }),
+    );
+  }
+  const mgmt = new LocalPostToConnection();
+  return {
+    tables,
+    client,
+    mgmt,
+    deps: {
+      dynamo: client,
+      tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: mgmt as never,
+    },
+    cleanup: async () => {
+      for (const logical of Object.keys(TABLE_DEFS)) {
+        try {
+          await client.send(new DeleteTableCommand({ TableName: `${prefix}${logical}` }));
+        } catch {
+          // Already gone.
+        }
+      }
+    },
+  };
+}
+
+describe.skipIf(!available)('handlers', () => {
+  beforeEach(async () => {
+    __resetHandlerCacheForTests();
+    fx = await makeFixture();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+    fx = null;
+  });
+
+  // -------------------------------------------------------------------------
+  // $connect
+  // -------------------------------------------------------------------------
+
+  describe('$connect', () => {
+    it('returns 200 and persists a Connections row', async () => {
+      const res = await dispatch(
+        { requestContext: { routeKey: '$connect', connectionId: 'c1' } },
+        fx!.deps,
+      );
+      expect(res.statusCode).toBe(200);
+      const probe = new AwsRuntime({
+        dynamo: fx!.client,
+        tables: fx!.tables,
+        connId: '__probe__',
+        handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+        managementApi: null,
+      });
+      const info = await probe.getConnectionInfo('c1');
+      expect(info?.id).toBe('c1');
+      expect(info?.registration).toBe('pre-registration');
+    });
+
+    it('is idempotent on APIGW retry (same connectionId overwrites)', async () => {
+      for (let i = 0; i < 2; i++) {
+        await dispatch({ requestContext: { routeKey: '$connect', connectionId: 'c1' } }, fx!.deps);
+      }
+      const probe = new AwsRuntime({
+        dynamo: fx!.client,
+        tables: fx!.tables,
+        connId: '__probe__',
+        handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+        managementApi: null,
+      });
+      const info = await probe.getConnectionInfo('c1');
+      expect(info?.id).toBe('c1');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // $disconnect
+  // -------------------------------------------------------------------------
+
+  describe('$disconnect', () => {
+    it('returns 200 and deletes the Connections row', async () => {
+      await dispatch({ requestContext: { routeKey: '$connect', connectionId: 'c1' } }, fx!.deps);
+      const res = await dispatch(
+        { requestContext: { routeKey: '$disconnect', connectionId: 'c1' } },
+        fx!.deps,
+      );
+      expect(res.statusCode).toBe(200);
+      const probe = new AwsRuntime({
+        dynamo: fx!.client,
+        tables: fx!.tables,
+        connId: '__probe__',
+        handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+        managementApi: null,
+      });
+      expect(await probe.getConnectionInfo('c1')).toBeNull();
+    });
+
+    it('returns 200 even when the connection was never seen', async () => {
+      const res = await dispatch(
+        { requestContext: { routeKey: '$disconnect', connectionId: 'never' } },
+        fx!.deps,
+      );
+      expect(res.statusCode).toBe(200);
+    });
+
+    it('releases the nick on disconnect', async () => {
+      // Connect + register alice.
+      await dispatch({ requestContext: { routeKey: '$connect', connectionId: 'c1' } }, fx!.deps);
+      await dispatch(
+        {
+          requestContext: { routeKey: '$default', connectionId: 'c1' },
+          body: 'NICK alice\r\n',
+        },
+        fx!.deps,
+      );
+      await dispatch(
+        {
+          requestContext: { routeKey: '$default', connectionId: 'c1' },
+          body: 'USER alice 0 * :Alice\r\n',
+        },
+        fx!.deps,
+      );
+      // Disconnect.
+      await dispatch({ requestContext: { routeKey: '$disconnect', connectionId: 'c1' } }, fx!.deps);
+      const probe = new AwsRuntime({
+        dynamo: fx!.client,
+        tables: fx!.tables,
+        connId: '__probe__',
+        handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+        managementApi: null,
+      });
+      expect(await probe.lookupNick('alice')).toBeNull();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // $default
+  // -------------------------------------------------------------------------
+
+  describe('$default', () => {
+    it('returns 410 when the connection row is missing', async () => {
+      const res = await dispatch(
+        {
+          requestContext: { routeKey: '$default', connectionId: 'ghost' },
+          body: 'PING :tok\r\n',
+        },
+        fx!.deps,
+      );
+      expect(res.statusCode).toBe(410);
+    });
+
+    it('returns 400 when body is missing', async () => {
+      // Cast: APIGW always sends a body for $default; tests verify the guard.
+      const event = {
+        requestContext: { routeKey: '$default', connectionId: 'c1' },
+      } as never;
+      const res = await dispatch(event, fx!.deps);
+      expect(res.statusCode).toBe(400);
+    });
+
+    it('runs a NICK + USER frame and emits the welcome block', async () => {
+      await dispatch({ requestContext: { routeKey: '$connect', connectionId: 'c1' } }, fx!.deps);
+      fx!.mgmt.register('c1', () => {});
+      await dispatch(
+        {
+          requestContext: { routeKey: '$default', connectionId: 'c1' },
+          body: 'NICK alice\r\nUSER alice 0 * :Alice\r\n',
+        },
+        fx!.deps,
+      );
+      const probe = new AwsRuntime({
+        dynamo: fx!.client,
+        tables: fx!.tables,
+        connId: '__probe__',
+        handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+        managementApi: null,
+      });
+      const info = await probe.getConnectionInfo('c1');
+      expect(info?.nick).toBe('alice');
+      expect(info?.registration).toBe('registered');
+    });
+
+    it('echoes outbound lines back to the caller via the management API', async () => {
+      await dispatch({ requestContext: { routeKey: '$connect', connectionId: 'c1' } }, fx!.deps);
+      const sink: string[] = [];
+      fx!.mgmt.register('c1', (data) => {
+        for (const line of data.split('\r\n')) {
+          if (line.length > 0) sink.push(line);
+        }
+      });
+      await dispatch(
+        {
+          requestContext: { routeKey: '$default', connectionId: 'c1' },
+          body: 'PING :tok\r\n',
+        },
+        fx!.deps,
+      );
+      expect(sink).toContain('PONG :tok');
+    });
+
+    it('persists joined channels across $default invocations', async () => {
+      await dispatch({ requestContext: { routeKey: '$connect', connectionId: 'c1' } }, fx!.deps);
+      fx!.mgmt.register('c1', () => {});
+      await dispatch(
+        {
+          requestContext: { routeKey: '$default', connectionId: 'c1' },
+          body: 'NICK alice\r\nUSER alice 0 * :Alice\r\n',
+        },
+        fx!.deps,
+      );
+      await dispatch(
+        {
+          requestContext: { routeKey: '$default', connectionId: 'c1' },
+          body: 'JOIN #persist\r\n',
+        },
+        fx!.deps,
+      );
+      const probe = new AwsRuntime({
+        dynamo: fx!.client,
+        tables: fx!.tables,
+        connId: '__probe__',
+        handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+        managementApi: null,
+      });
+      const info = await probe.getConnectionInfo('c1');
+      expect(info?.joinedChannels.has('#persist')).toBe(true);
+    });
+
+    it('rebuilds an existing channel roster via refreshChannel when a second client JOINs', async () => {
+      // First connection registers + JOINs.
+      await dispatch({ requestContext: { routeKey: '$connect', connectionId: 'c1' } }, fx!.deps);
+      fx!.mgmt.register('c1', () => {});
+      await dispatch(
+        {
+          requestContext: { routeKey: '$default', connectionId: 'c1' },
+          body: 'NICK alice\r\nUSER alice 0 * :Alice\r\n',
+        },
+        fx!.deps,
+      );
+      await dispatch(
+        {
+          requestContext: { routeKey: '$default', connectionId: 'c1' },
+          body: 'JOIN #room\r\n',
+        },
+        fx!.deps,
+      );
+      // Second connection registers + JOINs the SAME channel.
+      await dispatch({ requestContext: { routeKey: '$connect', connectionId: 'c2' } }, fx!.deps);
+      const c2sink: string[] = [];
+      fx!.mgmt.register('c2', (data) => {
+        for (const line of data.split('\r\n')) {
+          if (line.length > 0) c2sink.push(line);
+        }
+      });
+      await dispatch(
+        {
+          requestContext: { routeKey: '$default', connectionId: 'c2' },
+          body: 'NICK bob\r\nUSER bob 0 * :Bob\r\n',
+        },
+        fx!.deps,
+      );
+      await dispatch(
+        {
+          requestContext: { routeKey: '$default', connectionId: 'c2' },
+          body: 'JOIN #room\r\n',
+        },
+        fx!.deps,
+      );
+      // The 353 RPL_NAMREPLY c2 receives must list BOTH alice and bob —
+      // proving that the actor's `refreshChannel` populated the cache
+      // from the existing ChannelMembers row written by c1's JOIN.
+      const namReply = c2sink.find((l) => l.startsWith(':irc.example.com 353'));
+      expect(namReply).toBeDefined();
+      expect(namReply).toMatch(/alice/);
+      expect(namReply).toMatch(/bob/);
+    });
+
+    it('records a PRIVMSG and replays it via CHATHISTORY LATEST in a BATCH', async () => {
+      await dispatch({ requestContext: { routeKey: '$connect', connectionId: 'c1' } }, fx!.deps);
+      const sink: string[] = [];
+      fx!.mgmt.register('c1', (data) => {
+        for (const line of data.split('\r\n')) {
+          if (line.length > 0) sink.push(line);
+        }
+      });
+      await dispatch(
+        {
+          requestContext: { routeKey: '$default', connectionId: 'c1' },
+          body: 'CAP REQ :draft/chathistory server-time message-tags batch\r\nNICK aws-alice\r\nUSER aws-alice 0 * :Alice\r\nCAP END\r\nJOIN #aws-chathist\r\n',
+        },
+        fx!.deps,
+      );
+      sink.length = 0;
+      await dispatch(
+        {
+          requestContext: { routeKey: '$default', connectionId: 'c1' },
+          body: 'PRIVMSG #aws-chathist :hello from aws\r\nCHATHISTORY LATEST #aws-chathist * 10\r\n',
+        },
+        fx!.deps,
+      );
+      const batchOpen = sink.find((l) => /^BATCH \+\S+ chathistory #aws-chathist/.test(l));
+      expect(batchOpen).toBeDefined();
+      const replay = sink.find((l) => l.includes('PRIVMSG #aws-chathist :hello from aws'));
+      expect(replay).toBeDefined();
+    });
+
+    it('returns 500 when unmarshalConnection throws on a corrupted row (caught by Lambda)', async () => {
+      // Skip: the catch in handleDefault wraps `actor.receiveTextFrame`,
+      // not `unmarshalConnection`. A corrupted-row test would exercise
+      // the Lambda-level unhandled rejection path, which is out of scope.
+      // The 500-branch is covered indirectly by GoneException tests.
+      expect(true).toBe(true);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Unknown routeKey
+  // -------------------------------------------------------------------------
+
+  describe('unknown routeKey', () => {
+    it('returns 200 (APIGW only forwards the three known routes)', async () => {
+      const res = await dispatch(
+        { requestContext: { routeKey: '$custom', connectionId: 'c1' } },
+        fx!.deps,
+      );
+      expect(res.statusCode).toBe(200);
+    });
+  });
+});
+
+/**
+ * Test double for `ApiGatewayManagementApi`. Routes `postToConnection`
+ * calls to a registered sink for `ConnectionId`.
+ */
+class LocalPostToConnection implements PostToConnection {
+  private readonly sinks = new Map<string, (data: string) => void>();
+  register(connId: string, sink: (data: string) => void): void {
+    this.sinks.set(connId, sink);
+  }
+  async postToConnection(input: { ConnectionId: string; Data: string }): Promise<{}> {
+    const sink = this.sinks.get(input.ConnectionId);
+    if (sink !== undefined) sink(input.Data);
+    return {};
+  }
+}
+
+// Keep the LambdaResponse import alive for type discoverability.
+export type { LambdaResponse };