serverless-ircd 0.1.0 → 0.3.0

package/packages/aws-adapter/src/aws-runtime.ts

@@ -0,0 +1,871 @@
+/**
+ * AWS Lambda-flavoured {@link IrcRuntime}.
+ *
+ * Backed by DynamoDB (Connections / ChannelMeta / ChannelMembers / Nicks)
+ * for authoritative state and `ApiGatewayManagementApi` for cross-connection
+ * WebSocket fanout. Constructed fresh per `$default` Lambda invocation;
+ * cheap to build, no caching across events.
+ *
+ * Pattern mirrors `cf-adapter/src/cf-runtime.ts`:
+ *   - Calls whose target *is* the bound connection shortcut through the
+ *     injected {@link AwsRuntimeHandlers} — no APIGW round-trip.
+ *   - Cross-connection calls hit DynamoDB (the authoritative store).
+ *   - `send()` to a connection whose APIGW socket is gone catches
+ *     `GoneException` and triggers {@link cleanupConnection}.
+ *
+ * Membership atomicity: JOIN/PART/KICK run as a single
+ * `TransactWriteItems` spanning `ChannelMembers` and
+ * `Connections.joinedChannels` — the two cannot diverge even under
+ * concurrent `$default` invocations for the same connection. A
+ * `TransactionConflict` (concurrent item access) is retried with a
+ * small linear backoff; `ADD`/`DELETE` on the String Set is naturally
+ * idempotent so retries never duplicate state.
+ */
+
+import {
+  type ApiGatewayManagementApi,
+  GoneException,
+} from '@aws-sdk/client-apigatewaymanagementapi';
+import type { TransactWriteItem } from '@aws-sdk/client-dynamodb';
+import type { DynamoDBDocumentClient, NativeAttributeValue } from '@aws-sdk/lib-dynamodb';
+import {
+  DeleteCommand,
+  GetCommand,
+  PutCommand,
+  QueryCommand,
+  ScanCommand,
+  TransactWriteCommand,
+  UpdateCommand,
+} from '@aws-sdk/lib-dynamodb';
+import {
+  type ChanName,
+  type ChanSnapshot,
+  type ChannelDelta,
+  type ChannelModes,
+  type ChannelState,
+  type ChannelTopic,
+  type Clock,
+  type ConnId,
+  type ConnSnapshot,
+  type ConnectionState,
+  type Nick,
+  type RawLine,
+  type RosterEntry,
+  SystemClock,
+  emptyModes,
+  toSnapshot as toConnSnapshot,
+} from '@serverless-ircd/irc-core';
+import type { IrcRuntime } from '@serverless-ircd/irc-server';
+import {
+  type MarshalledChannelMember,
+  type MarshalledChannelMeta,
+  type MarshalledConnection,
+  type MarshalledNick,
+  marshalChannelMember,
+  marshalConnection,
+  marshalNick,
+  unmarshalChannelMember,
+  unmarshalChannelMeta,
+  unmarshalConnection,
+} from './serialize.js';
+import type { TablesConfig } from './tables.js';
+
+/**
+ * Per-connection transport callbacks the Lambda handler wires up. Mirrors
+ * {@link CfConnectionHandlers} in cf-adapter — same shape, same semantics.
+ *
+ *   - `send(lines)` writes already-framed bytes to the bound socket.
+ *     In a Lambda `$default` invocation this pushes into the handler's
+ *     `received[]` (the APIGW echo back to the caller). In tests this
+ *     is the in-memory `received` array.
+ *   - `disconnect(reason?)` closes the bound transport. In Lambda this
+ *     is a no-op — the canonical disconnect path is the APIGW `$disconnect`
+ *     route, which fires after the socket is already gone.
+ *   - `snapshot()` returns the in-memory ConnectionState the actor is
+ *     mutating this frame. Critical so `getConnection(boundId)` returns
+ *     the live view (and dispatch's reducer-observable effects see
+ *     mutations made earlier in the same frame).
+ */
+export interface AwsRuntimeHandlers {
+  send: (lines: RawLine[]) => void;
+  disconnect: (reason?: string) => void;
+  snapshot: () => ConnectionState | undefined;
+}
+
+/**
+ * Minimal port for pushing bytes to a remote WebSocket connection. Both
+ * `ApiGatewayManagementApi` and test doubles satisfy this structurally —
+ * aws-runtime does not care which it gets.
+ */
+export interface PostToConnection {
+  postToConnection(input: { ConnectionId: ConnId; Data: string }): Promise<unknown>;
+}
+
+/** Constructor options for {@link AwsRuntime}. */
+export interface AwsRuntimeOptions {
+  dynamo: DynamoDBDocumentClient;
+  tables: TablesConfig;
+  connId: ConnId;
+  handlers: AwsRuntimeHandlers;
+  /**
+   * Backend used by {@link send} for cross-connection fanout. May be:
+   *   - a real `ApiGatewayManagementApi` client (production),
+   *   - a test double that satisfies {@link PostToConnection} (integration
+   *     tests route to other actors' `received` arrays),
+   *   - `null` when no cross-connection send is ever needed (self-only
+   *     unit tests). `send` to a non-self connection is a silent no-op
+   *     in that mode — the caller is asserting on DynamoDB state only.
+   */
+  managementApi: ApiGatewayManagementApi | PostToConnection | null;
+  clock?: Clock;
+}
+
+/**
+ * AWS-flavoured {@link IrcRuntime} bound to one connection.
+ *
+ * Construct one per inbound Lambda event.
+ */
+export class AwsRuntime implements IrcRuntime {
+  private readonly dynamo: DynamoDBDocumentClient;
+  private readonly tables: TablesConfig;
+  private readonly connId: ConnId;
+  private readonly handlers: AwsRuntimeHandlers;
+  private readonly managementApi: ApiGatewayManagementApi | PostToConnection | null;
+  private readonly clock: Clock;
+
+  constructor(opts: AwsRuntimeOptions) {
+    this.dynamo = opts.dynamo;
+    this.tables = opts.tables;
+    this.connId = opts.connId;
+    this.handlers = opts.handlers;
+    this.managementApi = opts.managementApi;
+    this.clock = opts.clock ?? SystemClock;
+  }
+
+  // -------------------------------------------------------------------------
+  // Transport
+  // -------------------------------------------------------------------------
+
+  async send(to: ConnId, lines: RawLine[]): Promise<void> {
+    if (to === this.connId) {
+      // Self-send goes through the handler so the actor's mutations are
+      // visible within the same frame (no APIGW round-trip).
+      this.handlers.send(lines);
+      return;
+    }
+    if (this.managementApi === null) {
+      // Cross-connection send with no backend — silent no-op. The caller
+      // is asserting on DynamoDB state only (e.g. a Connections row was
+      // written, a nick was reserved). Production never hits this path.
+      return;
+    }
+    const data = lines.map((l) => l.text).join('\r\n');
+    try {
+      await this.managementApi.postToConnection({ ConnectionId: to, Data: data });
+    } catch (err: unknown) {
+      if (err instanceof GoneException || isGone(err)) {
+        await cleanupConnection(this.dynamo, this.tables, to, this.managementApi);
+        return;
+      }
+      throw err;
+    }
+  }
+
+  async broadcast(chan: ChanName, lines: RawLine[], except?: ConnId): Promise<void> {
+    const key = chan.toLowerCase();
+    const members = await this.queryMembers(key);
+    for (const entry of members) {
+      if (entry.connectionId === except) continue;
+      await this.send(entry.connectionId, lines);
+    }
+  }
+
+  async disconnect(conn: ConnId, reason?: string): Promise<void> {
+    if (conn === this.connId) {
+      this.handlers.disconnect(reason);
+      return;
+    }
+    // Cross-connection disconnect is a no-op in 040: the Lambda runtime
+    // cannot directly close another connection's WebSocket. The canonical
+    // disconnect path is the APIGW `$disconnect` route, which fires when
+    // the socket is already gone. KICK/PART remove membership rows but
+    // do not need to force-close the socket.
+  }
+
+  async sendToNick(
+    nick: Nick,
+    sender: ConnId,
+    lines: RawLine[],
+    notFoundLines?: RawLine[],
+  ): Promise<void> {
+    const owner = await this.lookupNick(nick);
+    if (owner !== null) {
+      await this.send(owner, lines);
+      return;
+    }
+    if (notFoundLines !== undefined) {
+      await this.send(sender, notFoundLines);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Nick registry
+  // -------------------------------------------------------------------------
+
+  async reserveNick(nick: Nick, conn: ConnId): Promise<{ ok: true } | { ok: false }> {
+    const row = marshalNick(nick, conn, this.clock.now());
+    try {
+      await this.dynamo.send(
+        new PutCommand({
+          TableName: this.tables.Nicks,
+          Item: row as unknown as Record<string, NativeAttributeValue>,
+          ConditionExpression: 'attribute_not_exists(nickLower)',
+        }),
+      );
+      return { ok: true };
+    } catch (err: unknown) {
+      if (isConditionalCheckFailed(err)) {
+        // Re-owning by the same conn is allowed — match the in-memory
+        // runtime's idempotent semantics so re-reservation doesn't fail.
+        const existing = await this.dynamo.send(
+          new GetCommand({ TableName: this.tables.Nicks, Key: { nickLower: nick.toLowerCase() } }),
+        );
+        if (existing.Item?.connectionId === conn) return { ok: true };
+        return { ok: false };
+      }
+      throw err;
+    }
+  }
+
+  async changeNick(conn: ConnId, oldNick: Nick, newNick: Nick): Promise<boolean> {
+    const reserved = await this.reserveNick(newNick, conn);
+    if (!reserved.ok) return false;
+    await this.releaseNick(oldNick);
+    return true;
+  }
+
+  async releaseNick(nick: Nick): Promise<void> {
+    try {
+      await this.dynamo.send(
+        new DeleteCommand({
+          TableName: this.tables.Nicks,
+          Key: { nickLower: nick.toLowerCase() },
+        }),
+      );
+    } catch (err: unknown) {
+      // Idempotent: ResourceNotFound is the only error we tolerate; the
+      // SDK v3 delete is already idempotent on missing rows, but defensive.
+      if (!isResourceNotFound(err)) throw err;
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Channel ownership
+  // -------------------------------------------------------------------------
+
+  async applyChannelDelta(chan: ChanName, delta: ChannelDelta): Promise<void> {
+    const key = chan.toLowerCase();
+    // Ensure a meta row exists so getChannelSnapshot can find the channel
+    // even when the delta only adds memberships (common JOIN case).
+    await this.ensureMetaRow(chan, key);
+    if (delta.memberships !== undefined && delta.memberships.length > 0) {
+      await this.applyMembershipTransaction(key, delta.memberships);
+    }
+    if (delta.modeChanges !== undefined && delta.modeChanges.length > 0) {
+      const baseModes = await this.readMetaModes(key);
+      const nextModes = applyModeChanges(baseModes ?? emptyModes(), delta.modeChanges);
+      await this.updateMetaModes(key, nextModes);
+    }
+    if (delta.banMaskChanges !== undefined && delta.banMaskChanges.length > 0) {
+      const existing = await this.readBanMasks(key);
+      const set = new Set(existing);
+      for (const b of delta.banMaskChanges) {
+        if (b.type === 'add') set.add(b.mask);
+        else set.delete(b.mask);
+      }
+      await this.updateBanMasks(key, set);
+    }
+    if (delta.topic !== undefined) {
+      await this.updateTopic(key, delta.topic);
+    }
+  }
+
+  // -------------------------------------------------------------------------
+  // Lookups
+  // -------------------------------------------------------------------------
+
+  async lookupNick(nick: Nick): Promise<ConnId | null> {
+    const result = await this.dynamo.send(
+      new GetCommand({ TableName: this.tables.Nicks, Key: { nickLower: nick.toLowerCase() } }),
+    );
+    if (result.Item === undefined) return null;
+    return (result.Item as unknown as MarshalledNick).connectionId;
+  }
+
+  async getConnectionInfo(conn: ConnId): Promise<ConnSnapshot | null> {
+    // Self-shortcut: the actor's mutations are visible to effects running
+    // in the same frame (cf-runtime mirrors this).
+    if (conn === this.connId) {
+      const live = this.handlers.snapshot();
+      return live === undefined ? null : toConnSnapshot(live);
+    }
+    const row = await this.readConnectionRow(conn);
+    if (row === null) return null;
+    return toConnSnapshot(unmarshalConnection(row));
+  }
+
+  async getConnection(conn: ConnId): Promise<ConnectionState | null> {
+    if (conn === this.connId) {
+      return this.handlers.snapshot() ?? null;
+    }
+    const row = await this.readConnectionRow(conn);
+    if (row === null) return null;
+    return unmarshalConnection(row);
+  }
+
+  async getChannelSnapshot(chan: ChanName): Promise<ChanSnapshot | null> {
+    const key = chan.toLowerCase();
+    const meta = await this.readMeta(key);
+    if (meta === null) return null;
+    const members = await this.queryMembers(key);
+    const chanState = unmarshalChannelMeta(
+      meta,
+      new Map(members.map((m) => [m.connectionId, unmarshalChannelMember(m)] as const)),
+    );
+    return chanStateToSnapshot(chanState);
+  }
+
+  async getChannelConnections(chan: ChanName): Promise<ReadonlyMap<ConnId, ConnectionState>> {
+    const key = chan.toLowerCase();
+    const members = await this.queryMembers(key);
+    const out = new Map<ConnId, ConnectionState>();
+    for (const m of members) {
+      const row = await this.readConnectionRow(m.connectionId);
+      if (row !== null) {
+        out.set(m.connectionId, unmarshalConnection(row));
+      }
+    }
+    return out;
+  }
+
+  async listChannels(): Promise<ChanSnapshot[]> {
+    const result = await this.dynamo.send(new ScanCommand({ TableName: this.tables.ChannelMeta }));
+    const items = (result.Items ?? []) as unknown as MarshalledChannelMeta[];
+    const out: ChanSnapshot[] = [];
+    for (const meta of items) {
+      const members = await this.queryMembers(meta.channelName);
+      const chanState = unmarshalChannelMeta(
+        meta,
+        new Map(members.map((m) => [m.connectionId, unmarshalChannelMember(m)] as const)),
+      );
+      out.push(chanStateToSnapshot(chanState));
+    }
+    return out;
+  }
+
+  // -------------------------------------------------------------------------
+  // Public helpers (re-exported surface)
+  // -------------------------------------------------------------------------
+
+  /**
+   * Persists the supplied {@link ConnectionState} as a Connections row,
+   * updating `idleSince` to `Date.now()` so the TTL stays fresh on
+   * every `$default` invocation.
+   */
+  async persistConnectionState(state: ConnectionState): Promise<void> {
+    const row = marshalConnection(state, this.clock.now());
+    await this.dynamo.send(
+      new PutCommand({
+        TableName: this.tables.Connections,
+        Item: row as unknown as Record<string, NativeAttributeValue>,
+      }),
+    );
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal — Connections
+  // -------------------------------------------------------------------------
+
+  private async readConnectionRow(conn: ConnId): Promise<MarshalledConnection | null> {
+    const result = await this.dynamo.send(
+      new GetCommand({
+        TableName: this.tables.Connections,
+        Key: { connectionId: conn },
+      }),
+    );
+    if (result.Item === undefined) return null;
+    return result.Item as unknown as MarshalledConnection;
+  }
+
+  // -------------------------------------------------------------------------
+  // Internal — Channels
+  // -------------------------------------------------------------------------
+
+  /**
+   * Atomically applies a batch of roster mutations for one channel.
+   * Each mutation produces:
+   *   - a `Put`/`Delete` on `ChannelMembers` (the authoritative roster), AND
+   *   - an `ADD`/`DELETE` on the owning connection's `joinedChannels` set.
+   *
+   * All items go into ONE `TransactWriteItems` so the two tables cannot
+   * diverge — even when two `$default` invocations for the same
+   * connection race (API Gateway may deliver a client's frames
+   * concurrently). ADD/DELETE on the String Set is idempotent, so the
+   * retry-on-conflict loop never doubles state.
+   *
+   * Per-connection updates are coalesced into a single `Update` item
+   * because DynamoDB rejects two transact items targeting the same key.
+   * Assumption: ≤ ~50 distinct connections per delta (DynamoDB caps
+   * TransactWriteItems at 100 items). Reducers today emit one membership
+   * per delta, so this is far below the ceiling.
+   */
+  private async applyMembershipTransaction(
+    key: string,
+    memberships: NonNullable<ChannelDelta['memberships']>,
+  ): Promise<void> {
+    const memberOps: Array<{ type: 'add'; entry: RosterEntry } | { type: 'remove'; conn: ConnId }> =
+      [];
+    const addsByConn = new Map<ConnId, Set<string>>();
+    const removesByConn = new Map<ConnId, Set<string>>();
+
+    for (const m of memberships) {
+      if (m.type === 'add') {
+        if (m.nick === undefined) continue;
+        const entry: RosterEntry = {
+          conn: m.conn,
+          nick: m.nick,
+          op: m.op ?? false,
+          voice: m.voice ?? false,
+        };
+        memberOps.push({ type: 'add', entry });
+        collectChannel(addsByConn, m.conn, key);
+      } else {
+        memberOps.push({ type: 'remove', conn: m.conn });
+        collectChannel(removesByConn, m.conn, key);
+      }
+    }
+
+    if (memberOps.length === 0) return;
+
+    const transactItems: TransactWriteItem[] = [];
+
+    for (const op of memberOps) {
+      if (op.type === 'add') {
+        transactItems.push({
+          Put: {
+            TableName: this.tables.ChannelMembers,
+            Item: marshalChannelMember(key, op.entry) as unknown as Record<
+              string,
+              NativeAttributeValue
+            >,
+          },
+        });
+      } else {
+        transactItems.push({
+          Delete: {
+            TableName: this.tables.ChannelMembers,
+            Key: {
+              channelName: key,
+              connectionId: op.conn,
+            } as unknown as Record<string, NativeAttributeValue>,
+          },
+        });
+      }
+    }
+
+    for (const [conn, chans] of addsByConn) {
+      transactItems.push({
+        Update: {
+          TableName: this.tables.Connections,
+          Key: { connectionId: conn } as unknown as Record<string, NativeAttributeValue>,
+          UpdateExpression: 'ADD joinedChannels :chans',
+          ExpressionAttributeValues: {
+            ':chans': chans as unknown as NativeAttributeValue,
+          },
+        },
+      });
+    }
+    for (const [conn, chans] of removesByConn) {
+      transactItems.push({
+        Update: {
+          TableName: this.tables.Connections,
+          Key: { connectionId: conn } as unknown as Record<string, NativeAttributeValue>,
+          UpdateExpression: 'DELETE joinedChannels :chans',
+          ExpressionAttributeValues: {
+            ':chans': chans as unknown as NativeAttributeValue,
+          },
+        },
+      });
+    }
+
+    await this.sendTransactWithRetry(transactItems);
+  }
+
+  /**
+   * Runs a `TransactWriteItems` with a bounded retry loop. Only
+   * `TransactionConflict` cancellations are retried (concurrent item
+   * access); condition/throughput failures rethrow immediately.
+   */
+  private async sendTransactWithRetry(items: TransactWriteItem[]): Promise<void> {
+    const MAX_ATTEMPTS = 6;
+    for (let attempt = 1; ; attempt++) {
+      try {
+        await this.dynamo.send(new TransactWriteCommand({ TransactItems: items }));
+        return;
+      } catch (err: unknown) {
+        if (isTransactionConflict(err) && attempt < MAX_ATTEMPTS) {
+          await sleep(RETRY_BACKOFF_BASE_MS * attempt);
+          continue;
+        }
+        throw err;
+      }
+    }
+  }
+
+  private async ensureMetaRow(displayName: ChanName, key: string): Promise<void> {
+    try {
+      await this.dynamo.send(
+        new PutCommand({
+          TableName: this.tables.ChannelMeta,
+          Item: {
+            channelName: key,
+            displayName,
+            modes: emptyModes(),
+            banMasks: [],
+            pendingInvites: [],
+            createdAt: this.clock.now(),
+          },
+          ConditionExpression: 'attribute_not_exists(channelName)',
+        }),
+      );
+    } catch (err: unknown) {
+      if (isConditionalCheckFailed(err)) return;
+      throw err;
+    }
+  }
+
+  private async readMeta(key: string): Promise<MarshalledChannelMeta | null> {
+    const result = await this.dynamo.send(
+      new GetCommand({ TableName: this.tables.ChannelMeta, Key: { channelName: key } }),
+    );
+    if (result.Item === undefined) return null;
+    return result.Item as unknown as MarshalledChannelMeta;
+  }
+
+  private async readMetaModes(key: string): Promise<ChannelModes | null> {
+    const meta = await this.readMeta(key);
+    return meta?.modes ?? null;
+  }
+
+  private async readBanMasks(key: string): Promise<string[]> {
+    const meta = await this.readMeta(key);
+    return meta?.banMasks ?? [];
+  }
+
+  private async updateMetaModes(key: string, modes: ChannelModes): Promise<void> {
+    await this.dynamo.send(
+      new UpdateCommand({
+        TableName: this.tables.ChannelMeta,
+        Key: { channelName: key },
+        UpdateExpression: 'SET modes = :m',
+        ExpressionAttributeValues: { ':m': modes },
+      }),
+    );
+  }
+
+  private async updateBanMasks(key: string, masks: Set<string>): Promise<void> {
+    await this.dynamo.send(
+      new UpdateCommand({
+        TableName: this.tables.ChannelMeta,
+        Key: { channelName: key },
+        UpdateExpression: 'SET banMasks = :b',
+        ExpressionAttributeValues: { ':b': [...masks] },
+      }),
+    );
+  }
+
+  private async updateTopic(key: string, topic: ChannelTopic | null): Promise<void> {
+    if (topic === null) {
+      await this.dynamo.send(
+        new UpdateCommand({
+          TableName: this.tables.ChannelMeta,
+          Key: { channelName: key },
+          UpdateExpression: 'REMOVE topicText, topicSetter, topicSetAt',
+        }),
+      );
+      return;
+    }
+    await this.dynamo.send(
+      new UpdateCommand({
+        TableName: this.tables.ChannelMeta,
+        Key: { channelName: key },
+        UpdateExpression: 'SET topicText = :t, topicSetter = :s, topicSetAt = :a',
+        ExpressionAttributeValues: {
+          ':t': topic.text,
+          ':s': topic.setter,
+          ':a': topic.setAt,
+        },
+      }),
+    );
+  }
+
+  private async queryMembers(key: string): Promise<MarshalledChannelMember[]> {
+    const result = await this.dynamo.send(
+      new QueryCommand({
+        TableName: this.tables.ChannelMembers,
+        KeyConditionExpression: 'channelName = :k',
+        ExpressionAttributeValues: { ':k': key },
+      }),
+    );
+    return (result.Items ?? []) as unknown as MarshalledChannelMember[];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// cleanupConnection — re-exported via index.ts and called from $disconnect
+// ---------------------------------------------------------------------------
+
+/**
+ * Tears down a connection: deletes its Connections row, removes every
+ * ChannelMembers row owned by it, releases its nick (if any), and — when
+ * a `managementApi` is supplied — broadcasts a `QUIT` line to every peer
+ * that shares a channel with the disconnecting connection.
+ *
+ * Idempotent: every step tolerates a missing row. Safe to call from
+ * `$disconnect`, from the `send`/`broadcast` `GoneException` path, and
+ * from the sweeper Lambda.
+ *
+ * Recursion safety: the Connections row is deleted *before* the QUIT
+ * fanout so a recursive `cleanupConnection` triggered by a gone peer
+ * during fanout finds the row already gone and returns immediately —
+ * no unbounded recursion.
+ *
+ * `managementApi` is optional because callers that never need fanout
+ * (the sweeper Lambda, or a no-op test) may pass `null`.
+ */
+export async function cleanupConnection(
+  dynamo: DynamoDBDocumentClient,
+  tables: TablesConfig,
+  connId: ConnId,
+  managementApi: ApiGatewayManagementApi | PostToConnection | null,
+  quitMessage = 'Client Quit',
+): Promise<void> {
+  const connRow = await dynamo.send(
+    new GetCommand({ TableName: tables.Connections, Key: { connectionId: connId } }),
+  );
+  const item = connRow.Item as unknown as MarshalledConnection | undefined;
+  if (item === undefined) return; // idempotent — already cleaned up
+
+  // Delete the Connections row FIRST. A recursive cleanup triggered by
+  // a gone peer during QUIT fanout reads this same row, finds it gone,
+  // and returns — bounding the recursion at one extra hop.
+  await dynamo.send(
+    new DeleteCommand({ TableName: tables.Connections, Key: { connectionId: connId } }),
+  );
+
+  if (item.nick !== undefined) {
+    try {
+      await dynamo.send(
+        new DeleteCommand({
+          TableName: tables.Nicks,
+          Key: { nickLower: item.nick.toLowerCase() },
+        }),
+      );
+    } catch {
+      // Idempotent — the nick may have been released already.
+    }
+  }
+
+  // Broadcast QUIT to peers in shared channels *before* removing the
+  // disconnecting connection's membership rows — the roster query needs
+  // those rows to resolve the fanout targets.
+  if (item.nick !== undefined && managementApi !== null) {
+    await broadcastQuitToChannels(dynamo, tables, connId, item, managementApi, quitMessage);
+  }
+
+  const joined = item.joinedChannels ?? [];
+  for (const chan of joined) {
+    try {
+      await dynamo.send(
+        new DeleteCommand({
+          TableName: tables.ChannelMembers,
+          Key: { channelName: chan.toLowerCase(), connectionId: connId },
+        }),
+      );
+    } catch {
+      // Idempotent — the membership may have been removed already.
+    }
+  }
+}
+
+/**
+ * Builds the canonical `:nick!user@host QUIT :<reason>` line for the
+ * disconnecting connection and fans it out to every *other* member of
+ * each channel the connection had joined. A peer whose APIGW socket is
+ * already gone raises `GoneException`, which is caught and routed back
+ * through {@link cleanupConnection} for lazy cleanup — a partially
+ * torn-down roster never crashes the fanout loop.
+ *
+ * Shared by both the `$disconnect` route and the `send()`/`broadcast()`
+ * `GoneException` cleanup path.
+ */
+async function broadcastQuitToChannels(
+  dynamo: DynamoDBDocumentClient,
+  tables: TablesConfig,
+  connId: ConnId,
+  item: MarshalledConnection,
+  managementApi: ApiGatewayManagementApi | PostToConnection,
+  quitMessage: string,
+): Promise<void> {
+  const hostmask = buildHostmask(item);
+  if (hostmask === undefined) return; // no nick → nothing to attribute the QUIT to
+  const line = `:${hostmask} QUIT :${quitMessage}`;
+  const joined = item.joinedChannels ?? [];
+  for (const chan of joined) {
+    const members = await queryChannelMembersRows(dynamo, tables, chan.toLowerCase());
+    for (const member of members) {
+      if (member.connectionId === connId) continue; // never echo to self
+      try {
+        await managementApi.postToConnection({ ConnectionId: member.connectionId, Data: line });
+      } catch (err: unknown) {
+        if (err instanceof GoneException || isGone(err)) {
+          await cleanupConnection(dynamo, tables, member.connectionId, managementApi, quitMessage);
+        } else {
+          throw err;
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Builds the `nick!user@host` hostmask from a stored connection row,
+ * omitting the absent parts. Mirrors {@link hostmaskOf} in irc-core but
+ * operates on the marshalled shape (no full unmarshal needed).
+ */
+function buildHostmask(item: MarshalledConnection): string | undefined {
+  if (item.nick === undefined) return undefined;
+  let out: string = item.nick;
+  if (item.user !== undefined) out = `${out}!${item.user}`;
+  if (item.host !== undefined) out = `${out}@${item.host}`;
+  return out;
+}
+
+/** Queries the raw `ChannelMembers` rows for one channel (by lowercased key). */
+async function queryChannelMembersRows(
+  dynamo: DynamoDBDocumentClient,
+  tables: TablesConfig,
+  key: string,
+): Promise<MarshalledChannelMember[]> {
+  const result = await dynamo.send(
+    new QueryCommand({
+      TableName: tables.ChannelMembers,
+      KeyConditionExpression: 'channelName = :k',
+      ExpressionAttributeValues: { ':k': key },
+    }),
+  );
+  return (result.Items ?? []) as unknown as MarshalledChannelMember[];
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/** Base backoff (ms) for `TransactWriteItems` conflict retries — linear. */
+const RETRY_BACKOFF_BASE_MS = 5;
+
+/** Adds `chan` to the per-connection channel set, creating it if missing. */
+function collectChannel(map: Map<ConnId, Set<string>>, conn: ConnId, chan: string): void {
+  const set = map.get(conn) ?? new Set<string>();
+  set.add(chan);
+  map.set(conn, set);
+}
+
+/** Resolves after `ms` milliseconds — used by the transact retry loop. */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * True iff the SDK error is a `TransactionCanceledException` whose
+ * cancellation reasons include a `TransactionConflict` (concurrent
+ * item access). Condition-check and validation failures return false
+ * so the caller rethrows instead of retrying pointlessly.
+ */
+function isTransactionConflict(err: unknown): boolean {
+  if (err === null || typeof err !== 'object') return false;
+  const e = err as { name?: string; CancellationReasons?: Array<{ Code?: string }> };
+  if (e.name !== 'TransactionCanceledException') return false;
+  const reasons = e.CancellationReasons ?? [];
+  return reasons.some((r) => r?.Code === 'TransactionConflict');
+}
+
+/** Applies a sequence of `ModeChange` to a `ChannelModes` (mutates in place). */
+function applyModeChanges(modes: ChannelModes, changes: ChannelDelta['modeChanges']): ChannelModes {
+  if (changes === undefined) return modes;
+  for (const change of changes) {
+    switch (change.mode) {
+      case 'inviteOnly':
+      case 'topicLock':
+      case 'noExternal':
+      case 'moderated':
+      case 'secret':
+      case 'private':
+        modes[change.mode] = change.set;
+        break;
+      case 'key':
+        if (change.set) {
+          if (typeof change.arg === 'string') modes.key = change.arg;
+        } else {
+          // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
+          delete modes.key;
+        }
+        break;
+      case 'limit':
+        if (change.set) {
+          if (typeof change.arg === 'number') modes.limit = change.arg;
+        } else {
+          // biome-ignore lint/performance/noDelete: exactOptionalPropertyTypes forbids `= undefined`.
+          delete modes.limit;
+        }
+        break;
+    }
+  }
+  return modes;
+}
+
+/** ChannelState → ChanSnapshot (mirrors irc-core's `toSnapshot`). */
+function chanStateToSnapshot(chan: ChannelState): ChanSnapshot {
+  const out: ChanSnapshot = {
+    name: chan.name,
+    nameLower: chan.nameLower,
+    modes: chan.modes,
+    banMasks: chan.banMasks,
+    members: chan.members,
+    pendingInvites: chan.pendingInvites,
+    createdAt: chan.createdAt,
+    ...(chan.topic !== undefined ? { topic: chan.topic } : {}),
+  };
+  return out;
+}
+
+/** True iff the SDK error is a `ConditionalCheckFailedException`. */
+function isConditionalCheckFailed(err: unknown): boolean {
+  if (err === null || typeof err !== 'object') return false;
+  const name = (err as { name?: string }).name;
+  return name === 'ConditionalCheckFailedException';
+}
+
+/** True iff the SDK error is a `ResourceNotFoundException`. */
+function isResourceNotFound(err: unknown): boolean {
+  if (err === null || typeof err !== 'object') return false;
+  const name = (err as { name?: string }).name;
+  return name === 'ResourceNotFoundException';
+}
+
+/** True iff the SDK error indicates the APIGW connection is gone. */
+function isGone(err: unknown): boolean {
+  if (err === null || typeof err !== 'object') return false;
+  const name = (err as { name?: string }).name;
+  return name === 'GoneException' || name === 'ForbiddenException';
+}