serverless-ircd 0.7.0 → 0.9.0

package/packages/aws-adapter/src/dynamo-services-store.ts

@@ -0,0 +1,649 @@
+/**
+ * DynamoDB-backed {@link PersistentServicesStore} for the AWS adapter.
+ *
+ * All nine services sections share a single `Services` table via a
+ * single-table key scheme:
+ *
+ *   - NickServ:   `NICK:<fold>` / `#`
+ *   - ChanServ channel meta:  `CHAN:<fold>` / `#META`
+ *   - ChanServ access:        `CHAN:<fold>` / `ACC:<foldAcct>`   (same partition as the channel)
+ *   - ChanServ levels:        `CHAN:<fold>` / `LVL:<op>`        (same partition as the channel)
+ *   - HostServ:   `VH:<fold>` / `#`
+ *   - HostServ pending: `PV:<fold>` / `#`
+ *   - MemoServ:   `MEMO:<id>` / `#`  (id is globally monotonic)
+ *   - read-marker:`RM:<foldAcct>` / `<foldChan>`
+ *   - OperServ AKILL: `AK:<foldMask>` / `#`
+ *   - OperServ JUPE:  `JP:<foldName>` / `#`
+ *
+ * Co-locating a channel's meta + access + levels on one partition lets
+ * `deleteChannel` / `resetChannelLevels` fan out as a single partition
+ * `Query` + `BatchWriteItem` instead of a per-row scan.
+ *
+ * Each item carries a `type` discriminator so the boot `Scan` can dispatch
+ * a row to the right snapshot section without parsing the key. Display
+ * spelling is preserved alongside the folded key so the wire renders the
+ * user's preferred casing after a reload.
+ */
+
+import {
+  BatchWriteCommand,
+  type BatchWriteCommandInput,
+  QueryCommand,
+  ScanCommand,
+  UpdateCommand,
+} from '@aws-sdk/lib-dynamodb';
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import {
+  type AkillEntry,
+  type ChannelAccessLevel,
+  type ChannelLevelOp,
+  type Clock,
+  type JupeEntry,
+  type MemoEntry,
+  type NickEnforcePolicy,
+  type PersistedTopic,
+  PersistentServicesStore,
+  type RegisteredChannel,
+  type ServicesAccessRow,
+  type ServicesLevelRow,
+  type ServicesNickRow,
+  type ServicesPendingVhostRow,
+  type ServicesSnapshot,
+  type ServicesVhostRow,
+  type ServicesWrite,
+  SystemClock,
+  caseFold,
+} from '@serverless-ircd/irc-core';
+
+/** rfc1459 case-fold used for every storage key. */
+function fold(value: string): string {
+  return caseFold('rfc1459', value);
+}
+
+const SINGLE_SK = '#';
+const CHANNEL_META_SK = '#META';
+const ACCESS_SK_PREFIX = 'ACC:';
+const LEVEL_SK_PREFIX = 'LVL:';
+
+/** Partition-key builders per section. */
+const nickPk = (nick: string): string => `NICK:${fold(nick)}`;
+const channelPk = (channel: string): string => `CHAN:${fold(channel)}`;
+const vhostPk = (account: string): string => `VH:${fold(account)}`;
+const pendingVhostPk = (account: string): string => `PV:${fold(account)}`;
+const memoPk = (id: number): string => `MEMO:${id}`;
+const readMarkerPk = (account: string): string => `RM:${fold(account)}`;
+const akillPk = (mask: string): string => `AK:${fold(mask)}`;
+const jupePk = (name: string): string => `JP:${fold(name)}`;
+
+/**
+ * DynamoDB-backed persistent services store. Extends the shared
+ * {@link PersistentServicesStore} write-behind base; the cache is hydrated
+ * from the snapshot loaded by {@link loadDynamoServicesStore} at
+ * construction.
+ *
+ * `applyWrites` translates each {@link ServicesWrite} into one (or more)
+ * `PutRequest` / `DeleteRequest` entries and runs them through
+ * `BatchWriteItem` (25 per request). `deleteChannel` / `resetChannelLevels`
+ * run a partition `Query` first to collect the keys to delete.
+ * `updateMemoRead` is a single-item `UpdateCommand` (it does not carry the
+ * full memo row, only the id).
+ */
+export class DynamoServicesStore extends PersistentServicesStore {
+  private readonly docClient: DynamoDBDocumentClient;
+  private readonly tableName: string;
+
+  constructor(opts: {
+    docClient: DynamoDBDocumentClient;
+    tableName: string;
+    clock?: Clock;
+    snapshot?: ServicesSnapshot;
+  }) {
+    const superOpts: { clock?: Clock; snapshot?: ServicesSnapshot } = {};
+    if (opts.clock !== undefined) superOpts.clock = opts.clock;
+    if (opts.snapshot !== undefined) superOpts.snapshot = opts.snapshot;
+    super(superOpts);
+    this.docClient = opts.docClient;
+    this.tableName = opts.tableName;
+  }
+
+  protected async applyWrites(writes: ServicesWrite[]): Promise<void> {
+    const batch: Array<
+      | { PutRequest: { Item: Record<string, unknown> } }
+      | { DeleteRequest: { Key: Record<string, unknown> } }
+    > = [];
+    for (const w of writes) {
+      switch (w.kind) {
+        case 'upsertNick':
+          batch.push({ PutRequest: { Item: this.nickItem(w.row) } });
+          break;
+        case 'deleteNick':
+          batch.push({ DeleteRequest: { Key: { pk: nickPk(w.nick), sk: SINGLE_SK } } });
+          break;
+        case 'upsertChannel':
+          batch.push({ PutRequest: { Item: this.channelItem(w.row) } });
+          break;
+        case 'deleteChannel': {
+          const keys = await this.queryChannelKeys(w.channel, undefined);
+          for (const key of keys) batch.push({ DeleteRequest: { Key: key } });
+          break;
+        }
+        case 'upsertChannelAccess':
+          batch.push({ PutRequest: { Item: this.accessItem(w.row) } });
+          break;
+        case 'deleteChannelAccess':
+          batch.push({
+            DeleteRequest: {
+              Key: { pk: channelPk(w.channel), sk: `${ACCESS_SK_PREFIX}${fold(w.account)}` },
+            },
+          });
+          break;
+        case 'upsertChannelLevel':
+          batch.push({ PutRequest: { Item: this.levelItem(w.row) } });
+          break;
+        case 'resetChannelLevels': {
+          const keys = await this.queryChannelKeys(w.channel, LEVEL_SK_PREFIX);
+          for (const key of keys) batch.push({ DeleteRequest: { Key: key } });
+          break;
+        }
+        case 'upsertVhost':
+          batch.push({ PutRequest: { Item: this.vhostItem(w.row) } });
+          break;
+        case 'deleteVhost':
+          batch.push({ DeleteRequest: { Key: { pk: vhostPk(w.account), sk: SINGLE_SK } } });
+          break;
+        case 'upsertPendingVhost':
+          batch.push({ PutRequest: { Item: this.pendingVhostItem(w.row) } });
+          break;
+        case 'deletePendingVhost':
+          batch.push({ DeleteRequest: { Key: { pk: pendingVhostPk(w.account), sk: SINGLE_SK } } });
+          break;
+        case 'insertMemo':
+          batch.push({ PutRequest: { Item: this.memoItem(w.row) } });
+          break;
+        case 'updateMemoRead':
+          await this.updateMemoRead(w.id);
+          break;
+        case 'deleteMemo':
+          batch.push({ DeleteRequest: { Key: { pk: memoPk(w.id), sk: SINGLE_SK } } });
+          break;
+        case 'upsertReadMarker':
+          batch.push({ PutRequest: { Item: this.readMarkerItem(w.row) } });
+          break;
+        case 'upsertAkill':
+          batch.push({ PutRequest: { Item: this.akillItem(w.row) } });
+          break;
+        case 'deleteAkill':
+          batch.push({ DeleteRequest: { Key: { pk: akillPk(w.mask), sk: SINGLE_SK } } });
+          break;
+        case 'upsertJupe':
+          batch.push({ PutRequest: { Item: this.jupeItem(w.row) } });
+          break;
+        case 'deleteJupe':
+          batch.push({ DeleteRequest: { Key: { pk: jupePk(w.name), sk: SINGLE_SK } } });
+          break;
+      }
+    }
+    await this.batchWrite(batch);
+  }
+
+  // ----- item builders -----
+
+  private nickItem(row: ServicesNickRow): Record<string, unknown> {
+    return {
+      pk: nickPk(row.nick),
+      sk: SINGLE_SK,
+      type: 'nick',
+      nick: row.nick,
+      account: row.account,
+      email: row.email,
+      createdAt: row.createdAt,
+      enforce: row.enforce,
+      algorithm: row.credential.algorithm,
+      salt: row.credential.salt,
+      hash: row.credential.hash,
+    };
+  }
+
+  private channelItem(row: RegisteredChannel): Record<string, unknown> {
+    const item: Record<string, unknown> = {
+      pk: channelPk(row.channel),
+      sk: CHANNEL_META_SK,
+      type: 'channel',
+      channel: row.channel,
+      founder: row.founder,
+      createdAt: row.createdAt,
+      mlock: row.mlock,
+      restricted: row.restricted,
+      keepTopic: row.keepTopic,
+    };
+    if (row.topic !== undefined) {
+      item.topicText = row.topic.text;
+      item.topicSetter = row.topic.setter;
+      item.topicSetAt = row.topic.setAt;
+    }
+    return item;
+  }
+
+  private accessItem(row: ServicesAccessRow): Record<string, unknown> {
+    return {
+      pk: channelPk(row.channel),
+      sk: `${ACCESS_SK_PREFIX}${fold(row.account)}`,
+      type: 'chanaccess',
+      channel: row.channel,
+      account: row.account,
+      level: row.level,
+    };
+  }
+
+  private levelItem(row: ServicesLevelRow): Record<string, unknown> {
+    return {
+      pk: channelPk(row.channel),
+      sk: `${LEVEL_SK_PREFIX}${row.op}`,
+      type: 'chanlevel',
+      channel: row.channel,
+      op: row.op,
+      level: row.level,
+    };
+  }
+
+  private vhostItem(row: ServicesVhostRow): Record<string, unknown> {
+    return {
+      pk: vhostPk(row.account),
+      sk: SINGLE_SK,
+      type: 'vhost',
+      account: row.account,
+      vhost: row.vhost,
+    };
+  }
+
+  private pendingVhostItem(row: ServicesPendingVhostRow): Record<string, unknown> {
+    return {
+      pk: pendingVhostPk(row.account),
+      sk: SINGLE_SK,
+      type: 'pendingvhost',
+      account: row.account,
+      vhost: row.vhost,
+    };
+  }
+
+  private memoItem(row: MemoEntry): Record<string, unknown> {
+    return {
+      pk: memoPk(row.id),
+      sk: SINGLE_SK,
+      type: 'memo',
+      id: row.id,
+      from: row.from,
+      to: row.to,
+      body: row.body,
+      sentAt: row.sentAt,
+      read: row.read,
+    };
+  }
+
+  private readMarkerItem(row: { account: string; channel: string; msgid: string }): Record<
+    string,
+    unknown
+  > {
+    return {
+      pk: readMarkerPk(row.account),
+      sk: fold(row.channel),
+      type: 'readmarker',
+      account: row.account,
+      channel: row.channel,
+      msgid: row.msgid,
+    };
+  }
+
+  private akillItem(row: AkillEntry): Record<string, unknown> {
+    return {
+      pk: akillPk(row.mask),
+      sk: SINGLE_SK,
+      type: 'akill',
+      mask: row.mask,
+      reason: row.reason,
+      createdAt: row.createdAt,
+    };
+  }
+
+  private jupeItem(row: JupeEntry): Record<string, unknown> {
+    return {
+      pk: jupePk(row.name),
+      sk: SINGLE_SK,
+      type: 'jupe',
+      name: row.name,
+      reason: row.reason,
+      createdAt: row.createdAt,
+    };
+  }
+
+  // ----- write helpers -----
+
+  /**
+   * Queries the channel partition (`CHAN:<fold>`). When `skPrefix` is
+   * supplied, restricts to sort keys beginning with it (used by
+   * `resetChannelLevels` → `LVL:`). Returns the `(pk, sk)` pairs so the
+   * caller can build `DeleteRequest` entries without re-deriving the keys.
+   */
+  private async queryChannelKeys(
+    channel: string,
+    skPrefix: string | undefined,
+  ): Promise<Array<{ pk: string; sk: string }>> {
+    const pk = channelPk(channel);
+    const names = { '#pk': 'pk', '#sk': 'sk' };
+    const cmd =
+      skPrefix === undefined
+        ? new QueryCommand({
+            TableName: this.tableName,
+            KeyConditionExpression: '#pk = :pk',
+            ExpressionAttributeNames: names,
+            ExpressionAttributeValues: { ':pk': pk },
+            ProjectionExpression: '#pk, #sk',
+          })
+        : new QueryCommand({
+            TableName: this.tableName,
+            KeyConditionExpression: '#pk = :pk AND begins_with(#sk, :prefix)',
+            ExpressionAttributeNames: names,
+            ExpressionAttributeValues: { ':pk': pk, ':prefix': skPrefix },
+            ProjectionExpression: '#pk, #sk',
+          });
+    const out: Array<{ pk: string; sk: string }> = [];
+    const result = await this.docClient.send(cmd);
+    for (const item of result.Items ?? []) {
+      const p = item.pk;
+      const s = item.sk;
+      if (typeof p === 'string' && typeof s === 'string') out.push({ pk: p, sk: s });
+    }
+    return out;
+  }
+
+  private async updateMemoRead(id: number): Promise<void> {
+    await this.docClient.send(
+      new UpdateCommand({
+        TableName: this.tableName,
+        Key: { pk: memoPk(id), sk: SINGLE_SK },
+        UpdateExpression: 'SET #r = :r',
+        ExpressionAttributeNames: { '#r': 'read' },
+        ExpressionAttributeValues: { ':r': true },
+      }),
+    );
+  }
+
+  /**
+   * Drains the accumulated put/delete requests through `BatchWriteItem`
+   * (25 items per request, the DynamoDB per-batch cap). No-op when the
+   * flush produced only `updateMemoRead` ops (handled inline above).
+   */
+  private async batchWrite(
+    requests: Array<
+      | { PutRequest: { Item: Record<string, unknown> } }
+      | { DeleteRequest: { Key: Record<string, unknown> } }
+    >,
+  ): Promise<void> {
+    for (let i = 0; i < requests.length; i += 25) {
+      const chunk = requests.slice(i, i + 25);
+      const input: BatchWriteCommandInput = {
+        RequestItems: { [this.tableName]: chunk },
+      };
+      await this.docClient.send(new BatchWriteCommand(input));
+    }
+  }
+}
+
+/**
+ * Scans the `Services` table into a {@link ServicesSnapshot}, paginating
+ * through `LastEvaluatedKey` so tables larger than the 1 MB scan page are
+ * fully loaded. Items with an unknown `type` or missing/ill-typed fields
+ * are silently skipped (defensive against schema drift).
+ */
+async function scanSnapshot(
+  docClient: DynamoDBDocumentClient,
+  tableName: string,
+): Promise<ServicesSnapshot> {
+  const snap: ServicesSnapshot = {
+    nicks: [],
+    channels: [],
+    access: [],
+    levels: [],
+    vhosts: [],
+    pendingVhosts: [],
+    memos: [],
+    readMarkers: [],
+    akills: [],
+    jupes: [],
+  };
+  let exclusiveStartKey: Record<string, unknown> | undefined;
+  do {
+    const result = await docClient.send(
+      new ScanCommand({ TableName: tableName, ExclusiveStartKey: exclusiveStartKey }),
+    );
+    for (const item of result.Items ?? []) {
+      dispatchItem(item, snap);
+    }
+    exclusiveStartKey = result.LastEvaluatedKey;
+  } while (exclusiveStartKey !== undefined);
+  return snap;
+}
+
+/**
+ * Routes a scanned item into the right snapshot section based on its
+ * `type` discriminator, coercing fields defensively. Mutates `snap` in
+ * place; unknown types are skipped.
+ */
+function dispatchItem(item: Record<string, unknown>, snap: ServicesSnapshot): void {
+  const type = item.type;
+  if (typeof type !== 'string') return;
+  switch (type) {
+    case 'nick': {
+      const row = coerceNick(item);
+      if (row !== undefined) snap.nicks.push(row);
+      return;
+    }
+    case 'channel': {
+      const row = coerceChannel(item);
+      if (row !== undefined) snap.channels.push(row);
+      return;
+    }
+    case 'chanaccess': {
+      if (
+        typeof item.channel === 'string' &&
+        typeof item.account === 'string' &&
+        typeof item.level === 'number'
+      ) {
+        snap.access.push({
+          channel: item.channel,
+          account: item.account,
+          level: item.level as ChannelAccessLevel,
+        });
+      }
+      return;
+    }
+    case 'chanlevel': {
+      if (
+        typeof item.channel === 'string' &&
+        typeof item.op === 'string' &&
+        typeof item.level === 'number'
+      ) {
+        snap.levels.push({
+          channel: item.channel,
+          op: item.op as ChannelLevelOp,
+          level: item.level,
+        });
+      }
+      return;
+    }
+    case 'vhost': {
+      if (typeof item.account === 'string' && typeof item.vhost === 'string') {
+        snap.vhosts.push({ account: item.account, vhost: item.vhost });
+      }
+      return;
+    }
+    case 'pendingvhost': {
+      if (typeof item.account === 'string' && typeof item.vhost === 'string') {
+        snap.pendingVhosts.push({ account: item.account, vhost: item.vhost });
+      }
+      return;
+    }
+    case 'memo': {
+      const memo = coerceMemo(item);
+      if (memo !== undefined) snap.memos.push(memo);
+      return;
+    }
+    case 'readmarker': {
+      if (
+        typeof item.account === 'string' &&
+        typeof item.channel === 'string' &&
+        typeof item.msgid === 'string'
+      ) {
+        snap.readMarkers.push({ account: item.account, channel: item.channel, msgid: item.msgid });
+      }
+      return;
+    }
+    case 'akill': {
+      if (
+        typeof item.mask === 'string' &&
+        typeof item.reason === 'string' &&
+        typeof item.createdAt === 'number'
+      ) {
+        snap.akills.push({ mask: item.mask, reason: item.reason, createdAt: item.createdAt });
+      }
+      return;
+    }
+    case 'jupe': {
+      if (
+        typeof item.name === 'string' &&
+        typeof item.reason === 'string' &&
+        typeof item.createdAt === 'number'
+      ) {
+        snap.jupes.push({ name: item.name, reason: item.reason, createdAt: item.createdAt });
+      }
+      return;
+    }
+    default:
+      return;
+  }
+}
+
+function coerceNick(item: Record<string, unknown>): ServicesNickRow | undefined {
+  if (
+    typeof item.nick !== 'string' ||
+    typeof item.account !== 'string' ||
+    typeof item.email !== 'string' ||
+    typeof item.createdAt !== 'number' ||
+    typeof item.enforce !== 'string' ||
+    typeof item.algorithm !== 'string' ||
+    typeof item.salt !== 'string' ||
+    typeof item.hash !== 'string'
+  ) {
+    return undefined;
+  }
+  return {
+    nick: item.nick,
+    account: item.account,
+    email: item.email,
+    createdAt: item.createdAt,
+    enforce: item.enforce as NickEnforcePolicy,
+    credential: {
+      account: item.account,
+      algorithm: 'scrypt',
+      salt: item.salt,
+      hash: item.hash,
+    },
+  };
+}
+
+function coerceChannel(item: Record<string, unknown>): RegisteredChannel | undefined {
+  if (
+    typeof item.channel !== 'string' ||
+    typeof item.founder !== 'string' ||
+    typeof item.createdAt !== 'number' ||
+    typeof item.mlock !== 'string' ||
+    typeof item.restricted !== 'boolean' ||
+    typeof item.keepTopic !== 'boolean'
+  ) {
+    return undefined;
+  }
+  const channel: RegisteredChannel = {
+    channel: item.channel,
+    founder: item.founder,
+    createdAt: item.createdAt,
+    mlock: item.mlock,
+    restricted: item.restricted,
+    keepTopic: item.keepTopic,
+  };
+  if (
+    typeof item.topicText === 'string' &&
+    typeof item.topicSetter === 'string' &&
+    typeof item.topicSetAt === 'number'
+  ) {
+    const topic: PersistedTopic = {
+      text: item.topicText,
+      setter: item.topicSetter,
+      setAt: item.topicSetAt,
+    };
+    channel.topic = topic;
+  }
+  return channel;
+}
+
+function coerceMemo(item: Record<string, unknown>): MemoEntry | undefined {
+  if (
+    typeof item.id !== 'number' ||
+    typeof item.from !== 'string' ||
+    typeof item.to !== 'string' ||
+    typeof item.body !== 'string' ||
+    typeof item.sentAt !== 'number' ||
+    typeof item.read !== 'boolean'
+  ) {
+    return undefined;
+  }
+  return {
+    id: item.id,
+    from: item.from,
+    to: item.to,
+    body: item.body,
+    sentAt: item.sentAt,
+    read: item.read,
+  };
+}
+
+/**
+ * Loads the full services snapshot from the `Services` table and returns a
+ * hydrated {@link DynamoServicesStore}. Returns `undefined` when the
+ * physical table name is absent (services not configured for this deploy).
+ *
+ * Scan failures are swallowed into an empty snapshot so the store can still
+ * mutate + flush — the deployer is responsible for provisioning the table
+ * (via {@link TABLE_DEFS}); a flush against a missing table surfaces the
+ * DynamoDB error to the caller.
+ *
+ * @param docClient DynamoDB client addressed at the deployment's tables.
+ * @param tableName Physical name of the `Services` table (`undefined` when
+ *   `SERVICES_TABLE` is unset → services unbound).
+ * @param clock     Optional injected clock (tests pass a `FakeClock`;
+ *   production leaves it at {@link SystemClock}).
+ */
+export async function loadDynamoServicesStore(
+  docClient: DynamoDBDocumentClient,
+  tableName: string | undefined,
+  clock: Clock = SystemClock,
+): Promise<DynamoServicesStore | undefined> {
+  if (tableName === undefined) return undefined;
+  let snapshot: ServicesSnapshot;
+  try {
+    snapshot = await scanSnapshot(docClient, tableName);
+  } catch {
+    snapshot = {
+      nicks: [],
+      channels: [],
+      access: [],
+      levels: [],
+      vhosts: [],
+      pendingVhosts: [],
+      memos: [],
+      readMarkers: [],
+      akills: [],
+      jupes: [],
+    };
+  }
+  return new DynamoServicesStore({ docClient, tableName, clock, snapshot });
+}