serverless-ircd 0.3.0 → 0.5.0

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

@@ -31,6 +31,11 @@ interface Fx {
 
 let fx: Fx | null = null;
 
+function requireFx(): Fx {
+  if (!fx) throw new Error('test fixture not initialized');
+  return fx;
+}
+
 async function makeFx(): Promise<Fx> {
   if (endpoint === undefined) throw new Error('DYNAMO_ENDPOINT missing');
   const tableName = `acct-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
@@ -69,55 +74,57 @@ describe.skipIf(!available)('Accounts table round-trip', () => {
   });
 
   it('putAccountCredential then loadDynamoAccountStore verifies the account', async () => {
-    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 's3cret');
-    const store = await loadDynamoAccountStore(fx!.client, fx!.tableName);
+    await putAccountCredential(requireFx().client, requireFx().tableName, 'alice', 's3cret');
+    const store = await loadDynamoAccountStore(requireFx().client, requireFx().tableName);
     expect(store).toBeDefined();
-    expect(store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 's3cret' })).toEqual(
-      {
-        ok: true,
-        account: 'alice',
-      },
-    );
+    expect(
+      store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 's3cret' }),
+    ).toEqual({
+      ok: true,
+      account: 'alice',
+    });
   });
 
   it('loadDynamoAccountStore returns undefined when the table has no rows', async () => {
-    const store = await loadDynamoAccountStore(fx!.client, fx!.tableName);
+    const store = await loadDynamoAccountStore(requireFx().client, requireFx().tableName);
     expect(store).toBeUndefined();
   });
 
   it('putAccountCredential writes multiple distinct accounts', async () => {
-    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 'a1');
-    await putAccountCredential(fx!.client, fx!.tableName, 'bob', 'b2');
-    const store = await loadDynamoAccountStore(fx!.client, fx!.tableName);
+    await putAccountCredential(requireFx().client, requireFx().tableName, 'alice', 'a1');
+    await putAccountCredential(requireFx().client, requireFx().tableName, 'bob', 'b2');
+    const store = await loadDynamoAccountStore(requireFx().client, requireFx().tableName);
     expect(store).toBeDefined();
-    expect(store!.size).toBe(2);
-    expect(store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'a1' }).ok).toBe(
+    expect(store?.size).toBe(2);
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'a1' }).ok).toBe(
+      true,
+    );
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'bob', password: 'b2' }).ok).toBe(
       true,
     );
-    expect(store!.verify('PLAIN', { kind: 'PLAIN', username: 'bob', password: 'b2' }).ok).toBe(true);
   });
 
   it('putAccountCredential overwrites an existing account (re-seed)', async () => {
-    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 'old');
-    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 'new');
-    const store = await loadDynamoAccountStore(fx!.client, fx!.tableName);
+    await putAccountCredential(requireFx().client, requireFx().tableName, 'alice', 'old');
+    await putAccountCredential(requireFx().client, requireFx().tableName, 'alice', 'new');
+    const store = await loadDynamoAccountStore(requireFx().client, requireFx().tableName);
     expect(store).toBeDefined();
-    expect(store!.size).toBe(1);
-    expect(store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'old' }).ok).toBe(
+    expect(store?.size).toBe(1);
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'old' }).ok).toBe(
       false,
     );
-    expect(store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'new' }).ok).toBe(
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'new' }).ok).toBe(
       true,
     );
   });
 
   it('rejects a wrong password after round-trip', async () => {
-    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 'right');
-    const store = await loadDynamoAccountStore(fx!.client, fx!.tableName);
+    await putAccountCredential(requireFx().client, requireFx().tableName, 'alice', 'right');
+    const store = await loadDynamoAccountStore(requireFx().client, requireFx().tableName);
     expect(store).toBeDefined();
-    expect(
-      store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'wrong' }).ok,
-    ).toBe(false);
+    expect(store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'wrong' }).ok).toBe(
+      false,
+    );
   });
 });
 
@@ -131,19 +138,19 @@ describe.skipIf(!available)('resolveAccountStore precedence', () => {
   });
 
   it('returns a DynamoAccountStore when the table has rows (table wins)', async () => {
-    await putAccountCredential(fx!.client, fx!.tableName, 'alice', 'table-secret');
+    await putAccountCredential(requireFx().client, requireFx().tableName, 'alice', 'table-secret');
     const cfgWithSasl = {
       ...DEFAULT_SERVER_CONFIG,
       saslAccounts: [{ username: 'envuser', password: 'env-secret' }],
     };
-    const store = await resolveAccountStore(fx!.client, fx!.tableName, cfgWithSasl);
+    const store = await resolveAccountStore(requireFx().client, requireFx().tableName, cfgWithSasl);
     expect(store).toBeDefined();
     // Table account verifies; config account does NOT (table is authoritative).
     expect(
-      store!.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'table-secret' }).ok,
+      store?.verify('PLAIN', { kind: 'PLAIN', username: 'alice', password: 'table-secret' }).ok,
     ).toBe(true);
     expect(
-      store!.verify('PLAIN', { kind: 'PLAIN', username: 'envuser', password: 'env-secret' }).ok,
+      store?.verify('PLAIN', { kind: 'PLAIN', username: 'envuser', password: 'env-secret' }).ok,
     ).toBe(false);
   });
 
@@ -152,20 +159,24 @@ describe.skipIf(!available)('resolveAccountStore precedence', () => {
       ...DEFAULT_SERVER_CONFIG,
       saslAccounts: [{ username: 'envuser', password: 'env-secret' }],
     };
-    const store = await resolveAccountStore(fx!.client, fx!.tableName, cfgWithSasl);
+    const store = await resolveAccountStore(requireFx().client, requireFx().tableName, cfgWithSasl);
     expect(store).toBeDefined();
     expect(
-      store!.verify('PLAIN', { kind: 'PLAIN', username: 'envuser', password: 'env-secret' }).ok,
+      store?.verify('PLAIN', { kind: 'PLAIN', username: 'envuser', password: 'env-secret' }).ok,
     ).toBe(true);
   });
 
   it('returns undefined when the table is empty and no config accounts are set', async () => {
-    const store = await resolveAccountStore(fx!.client, fx!.tableName, DEFAULT_SERVER_CONFIG);
+    const store = await resolveAccountStore(
+      requireFx().client,
+      requireFx().tableName,
+      DEFAULT_SERVER_CONFIG,
+    );
     expect(store).toBeUndefined();
   });
 
   it('returns undefined when the table is empty and serverConfig is undefined', async () => {
-    const store = await resolveAccountStore(fx!.client, fx!.tableName, undefined);
+    const store = await resolveAccountStore(requireFx().client, requireFx().tableName, undefined);
     expect(store).toBeUndefined();
   });
 });

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/aws-integration.test.ts

@@ -8,7 +8,7 @@
  *
  * Gated on `process.env.DDB_AVAILABLE`: the suite is skipped when
  * DynamoDB Local cannot be booted (no Docker, no Java). When available,
- * every scenario MUST pass — that is the 040 acceptance criterion.
+ * every scenario MUST pass — that is the acceptance criterion.
  */
 
 import { runIrcScenarios } from '@serverless-ircd/irc-test-support';

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

@@ -12,6 +12,7 @@ import {
   type Clock,
   type ConnectionState,
   type RawLine,
+  type ServerConfig,
   createConnection,
 } from '@serverless-ircd/irc-core';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
@@ -652,3 +653,63 @@ function handlersSink(sink: string[], snapshot?: ConnectionState): AwsRuntimeHan
     snapshot: () => snapshot,
   };
 }
+
+// ---------------------------------------------------------------------------
+// reloadConfig (REHASH) — no DynamoDB access, so this group runs unconditionally.
+// ---------------------------------------------------------------------------
+
+describe('AwsRuntime — reloadConfig (REHASH)', () => {
+  const baseConfig: ServerConfig = {
+    serverName: 'irc.example.com',
+    networkName: 'ExampleNet',
+    maxChannelsPerUser: 30,
+    maxTargetsPerCommand: 10,
+    maxListEntries: 50,
+    nickLen: 30,
+    channelLen: 50,
+    topicLen: 390,
+    quitMessage: 'Client Quit',
+  };
+
+  function makeReloadRuntime(loader?: () => Promise<ServerConfig>): AwsRuntime {
+    return new AwsRuntime({
+      // reloadConfig never touches DynamoDB; a default client + empty tables
+      // suffice for the no-IO reload path.
+      dynamo: createDynamoDocumentClient({}),
+      tables: {} as TablesConfig,
+      connId: 'c1',
+      handlers: noopHandlers(),
+      managementApi: null,
+      ...(loader !== undefined ? { configLoader: loader } : {}),
+    });
+  }
+
+  it('re-invokes the bound loader and returns the fresh config', async () => {
+    let password = 'old';
+    const rt = makeReloadRuntime(async () => ({
+      ...baseConfig,
+      operCreds: [{ user: 'admin', password }],
+    }));
+
+    const first = await rt.reloadConfig();
+    expect(first.operCreds).toEqual([{ user: 'admin', password: 'old' }]);
+
+    password = 'rotated';
+    const second = await rt.reloadConfig();
+    expect(second.operCreds).toEqual([{ user: 'admin', password: 'rotated' }]);
+  });
+
+  it('propagates a loader rejection so the actor applies the graceful 382', async () => {
+    const rt = makeReloadRuntime(async () => {
+      throw new Error('Secrets Manager unreachable');
+    });
+
+    await expect(rt.reloadConfig()).rejects.toThrow('Secrets Manager unreachable');
+  });
+
+  it('rejects when no loader was bound at construction', async () => {
+    const rt = makeReloadRuntime();
+
+    await expect(rt.reloadConfig()).rejects.toThrow('no config loader bound');
+  });
+});

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,174 @@
+/**
+ * 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 { MarshalledConnection } from '../src/serialize.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;
+  /** Most recently PutCommand Item (undefined when no put happened). */
+  lastPutItem: Record<string, unknown> | undefined;
+}
+
+/** 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 };
+  let lastPutItem: Record<string, unknown> | undefined;
+  const dynamo = {
+    send: async (cmd: unknown) => {
+      if (cmd instanceof ScanCommand) {
+        return pages[scanIdx++] ?? { Count: 0 };
+      }
+      if (cmd instanceof PutCommand) {
+        calls.puts++;
+        lastPutItem = cmd.input.Item as Record<string, unknown> | undefined;
+        return {};
+      }
+      throw new Error('unexpected command');
+    },
+  } as unknown as DynamoDBDocumentClient;
+  return {
+    dynamo,
+    get puts() {
+      return calls.puts;
+    },
+    get lastPutItem() {
+      return lastPutItem;
+    },
+  };
+}
+
+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, subprotocol: null });
+    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);
+  });
+});
+
+describe('handleConnect — IRCv3 WebSocket subprotocol negotiation', () => {
+  it('selects binary.ircv3.net, echoes it, and persists a spec-binary mode row', async () => {
+    const stub = makeStub([{ Count: 0 }]);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-binary',
+      now: 42,
+      secWebSocketProtocol: 'binary.ircv3.net',
+      serverConfig: { ...DEFAULT_SERVER_CONFIG, maxClients: 5 },
+    });
+    expect(outcome).toEqual({ admitted: true, subprotocol: 'binary.ircv3.net' });
+    expect(stub.puts).toBe(1);
+    const item = stub.lastPutItem as MarshalledConnection | undefined;
+    expect(item?.wsMode).toBe('spec-binary');
+  });
+
+  it('selects text.ircv3.net and persists a spec-text mode row', async () => {
+    const stub = makeStub([{ Count: 0 }]);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-text',
+      now: 42,
+      secWebSocketProtocol: 'text.ircv3.net',
+      serverConfig: { ...DEFAULT_SERVER_CONFIG, maxClients: 5 },
+    });
+    expect(outcome).toEqual({ admitted: true, subprotocol: 'text.ircv3.net' });
+    const item = stub.lastPutItem as MarshalledConnection | undefined;
+    expect(item?.wsMode).toBe('spec-text');
+  });
+
+  it('honours client-preference order when both subprotocols are offered', async () => {
+    const stub = makeStub([{ Count: 0 }]);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-pref',
+      now: 42,
+      secWebSocketProtocol: 'text.ircv3.net, binary.ircv3.net',
+      serverConfig: { ...DEFAULT_SERVER_CONFIG, maxClients: 5 },
+    });
+    expect(outcome).toEqual({ admitted: true, subprotocol: 'text.ircv3.net' });
+  });
+
+  it('falls back to legacy (null subprotocol, no mode column) when no offer is present', async () => {
+    const stub = makeStub([{ Count: 0 }]);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-legacy',
+      now: 42,
+      serverConfig: { ...DEFAULT_SERVER_CONFIG, maxClients: 5 },
+    });
+    expect(outcome).toEqual({ admitted: true, subprotocol: null });
+    const item = stub.lastPutItem as MarshalledConnection | undefined;
+    expect(item?.wsMode).toBeUndefined();
+  });
+
+  it('falls back to legacy when only unsupported subprotocols are offered', async () => {
+    const stub = makeStub([{ Count: 0 }]);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-unsupported',
+      now: 42,
+      secWebSocketProtocol: 'chat, superchat.v2',
+      serverConfig: { ...DEFAULT_SERVER_CONFIG, maxClients: 5 },
+    });
+    expect(outcome).toEqual({ admitted: true, subprotocol: null });
+    const item = stub.lastPutItem as MarshalledConnection | undefined;
+    expect(item?.wsMode).toBeUndefined();
+  });
+
+  it('does not negotiate a subprotocol when the admission gate rejects', async () => {
+    const stub = makeStub([{ Count: 5 }]);
+    const outcome = await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-full',
+      secWebSocketProtocol: 'binary.ircv3.net',
+      serverConfig: { ...DEFAULT_SERVER_CONFIG, maxClients: 5 },
+    });
+    expect(outcome).toEqual({ admitted: false, statusCode: 429, reason: 'server full' });
+    expect(stub.puts).toBe(0);
+  });
+});