serverless-ircd 0.1.0 → 0.2.0

package/packages/aws-adapter/tests/message-store.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Unit tests for the AWS adapter's chat-history store binding helper.
+ *
+ * The helper centralises MessageStore construction so a future
+ * DynamoDB-backed persistent variant can replace the in-memory v1 impl
+ * at a single site. These tests prove the helper returns a functional
+ * store (record → query round-trip) without needing DynamoDB Local.
+ */
+
+import { DEFAULT_SERVER_CONFIG, type StoredMessage } from '@serverless-ircd/irc-core';
+import { describe, expect, it } from 'vitest';
+import { bindMessageStore } from '../src/message-store.js';
+
+function sampleMessage(chan: string, text: string): StoredMessage {
+  return {
+    msgid: 'm1',
+    time: 1_000,
+    chan: chan.toLowerCase(),
+    command: 'PRIVMSG',
+    nick: 'alice',
+    user: 'alice',
+    host: 'ex.org',
+    text,
+  };
+}
+
+describe('bindMessageStore', () => {
+  it('returns a store that records and replays a message via LATEST', () => {
+    const store = bindMessageStore(DEFAULT_SERVER_CONFIG);
+    store.record(sampleMessage('#aws', 'hello aws'));
+
+    const result = store.query({ chan: '#aws', direction: 'latest', limit: 10 });
+    expect(result).toHaveLength(1);
+    expect(result[0]?.text).toBe('hello aws');
+  });
+
+  it('returns a store scoped per channel (no cross-channel leak)', () => {
+    const store = bindMessageStore(DEFAULT_SERVER_CONFIG);
+    store.record(sampleMessage('#a', 'in a'));
+    store.record(sampleMessage('#b', 'in b'));
+
+    expect(store.query({ chan: '#a', direction: 'latest', limit: 10 })).toHaveLength(1);
+    expect(store.query({ chan: '#b', direction: 'latest', limit: 10 })).toHaveLength(1);
+    expect(store.query({ chan: '#c', direction: 'latest', limit: 10 })).toHaveLength(0);
+  });
+
+  it('returns an independent store instance per call', () => {
+    const a = bindMessageStore(DEFAULT_SERVER_CONFIG);
+    const b = bindMessageStore(DEFAULT_SERVER_CONFIG);
+    a.record(sampleMessage('#aws', 'only in a'));
+
+    expect(a.query({ chan: '#aws', direction: 'latest', limit: 10 })).toHaveLength(1);
+    expect(b.query({ chan: '#aws', direction: 'latest', limit: 10 })).toHaveLength(0);
+  });
+});

package/packages/aws-adapter/tests/ping-checker.test.ts

@@ -0,0 +1,571 @@
+/**
+ * EventBridge idle / PING sweep — a Lambda on a fixed EventBridge
+ * schedule (rate(1 minute)) that scans `Connections` for rows past
+ * the PING threshold and either posts a `PING` or, if the PONG
+ * window has also elapsed, tears the connection down via
+ * {@link cleanupConnection}.
+ *
+ * Catches the case where a client has gone silent but APIGW has not
+ * yet observed a TCP-level close (so no `$disconnect` event). Mirrors
+ * the Cloudflare adapter's `ConnectionDO.alarm()` PING/PONG logic,
+ * adapted to the batch-scan Lambda model AWS requires (one Lambda
+ * invocation inspects every connection; per-connection EventBridge
+ * one-shot schedules would scale to N scheduler entries per active
+ * user and were ruled out for v1).
+ *
+ * Gated on `process.env.DDB_AVAILABLE` (real DynamoDB Local). A
+ * second `describe` block covers scan-edge-case branches against a
+ * fake document client so the suite is green even without Docker.
+ */
+
+import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
+import {
+  type DynamoDBDocumentClient,
+  GetCommand,
+  PutCommand,
+  ScanCommand,
+} 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 {
+  DEFAULT_PING_INTERVAL_MS,
+  DEFAULT_PONG_TIMEOUT_MS,
+  type PingCheckParams,
+  type PingCheckResult,
+  handlePingCheck,
+} from '../src/handlers/ping-checker.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>;
+  mgmt: RecordingPostToConnection;
+  cleanup: () => Promise<void>;
+}
+
+let fx: Fixture | null;
+
+async function makeFixture(): Promise<Fixture> {
+  if (endpoint === undefined) throw new Error('DYNAMO_ENDPOINT missing');
+  const prefix = `p${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,
+    mgmt: new RecordingPostToConnection(),
+    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<PingCheckParams> = {}): PingCheckParams {
+  return {
+    dynamo: fx!.client,
+    tables: fx!.tables,
+    managementApi: fx!.mgmt,
+    ...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 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 { QueryCommand } = await import('@aws-sdk/lib-dynamodb');
+  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 res = await fx!.client.send(
+    new GetCommand({ TableName: fx!.tables.Nicks, Key: { nickLower: nick.toLowerCase() } }),
+  );
+  return res.Item !== undefined;
+}
+
+describe.skipIf(!available)('idle / PING checker', () => {
+  beforeEach(async () => {
+    fx = await makeFixture();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+    fx = null;
+  });
+
+  // -------------------------------------------------------------------------
+  // Acceptance criteria
+  // -------------------------------------------------------------------------
+
+  it('sends a PING to an idle connection past the PING interval', async () => {
+    const pingInterval = 60_000;
+    const now = 100_000;
+    await seedConnection({ connId: 'idle', idleSince: 0 }); // idleFor = 100s > 60s
+
+    const result: PingCheckResult = await handlePingCheck(
+      params({ now, pingIntervalMs: pingInterval, pongTimeoutMs: 60_000 }),
+    );
+
+    expect(result.scanned).toBe(1);
+    expect(result.pinged).toBe(1);
+    expect(result.disconnected).toBe(0);
+    expect(fx!.mgmt.calls.size).toBe(1);
+    expect(fx!.mgmt.calls.has('idle')).toBe(true);
+    // PING line format: `PING :<token>` (token is opaque, server-chosen).
+    const line = fx!.mgmt.calls.get('idle')!.join('\r\n');
+    expect(line).toMatch(/^PING :.+\r?\n?$/);
+  });
+
+  it('disconnects a connection that has not answered PING within the PONG window', async () => {
+    const pingInterval = 60_000;
+    const pongTimeout = 60_000;
+    // Idle for 2× interval → no PONG within window → disconnect.
+    const now = (pingInterval + pongTimeout) * 2;
+    await seedConnection({ connId: 'ghost', idleSince: 0 });
+
+    const result = await handlePingCheck(
+      params({ now, pingIntervalMs: pingInterval, pongTimeoutMs: pongTimeout }),
+    );
+
+    expect(result.disconnected).toBe(1);
+    expect(await connectionExists('ghost')).toBe(false);
+    // No PING is sent in the disconnect window — past it.
+    expect(fx!.mgmt.calls.size).toBe(0);
+  });
+
+  // -------------------------------------------------------------------------
+  // Sibling cases (driven by the TDD outline + AC text)
+  // -------------------------------------------------------------------------
+
+  it('leaves an active connection alone (idleFor < pingInterval)', async () => {
+    const now = 1_000;
+    await seedConnection({ connId: 'live', idleSince: now }); // idleFor = 0
+
+    const result = await handlePingCheck(
+      params({ now, pingIntervalMs: 60_000, pongTimeoutMs: 60_000 }),
+    );
+
+    expect(result.scanned).toBe(1);
+    expect(result.pinged).toBe(0);
+    expect(result.disconnected).toBe(0);
+    expect(fx!.mgmt.calls.size).toBe(0);
+    expect(await connectionExists('live')).toBe(true);
+  });
+
+  it('disconnect path also removes memberships and releases the nick', async () => {
+    const now = 1_000_000;
+    await seedConnection({
+      connId: 'stale',
+      idleSince: 0,
+      nick: 'alice',
+      channels: ['#foo' as ChanName, '#bar' as ChanName],
+    });
+
+    await handlePingCheck(params({ now, pingIntervalMs: 60_000, pongTimeoutMs: 60_000 }));
+
+    expect(await connectionExists('stale')).toBe(false);
+    expect(await nickExists('alice')).toBe(false);
+    expect(await membersOf('#foo')).toHaveLength(0);
+    expect(await membersOf('#bar')).toHaveLength(0);
+  });
+
+  it('treats a PONG-refreshed connection as active (idleSince recent)', async () => {
+    // PONG came back recently via $default → idleSince updated → not idle.
+    const pingInterval = 60_000;
+    const now = 1_000_000;
+    await seedConnection({ connId: 'healthy', idleSince: now - 5_000 }); // idleFor = 5s
+
+    const result = await handlePingCheck(
+      params({ now, pingIntervalMs: pingInterval, pongTimeoutMs: 60_000 }),
+    );
+
+    expect(result.pinged).toBe(0);
+    expect(result.disconnected).toBe(0);
+    expect(await connectionExists('healthy')).toBe(true);
+  });
+
+  it('disconnects exactly at the idle threshold (idleFor == pingInterval + pongTimeout)', async () => {
+    const pingInterval = 60_000;
+    const pongTimeout = 60_000;
+    const threshold = pingInterval + pongTimeout;
+    await seedConnection({ connId: 'edge', idleSince: 0 });
+    // now - idleSince == threshold → disconnect.
+    const result = await handlePingCheck(
+      params({ now: threshold, pingIntervalMs: pingInterval, pongTimeoutMs: pongTimeout }),
+    );
+    expect(result.disconnected).toBe(1);
+    expect(await connectionExists('edge')).toBe(false);
+  });
+
+  it('pings but does not disconnect just below the disconnect threshold', async () => {
+    const pingInterval = 60_000;
+    const pongTimeout = 60_000;
+    const threshold = pingInterval + pongTimeout;
+    await seedConnection({ connId: 'waiting', idleSince: 0 });
+    const result = await handlePingCheck(
+      params({ now: threshold - 1, pingIntervalMs: pingInterval, pongTimeoutMs: pongTimeout }),
+    );
+    expect(result.pinged).toBe(1);
+    expect(result.disconnected).toBe(0);
+    expect(await connectionExists('waiting')).toBe(true);
+  });
+
+  it('does not ping just below the PING threshold', async () => {
+    const pingInterval = 60_000;
+    await seedConnection({ connId: 'fresh', idleSince: 0 });
+    const result = await handlePingCheck(
+      params({ now: pingInterval - 1, pingIntervalMs: pingInterval, pongTimeoutMs: 60_000 }),
+    );
+    expect(result.pinged).toBe(0);
+    expect(result.disconnected).toBe(0);
+  });
+
+  it('handles a mixed table: one PING, one disconnect, one active', async () => {
+    const pingInterval = 60_000;
+    const pongTimeout = 60_000;
+    const now = (pingInterval + pongTimeout) * 2;
+    await seedConnection({ connId: 'live', idleSince: now });
+    await seedConnection({ connId: 'pingMe', idleSince: now - pingInterval }); // idleFor = 60s
+    await seedConnection({ connId: 'reap', idleSince: 0 }); // idleFor = 240s
+
+    const result = await handlePingCheck(
+      params({ now, pingIntervalMs: pingInterval, pongTimeoutMs: pongTimeout }),
+    );
+
+    expect(result.scanned).toBe(3);
+    expect(result.pinged).toBe(1);
+    expect(result.disconnected).toBe(1);
+    expect(await connectionExists('live')).toBe(true);
+    expect(await connectionExists('pingMe')).toBe(true);
+    expect(await connectionExists('reap')).toBe(false);
+    expect([...fx!.mgmt.calls.keys()]).toEqual(['pingMe']);
+  });
+
+  it('uses Date.now() when `now` is omitted (real-clock default path)', async () => {
+    // Seed a connection idle in the distant past; whatever Date.now() is,
+    // it's idle past the disconnect threshold.
+    await seedConnection({ connId: 'ancient', idleSince: 0 });
+    const result = await handlePingCheck(params({ pingIntervalMs: 1_000, pongTimeoutMs: 1_000 }));
+    expect(result.disconnected).toBeGreaterThanOrEqual(1);
+  });
+
+  it('applies the documented default thresholds when none are passed', async () => {
+    // Sanity: defaults are positive and PONG timeout > 0.
+    expect(DEFAULT_PING_INTERVAL_MS).toBeGreaterThan(0);
+    expect(DEFAULT_PONG_TIMEOUT_MS).toBeGreaterThan(0);
+    // Seed a connection idle for 10× the default disconnect threshold → reaped.
+    const big = DEFAULT_PING_INTERVAL_MS + DEFAULT_PONG_TIMEOUT_MS + 1;
+    await seedConnection({ connId: 'gone', idleSince: -big });
+    const result = await handlePingCheck(params({ now: 0 }));
+    expect(result.disconnected).toBe(1);
+  });
+
+  it('is idempotent — running twice pings once then sweeps 0 (connection already removed)', async () => {
+    const now = 1_000_000;
+    await seedConnection({ connId: 'stale', idleSince: 0 });
+    const first = await handlePingCheck(
+      params({ now, pingIntervalMs: 60_000, pongTimeoutMs: 60_000 }),
+    );
+    const second = await handlePingCheck(
+      params({ now, pingIntervalMs: 60_000, pongTimeoutMs: 60_000 }),
+    );
+    expect(first.disconnected).toBe(1);
+    expect(second.scanned).toBe(0);
+    expect(second.pinged).toBe(0);
+    expect(second.disconnected).toBe(0);
+  });
+
+  it('paginates: scans across multiple Scan pages', async () => {
+    await seedConnection({ connId: 'p1', idleSince: 0 });
+    await seedConnection({ connId: 'p2', idleSince: 0 });
+    const result = await handlePingCheck(
+      params({ now: 1_000_000, pingIntervalMs: 60_000, pongTimeoutMs: 60_000 }),
+    );
+    expect(result.scanned).toBe(2);
+    expect(result.disconnected).toBe(2);
+  });
+
+  it('skips a row whose idleSince is not a number (defensive)', async () => {
+    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 handlePingCheck(
+      params({ now: 1_000_000, pingIntervalMs: 60_000, pongTimeoutMs: 60_000 }),
+    );
+    expect(result.scanned).toBe(1);
+    expect(result.pinged).toBe(0);
+    expect(result.disconnected).toBe(0);
+    expect(await connectionExists('corrupt')).toBe(true);
+  });
+
+  it('catches GoneException on PING send and cleans up the connection', async () => {
+    // The socket is gone but the row is still there. handlePingCheck's
+    // send path should catch GoneException and reap the row, returning
+    // the connection as disconnected.
+    const now = 100_000;
+    await seedConnection({ connId: 'halfopen', idleSince: 0 }); // idleFor = 100s
+    fx!.mgmt.failNextWithGone('halfopen');
+
+    const result = await handlePingCheck(
+      params({ now, pingIntervalMs: 60_000, pongTimeoutMs: 60_000 }),
+    );
+
+    expect(result.pinged).toBe(1); // PING attempt counted even though send threw
+    expect(await connectionExists('halfopen')).toBe(false);
+  });
+
+  it('is safe to run when managementApi is null (PING path is a silent no-op)', async () => {
+    const now = 100_000;
+    await seedConnection({ connId: 'idle', idleSince: 0 });
+    const result = await handlePingCheck(
+      params({ now, pingIntervalMs: 60_000, pongTimeoutMs: 60_000, managementApi: null }),
+    );
+    expect(result.pinged).toBe(0); // no backend → no PING attempt counted
+    expect(await connectionExists('idle')).toBe(true);
+  });
+
+  it('rethrows non-Gone errors from the PING send (no silent swallow)', async () => {
+    const now = 100_000;
+    await seedConnection({ connId: 'idle', idleSince: 0 });
+    fx!.mgmt.throwNext('idle', new Error('InternalServerError: boom'));
+
+    await expect(
+      handlePingCheck(params({ now, pingIntervalMs: 60_000, pongTimeoutMs: 60_000 })),
+    ).rejects.toThrow(/boom/);
+    // The row is still there — we did not run cleanupConnection.
+    expect(await connectionExists('idle')).toBe(true);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Scan-response edge cases (no DynamoDB Local — fake client)
+// ---------------------------------------------------------------------------
+
+/**
+ * Scripted page for the fake Scan client (mirrors `sweeper.test.ts`).
+ */
+interface ScriptedPage {
+  items?: unknown[];
+  lastKey?: unknown;
+}
+
+/**
+ * Fake document client: returns scripted `ScanCommand` pages and empty
+ * success for every other command. Lets the checker's pagination and
+ * defensive branches run without real DynamoDB.
+ */
+class FakeScanDynamo {
+  public sent: unknown[] = [];
+  constructor(private readonly pages: ScriptedPage[]) {}
+  async send(cmd: unknown): Promise<unknown> {
+    this.sent.push(cmd);
+    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;
+    }
+    return {};
+  }
+}
+
+function fakeParams(client: FakeScanDynamo): PingCheckParams {
+  return {
+    dynamo: client as unknown as DynamoDBDocumentClient,
+    tables: {
+      Connections: 'C',
+      ChannelMeta: 'CM',
+      ChannelMembers: 'CMem',
+      Nicks: 'N',
+      Accounts: 'A',
+    },
+    managementApi: null,
+    now: 100_000,
+    pingIntervalMs: 60_000,
+    pongTimeoutMs: 60_000,
+  };
+}
+
+describe('idle / PING checker — scan edge cases', () => {
+  it('paginates across multiple Scan pages (LastEvaluatedKey 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 handlePingCheck(fakeParams(client));
+    expect(result.scanned).toBe(3);
+    // managementApi is null → pinged stays 0 even though idleFor > pingInterval.
+    expect(result.pinged).toBe(0);
+  });
+
+  it('treats a missing Items field as an empty page (defensive)', async () => {
+    const client = new FakeScanDynamo([{}]);
+    const result = await handlePingCheck(fakeParams(client));
+    expect(result.scanned).toBe(0);
+    expect(result.pinged).toBe(0);
+    expect(result.disconnected).toBe(0);
+  });
+
+  it('skips a row whose connectionId is not a string (defensive)', async () => {
+    // Real DynamoDB rejects non-string PKs at write time, so this only
+    // surfaces in synthetic scans. The fake client lets us inject the
+    // malformed row directly.
+    const client = new FakeScanDynamo([{ items: [{ connectionId: 12345, idleSince: 0 }] }]);
+    const result = await handlePingCheck(fakeParams(client));
+    expect(result.scanned).toBe(1);
+    expect(result.pinged).toBe(0);
+    expect(result.disconnected).toBe(0);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Test double for ApiGatewayManagementApi.postToConnection
+// ---------------------------------------------------------------------------
+
+/**
+ * Records every `postToConnection` call, grouped by ConnectionId.
+ * Optionally throws a GoneException-shaped error on the next call for
+ * a registered connection id, so the PING path's gone-cleanup branch
+ * is exercisable without real APIGW.
+ */
+class RecordingPostToConnection {
+  readonly calls = new Map<string, string[]>();
+  private readonly goneNext = new Set<string>();
+  private readonly throwNextErr = new Map<string, Error>();
+  register(connId: string): void {
+    this.calls.set(connId, []);
+  }
+  failNextWithGone(connId: string): void {
+    this.goneNext.add(connId);
+  }
+  /** Next call for `connId` throws `err` verbatim (used to exercise the non-Gone rethrow). */
+  throwNext(connId: string, err: Error): void {
+    this.throwNextErr.set(connId, err);
+  }
+  async postToConnection(input: { ConnectionId: string; Data: string }): Promise<{}> {
+    const throwErr = this.throwNextErr.get(input.ConnectionId);
+    if (throwErr !== undefined) {
+      this.throwNextErr.delete(input.ConnectionId);
+      throw throwErr;
+    }
+    if (this.goneNext.has(input.ConnectionId)) {
+      this.goneNext.delete(input.ConnectionId);
+      const err = new Error('Gone');
+      (err as { name: string }).name = 'GoneException';
+      throw err;
+    }
+    const list = this.calls.get(input.ConnectionId) ?? [];
+    list.push(input.Data);
+    this.calls.set(input.ConnectionId, list);
+    return {};
+  }
+}
+
+// Keep the import live for type usage in `params`.
+export type { DynamoDBDocumentClient };