serverless-ircd 0.7.0 → 0.9.0

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

@@ -0,0 +1,568 @@
+/**
+ * Pure unit tests for `DynamoServicesStore`.
+ *
+ * The DynamoDB-Local-backed round-trip lives in
+ * `dynamo-services-store-dynamo.test.ts` (gated on `DDB_AVAILABLE`). This
+ * suite runs everywhere by injecting a **recording fake** document client
+ * that answers `Scan` / `Query` / `BatchWriteItem` / `UpdateItem` against
+ * an in-process JS store keyed by `(pk, sk)`. Every `applyWrites` branch
+ * and every `scanSnapshot` coercion is exercised here, so the new code is
+ * covered locally even on hosts without Docker / Java.
+ */
+
+import type { BatchWriteCommandInput } from '@aws-sdk/lib-dynamodb';
+import { FakeClock } from '@serverless-ircd/irc-core';
+import { describe, expect, it } from 'vitest';
+import { DynamoServicesStore, loadDynamoServicesStore } from '../src/dynamo-services-store';
+
+const NOW = 1_700_000_000_000;
+
+/**
+ * Minimal fake `DynamoDBDocumentClient`. Implements only `send` for the
+ * command shapes the store emits. Items live in a `Map<"pk\x00sk", item>`.
+ */
+function makeFakeClient(initial: Array<Record<string, unknown>> = []): {
+  client: { send: (cmd: { input: unknown; constructor: { name: string } }) => Promise<unknown> };
+  items: Map<string, Record<string, unknown>>;
+} {
+  const items = new Map<string, Record<string, unknown>>();
+  for (const item of initial) {
+    items.set(`${String(item.pk)}\x00${String(item.sk)}`, { ...item });
+  }
+  const scan = (input: { TableName?: string; ExclusiveStartKey?: unknown }): {
+    Items: Record<string, unknown>[];
+    LastEvaluatedKey: undefined;
+  } => {
+    void input.TableName;
+    void input.ExclusiveStartKey;
+    return { Items: [...items.values()].map((i) => ({ ...i })), LastEvaluatedKey: undefined };
+  };
+  const query = (input: {
+    KeyConditionExpression?: string;
+    ExpressionAttributeValues?: Record<string, unknown>;
+    ProjectionExpression?: string;
+  }): { Items: Array<{ pk: string; sk: string }> } => {
+    const pk = String(input.ExpressionAttributeValues?.[':pk']);
+    const prefix = input.ExpressionAttributeValues?.[':prefix'];
+    const out: Array<{ pk: string; sk: string }> = [];
+    for (const item of items.values()) {
+      if (String(item.pk) !== pk) continue;
+      if (typeof prefix === 'string' && !String(item.sk).startsWith(prefix)) continue;
+      out.push({ pk: String(item.pk), sk: String(item.sk) });
+    }
+    void input.KeyConditionExpression;
+    void input.ProjectionExpression;
+    return { Items: out };
+  };
+  const client = {
+    async send(cmd: { input: unknown; constructor: { name: string } }): Promise<unknown> {
+      switch (cmd.constructor.name) {
+        case 'ScanCommand':
+          return scan(cmd.input as Parameters<typeof scan>[0]);
+        case 'QueryCommand':
+          return query(cmd.input as Parameters<typeof query>[0]);
+        case 'BatchWriteCommand': {
+          const reqs = (cmd.input as BatchWriteCommandInput).RequestItems ?? {};
+          for (const [table, list] of Object.entries(reqs)) {
+            void table;
+            for (const req of list) {
+              if (req.PutRequest !== undefined) {
+                const item = req.PutRequest.Item as Record<string, unknown>;
+                items.set(`${String(item.pk)}\x00${String(item.sk)}`, { ...item });
+              } else if (req.DeleteRequest !== undefined) {
+                const key = req.DeleteRequest.Key as { pk: string; sk: string };
+                items.delete(`${key.pk}\x00${key.sk}`);
+              }
+            }
+          }
+          return { UnprocessedItems: {} };
+        }
+        case 'UpdateCommand': {
+          const input = cmd.input as {
+            Key: { pk: string; sk: string };
+            UpdateExpression?: string;
+            ExpressionAttributeValues?: Record<string, unknown>;
+          };
+          const k = `${input.Key.pk}\x00${input.Key.sk}`;
+          const item = items.get(k);
+          if (item !== undefined && input.ExpressionAttributeValues?.[':r'] !== undefined) {
+            item.read = input.ExpressionAttributeValues[':r'];
+          }
+          return {};
+        }
+        default:
+          throw new Error(`fake client: unhandled command ${cmd.constructor.name}`);
+      }
+    },
+  };
+  return { client, items };
+}
+
+// Cast helper: the store types against `DynamoDBDocumentClient`; the fake
+// only implements `send`. The runtime contract is send-only.
+type DocClient = ConstructorParameters<typeof DynamoServicesStore>[0]['docClient'];
+const asClient = (fake: { send: unknown }): DocClient => fake as unknown as DocClient;
+
+describe('loadDynamoServicesStore', () => {
+  it('returns undefined when the table name is absent', async () => {
+    const { client } = makeFakeClient();
+    const store = await loadDynamoServicesStore(asClient(client), undefined, new FakeClock(NOW));
+    expect(store).toBeUndefined();
+  });
+
+  it('returns an empty store on a fresh scan', async () => {
+    const { client } = makeFakeClient();
+    const store = await loadDynamoServicesStore(asClient(client), 'Services', new FakeClock(NOW));
+    expect(store).toBeDefined();
+    expect(store?.snapshot()).toEqual({
+      nicks: [],
+      channels: [],
+      access: [],
+      levels: [],
+      vhosts: [],
+      pendingVhosts: [],
+      memos: [],
+      readMarkers: [],
+      akills: [],
+      jupes: [],
+    });
+  });
+});
+
+describe('DynamoServicesStore — round-trip via fake DDB', () => {
+  async function fresh(): Promise<{
+    store: DynamoServicesStore;
+    items: Map<string, Record<string, unknown>>;
+    client: { send: unknown };
+  }> {
+    const { client, items } = makeFakeClient();
+    const store = await loadDynamoServicesStore(asClient(client), 'Services', new FakeClock(NOW));
+    if (store === undefined) throw new Error('store not loaded');
+    return { store, items, client };
+  }
+
+  async function reload(client: { send: unknown }): Promise<DynamoServicesStore> {
+    const store = await loadDynamoServicesStore(
+      asClient(client),
+      'Services',
+      new FakeClock(NOW + 1),
+    );
+    if (store === undefined) throw new Error('store not loaded');
+    return store;
+  }
+
+  it('persists a NickServ registration + enforce + verifies after reload', async () => {
+    const { store, client } = await fresh();
+    store.registerNick('alice', 'hunter2', 'a@x');
+    store.setNickEnforce('alice', 'kill');
+    await store.flush();
+
+    const reloaded = await reload(client);
+    expect(reloaded.isRegisteredNick('Alice')).toBe(true);
+    expect(reloaded.verifyNick('alice', 'hunter2')).toEqual({ ok: true, account: 'alice' });
+    expect(reloaded.getNickEnforce('alice')).toBe('kill');
+  });
+
+  it('drops a NickServ registration after flush + reload', async () => {
+    const { store, client } = await fresh();
+    store.registerNick('alice', 'pw', 'a@x');
+    await store.flush();
+    const mid = await reload(client);
+    mid.dropNick('alice');
+    await mid.flush();
+    expect((await reload(client)).isRegisteredNick('alice')).toBe(false);
+  });
+
+  it('persists channel + access + levels + topic, then drops the whole subtree', async () => {
+    const { store, client } = await fresh();
+    store.registerChannel('#chan', 'alice');
+    store.setChannelAccess('#chan', 'bob', 5);
+    store.setChannelLevel('#chan', 'AUTOOP', 7);
+    store.setChannelKeepTopic('#chan', true);
+    store.setChannelTopic('#chan', { text: 'hi', setter: 'alice', setAt: NOW });
+    await store.flush();
+
+    const reloaded = await reload(client);
+    expect(reloaded.getChannelFounder('#chan')).toBe('alice');
+    expect(reloaded.getChannelAccess('#chan', 'bob')).toBe(5);
+    expect(reloaded.getChannelLevel('#chan', 'AUTOOP')).toBe(7);
+    expect(reloaded.getChannelTopic('#chan')?.text).toBe('hi');
+
+    reloaded.dropChannel('#chan');
+    await reloaded.flush();
+    const after = await reload(client);
+    expect(after.getChannelFounder('#chan')).toBeUndefined();
+    expect(after.getChannelAccess('#chan', 'bob')).toBe(0);
+    expect(after.getChannelLevel('#chan', 'AUTOOP')).toBeUndefined();
+  });
+
+  it('resetChannelLevels wipes only levels, leaving access intact', async () => {
+    const { store, client } = await fresh();
+    store.registerChannel('#chan', 'alice');
+    store.setChannelAccess('#chan', 'bob', 5);
+    store.setChannelLevel('#chan', 'AUTOOP', 7);
+    await store.flush();
+    const mid = await reload(client);
+    mid.resetChannelLevels('#chan');
+    await mid.flush();
+
+    const after = await reload(client);
+    expect(after.getChannelLevel('#chan', 'AUTOOP')).toBeUndefined();
+    expect(after.getChannelAccess('#chan', 'bob')).toBe(5);
+  });
+
+  it('removes access on setChannelAccess level<=0', async () => {
+    const { store, client } = await fresh();
+    store.registerChannel('#chan', 'alice');
+    store.setChannelAccess('#chan', 'bob', 5);
+    store.setChannelAccess('#chan', 'bob', 0);
+    await store.flush();
+    expect((await reload(client)).getChannelAccess('#chan', 'bob')).toBe(0);
+  });
+
+  it('persists + clears a vhost', async () => {
+    const { store, client } = await fresh();
+    store.setVhost('alice', 'cloak.example');
+    await store.flush();
+    const mid = await reload(client);
+    expect(mid.getVhost('alice')).toBe('cloak.example');
+    mid.setVhost('alice', '');
+    await mid.flush();
+    expect((await reload(client)).getVhost('alice')).toBeUndefined();
+  });
+
+  it('persists a pending vhost and round-trips approve across reload', async () => {
+    const { store, client } = await fresh();
+    store.requestVhost('alice', 'queued.example');
+    await store.flush();
+    const mid = await reload(client);
+    expect(mid.getPendingVhost('alice')).toBe('queued.example');
+    expect(mid.getVhost('alice')).toBeUndefined();
+    // approveVhost activates the request and clears the pending entry.
+    mid.approveVhost('alice');
+    await mid.flush();
+    const approved = await reload(client);
+    expect(approved.getPendingVhost('alice')).toBeUndefined();
+    expect(approved.getVhost('alice')).toBe('queued.example');
+  });
+
+  it('persists a rejected pending vhost across reload', async () => {
+    const { store, client } = await fresh();
+    store.requestVhost('alice', 'queued.example');
+    await store.flush();
+    const mid = await reload(client);
+    mid.rejectVhost('alice');
+    await mid.flush();
+    const rejected = await reload(client);
+    expect(rejected.getPendingVhost('alice')).toBeUndefined();
+    expect(rejected.getVhost('alice')).toBeUndefined();
+  });
+
+  it('persists a memo, marks it read, deletes it', async () => {
+    const { store, client } = await fresh();
+    const id = store.recordMemo({ from: 'bob', to: 'alice', body: 'hi', sentAt: NOW });
+    await store.flush();
+    const mid = await reload(client);
+    expect(mid.listMemos('alice')).toHaveLength(1);
+    mid.markMemoRead('alice', id);
+    await mid.flush();
+    const read = await reload(client);
+    expect(read.listMemos('alice')[0]?.read).toBe(true);
+    // next id continues after reloaded max (the counter resumes from id).
+    expect(read.recordMemo({ from: 'x', to: 'alice', body: 'y', sentAt: NOW })).toBe(id + 1);
+    await read.flush();
+
+    const deleter = await reload(client);
+    deleter.deleteMemo('alice', id);
+    await deleter.flush();
+    const after = await reload(client);
+    // The deleted memo (id=1) is gone; the one created by the id-continuation
+    // check (id=2) remains — the assertion is "id was deleted", not "empty".
+    expect(after.listMemos('alice').find((m) => m.id === id)).toBeUndefined();
+    expect(after.listMemos('alice').find((m) => m.id === id + 1)).toBeDefined();
+  });
+
+  it('persists a read-marker', async () => {
+    const { store, client } = await fresh();
+    store.setLastReadMarker('alice', '#chan', 'm1');
+    await store.flush();
+    expect((await reload(client)).getLastReadMarker('alice', '#chan')).toBe('m1');
+  });
+
+  it('persists + matches + removes an AKILL', async () => {
+    const { store, client } = await fresh();
+    store.addAkill('*!*@bad.example', 'flooding');
+    await store.flush();
+    const mid = await reload(client);
+    expect(mid.matchAkill('evil!spam@bad.example')?.reason).toBe('flooding');
+    mid.removeAkill('*!*@bad.example');
+    await mid.flush();
+    expect((await reload(client)).matchAkill('evil!spam@bad.example')).toBeUndefined();
+  });
+
+  it('persists + queries + removes a JUPE', async () => {
+    const { store, client } = await fresh();
+    store.addJupe('moo', 'blocked');
+    await store.flush();
+    const mid = await reload(client);
+    expect(mid.isJuped('moo')).toBe(true);
+    mid.removeJupe('moo');
+    await mid.flush();
+    expect((await reload(client)).isJuped('moo')).toBe(false);
+  });
+});
+
+describe('DynamoServicesStore — snapshot coercion tolerance', () => {
+  it('skips items with unknown or ill-typed fields', async () => {
+    // Hand-craft malformed items directly in the fake table.
+    const { client, items } = makeFakeClient();
+    items.set('NICK:b\x00#', {
+      pk: 'NICK:b',
+      sk: '#',
+      type: 'nick',
+      nick: 'b',
+      account: 'b',
+      email: 7,
+    }); // ill-typed email
+    items.set('NICK:c\x00#', { pk: 'NICK:c', sk: '#' }); // no type discriminator
+    items.set('CHAN:x\x00#META', {
+      pk: 'CHAN:x',
+      sk: '#META',
+      type: 'channel',
+      channel: '#x',
+      founder: 'f',
+      createdAt: NOW,
+      mlock: '',
+      restricted: 'yes', // ill-typed boolean
+      keepTopic: false,
+    });
+    items.set('MEMO:9\x00#', {
+      pk: 'MEMO:9',
+      sk: '#',
+      type: 'memo',
+      id: 9,
+      from: 'a',
+      to: 'b',
+      body: 'x',
+      sentAt: NOW,
+      read: 'no', // ill-typed boolean
+    });
+    // Ill-typed items for the remaining sections (covers each loader's skip).
+    items.set('VH:bad\x00#', { pk: 'VH:bad', sk: '#', type: 'vhost', account: 7, vhost: 'x' }); // account non-string
+    items.set('PV:bad\x00#', {
+      pk: 'PV:bad',
+      sk: '#',
+      type: 'pendingvhost',
+      account: 'a',
+      vhost: 7,
+    }); // vhost non-string
+    items.set('RM:bad\x00#c', {
+      pk: 'RM:bad',
+      sk: '#c',
+      type: 'readmarker',
+      account: 'a',
+      channel: '#c',
+      msgid: 7,
+    }); // msgid non-string
+    items.set('ACC:bad\x00ACC:b', {
+      pk: 'CHAN:bad\x00ACC:b',
+      sk: 'ACC:b',
+      type: 'chanaccess',
+      channel: '#c',
+      account: 'b',
+      level: 'big',
+    }); // level non-number
+    items.set('LVL:bad\x00LVL:AUTOOP', {
+      pk: 'CHAN:bad\x00LVL:AUTOOP',
+      sk: 'LVL:AUTOOP',
+      type: 'chanlevel',
+      channel: '#c',
+      op: 'AUTOOP',
+      level: 'big',
+    }); // level non-number
+    items.set('AK:bad\x00#', {
+      pk: 'AK:bad',
+      sk: '#',
+      type: 'akill',
+      mask: '*!*@x',
+      reason: 'r',
+      createdAt: 'when',
+    }); // createdAt non-number
+    items.set('JP:bad\x00#', {
+      pk: 'JP:bad',
+      sk: '#',
+      type: 'jupe',
+      name: 'n',
+      reason: 'r',
+      createdAt: 'when',
+    }); // createdAt non-number
+    items.set('UNKNOWN\x00#', { pk: 'UNKNOWN', sk: '#', type: 'something-else' });
+    const store = await loadDynamoServicesStore(asClient(client), 'Services', new FakeClock(NOW));
+    expect(store).toBeDefined();
+    if (!store) throw new Error('services store failed to load');
+    const snap = store.snapshot();
+    expect(snap.nicks).toEqual([]);
+    expect(snap.channels).toEqual([]);
+    expect(snap.memos).toEqual([]);
+    expect(snap.vhosts).toEqual([]);
+    expect(snap.pendingVhosts).toEqual([]);
+    expect(snap.readMarkers).toEqual([]);
+    expect(snap.access).toEqual([]);
+    expect(snap.levels).toEqual([]);
+    expect(snap.akills).toEqual([]);
+    expect(snap.jupes).toEqual([]);
+  });
+
+  it('hydrates a channel topic only when all three topic fields are present', async () => {
+    const { client, items } = makeFakeClient();
+    // channel with partial topic (missing topicSetAt) — topic should be dropped.
+    items.set('CHAN:t\x00#META', {
+      pk: 'CHAN:t',
+      sk: '#META',
+      type: 'channel',
+      channel: '#t',
+      founder: 'f',
+      createdAt: NOW,
+      mlock: '',
+      restricted: false,
+      keepTopic: true,
+      topicText: 'hi',
+      topicSetter: 'f',
+    });
+    const store = await loadDynamoServicesStore(asClient(client), 'Services', new FakeClock(NOW));
+    const ch = store?.getChannel('#t');
+    expect(ch).toBeDefined();
+    expect(ch?.topic).toBeUndefined();
+  });
+});
+
+describe('DynamoServicesStore — batch chunking', () => {
+  it('flushes more than 25 puts across multiple BatchWriteItem calls', async () => {
+    const { client, items } = makeFakeClient();
+    const store = await loadDynamoServicesStore(asClient(client), 'Services', new FakeClock(NOW));
+    expect(store).toBeDefined();
+    // 30 distinct channel access rows → 30 PutRequests → 2 batches (25 + 5).
+    for (let i = 0; i < 30; i++) {
+      store?.registerChannel(`#c${i}`, 'alice');
+    }
+    await store?.flush();
+    // Each channel produced exactly one item (#META). 30 channels → 30 items.
+    let channelItems = 0;
+    for (const item of items.values()) {
+      if (item.type === 'channel') channelItems++;
+    }
+    expect(channelItems).toBe(30);
+  });
+});
+
+describe('DynamoServicesStore — no-op flush', () => {
+  it('a flush with no mutations completes without writing', async () => {
+    const { client } = makeFakeClient();
+    const store = await loadDynamoServicesStore(asClient(client), 'Services', new FakeClock(NOW));
+    await expect(store?.flush()).resolves.toBeUndefined();
+  });
+});
+
+describe('loadDynamoServicesStore — scan failure tolerance', () => {
+  it('returns an empty store when the initial scan throws', async () => {
+    // A client whose ScanCommand rejects → loadDynamoServicesStore swallows
+    // the failure into an empty snapshot (the deployer provisions the table;
+    // a flush against the missing table surfaces the real error).
+    const throwingClient = {
+      async send(cmd: { constructor: { name: string } }): Promise<unknown> {
+        if (cmd.constructor.name === 'ScanCommand') {
+          throw new Error('TableNotFound');
+        }
+        throw new Error(`unhandled command ${cmd.constructor.name}`);
+      },
+    };
+    const store = await loadDynamoServicesStore(
+      asClient(throwingClient),
+      'Services',
+      new FakeClock(NOW),
+    );
+    expect(store).toBeDefined();
+    expect(store?.listAkills()).toEqual([]);
+    expect(store?.listMemos('alice')).toEqual([]);
+  });
+
+  it('constructs with defaults (no clock / no snapshot)', async () => {
+    const { client } = makeFakeClient();
+    // Direct construction without clock/snapshot exercises the constructor's
+    // undefined branches (loadDynamoServicesStore always passes both).
+    const store = new DynamoServicesStore({ docClient: asClient(client), tableName: 'Services' });
+    store.registerNick('alice', 'pw', 'a@x');
+    await store.flush();
+    expect(store.isRegisteredNick('alice')).toBe(true);
+  });
+
+  it('tolerates undefined Items in scan/query results (defensive ?? [])', async () => {
+    // A client that omits Items from Scan/Query output exercises the
+    // `result.Items ?? []` defensive fallback in scanSnapshot + queryChannelKeys.
+    const undefItemsClient = {
+      async send(cmd: { constructor: { name: string } }): Promise<unknown> {
+        switch (cmd.constructor.name) {
+          case 'ScanCommand':
+            return { LastEvaluatedKey: undefined }; // no Items field
+          case 'QueryCommand':
+            return {}; // no Items field
+          case 'BatchWriteCommand':
+            return { UnprocessedItems: {} };
+          case 'UpdateCommand':
+            return {};
+          default:
+            throw new Error(`unhandled command ${cmd.constructor.name}`);
+        }
+      },
+    };
+    const store = await loadDynamoServicesStore(
+      asClient(undefItemsClient),
+      'Services',
+      new FakeClock(NOW),
+    );
+    expect(store?.snapshot().nicks).toEqual([]);
+    // deleteChannel fans out via queryChannelKeys (Query with undefined Items).
+    store?.registerChannel('#chan', 'alice');
+    await store?.flush();
+    store?.dropChannel('#chan');
+    await store?.flush();
+    expect(store?.getChannelFounder('#chan')).toBeUndefined();
+  });
+
+  it('skips query results with non-string pk/sk keys', async () => {
+    // queryChannelKeys guards each item's pk/sk; a row where pk is numeric
+    // is dropped (covers the `typeof === 'string'` false branch).
+    const badKeyClient = {
+      async send(cmd: { constructor: { name: string } }): Promise<unknown> {
+        switch (cmd.constructor.name) {
+          case 'ScanCommand':
+            return { Items: [] };
+          case 'QueryCommand':
+            return {
+              Items: [
+                { pk: 7, sk: 'x' },
+                { pk: 'CHAN:#c', sk: '#META' },
+              ],
+            };
+          case 'BatchWriteCommand':
+            return { UnprocessedItems: {} };
+          case 'UpdateCommand':
+            return {};
+          default:
+            throw new Error(`unhandled command ${cmd.constructor.name}`);
+        }
+      },
+    };
+    const store = await loadDynamoServicesStore(
+      asClient(badKeyClient),
+      'Services',
+      new FakeClock(NOW),
+    );
+    store?.registerChannel('#c', 'alice');
+    await store?.flush();
+    // dropChannel queries the partition; the numeric-pk row is skipped, the
+    // valid row is deleted. No throw, channel founder gone afterwards.
+    store?.dropChannel('#c');
+    await expect(store?.flush()).resolves.toBeUndefined();
+  });
+});

package/packages/aws-adapter/tests/global-setup.ts

@@ -71,7 +71,11 @@ export default async function globalSetup(): Promise<(() => Promise<void>) | und
   const wantZip = strategy === 'auto' || strategy === 'zip';
 
   // Strategy 1: testcontainers (Docker).
-  if (wantDocker) {
+  // Pre-probe the Docker daemon: `docker info` hangs indefinitely on macOS
+  // when Docker Desktop is installed but not running (the CLI waits for
+  // the daemon to spin up). Bound that wait so we fall through to the
+  // ZIP strategy instead of stalling the whole test run.
+  if (wantDocker && (await dockerDaemonReachable())) {
     try {
       const handle = await tryTestcontainers();
       if (handle !== null) {
@@ -85,6 +89,10 @@ export default async function globalSetup(): Promise<(() => Promise<void>) | und
     } catch (err: unknown) {
       console.warn('[aws-adapter global-setup] testcontainers unavailable:', renderErr(err));
     }
+  } else if (wantDocker) {
+    console.warn(
+      '[aws-adapter global-setup] Docker daemon not reachable within probe window; skipping testcontainers.',
+    );
   }
 
   // Strategy 2: local ZIP + Java.
@@ -119,6 +127,25 @@ export default async function globalSetup(): Promise<(() => Promise<void>) | und
 // Strategy 1: testcontainers
 // ---------------------------------------------------------------------------
 
+/**
+ * Bounds the `docker info` probe. The Docker CLI on macOS waits silently for
+ * the daemon to start when Docker Desktop is installed but stopped, which
+ * would otherwise hang the entire global setup. Treat anything that doesn't
+ * return within `DOCKER_PROBE_MS` as "unavailable" and fall through to the
+ * ZIP strategy.
+ */
+const DOCKER_PROBE_MS = 5_000;
+
+async function dockerDaemonReachable(): Promise<boolean> {
+  if (which('docker') === null) return false;
+  try {
+    await execAsync('docker info', { timeout: DOCKER_PROBE_MS });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 async function tryTestcontainers(): Promise<DdbHandle | null> {
   let mod: typeof import('testcontainers') | undefined;
   try {

package/packages/aws-adapter/tests/gone-exception.test.ts

@@ -10,10 +10,10 @@
 
 import { GoneException } from '@aws-sdk/client-apigatewaymanagementapi';
 import { CreateTableCommand, DeleteTableCommand } from '@aws-sdk/client-dynamodb';
-import { PutCommand } from '@aws-sdk/lib-dynamodb';
+import { GetCommand, PutCommand } from '@aws-sdk/lib-dynamodb';
 import { type Nick, type ParsedServerConfig, createConnection } from '@serverless-ircd/irc-core';
 import { makeTestServerConfig } from '@serverless-ircd/irc-test-support';
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 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';
@@ -219,6 +219,25 @@ describe.skipIf(!available)('GoneException cleanup', () => {
     ).resolves.toBeUndefined();
   });
 
+  it('cleanupConnection reads the Connections row strongly consistently', async () => {
+    // $disconnect runs cleanupConnection immediately after the connection's
+    // own row was last written/updated. An eventually-consistent Get can miss
+    // that just-written row under replication lag and skip nick release +
+    // roster fanout. The Get MUST be strongly consistent.
+    await seedConnection(requireFx().client, requireFx().tables, 'cr', 'crnick', '#room');
+    const sendSpy = vi.spyOn(requireFx().client, 'send');
+    await cleanupConnection(requireFx().client, requireFx().tables, 'cr', null);
+    const conGets = sendSpy.mock.calls
+      .map((call) => call[0] as unknown)
+      .filter(
+        (cmd): cmd is GetCommand =>
+          cmd instanceof GetCommand && (cmd.input.TableName?.endsWith('Connections') ?? false),
+      );
+    expect(conGets.length).toBeGreaterThan(0);
+    expect((conGets[0]?.input as { ConsistentRead?: boolean }).ConsistentRead).toBe(true);
+    sendSpy.mockRestore();
+  });
+
   it('broadcast() skips and cleans up gone members', async () => {
     await seedConnection(requireFx().client, requireFx().tables, 'gone3', 'eve', '#room');
     const mgmt: PostToConnection = {