serverless-ircd 0.7.0 → 0.8.0

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

@@ -1,13 +1,11 @@
 /**
- * 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`.
+ * Unit tests for `handleConnect`. A hand-rolled stub client stands in for
+ * `DynamoDBDocumentClient`, simulating the atomic admission counter
+ * (`UpdateItem` increment/decrement on the meta row) and the `Put` of the
+ * new connection row. The admission policy itself is covered by
+ * `admission.test.ts`; the counter primitives by `connection-counter.test.ts`.
  */
-
-import { type DynamoDBDocumentClient, PutCommand, ScanCommand } from '@aws-sdk/lib-dynamodb';
+import { type DynamoDBDocumentClient, PutCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
 import { makeTestServerConfig } from '@serverless-ircd/irc-test-support';
 import { describe, expect, it } from 'vitest';
 import { handleConnect } from '../src/handlers/connect.js';
@@ -27,53 +25,114 @@ interface Stub {
   puts: number;
   /** Most recently PutCommand Item (undefined when no put happened). */
   lastPutItem: Record<string, unknown> | undefined;
+  /** Current simulated counter value. */
+  count: number;
+  increments: number;
+  decrements: number;
+  /** Commands issued, in order (for asserting no Scan is used). */
+  commands: string[];
 }
 
-/** 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 };
+/**
+ * Builds a stub client with an initial admission counter value. The stub
+ * honours the floor-at-0 decrement condition the real handler relies on.
+ */
+function makeStub(initialCount: number): Stub {
+  const state = { count: initialCount, puts: 0, increments: 0, decrements: 0 };
   let lastPutItem: Record<string, unknown> | undefined;
+  const commands: string[] = [];
   const dynamo = {
     send: async (cmd: unknown) => {
-      if (cmd instanceof ScanCommand) {
-        return pages[scanIdx++] ?? { Count: 0 };
+      if (cmd instanceof UpdateCommand) {
+        const expr = (cmd.input as { UpdateExpression?: string }).UpdateExpression ?? '';
+        const cond = (cmd.input as { ConditionExpression?: string }).ConditionExpression;
+        commands.push('Update');
+        if (expr.includes('+ :one')) {
+          state.count += 1;
+          state.increments += 1;
+          return { Attributes: { count: state.count } };
+        }
+        if (expr.includes('- :one')) {
+          // Floor at 0: when a condition is present and count <= 0, reject.
+          if (cond !== undefined && state.count <= 0) {
+            throw Object.assign(new Error('conditional request failed'), {
+              name: 'ConditionalCheckFailedException',
+            });
+          }
+          if (state.count > 0) {
+            state.count -= 1;
+            state.decrements += 1;
+          }
+          return { Attributes: { count: state.count } };
+        }
+        throw new Error(`unexpected Update expression: ${expr}`);
       }
       if (cmd instanceof PutCommand) {
-        calls.puts++;
+        commands.push('Put');
+        state.puts += 1;
         lastPutItem = cmd.input.Item as Record<string, unknown> | undefined;
         return {};
       }
-      throw new Error('unexpected command');
+      commands.push('Unknown');
+      throw new Error(`unexpected command (Scan must not be used): ${String(cmd)}`);
     },
   } as unknown as DynamoDBDocumentClient;
   return {
     dynamo,
     get puts() {
-      return calls.puts;
+      return state.puts;
     },
     get lastPutItem() {
       return lastPutItem;
     },
+    get count() {
+      return state.count;
+    },
+    get increments() {
+      return state.increments;
+    },
+    get decrements() {
+      return state.decrements;
+    },
+    get commands() {
+      return commands;
+    },
   };
 }
 
 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' } }, {}]);
+  it('admits (writes the row) and reserves a counter slot when below the cap', async () => {
+    const stub = makeStub(0);
     const outcome = await handleConnect({
       dynamo: stub.dynamo,
       tables: TABLES,
-      connectionId: 'c-paged',
+      connectionId: 'c-admit',
       now: 42,
       serverConfig: makeTestServerConfig({ maxClients: 5 }),
     });
     expect(outcome).toEqual({ admitted: true, subprotocol: null });
     expect(stub.puts).toBe(1);
+    expect(stub.increments).toBe(1);
+    expect(stub.decrements).toBe(0);
+    expect(stub.count).toBe(1);
+  });
+
+  it('uses only O(1) UpdateItem for admission (no full-table Scan)', async () => {
+    const stub = makeStub(0);
+    await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-noop',
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+    });
+    // Every command must be Update or Put — a Scan would throw via the
+    // stub's Unknown branch, and the recorded commands prove the shape.
+    expect(stub.commands.every((c) => c === 'Update' || c === 'Put')).toBe(true);
+    expect(stub.commands).toContain('Update');
   });
 
   it('does not write a row when the count reaches the cap', async () => {
-    const stub = makeStub([{ Count: 5 }]);
+    const stub = makeStub(5);
     const outcome = await handleConnect({
       dynamo: stub.dynamo,
       tables: TABLES,
@@ -83,11 +142,70 @@ describe('handleConnect admission plumbing', () => {
     expect(outcome).toEqual({ admitted: false, statusCode: 429, reason: 'server full' });
     expect(stub.puts).toBe(0);
   });
+
+  it('rolls back the counter reservation when admission rejects', async () => {
+    const stub = makeStub(5);
+    await handleConnect({
+      dynamo: stub.dynamo,
+      tables: TABLES,
+      connectionId: 'c-rollback',
+      serverConfig: makeTestServerConfig({ maxClients: 5 }),
+    });
+    expect(stub.increments).toBe(1);
+    expect(stub.decrements).toBe(1); // reservation released
+    expect(stub.count).toBe(5); // back to the starting count
+  });
+
+  it('rolls back the reservation when the row Put fails', async () => {
+    // Stub whose Put throws; count starts below cap so admission passes.
+    let lastPutItem: Record<string, unknown> | undefined;
+    const state = { count: 0, increments: 0, decrements: 0 };
+    const dynamo = {
+      send: async (cmd: unknown) => {
+        if (cmd instanceof UpdateCommand) {
+          const expr = (cmd.input as { UpdateExpression?: string }).UpdateExpression ?? '';
+          if (expr.includes('+ :one')) {
+            state.count += 1;
+            state.increments += 1;
+            return { Attributes: { count: state.count } };
+          }
+          if (state.count > 0) {
+            state.count -= 1;
+            state.decrements += 1;
+          }
+          return { Attributes: { count: state.count } };
+        }
+        if (cmd instanceof PutCommand) {
+          lastPutItem = cmd.input.Item as Record<string, unknown> | undefined;
+          throw new Error('Put failed');
+        }
+        throw new Error('unexpected');
+      },
+    } as unknown as DynamoDBDocumentClient;
+    await expect(
+      handleConnect({
+        dynamo,
+        tables: TABLES,
+        connectionId: 'c-putfail',
+        serverConfig: makeTestServerConfig({ maxClients: 5 }),
+      }),
+    ).rejects.toThrow('Put failed');
+    expect(state.increments).toBe(1);
+    expect(state.decrements).toBe(1); // released despite the failed Put
+    expect(state.count).toBe(0);
+    void lastPutItem;
+  });
 });
 
 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 }]);
+  it('falls back to legacy when only binary.ircv3.net is offered (API Gateway cannot transport binary frames)', async () => {
+    // API Gateway WebSocket APIs carry TEXT frames only; agreeing to
+    // binary.ircv3.net makes APIGW close the connection with code 1003
+    // ("Binary is not supported") the instant it is negotiated. A client
+    // that offers only binary is therefore downgraded to legacy (no
+    // subprotocol, no wsMode column) rather than being handed a binary
+    // agreement APIGW cannot honour.
+    const stub = makeStub(0);
     const outcome = await handleConnect({
       dynamo: stub.dynamo,
       tables: TABLES,
@@ -96,14 +214,14 @@ describe('handleConnect — IRCv3 WebSocket subprotocol negotiation', () => {
       secWebSocketProtocol: 'binary.ircv3.net',
       serverConfig: makeTestServerConfig({ maxClients: 5 }),
     });
-    expect(outcome).toEqual({ admitted: true, subprotocol: 'binary.ircv3.net' });
+    expect(outcome).toEqual({ admitted: true, subprotocol: null });
     expect(stub.puts).toBe(1);
     const item = stub.lastPutItem as MarshalledConnection | undefined;
-    expect(item?.wsMode).toBe('spec-binary');
+    expect(item?.wsMode).toBeUndefined();
   });
 
   it('selects text.ircv3.net and persists a spec-text mode row', async () => {
-    const stub = makeStub([{ Count: 0 }]);
+    const stub = makeStub(0);
     const outcome = await handleConnect({
       dynamo: stub.dynamo,
       tables: TABLES,
@@ -117,21 +235,29 @@ describe('handleConnect — IRCv3 WebSocket subprotocol negotiation', () => {
     expect(item?.wsMode).toBe('spec-text');
   });
 
-  it('honours client-preference order when both subprotocols are offered', async () => {
-    const stub = makeStub([{ Count: 0 }]);
+  it('selects text.ircv3.net even when binary.ircv3.net is offered first (API Gateway is text-only)', async () => {
+    // Reproduces the 1003 close from production: the IRCv3 relay
+    // (tcp-ws-forwarder) offers `binary.ircv3.net, text.ircv3.net` (binary
+    // first by preference). The generic core selector would agree to
+    // binary and APIGW immediately closes with code 1003
+    // "Binary is not supported". On the APIGW transport the handler MUST
+    // select text.ircv3.net regardless of client-preference order.
+    const stub = makeStub(0);
     const outcome = await handleConnect({
       dynamo: stub.dynamo,
       tables: TABLES,
       connectionId: 'c-pref',
       now: 42,
-      secWebSocketProtocol: 'text.ircv3.net, binary.ircv3.net',
+      secWebSocketProtocol: 'binary.ircv3.net, text.ircv3.net',
       serverConfig: makeTestServerConfig({ 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('falls back to legacy (null subprotocol, no mode column) when no offer is present', async () => {
-    const stub = makeStub([{ Count: 0 }]);
+    const stub = makeStub(0);
     const outcome = await handleConnect({
       dynamo: stub.dynamo,
       tables: TABLES,
@@ -145,7 +271,7 @@ describe('handleConnect — IRCv3 WebSocket subprotocol negotiation', () => {
   });
 
   it('falls back to legacy when only unsupported subprotocols are offered', async () => {
-    const stub = makeStub([{ Count: 0 }]);
+    const stub = makeStub(0);
     const outcome = await handleConnect({
       dynamo: stub.dynamo,
       tables: TABLES,
@@ -160,7 +286,7 @@ describe('handleConnect — IRCv3 WebSocket subprotocol negotiation', () => {
   });
 
   it('does not negotiate a subprotocol when the admission gate rejects', async () => {
-    const stub = makeStub([{ Count: 5 }]);
+    const stub = makeStub(5);
     const outcome = await handleConnect({
       dynamo: stub.dynamo,
       tables: TABLES,

package/packages/aws-adapter/tests/connection-counter.test.ts

@@ -0,0 +1,127 @@
+/**
+ * Unit tests for the O(1) admission counter (`connection-counter.ts`).
+ *
+ * A hand-rolled stub stands in for `DynamoDBDocumentClient` so the atomic
+ * increment/decrement `UpdateItem` shapes and the floor-at-0 behaviour are
+ * verified without DynamoDB Local.
+ */
+import { type DynamoDBDocumentClient, UpdateCommand } from '@aws-sdk/lib-dynamodb';
+import { describe, expect, it } from 'vitest';
+import {
+  CONNECTION_COUNT_ATTR,
+  CONNECTION_COUNT_META_ID,
+  decrementConnectionCount,
+  incrementConnectionCount,
+} from '../src/connection-counter.js';
+
+interface Stub {
+  dynamo: DynamoDBDocumentClient;
+  /** Current simulated counter value (`undefined` = meta row absent). */
+  count: number | undefined;
+  updates: Array<{ setExpr: string; conditionExpr?: string }>;
+}
+
+function makeStub(count: number | undefined): Stub {
+  const state = { count };
+  const updates: Array<{ setExpr: string; conditionExpr?: string }> = [];
+  const dynamo = {
+    send: async (cmd: unknown) => {
+      if (cmd instanceof UpdateCommand) {
+        const input = cmd.input as {
+          UpdateExpression?: string;
+          ConditionExpression?: string;
+        };
+        updates.push({
+          setExpr: input.UpdateExpression ?? '',
+          ...(input.ConditionExpression !== undefined
+            ? { conditionExpr: input.ConditionExpression }
+            : {}),
+        });
+        // Honour the floor-at-0 condition the real handler relies on.
+        if (
+          input.ConditionExpression !== undefined &&
+          (state.count === undefined || state.count <= 0)
+        ) {
+          throw Object.assign(new Error('conditional request failed'), {
+            name: 'ConditionalCheckFailedException',
+          });
+        }
+        // Apply increment / decrement by inspecting the expression.
+        const expr = input.UpdateExpression ?? '';
+        if (expr.includes('+ :one')) {
+          state.count = (state.count ?? 0) + 1;
+        } else if (expr.includes('- :one')) {
+          state.count = (state.count ?? 0) - 1;
+        }
+        return { Attributes: { [CONNECTION_COUNT_ATTR]: state.count } };
+      }
+      throw new Error('unexpected command');
+    },
+  } as unknown as DynamoDBDocumentClient;
+  return {
+    dynamo,
+    get count() {
+      return state.count;
+    },
+    get updates() {
+      return updates;
+    },
+  };
+}
+
+describe('incrementConnectionCount', () => {
+  it('issues a single UpdateItem on the meta row and returns the new value', async () => {
+    const stub = makeStub(4);
+    const result = await incrementConnectionCount(stub.dynamo, 'Connections');
+    expect(result).toBe(5);
+    expect(stub.updates).toHaveLength(1);
+    expect(stub.count).toBe(5);
+  });
+
+  it('creates the meta row on first use (if_not_exists from 0)', async () => {
+    const stub = makeStub(undefined);
+    const result = await incrementConnectionCount(stub.dynamo, 'Connections');
+    expect(result).toBe(1);
+    expect(stub.count).toBe(1);
+    // The expression must use if_not_exists so an absent row seeds at 0.
+    expect(stub.updates[0]?.setExpr).toContain('if_not_exists');
+  });
+
+  it('targets the sentinel meta row key and the count attribute', async () => {
+    const stub = makeStub(0);
+    await incrementConnectionCount(stub.dynamo, 'Connections');
+    // The stub applied the increment; the contract is the sentinel key +
+    // count attr names are used (verified via the ExpressionAttributeNames).
+    expect(stub.count).toBe(1);
+    expect(CONNECTION_COUNT_META_ID).toContain('__meta:');
+  });
+});
+
+describe('decrementConnectionCount', () => {
+  it('decrements the counter by one', async () => {
+    const stub = makeStub(3);
+    await decrementConnectionCount(stub.dynamo, 'Connections');
+    expect(stub.count).toBe(2);
+  });
+
+  it('floors at 0 (condition prevents a negative count)', async () => {
+    const stub = makeStub(0);
+    await decrementConnectionCount(stub.dynamo, 'Connections');
+    expect(stub.count).toBe(0); // unchanged — condition rejected the update
+  });
+
+  it('is a silent no-op when the meta row is absent', async () => {
+    const stub = makeStub(undefined);
+    await expect(decrementConnectionCount(stub.dynamo, 'Connections')).resolves.toBeUndefined();
+    expect(stub.count).toBeUndefined();
+  });
+
+  it('never throws (teardown must not fail on counter drift)', async () => {
+    const dynamo = {
+      send: async () => {
+        throw new Error('network exploded');
+      },
+    } as unknown as DynamoDBDocumentClient;
+    await expect(decrementConnectionCount(dynamo, 'Connections')).resolves.toBeUndefined();
+  });
+});

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

@@ -0,0 +1,183 @@
+/**
+ * DynamoDB-backed integration tests for `DynamoServicesStore`.
+ *
+ * Exercises the real DynamoDB round-trip that the pure unit suite
+ * (`dynamo-services-store-unit.test.ts`) cannot: every services mutator
+ * enqueues a write-behind op, `flush()` drains it into the `Services`
+ * table, and a fresh `loadDynamoServicesStore` against the same table
+ * rehydrates the snapshot. This is the services-state persistence
+ * contract for the AWS adapter — a cold start must not lose services state.
+ *
+ * Gated on DynamoDB Local availability (same `DDB_AVAILABLE` flag as
+ * `account-store-dynamo.test.ts`).
+ */
+
+import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
+import { FakeClock } from '@serverless-ircd/irc-core';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { createDynamoDocumentClient } from '../src/dynamo';
+import { loadDynamoServicesStore } from '../src/dynamo-services-store';
+
+const available = process.env.DDB_AVAILABLE === '1';
+const endpoint = process.env.DYNAMO_ENDPOINT;
+
+const NOW = 1_700_000_000_000;
+
+interface Fx {
+  tableName: string;
+  client: ReturnType<typeof createDynamoDocumentClient>;
+  cleanup: () => Promise<void>;
+}
+
+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 = `svc-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+  const client = createDynamoDocumentClient({ endpoint });
+  await client.send(
+    new CreateTableCommand({
+      TableName: tableName,
+      AttributeDefinitions: [
+        { AttributeName: 'pk', AttributeType: 'S' },
+        { AttributeName: 'sk', AttributeType: 'S' },
+      ],
+      KeySchema: [
+        { AttributeName: 'pk', KeyType: 'HASH' },
+        { AttributeName: 'sk', KeyType: 'RANGE' },
+      ],
+      BillingMode: 'PAY_PER_REQUEST',
+    }),
+  );
+  return {
+    tableName,
+    client,
+    cleanup: async () => {
+      try {
+        await client.send(new DeleteTableCommand({ TableName: tableName }));
+      } catch {
+        // Idempotent.
+      }
+    },
+  };
+}
+
+describe.skipIf(!available)('DynamoServicesStore — real DynamoDB round-trip', () => {
+  beforeEach(async () => {
+    fx = await makeFx();
+  });
+  afterEach(async () => {
+    if (fx) await fx.cleanup();
+    fx = null;
+  });
+
+  it('persists a NickServ registration and verifies after reload (register→identify→SASL)', async () => {
+    const store = await loadDynamoServicesStore(
+      requireFx().client,
+      requireFx().tableName,
+      new FakeClock(NOW),
+    );
+    expect(store).toBeDefined();
+    store?.registerNick('alice', 'hunter2', 'a@example.com');
+    await store?.flush();
+
+    const reloaded = await loadDynamoServicesStore(
+      requireFx().client,
+      requireFx().tableName,
+      new FakeClock(NOW),
+    );
+    expect(reloaded).toBeDefined();
+    expect(reloaded?.isRegisteredNick('Alice')).toBe(true);
+    expect(reloaded?.verifyNick('alice', 'hunter2')).toEqual({ ok: true, account: 'alice' });
+  });
+
+  it('channel registration survives a reload (persists across a deploy)', async () => {
+    const store = await loadDynamoServicesStore(
+      requireFx().client,
+      requireFx().tableName,
+      new FakeClock(NOW),
+    );
+    store?.registerChannel('#chan', 'alice');
+    store?.setChannelAccess('#chan', 'bob', 5);
+    await store?.flush();
+
+    const reloaded = await loadDynamoServicesStore(
+      requireFx().client,
+      requireFx().tableName,
+      new FakeClock(NOW),
+    );
+    expect(reloaded?.getChannelFounder('#chan')).toBe('alice');
+    expect(reloaded?.getChannelAccess('#chan', 'bob')).toBe(5);
+  });
+
+  it('delivers a queued memo on reconnect after identify', async () => {
+    const store = await loadDynamoServicesStore(
+      requireFx().client,
+      requireFx().tableName,
+      new FakeClock(NOW),
+    );
+    const id = store?.recordMemo({ from: 'bob', to: 'alice', body: 'hi', sentAt: NOW });
+    await store?.flush();
+
+    const reloaded = await loadDynamoServicesStore(
+      requireFx().client,
+      requireFx().tableName,
+      new FakeClock(NOW),
+    );
+    expect(reloaded).toBeDefined();
+    if (!reloaded) throw new Error('reloaded services store failed to load');
+    const memos = reloaded.listMemos('alice');
+    expect(memos).toHaveLength(1);
+    expect(memos[0]?.id).toBe(id);
+    expect(memos[0]?.body).toBe('hi');
+  });
+
+  it('drops a channel subtree (channel + access + levels) on dropChannel', async () => {
+    const store = await loadDynamoServicesStore(
+      requireFx().client,
+      requireFx().tableName,
+      new FakeClock(NOW),
+    );
+    store?.registerChannel('#chan', 'alice');
+    store?.setChannelAccess('#chan', 'bob', 5);
+    store?.setChannelLevel('#chan', 'AUTOOP', 7);
+    await store?.flush();
+    const mid = await loadDynamoServicesStore(
+      requireFx().client,
+      requireFx().tableName,
+      new FakeClock(NOW),
+    );
+    mid?.dropChannel('#chan');
+    await mid?.flush();
+
+    const reloaded = await loadDynamoServicesStore(
+      requireFx().client,
+      requireFx().tableName,
+      new FakeClock(NOW),
+    );
+    expect(reloaded?.getChannelFounder('#chan')).toBeUndefined();
+    expect(reloaded?.getChannelAccess('#chan', 'bob')).toBe(0);
+    expect(reloaded?.getChannelLevel('#chan', 'AUTOOP')).toBeUndefined();
+  });
+
+  it('returns undefined when the table name is absent (services unbound)', async () => {
+    const store = await loadDynamoServicesStore(requireFx().client, undefined, new FakeClock(NOW));
+    expect(store).toBeUndefined();
+  });
+
+  it('returns an empty store on a fresh table', async () => {
+    const store = await loadDynamoServicesStore(
+      requireFx().client,
+      requireFx().tableName,
+      new FakeClock(NOW),
+    );
+    expect(store).toBeDefined();
+    expect(store?.listAkills()).toEqual([]);
+    expect(store?.listMemos('alice')).toEqual([]);
+  });
+});