serverless-ircd 0.3.0 → 0.4.0

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

@@ -1,12 +1,16 @@
-import { mockClient } from 'aws-sdk-client-mock';
 import { DynamoDBDocumentClient, PutCommand, ScanCommand } from '@aws-sdk/lib-dynamodb';
-import { type SaslPayload, DEFAULT_SERVER_CONFIG, type ParsedServerConfig } from '@serverless-ircd/irc-core';
+import {
+  DEFAULT_SERVER_CONFIG,
+  type ParsedServerConfig,
+  type SaslPayload,
+} from '@serverless-ircd/irc-core';
+import { mockClient } from 'aws-sdk-client-mock';
 import { describe, expect, it } from 'vitest';
 import {
   DynamoAccountStore,
+  type HashedAccountCredential,
   bindAccountStore,
   hashAccountCredential,
-  type HashedAccountCredential,
   putAccountCredential,
   resolveAccountStore,
 } from '../src/account-store';
@@ -28,7 +32,7 @@ describe('bindAccountStore', () => {
   it('returns an AccountStore that accepts valid PLAIN creds', () => {
     const store = bindAccountStore(configWith([{ username: 'alice', password: 'secret' }]));
     expect(store).toBeDefined();
-    const out = store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'secret' });
+    const out = store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'secret' });
     expect(out).toEqual({ ok: true, account: 'alice' });
   });
 
@@ -41,8 +45,9 @@ describe('bindAccountStore', () => {
   });
 
   it('rejects wrong credentials', () => {
-    const store = bindAccountStore(configWith([{ username: 'alice', password: 'secret' }]))!;
-    expect(store.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'wrong' }).ok).toBe(
+    const store = bindAccountStore(configWith([{ username: 'alice', password: 'secret' }]));
+    expect(store).toBeDefined();
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'wrong' }).ok).toBe(
       false,
     );
   });
@@ -177,16 +182,14 @@ describe('resolveAccountStore', () => {
     const store = await resolveAccountStore(
       ddb as unknown as DynamoDBDocumentClient,
       'Accounts',
-      fallback === undefined ? undefined : { ...DEFAULT_SERVER_CONFIG, saslAccounts: [{ username: 'envuser', password: 'env-pw' }] },
+      fallback === undefined
+        ? undefined
+        : { ...DEFAULT_SERVER_CONFIG, saslAccounts: [{ username: 'envuser', password: 'env-pw' }] },
     );
     expect(store).toBeDefined();
-    expect(
-      store!.verify('PLAIN', plainPayload('alice', 's3cret')).ok,
-    ).toBe(true);
+    expect(store?.verify('PLAIN', plainPayload('alice', 's3cret')).ok).toBe(true);
     // Config account does NOT verify (table is authoritative).
-    expect(
-      store!.verify('PLAIN', plainPayload('envuser', 'env-pw')).ok,
-    ).toBe(false);
+    expect(store?.verify('PLAIN', plainPayload('envuser', 'env-pw')).ok).toBe(false);
   });
 
   it('falls back to config-seeded store when the table is empty', async () => {
@@ -199,9 +202,7 @@ describe('resolveAccountStore', () => {
       configWith([{ username: 'bob', password: 'pw' }]),
     );
     expect(store).toBeDefined();
-    expect(
-      store!.verify('PLAIN', plainPayload('bob', 'pw')).ok,
-    ).toBe(true);
+    expect(store?.verify('PLAIN', plainPayload('bob', 'pw')).ok).toBe(true);
   });
 
   it('falls back to config-seeded store when the scan throws', async () => {
@@ -214,9 +215,7 @@ describe('resolveAccountStore', () => {
       configWith([{ username: 'bob', password: 'pw' }]),
     );
     expect(store).toBeDefined();
-    expect(
-      store!.verify('PLAIN', plainPayload('bob', 'pw')).ok,
-    ).toBe(true);
+    expect(store?.verify('PLAIN', plainPayload('bob', 'pw')).ok).toBe(true);
   });
 
   it('returns undefined when table is empty and no config accounts', async () => {
@@ -252,7 +251,7 @@ describe('putAccountCredential', () => {
 
     const calls = ddb.commandCalls(PutCommand);
     expect(calls).toHaveLength(1);
-    const item = calls[0]!.args[0].input.Item as HashedAccountCredential;
+    const item = calls[0]?.args[0].input.Item as HashedAccountCredential;
     expect(item.account).toBe('alice');
     expect(item.algorithm).toBe('scrypt');
     expect(item.salt).toBe(entry.salt);

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

@@ -0,0 +1,70 @@
+/**
+ * Pure unit tests for the AWS `$connect` admission policy
+ * (`src/admission.ts`). No DynamoDB — these exercise every branch of
+ * {@link decideConnectAdmission} directly so the per-IP branch is covered
+ * even though the AWS handler does not yet feed it a `perIp` count.
+ */
+
+import { describe, expect, it } from 'vitest';
+import { decideConnectAdmission } from '../src/admission.js';
+
+describe('decideConnectAdmission', () => {
+  it('admits when the total is below the cap and no per-IP limit is set', () => {
+    const outcome = decideConnectAdmission({ total: 0 }, { maxClients: 2 });
+    expect(outcome).toEqual({ admitted: true });
+  });
+
+  it('admits when the total is exactly one below the cap', () => {
+    expect(decideConnectAdmission({ total: 1 }, { maxClients: 2 })).toEqual({
+      admitted: true,
+    });
+  });
+
+  it('rejects with 429 once the total reaches the cap', () => {
+    expect(decideConnectAdmission({ total: 2 }, { maxClients: 2 })).toEqual({
+      admitted: false,
+      statusCode: 429,
+      reason: 'server full',
+    });
+  });
+
+  it('rejects with 429 when the total exceeds the cap', () => {
+    expect(decideConnectAdmission({ total: 9999 }, { maxClients: 10 })).toEqual({
+      admitted: false,
+      statusCode: 429,
+      reason: 'server full',
+    });
+  });
+
+  it('admits when a per-IP limit is set but no per-IP count is supplied', () => {
+    expect(
+      decideConnectAdmission({ total: 0 }, { maxClients: 10, maxConnectionsPerIp: 3 }),
+    ).toEqual({ admitted: true });
+  });
+
+  it('admits when the per-IP count is below the per-IP limit', () => {
+    expect(
+      decideConnectAdmission({ total: 0, perIp: 2 }, { maxClients: 10, maxConnectionsPerIp: 3 }),
+    ).toEqual({ admitted: true });
+  });
+
+  it('rejects with 429 once the per-IP count reaches the per-IP limit', () => {
+    expect(
+      decideConnectAdmission({ total: 0, perIp: 3 }, { maxClients: 10, maxConnectionsPerIp: 3 }),
+    ).toEqual({
+      admitted: false,
+      statusCode: 429,
+      reason: 'too many connections from this IP',
+    });
+  });
+
+  it('checks the global cap before the per-IP cap', () => {
+    expect(
+      decideConnectAdmission({ total: 10, perIp: 3 }, { maxClients: 10, maxConnectionsPerIp: 3 }),
+    ).toEqual({
+      admitted: false,
+      statusCode: 429,
+      reason: 'server full',
+    });
+  });
+});

package/packages/aws-adapter/tests/aws-harness.ts

@@ -57,7 +57,8 @@ const endpoint = process.env.DYNAMO_ENDPOINT;
  * unavailable so `describe.skipIf` short-circuits before any test runs.
  */
 export const awsHarnessFactory: IrcHarnessFactory = Object.freeze({
-  name: 'aws',
+  name: 'aws+ws',
+  transport: 'ws',
   async create() {
     return new AwsHarness();
   },
@@ -344,6 +345,17 @@ class AwsClientHandle implements ClientHarness {
     await this.actor.receiveTextFrame(`${line}\r\n`);
   }
 
+  async feed(chunk: string): Promise<void> {
+    if (this.actor === undefined) {
+      throw new Error(`client ${this.id} has no bound actor`);
+    }
+    if (this.closed) return;
+    // Routes the raw chunk through the bound transport (the WS text-frame
+    // transport by default; a future aws+tcp factory via the NLB+Lambda
+    // byte-stream path would inject a TcpByteStreamTransport).
+    await this.actor.receive(chunk);
+  }
+
   async waitForLine(
     predicate: (line: string) => boolean,
     timeoutMs: number = DEFAULT_TIMEOUT_MS,

package/packages/aws-adapter/tests/config-loader.test.ts

@@ -76,6 +76,26 @@ describe('buildLambdaConfigInput', () => {
     expect(buildLambdaConfigInput({ QUIT_MESSAGE: 'bye' }).quitMessage).toBe('bye');
   });
 
+  it('threads SERVER_VERSION into serverVersion', () => {
+    expect(buildLambdaConfigInput({ SERVER_VERSION: '1.2.3' }).serverVersion).toBe('1.2.3');
+  });
+
+  it('passes a non-numeric CREATED_AT through verbatim', () => {
+    expect(buildLambdaConfigInput({ CREATED_AT: '2024-06-01' }).createdAt).toBe('2024-06-01');
+  });
+
+  it('parses a numeric CREATED_AT string into an epoch-ms number', () => {
+    expect(buildLambdaConfigInput({ CREATED_AT: '1700000000000' }).createdAt).toBe(
+      1_700_000_000_000,
+    );
+  });
+
+  it('omits serverVersion/createdAt when their env vars are unset', () => {
+    const out = buildLambdaConfigInput({});
+    expect('serverVersion' in out).toBe(false);
+    expect('createdAt' in out).toBe(false);
+  });
+
   it('parses SASL_ACCOUNTS newline-delimited username:password pairs', () => {
     const out = buildLambdaConfigInput({ SASL_ACCOUNTS: 'alice:secret\nbob:b-pass' });
     expect(out.saslAccounts).toEqual([

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

@@ -19,15 +19,11 @@ import {
   createConnection,
 } from '@serverless-ircd/irc-core';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { AwsRuntime, cleanupConnection, type PostToConnection } from '../src/aws-runtime.js';
-import { handleDisconnect } from '../src/handlers/disconnect.js';
-import {
-  type HandlerDeps,
-  __resetHandlerCacheForTests,
-  dispatch,
-} from '../src/handlers/index.js';
+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';
 
@@ -49,6 +45,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 = `q${Date.now()}-${Math.floor(Math.random() * 1e6)}-`;
@@ -182,13 +183,13 @@ describe.skipIf(!available)('$disconnect QUIT fanout', () => {
   });
 
   it('handleDisconnect fans the QUIT line out to every other channel member', async () => {
-    await seedConnection(fx!.client, fx!.tables, 'a', 'alice', '#room');
-    await seedConnection(fx!.client, fx!.tables, 'b', 'bob', '#room');
+    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: fx!.client,
-      tables: fx!.tables,
+      dynamo: requireFx().client,
+      tables: requireFx().tables,
       connectionId: 'a',
       managementApi: mgmt,
     });
@@ -201,14 +202,14 @@ describe.skipIf(!available)('$disconnect QUIT fanout', () => {
   });
 
   it('handleDisconnect without a managementApi performs no fanout but still cleans up', async () => {
-    await seedConnection(fx!.client, fx!.tables, 'a', 'alice', '#room');
+    await seedConnection(requireFx().client, requireFx().tables, 'a', 'alice', '#room');
     await handleDisconnect({
-      dynamo: fx!.client,
-      tables: fx!.tables,
+      dynamo: requireFx().client,
+      tables: requireFx().tables,
       connectionId: 'a',
       managementApi: null,
     });
-    const p = probe(fx!.client, fx!.tables);
+    const p = probe(requireFx().client, requireFx().tables);
     expect(await p.getConnectionInfo('a')).toBeNull();
     expect(await p.lookupNick('alice' as Nick)).toBeNull();
   });
@@ -216,8 +217,8 @@ describe.skipIf(!available)('$disconnect QUIT fanout', () => {
   it('a never-registered connection disconnects without fanout (no nick)', async () => {
     const mgmt = new RecordingPostToConnection();
     await handleDisconnect({
-      dynamo: fx!.client,
-      tables: fx!.tables,
+      dynamo: requireFx().client,
+      tables: requireFx().tables,
       connectionId: 'nobody',
       managementApi: mgmt,
     });
@@ -225,43 +226,43 @@ describe.skipIf(!available)('$disconnect QUIT fanout', () => {
   });
 
   it('fanout to a gone peer triggers lazy cleanup instead of crashing', async () => {
-    await seedConnection(fx!.client, fx!.tables, 'a', 'alice', '#room');
-    await seedConnection(fx!.client, fx!.tables, 'b', 'bob', '#room');
+    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: fx!.client,
-        tables: fx!.tables,
+        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(fx!.client, fx!.tables);
+    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(fx!.client, fx!.tables, 'a', 'alice', '#room');
-    await seedConnection(fx!.client, fx!.tables, 'b', 'bob', '#room');
+    await seedConnection(requireFx().client, requireFx().tables, 'a', 'alice', '#room');
+    await seedConnection(requireFx().client, requireFx().tables, 'b', 'bob', '#room');
 
     const mgmt = new RecordingPostToConnection();
-    await cleanupConnection(fx!.client, fx!.tables, 'a', mgmt);
+    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(fx!.client, fx!.tables);
+    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: fx!.client,
-      tables: fx!.tables,
+      dynamo: requireFx().client,
+      tables: requireFx().tables,
       serverConfig: SERVER_CONFIG,
       motd: new StaticMotdProvider([]),
       messages: { record() {}, query: () => Promise.resolve([]) } as never,
@@ -273,11 +274,17 @@ describe.skipIf(!available)('$disconnect QUIT fanout', () => {
     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' },
+      {
+        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' },
+      {
+        requestContext: { routeKey: '$default', connectionId: 'b' },
+        body: 'NICK bob\r\nUSER bob 0 * :Bob\r\nJOIN #room\r\n',
+      },
       deps,
     );
     mgmt.sent.clear();
@@ -289,18 +296,18 @@ describe.skipIf(!available)('$disconnect QUIT fanout', () => {
     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 () => {
+  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(fx!.client, fx!.tables, 'alice', 'alice', '#room');
-    await seedConnection(fx!.client, fx!.tables, 'carol', 'carol', '#room');
+    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: fx!.client,
-      tables: fx!.tables,
+      dynamo: requireFx().client,
+      tables: requireFx().tables,
       connId: 'carol',
       handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
       managementApi: mgmt,
@@ -313,21 +320,21 @@ describe.skipIf(!available)('$disconnect QUIT fanout', () => {
     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(fx!.client, fx!.tables);
+    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(fx!.client, fx!.tables, 'a', 'alice', '#room');
-    await seedConnection(fx!.client, fx!.tables, 'b', 'bob', '#room');
+    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: fx!.client,
-        tables: fx!.tables,
+        dynamo: requireFx().client,
+        tables: requireFx().tables,
         connectionId: 'a',
         managementApi: mgmt,
       }),

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,