serverless-ircd 0.1.0 → 0.2.0

package/packages/aws-adapter/src/cdk-table-defs.ts

@@ -0,0 +1,69 @@
+/**
+ * CDK-coupled table definitions (PLAN §4).
+ *
+ * The single source of truth for the deployed table shapes
+ * (`partitionKey`, `sortKey`, `timeToLiveAttribute`, …). Lives in
+ * `aws-adapter` (not `aws-stack`) so the runtime can reference the same
+ * logical names via {@link TABLE_NAMES} without round-tripping through
+ * the app directory.
+ *
+ * Re-exported from `apps/aws-stack/src/aws-stack.ts`. NOT re-exported
+ * from `aws-adapter`'s `index.ts` so the Lambda handler bundle does
+ * not transitively include `aws-cdk-lib`.
+ *
+ * Schema invariants (PLAN §4):
+ *   • `Nicks` uniqueness is enforced at write-time via conditional PutItem
+ *     (PK = lowercased nick) — not by the schema itself.
+ *   • `ChannelMembers` uses a composite key (channelName PK + connectionId SK)
+ *     so a future `TransactWriteItems` can span Connections ↔ membership
+ *     atomically. (Atomicity across Connections/ChannelMembers lands in the
+ *     membership-transaction follow-up.)
+ *   • `Accounts` never stores plaintext credentials (hash only).
+ *   • `Connections.idleSince` is the DynamoDB TTL attribute; idle connections
+ *     are reaped automatically in addition to the explicit sweeper.
+ */
+
+import { AttributeType, BillingMode } from 'aws-cdk-lib/aws-dynamodb';
+import type { TableProps } from 'aws-cdk-lib/aws-dynamodb';
+import type { TableName } from './tables.js';
+
+/**
+ * All five tables keyed by their logical construct id. The id doubles as the
+ * CloudFormation logical id; the physical `TableName` is set on each entry.
+ *
+ * NOTE: the deployed physical name is **environment-prefixed** by
+ * `IrcAwsStack` (`<Env><LogicalId>`, e.g. `StagingConnections`) — the
+ * `tableName` here is the schema default overridden at synth time. Both
+ * the CDK stack and the runtime read from this record. Tests that prefix
+ * every physical name (to isolate parallel runs) consume the
+ * `TABLE_DEFS` entries' key/attribute names only.
+ */
+export const TABLE_DEFS: Record<TableName, TableProps> = {
+  Connections: {
+    tableName: 'Connections',
+    partitionKey: { name: 'connectionId', type: AttributeType.STRING },
+    billingMode: BillingMode.PAY_PER_REQUEST,
+    timeToLiveAttribute: 'idleSince',
+  },
+  ChannelMeta: {
+    tableName: 'ChannelMeta',
+    partitionKey: { name: 'channelName', type: AttributeType.STRING },
+    billingMode: BillingMode.PAY_PER_REQUEST,
+  },
+  ChannelMembers: {
+    tableName: 'ChannelMembers',
+    partitionKey: { name: 'channelName', type: AttributeType.STRING },
+    sortKey: { name: 'connectionId', type: AttributeType.STRING },
+    billingMode: BillingMode.PAY_PER_REQUEST,
+  },
+  Nicks: {
+    tableName: 'Nicks',
+    partitionKey: { name: 'nickLower', type: AttributeType.STRING },
+    billingMode: BillingMode.PAY_PER_REQUEST,
+  },
+  Accounts: {
+    tableName: 'Accounts',
+    partitionKey: { name: 'account', type: AttributeType.STRING },
+    billingMode: BillingMode.PAY_PER_REQUEST,
+  },
+};

package/packages/aws-adapter/src/config-loader.ts

@@ -0,0 +1,96 @@
+/**
+ * Lambda env config loader.
+ *
+ * Mirrors the Cloudflare (`cf-adapter/src/config-loader.ts`) and local-cli
+ * (`local-cli/src/config-loader.ts`) adapters: takes platform-native env
+ * vars and feeds them through the shared {@link parseServerConfig} so a
+ * single boot-time failure mode covers every adapter.
+ *
+ * Lambda env vars are all strings; numeric knobs are coerced here.
+ */
+
+import { type ParsedServerConfig, parseServerConfig } from '@serverless-ircd/irc-core';
+
+/**
+ * The subset of `process.env` this loader reads. Optional members are
+ * omitted from the input object when undefined so the schema's defaults
+ * apply.
+ */
+export interface LambdaConfigEnv {
+  SERVER_NAME?: string;
+  NETWORK_NAME?: string;
+  MOTD?: string;
+  MAX_CLIENTS?: string;
+  CHANNEL_PREFIXES?: string;
+  OPER_USER?: string;
+  OPER_PASSWORD?: string;
+  MAX_CHANNELS_PER_USER?: string;
+  MAX_TARGETS_PER_COMMAND?: string;
+  NICK_LEN?: string;
+  CHANNEL_LEN?: string;
+  TOPIC_LEN?: string;
+  MAX_LIST_ENTRIES?: string;
+  QUIT_MESSAGE?: string;
+}
+
+/**
+ * Builds the input object the shared schema expects from a Lambda env.
+ *
+ * Exported so the assemble→parse boundary is unit-testable in isolation.
+ * Mirrors `cf-adapter`'s `buildConfigInput` line-for-line except for the
+ * MOTD env-var name (`MOTD` here vs `MOTD_LINES` in CF — Lambda env vars
+ * conventionally use bare names).
+ */
+export function buildLambdaConfigInput(env: LambdaConfigEnv): Record<string, unknown> {
+  const input: Record<string, unknown> = {
+    serverName: env.SERVER_NAME,
+    networkName: env.NETWORK_NAME,
+  };
+  if (env.MOTD !== undefined && env.MOTD.length > 0) {
+    input.motdLines = env.MOTD.split('\n');
+  }
+  if (env.MAX_CLIENTS !== undefined) {
+    input.maxClients = Number.parseInt(env.MAX_CLIENTS, 10);
+  }
+  if (env.CHANNEL_PREFIXES !== undefined) {
+    input.channelPrefixes = env.CHANNEL_PREFIXES;
+  }
+  if (env.OPER_USER !== undefined || env.OPER_PASSWORD !== undefined) {
+    input.operCreds = [
+      {
+        user: env.OPER_USER ?? '',
+        password: env.OPER_PASSWORD ?? '',
+      },
+    ];
+  }
+  if (env.MAX_CHANNELS_PER_USER !== undefined) {
+    input.maxChannelsPerUser = Number.parseInt(env.MAX_CHANNELS_PER_USER, 10);
+  }
+  if (env.MAX_TARGETS_PER_COMMAND !== undefined) {
+    input.maxTargetsPerCommand = Number.parseInt(env.MAX_TARGETS_PER_COMMAND, 10);
+  }
+  if (env.NICK_LEN !== undefined) {
+    input.nickLen = Number.parseInt(env.NICK_LEN, 10);
+  }
+  if (env.CHANNEL_LEN !== undefined) {
+    input.channelLen = Number.parseInt(env.CHANNEL_LEN, 10);
+  }
+  if (env.TOPIC_LEN !== undefined) {
+    input.topicLen = Number.parseInt(env.TOPIC_LEN, 10);
+  }
+  if (env.MAX_LIST_ENTRIES !== undefined) {
+    input.maxListEntries = Number.parseInt(env.MAX_LIST_ENTRIES, 10);
+  }
+  if (env.QUIT_MESSAGE !== undefined) {
+    input.quitMessage = env.QUIT_MESSAGE;
+  }
+  return input;
+}
+
+/**
+ * Loads and validates the server config from a Lambda env. Throws a
+ * readable `Error` listing every invalid field on failure.
+ */
+export function loadServerConfigFromLambdaEnv(env: LambdaConfigEnv): ParsedServerConfig {
+  return parseServerConfig(buildLambdaConfigInput(env));
+}

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

@@ -0,0 +1,61 @@
+/**
+ * DynamoDB DocumentClient factory.
+ *
+ * Centralised so the runtime, the handlers, and the test harness all
+ * build their clients with the same marshalling conventions
+ * (`removeUndefinedValues: true`, native JS values in/out).
+ */
+
+import { DynamoDBClient } from '@aws-sdk/client-dynamodb';
+import {
+  DynamoDBDocumentClient,
+  type TranslateConfig,
+  type marshallOptions,
+  type unmarshallOptions,
+} from '@aws-sdk/lib-dynamodb';
+
+/** Default marshalling options — every caller uses these. */
+const DEFAULT_TRANSLATE: TranslateConfig = {
+  marshallOptions: {
+    removeUndefinedValues: true,
+    convertClassInstanceToMap: false,
+  } as marshallOptions,
+  unmarshallOptions: {} as unmarshallOptions,
+};
+
+/**
+ * Builds a {@link DynamoDBDocumentClient} pointed at `endpoint`
+ * (or AWS proper when `endpoint` is omitted).
+ *
+ * Tests pass `endpoint` so they can address DynamoDB Local; production
+ * constructs the client with no endpoint and lets the SDK resolve the
+ * region from the Lambda execution role.
+ *
+ * `region` defaults to `'us-east-1'` when unset. DynamoDB Local ignores
+ * the value but the SDK requires one to be present so it can build the
+ * SigV4 signature. Production deployments inject a real region via the
+ * Lambda execution environment (`AWS_REGION`).
+ *
+ * When `endpoint` is supplied (the documented signal for DynamoDB Local
+ * / test mode) dummy static credentials are injected. The SDK v3 signs
+ * every request with SigV4 even against a local endpoint, so without
+ * credentials the default provider chain fails with
+ * `CredentialsProviderError`. Production never passes an endpoint and
+ * therefore resolves real credentials from the Lambda execution role.
+ */
+export function createDynamoDocumentClient(opts: {
+  endpoint?: string;
+  region?: string;
+}): DynamoDBDocumentClient {
+  const region = opts.region ?? process.env.AWS_REGION ?? 'us-east-1';
+  const client = new DynamoDBClient({
+    region,
+    ...(opts.endpoint !== undefined
+      ? {
+          endpoint: opts.endpoint,
+          credentials: { accessKeyId: 'local', secretAccessKey: 'local' },
+        }
+      : {}),
+  });
+  return DynamoDBDocumentClient.from(client, DEFAULT_TRANSLATE);
+}

package/packages/aws-adapter/src/handlers/connect.ts

@@ -0,0 +1,44 @@
+/**
+ * `$connect` handler — Lambda entry for `event.requestContext.routeKey === '$connect'`.
+ *
+ * Persists a fresh `Connections` row keyed by the APIGW connection id.
+ * Subsequent `$default` invocations load this row, run the actor, and
+ * persist the mutated state back.
+ */
+
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { PutCommand } from '@aws-sdk/lib-dynamodb';
+import type { ParsedServerConfig } from '@serverless-ircd/irc-core';
+import { marshalConnection } from '../serialize.js';
+import type { TablesConfig } from '../tables.js';
+import { createInitialConnectionState } from './state.js';
+
+/** Parameters accepted by {@link handleConnect}. */
+export interface ConnectParams {
+  dynamo: DynamoDBDocumentClient;
+  tables: TablesConfig;
+  connectionId: string;
+  /** Wall clock used to seed `connectedSince` / `idleSince` (default: now). */
+  now?: number;
+  /** Reserved for future use; required so the signature mirrors `$default`. */
+  serverConfig?: ParsedServerConfig;
+}
+
+/**
+ * Inserts the Connections row for a fresh WebSocket upgrade.
+ *
+ * Idempotent: APIGW retries `$connect` on transient failures, so we
+ * use `PutCommand` (overwrites) rather than a conditional insert.
+ */
+export async function handleConnect(params: ConnectParams): Promise<void> {
+  const now = params.now ?? Date.now();
+  const state = createInitialConnectionState(params.connectionId, now);
+  void params.serverConfig; // reserved for max-clients gating (later ticket)
+  const row = marshalConnection(state, now);
+  await params.dynamo.send(
+    new PutCommand({
+      TableName: params.tables.Connections,
+      Item: row,
+    }),
+  );
+}

package/packages/aws-adapter/src/handlers/default.ts

@@ -0,0 +1,322 @@
+/**
+ * `$default` handler — Lambda entry for every non-`$connect`/`$disconnect`
+ * route. Receives one (or more) IRC frames as `event.body`, runs them
+ * through {@link ConnectionActor}, and persists the mutated state back.
+ *
+ * One Lambda invocation = one WebSocket frame. The frame may contain
+ * multiple `\r\n`-separated lines; the actor splits them and runs each
+ * in order.
+ */
+
+import type { ApiGatewayManagementApi } from '@aws-sdk/client-apigatewaymanagementapi';
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { GetCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
+import {
+  type ChannelState,
+  type Clock,
+  type ConnectionState,
+  type IdFactory,
+  type MessageStore,
+  type MotdProvider,
+  type ParsedServerConfig,
+  SystemClock,
+  UuidIdFactory,
+  createConnection,
+} from '@serverless-ircd/irc-core';
+import { type ActorChannelAccess, ConnectionActor } from '@serverless-ircd/irc-server';
+import { AwsRuntime, type AwsRuntimeHandlers, type PostToConnection } from '../aws-runtime.js';
+import {
+  CONNECTION_VERSION,
+  type MarshalledConnection,
+  unmarshalConnection,
+} from '../serialize.js';
+import type { TablesConfig } from '../tables.js';
+
+/** Parameters accepted by {@link handleDefault}. */
+export interface DefaultParams {
+  dynamo: DynamoDBDocumentClient;
+  tables: TablesConfig;
+  connectionId: string;
+  body: string;
+  serverConfig: ParsedServerConfig;
+  motd: MotdProvider;
+  /**
+   * Chat-history persistence source. When omitted the actor runs with
+   * chathistory disabled (no recording, no playback) — preserves the
+   * behaviour of callers that have not opted in.
+   */
+  messages?: MessageStore;
+  managementApi: ApiGatewayManagementApi | PostToConnection | null;
+  /** Injected for tests; defaults to {@link SystemClock}. */
+  clock?: Clock;
+  /** Injected for tests; defaults to {@link UuidIdFactory}. */
+  ids?: IdFactory;
+  /** Optional management endpoint URL used when constructing a default client. */
+  managementEndpoint?: string;
+}
+
+/**
+ * Loads the Connections row, runs the actor over `body`, persists state.
+ *
+ * Returns the status code the Lambda should return to APIGW:
+ *   - `200` on success,
+ *   - `410` if the connection row is gone (client should reconnect),
+ *   - `500` for any unhandled error.
+ */
+export async function handleDefault(params: DefaultParams): Promise<{ statusCode: number }> {
+  const clock = params.clock ?? SystemClock;
+  const ids = params.ids ?? new UuidIdFactory();
+  // Load persisted state.
+  const result = await params.dynamo.send(
+    new GetCommand({
+      TableName: params.tables.Connections,
+      Key: { connectionId: params.connectionId },
+    }),
+  );
+  if (result.Item === undefined) {
+    return { statusCode: 410 };
+  }
+  const persisted = result.Item as unknown as MarshalledConnection;
+  const state = unmarshalConnection(persisted);
+
+  // Mark this frame's activity.
+  state.lastSeen = clock.now();
+
+  // Build the runtime + handlers.
+  const outbound: string[] = [];
+  const handlers: AwsRuntimeHandlers = {
+    send: (lines) => {
+      // Self-send: APIGW echoes back to the caller's open socket via the
+      // management API in production; in tests we collect for assertions.
+      for (const l of lines) outbound.push(l.text);
+    },
+    disconnect: () => {
+      // Lambda cannot close its own socket from inside the handler
+      // (the `$disconnect` route fires when APIGW observes the close).
+    },
+    snapshot: () => state,
+  };
+  const runtime = new AwsRuntime({
+    dynamo: params.dynamo,
+    tables: params.tables,
+    connId: params.connectionId,
+    handlers,
+    managementApi: params.managementApi,
+    clock,
+  });
+
+  const channelAccess = new LambdaChannelAccess(runtime, clock.now());
+
+  const actor = new ConnectionActor({
+    state,
+    runtime,
+    channels: channelAccess,
+    serverConfig: params.serverConfig,
+    clock,
+    ids,
+    motd: params.motd,
+    ...(params.messages !== undefined ? { messages: params.messages } : {}),
+  });
+
+  try {
+    await actor.receiveTextFrame(params.body);
+  } catch (err: unknown) {
+    console.error('[irc-handler] actor.receiveTextFrame failed', err);
+    // Still persist the state — partial mutations are valuable for debug.
+    await persistState(params.dynamo, params.tables, params.connectionId, state, clock.now());
+    return { statusCode: 500 };
+  }
+
+  // Persist the mutated state and flush outbound bytes.
+  await persistState(params.dynamo, params.tables, params.connectionId, state, clock.now());
+
+  // In production, deliver outbound bytes back to the caller via APIGW.
+  if (params.managementApi !== null && outbound.length > 0) {
+    const data = outbound.join('\r\n');
+    try {
+      await params.managementApi.postToConnection({
+        ConnectionId: params.connectionId,
+        Data: data,
+      });
+    } catch {
+      // The handler still returns 200 — the actor's mutations are
+      // persisted; the caller just didn't see the reply this frame.
+    }
+  }
+  return { statusCode: 200 };
+}
+
+/**
+ * Writes the actor's mutated `state` back to the Connections row.
+ *
+ * Uses an `UpdateCommand` that SETs every actor-owned field EXCEPT
+ * `joinedChannels`. The membership transaction (see `AwsRuntime`)
+ * owns `joinedChannels` atomically; if this frame's full-state write
+ * touched it, a concurrent `$default` for the same connection would
+ * lose the other frame's JOIN/PART. Optional fields (nick, user, …)
+ * are SET when present and REMOVE'd when absent so a cleared value
+ * does not linger from a previous frame.
+ */
+async function persistState(
+  dynamo: DynamoDBDocumentClient,
+  tables: TablesConfig,
+  _connId: string,
+  state: ConnectionState,
+  now: number,
+): Promise<void> {
+  const expr = buildPersistUpdate(state, now);
+  const hasNames = Object.keys(expr.expressionAttributeNames).length > 0;
+  await dynamo.send(
+    new UpdateCommand({
+      TableName: tables.Connections,
+      Key: { connectionId: state.id },
+      UpdateExpression: expr.updateExpression,
+      ExpressionAttributeValues: expr.expressionAttributeValues,
+      ...(hasNames ? { ExpressionAttributeNames: expr.expressionAttributeNames } : {}),
+    }),
+  );
+}
+
+/** Optional connection fields mirrored into the SET/REMOVE split. */
+const OPTIONAL_FIELDS = [
+  'nick',
+  'user',
+  'host',
+  'realname',
+  'passAttempt',
+  'account',
+  'away',
+  'saslMech',
+  'saslBuffer',
+] as const;
+
+/**
+ * Builds the `UpdateExpression` for {@link persistState}. Always SETs
+ * the required fields; SETs optional fields that are present and
+ * REMOVEs those that are absent. `joinedChannels` is intentionally
+ * excluded — owned by the membership transaction.
+ */
+function buildPersistUpdate(
+  state: ConnectionState,
+  now: number,
+): {
+  updateExpression: string;
+  expressionAttributeNames: Record<string, string>;
+  expressionAttributeValues: Record<string, unknown>;
+} {
+  const values: Record<string, unknown> = {
+    ':reg': state.registration,
+    ':capN': state.capNegotiating,
+    ':caps': [...state.caps],
+    ':um': { ...state.userModes },
+    ':ls': state.lastSeen,
+    ':is': now,
+    ':v': CONNECTION_VERSION,
+  };
+  const setNames = [
+    'registration = :reg',
+    'capNegotiating = :capN',
+    'caps = :caps',
+    'userModes = :um',
+    'lastSeen = :ls',
+    'idleSince = :is',
+    'version = :v',
+  ];
+  const removeNames: string[] = [];
+  const nameMap: Record<string, string> = {};
+
+  for (const field of OPTIONAL_FIELDS) {
+    const placeholder = `:${field}`;
+    const value = state[field] as string | undefined;
+    const nameKey = `#${field}`;
+    nameMap[nameKey] = field;
+    if (value !== undefined) {
+      values[placeholder] = value;
+      setNames.push(`${nameKey} = ${placeholder}`);
+    } else {
+      removeNames.push(nameKey);
+    }
+  }
+
+  const parts: string[] = [`SET ${setNames.join(', ')}`];
+  if (removeNames.length > 0) {
+    parts.push(`REMOVE ${removeNames.join(', ')}`);
+  }
+  return {
+    updateExpression: parts.join(' '),
+    expressionAttributeNames: nameMap,
+    expressionAttributeValues: values,
+  };
+}
+
+/**
+ * `ActorChannelAccess` backed by the per-invocation {@link AwsRuntime}.
+ *
+ * Mirrors `cf-adapter/src/connection-do.ts`'s `PassthroughChannelAccess`:
+ *   - `getOrCreateChannel(name)` returns a cached or freshly-seeded
+ *     {@link ChannelState} for the local reducer.
+ *   - `refreshChannel(name)` pulls the authoritative snapshot from
+ *     DynamoDB and rebuilds the cache so subsequent reducers observe
+ *     the current roster / modes / topic.
+ */
+class LambdaChannelAccess implements ActorChannelAccess {
+  private readonly cache = new Map<string, ChannelState>();
+  constructor(
+    private readonly runtime: AwsRuntime,
+    private readonly now: number,
+  ) {}
+
+  getOrCreateChannel(name: string): ChannelState {
+    const key = name.toLowerCase();
+    const existing = this.cache.get(key);
+    if (existing !== undefined) return existing;
+    const created: ChannelState = {
+      name,
+      nameLower: key,
+      modes: {
+        inviteOnly: false,
+        topicLock: false,
+        noExternal: false,
+        moderated: false,
+        secret: false,
+        private: false,
+      },
+      banMasks: new Set<string>(),
+      members: new Map(),
+      pendingInvites: new Set<string>(),
+      createdAt: this.now,
+    };
+    this.cache.set(key, created);
+    return created;
+  }
+
+  async refreshChannel(name: string): Promise<void> {
+    const key = name.toLowerCase();
+    const snap = await this.runtime.getChannelSnapshot(name);
+    if (snap === null) return;
+    const existing = this.cache.get(key);
+    if (snap.members.size === 0) {
+      if (existing !== undefined) {
+        existing.modes = { ...snap.modes };
+        existing.banMasks = new Set(snap.banMasks);
+        existing.pendingInvites = new Set(snap.pendingInvites);
+        if (snap.topic !== undefined) existing.topic = snap.topic;
+      }
+      return;
+    }
+    const rebuilt: ChannelState = {
+      name,
+      nameLower: key,
+      modes: { ...snap.modes },
+      banMasks: new Set(snap.banMasks),
+      members: new Map(snap.members),
+      pendingInvites: new Set(snap.pendingInvites),
+      createdAt: snap.createdAt,
+    };
+    if (snap.topic !== undefined) rebuilt.topic = snap.topic;
+    this.cache.set(key, rebuilt);
+  }
+}
+
+// Re-export for type-completeness in callers.
+export { createConnection };

package/packages/aws-adapter/src/handlers/disconnect.ts

@@ -0,0 +1,29 @@
+/**
+ * `$disconnect` handler — Lambda entry for `event.requestContext.routeKey === '$disconnect'`.
+ *
+ * Tears down the connection via {@link cleanupConnection} — deletes the
+ * Connections row, every ChannelMembers row owned by it, and the nick
+ * reservation if any. Idempotent: every step tolerates a missing row.
+ */
+
+import type { ApiGatewayManagementApi } from '@aws-sdk/client-apigatewaymanagementapi';
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { cleanupConnection } from '../aws-runtime.js';
+import type { TablesConfig } from '../tables.js';
+
+/** Parameters accepted by {@link handleDisconnect}. */
+export interface DisconnectParams {
+  dynamo: DynamoDBDocumentClient;
+  tables: TablesConfig;
+  connectionId: string;
+  /** Reserved for future "broadcast QUIT to peers" work; unused today. */
+  managementApi?: ApiGatewayManagementApi | null;
+}
+
+/**
+ * Cleans up the connection state. Safe to call after APIGW has already
+ * torn the WebSocket down — the management API is best-effort only.
+ */
+export async function handleDisconnect(params: DisconnectParams): Promise<void> {
+  await cleanupConnection(params.dynamo, params.tables, params.connectionId, null);
+}