serverless-ircd 0.1.0 → 0.2.0

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

@@ -0,0 +1,283 @@
+/**
+ * Marshal / unmarshal helpers between irc-core state objects and the
+ * DynamoDB NativeAttributeMap shapes (`@aws-sdk/util-dynamodb`).
+ *
+ * Why custom (not `marshall`/`unmarshall` alone): irc-core uses `Set`
+ * and `Map` for `caps`, `joinedChannels`, channel `members`, `banMasks`,
+ * etc. The AWS SDK's default marshallers turn `Set` into a DynamoDB
+ * `SS`/`NS`/`BS` typed value and `Map` into an `M`-typed nested attribute
+ * — both of which are awkward to query. We expand Sets to arrays and
+ * Maps to arrays of `[key, value]` pairs so every column is a flat
+ * scalar/list whose shape matches the PLAN §4 access patterns.
+ *
+ * Lifecycle:
+ *   - `marshal*` — irc-core value → DynamoDB item (write path).
+ *   - `unmarshal*` — DynamoDB item → irc-core value (read path).
+ *
+ * Round-trip invariant: `unmarshal*(marshal*(x))` is structurally equal
+ * to `x` for every value `x`. Tested exhaustively against the
+ * irc-core state generators.
+ */
+
+import type {
+  ChanName,
+  ChannelModes,
+  ChannelState,
+  ChannelTopic,
+  ConnId,
+  ConnectionState,
+  Nick,
+  RegistrationState,
+  RosterEntry,
+  UserModes,
+} from '@serverless-ircd/irc-core';
+
+// ---------------------------------------------------------------------------
+// Connections
+// ---------------------------------------------------------------------------
+
+/** Current Connections schema version. Bump when the shape changes. */
+export const CONNECTION_VERSION = 1;
+
+/**
+ * Persists a {@link ConnectionState} row. The `version` field supports
+ * forward migrations on read (mirrors the CF adapter's `PersistedConnectionState`).
+ *
+ * Storage-shape notes:
+ *   - `joinedChannels` is stored as a DynamoDB **String Set** (`SS`) so
+ *     the membership transaction can atomically `ADD`/`DELETE` a channel
+ *     (DynamoDB set ops). The attribute is OMITTED when empty because
+ *     DynamoDB rejects empty sets — the transaction path creates it on
+ *     the first JOIN. `caps` stays an array: nothing needs to mutate a
+ *     single cap atomically.
+ */
+export interface MarshalledConnection {
+  connectionId: ConnId;
+  registration: RegistrationState;
+  capNegotiating: boolean;
+  caps: string[];
+  /**
+   * Present (as a JS `Set`, auto-marshalled to `SS`) only when the
+   * connection has joined at least one channel. Absent otherwise —
+   * DynamoDB forbids empty sets, so we omit rather than store `SS: []`.
+   */
+  joinedChannels?: Set<ChanName>;
+  userModes: UserModes;
+  lastSeen: number;
+  connectedSince: number;
+  idleSince: number;
+  version: number;
+  nick?: Nick;
+  user?: string;
+  host?: string;
+  realname?: string;
+  passAttempt?: string;
+  account?: string;
+  away?: string;
+  saslMech?: string;
+  saslBuffer?: string;
+}
+
+/**
+ * Marshals a {@link ConnectionState} into a plain JS object ready for
+ * `PutCommand` / `UpdateCommand`. `idleSince` is the TTL attribute and
+ * is set to the supplied epoch ms (callers pass `Date.now()`).
+ *
+ * `joinedChannels` is emitted as a native `Set` only when non-empty;
+ * the AWS SDK marshalls it to a DynamoDB `SS`, enabling atomic
+ * `ADD`/`DELETE` from the membership transaction without read-modify-write.
+ */
+export function marshalConnection(state: ConnectionState, idleSince: number): MarshalledConnection {
+  const out: MarshalledConnection = {
+    connectionId: state.id,
+    registration: state.registration,
+    capNegotiating: state.capNegotiating,
+    caps: [...state.caps],
+    userModes: { ...state.userModes },
+    lastSeen: state.lastSeen,
+    connectedSince: state.connectedSince,
+    idleSince,
+    version: CONNECTION_VERSION,
+  };
+  if (state.joinedChannels.size > 0) {
+    // Copy so later mutations to `state` don't alias the stored value.
+    out.joinedChannels = new Set<ChanName>(state.joinedChannels);
+  }
+  if (state.nick !== undefined) out.nick = state.nick;
+  if (state.user !== undefined) out.user = state.user;
+  if (state.host !== undefined) out.host = state.host;
+  if (state.realname !== undefined) out.realname = state.realname;
+  if (state.passAttempt !== undefined) out.passAttempt = state.passAttempt;
+  if (state.account !== undefined) out.account = state.account;
+  if (state.away !== undefined) out.away = state.away;
+  if (state.saslMech !== undefined) out.saslMech = state.saslMech;
+  if (state.saslBuffer !== undefined) out.saslBuffer = state.saslBuffer;
+  return out;
+}
+
+/**
+ * Materialises a {@link ConnectionState} from a stored row. Rehydrates
+ * `caps` and `joinedChannels` into Sets. Throws on unrecognised
+ * `version` values (forward migrations live in a future ticket).
+ */
+export function unmarshalConnection(row: MarshalledConnection): ConnectionState {
+  if (row.version > CONNECTION_VERSION) {
+    throw new Error(
+      `Connections row version ${row.version} is newer than supported ${CONNECTION_VERSION}`,
+    );
+  }
+  const state: ConnectionState = {
+    id: row.connectionId,
+    registration: row.registration,
+    capNegotiating: row.capNegotiating,
+    caps: new Set<string>(row.caps),
+    // `joinedChannels` is absent on rows that never joined a channel
+    // (DynamoDB rejects empty sets); default to an empty Set. The SDK
+    // unmarshalls `SS` back to a native Set, which the Set constructor
+    // copies; arrays (older rows) also iterate fine.
+    joinedChannels: new Set<ChanName>(row.joinedChannels ?? []),
+    userModes: { ...row.userModes },
+    lastSeen: row.lastSeen,
+    connectedSince: row.connectedSince,
+  };
+  if (row.nick !== undefined) state.nick = row.nick;
+  if (row.user !== undefined) state.user = row.user;
+  if (row.host !== undefined) state.host = row.host;
+  if (row.realname !== undefined) state.realname = row.realname;
+  if (row.passAttempt !== undefined) state.passAttempt = row.passAttempt;
+  if (row.account !== undefined) state.account = row.account;
+  if (row.away !== undefined) state.away = row.away;
+  if (row.saslMech !== undefined) state.saslMech = row.saslMech;
+  if (row.saslBuffer !== undefined) state.saslBuffer = row.saslBuffer;
+  return state;
+}
+
+// ---------------------------------------------------------------------------
+// Nicks
+// ---------------------------------------------------------------------------
+
+/** Stored shape for the `Nicks` table. */
+export interface MarshalledNick {
+  nickLower: string;
+  nick: Nick;
+  connectionId: ConnId;
+  reservedAt: number;
+}
+
+/** Marshals a nick registration into the stored row shape. */
+export function marshalNick(nick: Nick, connectionId: ConnId, reservedAt: number): MarshalledNick {
+  return {
+    nickLower: nick.toLowerCase(),
+    nick,
+    connectionId,
+    reservedAt,
+  };
+}
+
+/** Materialises the canonical (nick → connectionId) lookup from a row. */
+export function unmarshalNick(row: MarshalledNick): { nick: Nick; connectionId: ConnId } {
+  return { nick: row.nick, connectionId: row.connectionId };
+}
+
+// ---------------------------------------------------------------------------
+// ChannelMeta
+// ---------------------------------------------------------------------------
+
+/** Stored shape for the `ChannelMeta` table (modes + topic, no members). */
+export interface MarshalledChannelMeta {
+  channelName: string;
+  displayName: ChanName;
+  modes: ChannelModes;
+  banMasks: string[];
+  pendingInvites: string[];
+  createdAt: number;
+  topicText?: string;
+  topicSetter?: string;
+  topicSetAt?: number;
+}
+
+/** Marshals a channel's metadata into the stored row shape. */
+export function marshalChannelMeta(chan: ChannelState): MarshalledChannelMeta {
+  const out: MarshalledChannelMeta = {
+    channelName: chan.nameLower,
+    displayName: chan.name,
+    modes: { ...chan.modes },
+    banMasks: [...chan.banMasks],
+    pendingInvites: [...chan.pendingInvites],
+    createdAt: chan.createdAt,
+  };
+  if (chan.topic !== undefined) {
+    out.topicText = chan.topic.text;
+    out.topicSetter = chan.topic.setter;
+    out.topicSetAt = chan.topic.setAt;
+  }
+  return out;
+}
+
+/**
+ * Materialises a {@link ChannelState} from the meta row + the (separately
+ * fetched) member list. The caller is expected to populate `members`
+ * afterwards — meta and members live in different tables so they're fetched
+ * in parallel by the runtime.
+ */
+export function unmarshalChannelMeta(
+  row: MarshalledChannelMeta,
+  members: ReadonlyMap<ConnId, RosterEntry>,
+): ChannelState {
+  let topic: ChannelTopic | undefined;
+  if (
+    row.topicText !== undefined &&
+    row.topicSetter !== undefined &&
+    row.topicSetAt !== undefined
+  ) {
+    topic = { text: row.topicText, setter: row.topicSetter, setAt: row.topicSetAt };
+  }
+  const chan: ChannelState = {
+    name: row.displayName,
+    nameLower: row.channelName,
+    modes: { ...row.modes },
+    banMasks: new Set<string>(row.banMasks),
+    members: new Map<ConnId, RosterEntry>(members),
+    pendingInvites: new Set<Nick>(row.pendingInvites),
+    createdAt: row.createdAt,
+  };
+  if (topic !== undefined) chan.topic = topic;
+  return chan;
+}
+
+// ---------------------------------------------------------------------------
+// ChannelMembers
+// ---------------------------------------------------------------------------
+
+/** Stored shape for the `ChannelMembers` table — one row per (chan, conn). */
+export interface MarshalledChannelMember {
+  channelName: string;
+  connectionId: ConnId;
+  nick: Nick;
+  op: boolean;
+  voice: boolean;
+}
+
+/** Marshals a single roster entry into the stored row shape. */
+export function marshalChannelMember(
+  channelName: string,
+  entry: RosterEntry,
+): MarshalledChannelMember {
+  return {
+    channelName,
+    connectionId: entry.conn,
+    nick: entry.nick,
+    op: entry.op,
+    voice: entry.voice,
+  };
+}
+
+/** Materialises a {@link RosterEntry} from a stored member row. */
+export function unmarshalChannelMember(row: MarshalledChannelMember): RosterEntry {
+  return {
+    conn: row.connectionId,
+    nick: row.nick,
+    op: row.op,
+    voice: row.voice,
+  };
+}

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

@@ -0,0 +1,53 @@
+/**
+ * Runtime-safe DynamoDB table metadata (PLAN §4).
+ *
+ * The CDK-coupled `TABLE_DEFS` (TableProps with `AttributeType`/`BillingMode`
+ * enums) lives in `./cdk-table-defs.ts` so the Lambda handler bundle does
+ * not have to ship `aws-cdk-lib`. The runtime only needs:
+ *
+ *   - the *names* of the logical tables (so env-var→TablesConfig lookup works),
+ *   - the *names* of the key columns (so DynamoDB DocumentClient commands
+ *     reference them without stringly-typed typos).
+ *
+ * Both files share {@link TableName} as the single source of truth for the
+ * canonical logical names (`Connections`, `ChannelMeta`, …).
+ */
+
+/** Logical table names — also used as CDK construct ids. */
+export type TableName = 'Connections' | 'ChannelMeta' | 'ChannelMembers' | 'Nicks' | 'Accounts';
+
+/** Logical table names in stable order. */
+export const TABLE_NAMES: readonly TableName[] = [
+  'Connections',
+  'ChannelMeta',
+  'ChannelMembers',
+  'Nicks',
+  'Accounts',
+];
+
+/** Key column names used throughout the runtime (avoids stringly-typed typos). */
+export const TABLE_KEYS = {
+  Connections: { pk: 'connectionId' },
+  ChannelMeta: { pk: 'channelName' },
+  ChannelMembers: { pk: 'channelName', sk: 'connectionId' },
+  Nicks: { pk: 'nickLower' },
+  Accounts: { pk: 'account' },
+} as const;
+
+/**
+ * Maps logical names to physical table names. Production uses the bare
+ * names; tests override with a unique prefix per harness to isolate
+ * parallel runs against a shared DynamoDB Local instance.
+ */
+export type TablesConfig = Record<TableName, string>;
+
+/** Builds a {@link TablesConfig} from the supplied physical table names. */
+export function tablesConfigFromNames(names: {
+  Connections: string;
+  ChannelMeta: string;
+  ChannelMembers: string;
+  Nicks: string;
+  Accounts: string;
+}): TablesConfig {
+  return { ...names };
+}