serverless-ircd 0.2.0 → 0.4.0

package/packages/aws-adapter/tests/nlb-stream.test.ts

@@ -0,0 +1,478 @@
+/**
+ * Unit tests for the NLB TCP+TLS Lambda streaming handler.
+ *
+ * Exercises the NLB→Lambda byte framing end-to-end against real DynamoDB
+ * Local: connection identity derivation, transport buffer persistence
+ * across invocations, chunk-boundary reassembly, and the streaming-back
+ * response path. The `LocalPostToConnection` double routes cross-connection
+ * fanout in-process (no actual NLB or 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 NlbStreamEvent,
+  deriveNlbConnectionId,
+  handleNlbStream,
+} from '../src/handlers/nlb-stream.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;
+  cleanup: () => Promise<void>;
+}
+
+let fx: Fixture | null;
+
+function requireFx(): Fixture {
+  if (!fx) throw new Error('test fixture not initialized');
+  return fx;
+}
+
+async function makeFixture(): Promise<Fixture> {
+  if (endpoint === undefined) throw new Error('DYNAMO_ENDPOINT missing');
+  const prefix = `n${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,
+    cleanup: async () => {
+      for (const logical of Object.keys(TABLE_DEFS)) {
+        try {
+          await client.send(new DeleteTableCommand({ TableName: `${prefix}${logical}` }));
+        } catch {
+          // Already gone.
+        }
+      }
+    },
+  };
+}
+
+/** Builds an NLB event from raw client bytes (base64-encodes the body). */
+function nlbEvent(sourceIp: string, sourcePort: string, data: string): NlbStreamEvent {
+  return {
+    requestContext: { elb: { targetGroupArn: 'arn:aws:elasticloadbalancing:::targetgroup/test' } },
+    version: '2.0',
+    body: Buffer.from(data, 'utf8').toString('base64'),
+    isBase64Encoded: true,
+    headers: {
+      'x-forwarded-for': sourceIp,
+      'x-forwarded-port': sourcePort,
+    },
+  };
+}
+
+describe.skipIf(!available)('deriveNlbConnectionId', () => {
+  it('derives a stable id from source IP + port', () => {
+    const id = deriveNlbConnectionId('10.0.0.1', '54321');
+    expect(id).toBe('nlb-10-0-0-1-54321');
+  });
+
+  it('produces different ids for different ports on the same IP', () => {
+    expect(deriveNlbConnectionId('10.0.0.1', '54321')).not.toBe(
+      deriveNlbConnectionId('10.0.0.1', '54322'),
+    );
+  });
+
+  it('handles IPv6 addresses (colons replaced with dashes)', () => {
+    const id = deriveNlbConnectionId('::1', '1234');
+    // Two colons → two dashes, then the digit.
+    expect(id).toBe('nlb---1-1234');
+  });
+});
+
+describe.skipIf(!available)('NLB stream handler — byte framing', () => {
+  beforeEach(async () => {
+    fx = await makeFixture();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+    fx = null;
+  });
+
+  it('creates a Connections row on the first chunk (connection establishment)', async () => {
+    const f = requireFx();
+    const res = await handleNlbStream(nlbEvent('10.0.0.1', '50001', 'PING :tok\r\n'), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+    expect(res.statusCode).toBe(200);
+
+    const probe = new AwsRuntime({
+      dynamo: f.client,
+      tables: f.tables,
+      connId: '__probe__',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: null,
+    });
+    const info = await probe.getConnectionInfo(deriveNlbConnectionId('10.0.0.1', '50001'));
+    expect(info?.id).toBe(deriveNlbConnectionId('10.0.0.1', '50001'));
+    expect(info?.registration).toBe('pre-registration');
+  });
+
+  it('returns a PONG in the response body for a single PING', async () => {
+    const f = requireFx();
+    // First chunk establishes the connection.
+    await handleNlbStream(nlbEvent('10.0.0.2', '50002', ''), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+    const res = await handleNlbStream(nlbEvent('10.0.0.2', '50002', 'PING :tok\r\n'), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.isBase64Encoded).toBe(true);
+    const decoded = Buffer.from(res.body, 'base64').toString('utf8');
+    expect(decoded).toContain('PONG :tok');
+  });
+
+  it('completes a full registration sequence (NICK + USER) and returns the welcome block', async () => {
+    const f = requireFx();
+    const connId = deriveNlbConnectionId('10.0.0.3', '50003');
+    // First chunk establishes the connection.
+    await handleNlbStream(nlbEvent('10.0.0.3', '50003', ''), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+    const res = await handleNlbStream(
+      nlbEvent('10.0.0.3', '50003', 'NICK alice\r\nUSER alice 0 * :Alice\r\n'),
+      {
+        dynamo: f.client,
+        tables: f.tables,
+        serverConfig: SERVER_CONFIG,
+        motd: MOTD,
+        messages: bindMessageStore(SERVER_CONFIG),
+        managementApi: f.mgmt,
+      },
+    );
+    expect(res.statusCode).toBe(200);
+    const decoded = Buffer.from(res.body, 'base64').toString('utf8');
+    expect(decoded).toContain('001');
+    expect(decoded).toContain('alice');
+
+    const probe = new AwsRuntime({
+      dynamo: f.client,
+      tables: f.tables,
+      connId: '__probe__',
+      handlers: { send: () => {}, disconnect: () => {}, snapshot: () => undefined },
+      managementApi: null,
+    });
+    const info = await probe.getConnectionInfo(connId);
+    expect(info?.nick).toBe('alice');
+    expect(info?.registration).toBe('registered');
+  });
+});
+
+describe.skipIf(!available)('NLB stream handler — chunk boundaries', () => {
+  beforeEach(async () => {
+    fx = await makeFixture();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+    fx = null;
+  });
+
+  it('buffers a partial line across two invocations and completes it on the second', async () => {
+    const f = requireFx();
+    // Establish + register.
+    await handleNlbStream(nlbEvent('10.0.0.10', '50010', ''), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+    await handleNlbStream(nlbEvent('10.0.0.10', '50010', 'NICK bob\r\nUSER bob 0 * :Bob\r\n'), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+
+    // First chunk: partial PING with no terminator.
+    const res1 = await handleNlbStream(nlbEvent('10.0.0.10', '50010', 'PING :to'), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+    expect(res1.statusCode).toBe(200);
+    // No PONG yet — the line is incomplete.
+    const decoded1 = Buffer.from(res1.body, 'base64').toString('utf8');
+    expect(decoded1).not.toContain('PONG');
+
+    // Second chunk: the rest of the line + terminator.
+    const res2 = await handleNlbStream(nlbEvent('10.0.0.10', '50010', 'k\r\n'), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+    expect(res2.statusCode).toBe(200);
+    const decoded2 = Buffer.from(res2.body, 'base64').toString('utf8');
+    expect(decoded2).toContain('PONG :tok');
+  });
+
+  it('reassembles a line split across three chunks', async () => {
+    const f = requireFx();
+    await handleNlbStream(nlbEvent('10.0.0.11', '50011', ''), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+    await handleNlbStream(
+      nlbEvent('10.0.0.11', '50011', 'NICK carol\r\nUSER carol 0 * :Carol\r\n'),
+      {
+        dynamo: f.client,
+        tables: f.tables,
+        serverConfig: SERVER_CONFIG,
+        motd: MOTD,
+        messages: bindMessageStore(SERVER_CONFIG),
+        managementApi: f.mgmt,
+      },
+    );
+
+    const commonOpts = {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    };
+
+    const r1 = await handleNlbStream(nlbEvent('10.0.0.11', '50011', 'PI'), commonOpts);
+    const d1 = Buffer.from(r1.body, 'base64').toString('utf8');
+    expect(d1).not.toContain('PONG');
+
+    const r2 = await handleNlbStream(nlbEvent('10.0.0.11', '50011', 'NG :hello'), commonOpts);
+    const d2 = Buffer.from(r2.body, 'base64').toString('utf8');
+    expect(d2).not.toContain('PONG');
+
+    const r3 = await handleNlbStream(nlbEvent('10.0.0.11', '50011', '\r\n'), commonOpts);
+    const d3 = Buffer.from(r3.body, 'base64').toString('utf8');
+    expect(d3).toContain('PONG :hello');
+  });
+
+  it('persists the transport buffer in DynamoDB between invocations', async () => {
+    const f = requireFx();
+    await handleNlbStream(nlbEvent('10.0.0.12', '50012', ''), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+    // Feed a partial line.
+    await handleNlbStream(nlbEvent('10.0.0.12', '50012', 'PING :partial'), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+
+    // The Connections row must carry the buffered partial line.
+    const { GetCommand } = await import('@aws-sdk/lib-dynamodb');
+    const row = await f.client.send(
+      new GetCommand({
+        TableName: f.tables.Connections,
+        Key: { connectionId: deriveNlbConnectionId('10.0.0.12', '50012') },
+      }),
+    );
+    expect(row.Item?.transportBuffer).toBe('PING :partial');
+  });
+});
+
+describe.skipIf(!available)('NLB stream handler — streaming back', () => {
+  beforeEach(async () => {
+    fx = await makeFixture();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+    fx = null;
+  });
+
+  it('returns base64-encoded response bytes for the NLB client', async () => {
+    const f = requireFx();
+    await handleNlbStream(nlbEvent('10.0.0.20', '50020', ''), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+    const res = await handleNlbStream(nlbEvent('10.0.0.20', '50020', 'PING :xyz\r\n'), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+    expect(res.statusCode).toBe(200);
+    expect(res.isBase64Encoded).toBe(true);
+    // The body must be valid base64 that decodes to the PONG line.
+    const decoded = Buffer.from(res.body, 'base64').toString('utf8');
+    expect(decoded).toMatch(/PONG :xyz\r?\n/);
+  });
+
+  it('fans out a PRIVMSG to a second NLB connection via the management API', async () => {
+    const f = requireFx();
+    // Connection A registers.
+    await handleNlbStream(nlbEvent('10.0.0.30', '50030', ''), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+    await handleNlbStream(
+      nlbEvent('10.0.0.30', '50030', 'NICK alice\r\nUSER alice 0 * :Alice\r\nJOIN #room\r\n'),
+      {
+        dynamo: f.client,
+        tables: f.tables,
+        serverConfig: SERVER_CONFIG,
+        motd: MOTD,
+        messages: bindMessageStore(SERVER_CONFIG),
+        managementApi: f.mgmt,
+      },
+    );
+    // Connection B registers + joins the same channel.
+    const bSink: string[] = [];
+    const bConnId = deriveNlbConnectionId('10.0.0.31', '50031');
+    f.mgmt.register(bConnId, (data) => {
+      for (const line of data.split('\r\n')) {
+        if (line.length > 0) bSink.push(line);
+      }
+    });
+    await handleNlbStream(nlbEvent('10.0.0.31', '50031', ''), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+    await handleNlbStream(
+      nlbEvent('10.0.0.31', '50031', 'NICK bob\r\nUSER bob 0 * :Bob\r\nJOIN #room\r\n'),
+      {
+        dynamo: f.client,
+        tables: f.tables,
+        serverConfig: SERVER_CONFIG,
+        motd: MOTD,
+        messages: bindMessageStore(SERVER_CONFIG),
+        managementApi: f.mgmt,
+      },
+    );
+    // Alice sends a PRIVMSG; Bob's sink should receive it via management API.
+    await handleNlbStream(nlbEvent('10.0.0.30', '50030', 'PRIVMSG #room :hello from alice\r\n'), {
+      dynamo: f.client,
+      tables: f.tables,
+      serverConfig: SERVER_CONFIG,
+      motd: MOTD,
+      messages: bindMessageStore(SERVER_CONFIG),
+      managementApi: f.mgmt,
+    });
+    expect(bSink.some((l) => l.includes('PRIVMSG #room :hello from alice'))).toBe(true);
+  });
+});
+
+/**
+ * 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<unknown> {
+    const sink = this.sinks.get(input.ConnectionId);
+    if (sink !== undefined) sink(input.Data);
+    return {};
+  }
+}

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

@@ -52,6 +52,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 = `p${Date.now()}-${Math.floor(Math.random() * 1e6)}-`;
@@ -100,9 +105,9 @@ async function makeFixture(): Promise<Fixture> {
 
 function params(overrides: Partial<PingCheckParams> = {}): PingCheckParams {
   return {
-    dynamo: fx!.client,
-    tables: fx!.tables,
-    managementApi: fx!.mgmt,
+    dynamo: requireFx().client,
+    tables: requireFx().tables,
+    managementApi: requireFx().mgmt,
     ...overrides,
   };
 }
@@ -120,18 +125,18 @@ async function seedConnection(opts: {
   if (opts.nick !== undefined) {
     state.nick = opts.nick as Nick;
     state.user = opts.nick;
-    await fx!.client.send(
+    await requireFx().client.send(
       new PutCommand({
-        TableName: fx!.tables.Nicks,
+        TableName: requireFx().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(
+    await requireFx().client.send(
       new PutCommand({
-        TableName: fx!.tables.ChannelMembers,
+        TableName: requireFx().tables.ChannelMembers,
         Item: marshalChannelMember(chan.toLowerCase(), {
           conn: opts.connId,
           nick: (opts.nick ?? 'x') as Nick,
@@ -141,26 +146,26 @@ async function seedConnection(opts: {
       }),
     );
   }
-  await fx!.client.send(
+  await requireFx().client.send(
     new PutCommand({
-      TableName: fx!.tables.Connections,
+      TableName: requireFx().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 } }),
+  const res = await requireFx().client.send(
+    new GetCommand({ TableName: requireFx().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(
+  const res = await requireFx().client.send(
     new QueryCommand({
-      TableName: fx!.tables.ChannelMembers,
+      TableName: requireFx().tables.ChannelMembers,
       KeyConditionExpression: 'channelName = :k',
       ExpressionAttributeValues: { ':k': channelKey },
     }),
@@ -169,8 +174,8 @@ async function membersOf(channelKey: string): Promise<{ 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() } }),
+  const res = await requireFx().client.send(
+    new GetCommand({ TableName: requireFx().tables.Nicks, Key: { nickLower: nick.toLowerCase() } }),
   );
   return res.Item !== undefined;
 }
@@ -200,10 +205,10 @@ describe.skipIf(!available)('idle / PING checker', () => {
     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);
+    expect(requireFx().mgmt.calls.size).toBe(1);
+    expect(requireFx().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');
+    const line = requireFx().mgmt.calls.get('idle')?.join('\r\n');
     expect(line).toMatch(/^PING :.+\r?\n?$/);
   });
 
@@ -221,7 +226,7 @@ describe.skipIf(!available)('idle / PING checker', () => {
     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);
+    expect(requireFx().mgmt.calls.size).toBe(0);
   });
 
   // -------------------------------------------------------------------------
@@ -239,7 +244,7 @@ describe.skipIf(!available)('idle / PING checker', () => {
     expect(result.scanned).toBe(1);
     expect(result.pinged).toBe(0);
     expect(result.disconnected).toBe(0);
-    expect(fx!.mgmt.calls.size).toBe(0);
+    expect(requireFx().mgmt.calls.size).toBe(0);
     expect(await connectionExists('live')).toBe(true);
   });
 
@@ -329,7 +334,10 @@ describe.skipIf(!available)('idle / PING checker', () => {
     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']);
+    expect(fx).toBeDefined();
+    if (fx) {
+      expect([...fx.mgmt.calls.keys()]).toEqual(['pingMe']);
+    }
   });
 
   it('uses Date.now() when `now` is omitted (real-clock default path)', async () => {
@@ -377,9 +385,9 @@ describe.skipIf(!available)('idle / PING checker', () => {
   });
 
   it('skips a row whose idleSince is not a number (defensive)', async () => {
-    await fx!.client.send(
+    await requireFx().client.send(
       new PutCommand({
-        TableName: fx!.tables.Connections,
+        TableName: requireFx().tables.Connections,
         Item: {
           connectionId: 'corrupt',
           registration: 'registered',
@@ -408,7 +416,7 @@ describe.skipIf(!available)('idle / PING checker', () => {
     // the connection as disconnected.
     const now = 100_000;
     await seedConnection({ connId: 'halfopen', idleSince: 0 }); // idleFor = 100s
-    fx!.mgmt.failNextWithGone('halfopen');
+    requireFx().mgmt.failNextWithGone('halfopen');
 
     const result = await handlePingCheck(
       params({ now, pingIntervalMs: 60_000, pongTimeoutMs: 60_000 }),
@@ -431,7 +439,7 @@ describe.skipIf(!available)('idle / PING checker', () => {
   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'));
+    requireFx().mgmt.throwNext('idle', new Error('InternalServerError: boom'));
 
     await expect(
       handlePingCheck(params({ now, pingIntervalMs: 60_000, pongTimeoutMs: 60_000 })),
@@ -548,7 +556,7 @@ class RecordingPostToConnection {
   throwNext(connId: string, err: Error): void {
     this.throwNextErr.set(connId, err);
   }
-  async postToConnection(input: { ConnectionId: string; Data: string }): Promise<{}> {
+  async postToConnection(input: { ConnectionId: string; Data: string }): Promise<unknown> {
     const throwErr = this.throwNextErr.get(input.ConnectionId);
     if (throwErr !== undefined) {
       this.throwNextErr.delete(input.ConnectionId);
@@ -566,6 +574,3 @@ class RecordingPostToConnection {
     return {};
   }
 }
-
-// Keep the import live for type usage in `params`.
-export type { DynamoDBDocumentClient };