serverless-ircd 0.1.0 → 0.3.0

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

@@ -0,0 +1,654 @@
+/**
+ * Unit tests for `AwsRuntime` — the DynamoDB-backed `IrcRuntime`.
+ *
+ * Uses real DynamoDB Local (no mocks) so the conditional writes, GSI
+ * semantics, and `KeyConditionExpression`s are exercised end-to-end.
+ * The harness in `aws-harness.ts` builds on these same primitives.
+ */
+
+import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
+import {
+  type ChannelDelta,
+  type Clock,
+  type ConnectionState,
+  type RawLine,
+  createConnection,
+} from '@serverless-ircd/irc-core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { AwsRuntime } from '../src/aws-runtime.js';
+import type { AwsRuntimeHandlers, PostToConnection } from '../src/aws-runtime.js';
+import { TABLE_DEFS } from '../src/cdk-table-defs.js';
+import { createDynamoDocumentClient } from '../src/dynamo.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 makeRuntime(
+  connId: string,
+  handlers: AwsRuntimeHandlers,
+  clockFn: () => number = () => 1_000,
+  managementApi: PostToConnection | null = null,
+): AwsRuntime {
+  const clock: Clock = { now: clockFn };
+  return new AwsRuntime({
+    dynamo: fx.client,
+    tables: fx.tables,
+    connId,
+    handlers,
+    managementApi,
+    clock,
+  });
+}
+
+/**
+ * Test double for `ApiGatewayManagementApi`. Routes `postToConnection`
+ * calls to the registered handler 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<unknown> {
+    const sink = this.sinks.get(input.ConnectionId);
+    if (sink !== undefined) sink(input.Data);
+    return {};
+  }
+}
+
+describe.skipIf(!available)('AwsRuntime', () => {
+  beforeEach(async () => {
+    fx = await makeFixture();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+  });
+
+  // -------------------------------------------------------------------------
+  // Nick registry
+  // -------------------------------------------------------------------------
+
+  describe('nick registry', () => {
+    it('reserveNick succeeds for a fresh nick', async () => {
+      const r = await makeRuntime('c1', noopHandlers()).reserveNick('Alice', 'c1');
+      expect(r).toEqual({ ok: true });
+    });
+
+    it('reserveNick fails when the nick is already owned by another conn', async () => {
+      const rt = makeRuntime('c1', noopHandlers());
+      await rt.reserveNick('Alice', 'c1');
+      const r = await rt.reserveNick('Alice', 'c2');
+      expect(r).toEqual({ ok: false });
+    });
+
+    it('reserveNick is idempotent for the same owner', async () => {
+      const rt = makeRuntime('c1', noopHandlers());
+      await rt.reserveNick('Alice', 'c1');
+      const r = await rt.reserveNick('Alice', 'c1');
+      expect(r).toEqual({ ok: true });
+    });
+
+    it('lookupNick returns the owning conn id (case-insensitive)', async () => {
+      const rt = makeRuntime('c1', noopHandlers());
+      await rt.reserveNick('Alice', 'c1');
+      expect(await rt.lookupNick('ALICE')).toBe('c1');
+      expect(await rt.lookupNick('alice')).toBe('c1');
+    });
+
+    it('lookupNick returns null for an unknown nick', async () => {
+      const rt = makeRuntime('c1', noopHandlers());
+      expect(await rt.lookupNick('nobody')).toBeNull();
+    });
+
+    it('releaseNick deletes the row', async () => {
+      const rt = makeRuntime('c1', noopHandlers());
+      await rt.reserveNick('Alice', 'c1');
+      await rt.releaseNick('Alice');
+      expect(await rt.lookupNick('Alice')).toBeNull();
+    });
+
+    it('releaseNick is idempotent on an unknown nick', async () => {
+      const rt = makeRuntime('c1', noopHandlers());
+      await rt.releaseNick('never-reserved');
+      await rt.reserveNick('Bob', 'c1');
+      await rt.releaseNick('Bob');
+      await rt.releaseNick('Bob');
+    });
+
+    it('changeNick moves the registration to the new nick', async () => {
+      const rt = makeRuntime('c1', noopHandlers());
+      await rt.reserveNick('Alice', 'c1');
+      const ok = await rt.changeNick('c1', 'Alice', 'Alice2');
+      expect(ok).toBe(true);
+      expect(await rt.lookupNick('Alice')).toBeNull();
+      expect(await rt.lookupNick('Alice2')).toBe('c1');
+    });
+
+    it('changeNick fails when the target is taken', async () => {
+      const rt = makeRuntime('c1', noopHandlers());
+      await rt.reserveNick('Alice', 'c1');
+      await rt.reserveNick('Bob', 'c2');
+      const ok = await rt.changeNick('c1', 'Alice', 'Bob');
+      expect(ok).toBe(false);
+      expect(await rt.lookupNick('Alice')).toBe('c1');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Connection info
+  // -------------------------------------------------------------------------
+
+  describe('connection info', () => {
+    it('getConnectionInfo returns null for an unknown connection', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      expect(await rt.getConnectionInfo('unknown')).toBeNull();
+    });
+
+    it('getConnection returns null for an unknown connection', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      expect(await rt.getConnection('unknown')).toBeNull();
+    });
+
+    it('getConnectionInfo reads a persisted connection row', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      const state = createConnection({ id: 'c1', connectedSince: 100 });
+      state.nick = 'Alice';
+      state.caps.add('echo-message');
+      await rt.persistConnectionState(state);
+      const info = await rt.getConnectionInfo('c1');
+      expect(info?.id).toBe('c1');
+      expect(info?.nick).toBe('Alice');
+      expect(info?.caps.has('echo-message')).toBe(true);
+    });
+
+    it('getConnection reads a persisted connection row (full state)', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      const state = createConnection({ id: 'c1', connectedSince: 0 });
+      state.nick = 'Alice';
+      state.user = 'alice';
+      await rt.persistConnectionState(state);
+      const got = await rt.getConnection('c1');
+      expect(got?.id).toBe('c1');
+      expect(got?.nick).toBe('Alice');
+      expect(got?.user).toBe('alice');
+    });
+
+    it('getConnection for the bound connection returns the in-memory snapshot', async () => {
+      const state = createConnection({ id: 'self', connectedSince: 0 });
+      state.nick = 'Me';
+      const rt = makeRuntime('self', {
+        send: () => {},
+        disconnect: () => {},
+        snapshot: () => state,
+      });
+      const got = await rt.getConnection('self');
+      expect(got).toBe(state);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // sendToNick
+  // -------------------------------------------------------------------------
+
+  describe('sendToNick', () => {
+    it('routes lines to the owning connection', async () => {
+      const received: string[] = [];
+      const state = createConnection({ id: 'c1', connectedSince: 0 });
+      state.nick = 'Alice';
+      const rt = makeRuntime('c1', handlersSink(received, state));
+      await rt.persistConnectionState(state);
+      await rt.reserveNick('Alice', 'c1');
+      await rt.sendToNick('Alice', 'sender', [{ text: ':hi Alice' }]);
+      expect(received).toEqual([':hi Alice']);
+    });
+
+    it('falls back to notFoundLines when the nick is unknown', async () => {
+      const received: string[] = [];
+      const state = createConnection({ id: 'self', connectedSince: 0 });
+      const rt = makeRuntime('self', handlersSink(received, state));
+      await rt.sendToNick(
+        'ghost',
+        'self',
+        [{ text: ':hello?' }],
+        [{ text: ':ghost 401 no such nick' }],
+      );
+      expect(received).toEqual([':ghost 401 no such nick']);
+    });
+
+    it('omits the fallback when notFoundLines is missing', async () => {
+      const received: string[] = [];
+      const state = createConnection({ id: 'self', connectedSince: 0 });
+      const rt = makeRuntime('self', handlersSink(received, state));
+      await rt.sendToNick('ghost', 'self', [{ text: ':hello?' }]);
+      expect(received).toEqual([]);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // applyChannelDelta + getChannelSnapshot
+  // -------------------------------------------------------------------------
+
+  describe('channel deltas', () => {
+    it('getChannelSnapshot returns null for an unknown channel', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      expect(await rt.getChannelSnapshot('#nope')).toBeNull();
+    });
+
+    it('adds memberships and reads them back via getChannelSnapshot', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      const delta: ChannelDelta = {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice', op: true }],
+      };
+      await rt.applyChannelDelta('#foo', delta);
+      const snap = await rt.getChannelSnapshot('#foo');
+      expect(snap?.nameLower).toBe('#foo');
+      expect(snap?.members.get('c1')).toEqual({
+        conn: 'c1',
+        nick: 'Alice',
+        op: true,
+        voice: false,
+      });
+    });
+
+    it('removes memberships via delta', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      await rt.applyChannelDelta('#foo', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' }],
+      });
+      await rt.applyChannelDelta('#foo', {
+        memberships: [{ type: 'remove', conn: 'c1' }],
+      });
+      const snap = await rt.getChannelSnapshot('#foo');
+      expect(snap?.members.has('c1')).toBe(false);
+    });
+
+    it('persists topic and modes in ChannelMeta', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      await rt.applyChannelDelta('#foo', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice', op: true }],
+        topic: { text: 'welcome', setter: 'alice', setAt: 100 },
+        modeChanges: [{ mode: 'topicLock', set: true }],
+      });
+      const snap = await rt.getChannelSnapshot('#foo');
+      expect(snap?.topic?.text).toBe('welcome');
+      expect(snap?.modes.topicLock).toBe(true);
+    });
+
+    it('getChannelSnapshot rehydrates members as a Map', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      await rt.applyChannelDelta('#foo', {
+        memberships: [
+          { type: 'add', conn: 'c1', nick: 'Alice', op: true },
+          { type: 'add', conn: 'c2', nick: 'Bob', voice: true },
+        ],
+      });
+      const snap = await rt.getChannelSnapshot('#foo');
+      expect(snap?.members).toBeInstanceOf(Map);
+      expect(snap?.members.size).toBe(2);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // send / broadcast / disconnect
+  // -------------------------------------------------------------------------
+
+  describe('transport', () => {
+    it('send to the bound connection routes through handlers.send', async () => {
+      const received: string[] = [];
+      const rt = makeRuntime('self', handlersSink(received));
+      await rt.send('self', [{ text: 'PING :tok' }]);
+      expect(received).toEqual(['PING :tok']);
+    });
+
+    it('broadcast fans out to every member except the caller', async () => {
+      const receivedA: string[] = [];
+      const receivedB: string[] = [];
+      const stateA = createConnection({ id: 'c-a', connectedSince: 0 });
+      const stateB = createConnection({ id: 'c-b', connectedSince: 0 });
+
+      const mgmt = new LocalPostToConnection();
+      mgmt.register('c-a', (data) => {
+        for (const line of data.split('\r\n')) {
+          if (line.length > 0) receivedA.push(line);
+        }
+      });
+      mgmt.register('c-b', (data) => {
+        for (const line of data.split('\r\n')) {
+          if (line.length > 0) receivedB.push(line);
+        }
+      });
+
+      const rtA = makeRuntime('c-a', handlersSink(receivedA, stateA), undefined, mgmt);
+      const rtB = makeRuntime('c-b', handlersSink(receivedB, stateB), undefined, mgmt);
+
+      await rtA.persistConnectionState(stateA);
+      await rtB.persistConnectionState(stateB);
+      await rtA.applyChannelDelta('#room', {
+        memberships: [
+          { type: 'add', conn: 'c-a', nick: 'Alice' },
+          { type: 'add', conn: 'c-b', nick: 'Bob' },
+        ],
+      });
+      await rtA.broadcast('#room', [{ text: ':hello' }], 'c-a');
+      expect(receivedA).toEqual([]);
+      expect(receivedB).toEqual([':hello']);
+    });
+
+    it('disconnect on the bound connection calls handlers.disconnect', async () => {
+      let disconnected = false;
+      const rt = makeRuntime('self', {
+        send: () => {},
+        disconnect: () => {
+          disconnected = true;
+        },
+        snapshot: () => undefined,
+      });
+      await rt.disconnect('self', 'reason');
+      expect(disconnected).toBe(true);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // listChannels + getChannelConnections
+  // -------------------------------------------------------------------------
+
+  describe('channel lookups', () => {
+    it('listChannels returns every channel that has a meta row', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      await rt.applyChannelDelta('#a', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' }],
+      });
+      await rt.applyChannelDelta('#b', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' }],
+      });
+      const list = await rt.listChannels();
+      const names = list.map((c) => c.nameLower).sort();
+      expect(names).toEqual(['#a', '#b']);
+    });
+
+    it('getChannelConnections returns full state for every member', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      const state = createConnection({ id: 'c1', connectedSince: 0 });
+      state.nick = 'Alice';
+      await rt.persistConnectionState(state);
+      await rt.applyChannelDelta('#a', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' }],
+      });
+      const map = await rt.getChannelConnections('#a');
+      expect(map.size).toBe(1);
+      expect(map.get('c1')?.nick).toBe('Alice');
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Mode-change coverage (key / limit / topic / banMasks)
+  // -------------------------------------------------------------------------
+
+  describe('channel modes', () => {
+    it('set + unset the key mode via applyChannelDelta', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      await rt.applyChannelDelta('#m', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' }],
+        modeChanges: [{ mode: 'key', set: true, arg: 'sekret' }],
+      });
+      let snap = await rt.getChannelSnapshot('#m');
+      expect(snap?.modes.key).toBe('sekret');
+      await rt.applyChannelDelta('#m', {
+        modeChanges: [{ mode: 'key', set: false }],
+      });
+      snap = await rt.getChannelSnapshot('#m');
+      expect(snap?.modes.key).toBeUndefined();
+    });
+
+    it('set + unset the limit mode via applyChannelDelta', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      await rt.applyChannelDelta('#m', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' }],
+        modeChanges: [{ mode: 'limit', set: true, arg: 5 }],
+      });
+      let snap = await rt.getChannelSnapshot('#m');
+      expect(snap?.modes.limit).toBe(5);
+      await rt.applyChannelDelta('#m', {
+        modeChanges: [{ mode: 'limit', set: false }],
+      });
+      snap = await rt.getChannelSnapshot('#m');
+      expect(snap?.modes.limit).toBeUndefined();
+    });
+
+    it('toggles every boolean mode (inviteOnly/topicLock/noExternal/moderated/secret/private)', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      await rt.applyChannelDelta('#m', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' }],
+        modeChanges: [
+          { mode: 'inviteOnly', set: true },
+          { mode: 'topicLock', set: true },
+          { mode: 'noExternal', set: true },
+          { mode: 'moderated', set: true },
+          { mode: 'secret', set: true },
+          { mode: 'private', set: true },
+        ],
+      });
+      const snap = await rt.getChannelSnapshot('#m');
+      expect(snap?.modes.inviteOnly).toBe(true);
+      expect(snap?.modes.topicLock).toBe(true);
+      expect(snap?.modes.noExternal).toBe(true);
+      expect(snap?.modes.moderated).toBe(true);
+      expect(snap?.modes.secret).toBe(true);
+      expect(snap?.modes.private).toBe(true);
+    });
+
+    it('ignores a key set without an arg', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      await rt.applyChannelDelta('#m', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' }],
+        modeChanges: [{ mode: 'key', set: true }],
+      });
+      const snap = await rt.getChannelSnapshot('#m');
+      expect(snap?.modes.key).toBeUndefined();
+    });
+
+    it('ignores a limit set with a non-numeric arg', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      await rt.applyChannelDelta('#m', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' }],
+        modeChanges: [{ mode: 'limit', set: true, arg: 'nope' as unknown as number }],
+      });
+      const snap = await rt.getChannelSnapshot('#m');
+      expect(snap?.modes.limit).toBeUndefined();
+    });
+
+    it('no-op applyChannelDelta (undefined modeChanges) leaves modes untouched', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      await rt.applyChannelDelta('#m', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' }],
+      });
+      await rt.applyChannelDelta('#m', {});
+      const snap = await rt.getChannelSnapshot('#m');
+      expect(snap?.modes.inviteOnly).toBe(false);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Ban masks
+  // -------------------------------------------------------------------------
+
+  describe('ban masks', () => {
+    it('add and remove banMasks via applyChannelDelta', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      await rt.applyChannelDelta('#b', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' }],
+        banMaskChanges: [{ type: 'add', mask: '*!bad@host' }],
+      });
+      let snap = await rt.getChannelSnapshot('#b');
+      expect([...(snap?.banMasks ?? [])]).toEqual(['*!bad@host']);
+      await rt.applyChannelDelta('#b', {
+        banMaskChanges: [{ type: 'remove', mask: '*!bad@host' }],
+      });
+      snap = await rt.getChannelSnapshot('#b');
+      expect([...(snap?.banMasks ?? [])]).toEqual([]);
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Topic unset
+  // -------------------------------------------------------------------------
+
+  describe('topic', () => {
+    it('clears the topic when the delta sends topic=null', async () => {
+      const rt = makeRuntime('self', noopHandlers());
+      await rt.applyChannelDelta('#t', {
+        memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' }],
+        topic: { text: 'hi', setter: 'alice', setAt: 100 },
+      });
+      let snap = await rt.getChannelSnapshot('#t');
+      expect(snap?.topic?.text).toBe('hi');
+      await rt.applyChannelDelta('#t', { topic: null });
+      snap = await rt.getChannelSnapshot('#t');
+      expect(snap?.topic).toBeUndefined();
+    });
+  });
+
+  // -------------------------------------------------------------------------
+  // Error-path coverage (releaseNick + ensureMetaRow rethrow branches)
+  // -------------------------------------------------------------------------
+
+  describe('error propagation', () => {
+    it('releaseNick rethrows non-ResourceNotFound errors', async () => {
+      // Inject a fake client whose `send` rejects with a generic error.
+      const fakeClient = {
+        send: async () => {
+          const err = new Error('network down') as Error & { name: string };
+          err.name = 'SomeOtherException';
+          throw err;
+        },
+      } as unknown as import('@aws-sdk/lib-dynamodb').DynamoDBDocumentClient;
+      const rt = new AwsRuntime({
+        dynamo: fakeClient,
+        tables: fx.tables,
+        connId: 'self',
+        handlers: noopHandlers(),
+        managementApi: null,
+      });
+      await expect(rt.releaseNick('Alice')).rejects.toThrow('network down');
+    });
+
+    it('releaseNick swallows ResourceNotFound errors (idempotent)', async () => {
+      const fakeClient = {
+        send: async () => {
+          const err = new Error('not found') as Error & { name: string };
+          err.name = 'ResourceNotFoundException';
+          throw err;
+        },
+      } as unknown as import('@aws-sdk/lib-dynamodb').DynamoDBDocumentClient;
+      const rt = new AwsRuntime({
+        dynamo: fakeClient,
+        tables: fx.tables,
+        connId: 'self',
+        handlers: noopHandlers(),
+        managementApi: null,
+      });
+      await expect(rt.releaseNick('Alice')).resolves.toBeUndefined();
+    });
+
+    it('applyChannelDelta rethrows non-conditional errors from ensureMetaRow', async () => {
+      // Track call count so we only fail on the first Put (ChannelMeta).
+      let firstPut = true;
+      const fakeClient = {
+        send: async (cmd: unknown) => {
+          const input = (cmd as { input?: { TableName?: string } }).input;
+          if (input?.TableName === fx.tables.ChannelMeta && firstPut) {
+            firstPut = false;
+            const err = new Error('throttled') as Error & { name: string };
+            err.name = 'ProvisionedThroughputExceededException';
+            throw err;
+          }
+          throw new Error('unexpected send');
+        },
+      } as unknown as import('@aws-sdk/lib-dynamodb').DynamoDBDocumentClient;
+      const rt = new AwsRuntime({
+        dynamo: fakeClient,
+        tables: fx.tables,
+        connId: 'self',
+        handlers: noopHandlers(),
+        managementApi: null,
+      });
+      await expect(
+        rt.applyChannelDelta('#x', {
+          memberships: [{ type: 'add', conn: 'c1', nick: 'Alice' }],
+        }),
+      ).rejects.toThrow('throttled');
+    });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function noopHandlers(): AwsRuntimeHandlers {
+  return {
+    send: () => {},
+    disconnect: () => {},
+    snapshot: () => undefined,
+  };
+}
+
+function handlersSink(sink: string[], snapshot?: ConnectionState): AwsRuntimeHandlers {
+  return {
+    send: (lines: RawLine[]) => {
+      for (const l of lines) sink.push(l.text);
+    },
+    disconnect: () => {},
+    snapshot: () => snapshot,
+  };
+}