serverless-ircd 0.1.0 → 0.3.0

package/packages/aws-adapter/src/handlers/ping-checker.ts

@@ -0,0 +1,217 @@
+/**
+ * `$ping` handler — Lambda entry invoked on a fixed EventBridge schedule
+ * (rate(1 minute) in the CDK stack). Scans `Connections` for rows past
+ * the configured idle thresholds and either:
+ *
+ *   • posts a server-initiated `PING :<token>` to the client via
+ *     `ApiGatewayManagementApi.postToConnection`, or
+ *   • tears the connection down via {@link cleanupConnection} when the
+ *     client has been silent past the PONG window.
+ *
+ * Why a batch-scan Lambda (not per-connection EventBridge one-shots):
+ * the architecture sketch in `docs/AWS-Adapter-Architecture.md` §6
+ * mentions per-connection Scheduler entries, but that model scales to
+ * N scheduler entries per active user and complicates cancellation
+ * on every `$default`. A single scheduled Lambda that scans and acts
+ * is simpler, cheaper, and matches how the gone-connection sweeper
+ * already works.
+ *
+ * Decision parity with the Cloudflare adapter: this is the AWS
+ * equivalent of `ConnectionDO.alarm()` in `cf-adapter/src/connection-do.ts`,
+ * which sends a PING every `pingIntervalMs` and disconnects when
+ * `lastSeen + pongTimeoutMs < now`. The AWS batch Lambda makes the
+ * same per-connection decision for every connection in a single pass.
+ *
+ * Idle timer: every `$default` invocation refreshes `idleSince` to
+ * `Date.now()` (see `handleDefault`'s `persistState`), so any frame
+ * from the client — including the `PONG` reply this handler's PING
+ * elicits — resets the idle window. `idleSince` is also the DynamoDB
+ * TTL attribute, so connections that slip past both this Lambda and
+ * the sweeper are eventually reaped by DynamoDB itself.
+ */
+
+import { randomUUID } from 'node:crypto';
+import {
+  type ApiGatewayManagementApi,
+  GoneException,
+} from '@aws-sdk/client-apigatewaymanagementapi';
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { ScanCommand, UpdateCommand } from '@aws-sdk/lib-dynamodb';
+import type { ConnId, RawLine } from '@serverless-ircd/irc-core';
+import { cleanupConnection } from '../aws-runtime.js';
+import type { PostToConnection } from '../aws-runtime.js';
+import type { TablesConfig } from '../tables.js';
+
+/**
+ * Default PING cadence — matches `cf-adapter`'s
+ * `DEFAULT_PING_INTERVAL_MS` so a connection sees the same liveness
+ * pressure on both substrates.
+ */
+export const DEFAULT_PING_INTERVAL_MS = 60_000;
+
+/**
+ * Default no-PONG disconnect window — total idle to disconnect equals
+ * `DEFAULT_PING_INTERVAL_MS + DEFAULT_PONG_TIMEOUT_MS` (150 s), giving
+ * the client ~90 s after the first PING to reply. Mirrors the CF
+ * adapter's `DEFAULT_PONG_TIMEOUT_MS`.
+ */
+export const DEFAULT_PONG_TIMEOUT_MS = 90_000;
+
+/** Parameters accepted by {@link handlePingCheck}. */
+export interface PingCheckParams {
+  dynamo: DynamoDBDocumentClient;
+  tables: TablesConfig;
+  /**
+   * Backend used to push `PING` bytes to the remote socket. May be:
+   *   - a real `ApiGatewayManagementApi` client (production),
+   *   - a test double that satisfies {@link PostToConnection},
+   *   - `null` when running in a context that has no APIGW endpoint
+   *     (the PING path becomes a silent no-op and only the disconnect
+   *     branch can fire). Used by the sweeper-style unit tests.
+   */
+  managementApi: ApiGatewayManagementApi | PostToConnection | null;
+  /** Wall-clock "now" (default: `Date.now()`). */
+  now?: number;
+  /** A connection is PINGed when `idleFor >= pingIntervalMs` (default 60 s). */
+  pingIntervalMs?: number;
+  /**
+   * A connection is disconnected when `idleFor >= pingIntervalMs + pongTimeoutMs`
+   * (default 90 s, so the total idle-to-disconnect is 150 s). The
+   * client gets roughly this long after the first PING to send PONG.
+   */
+  pongTimeoutMs?: number;
+  /**
+   * Overrides the PING token source. Defaults to `crypto.randomUUID()`.
+   * Exposed for determinism in tests; production callers should not
+   * set this.
+   */
+  makeToken?: () => string;
+}
+
+/** Result returned by {@link handlePingCheck}. */
+export interface PingCheckResult {
+  /** Total rows examined (post-pagination sum). */
+  scanned: number;
+  /** Rows that received a `PING` this pass. */
+  pinged: number;
+  /** Rows torn down this pass. */
+  disconnected: number;
+}
+
+/**
+ * Scans `Connections` and applies the PING / disconnect policy per row.
+ *
+ * Idempotent: running twice pings 0 the second time once the disconnect
+ * threshold has elapsed (the row is gone), and PINGing the same live
+ * client twice is harmless (clients reply to every PING with a PONG).
+ */
+export async function handlePingCheck(params: PingCheckParams): Promise<PingCheckResult> {
+  const now = params.now ?? Date.now();
+  const pingIntervalMs = params.pingIntervalMs ?? DEFAULT_PING_INTERVAL_MS;
+  const pongTimeoutMs = params.pongTimeoutMs ?? DEFAULT_PONG_TIMEOUT_MS;
+  const disconnectAfter = pingIntervalMs + pongTimeoutMs;
+  const makeToken = params.makeToken ?? defaultToken;
+
+  let scanned = 0;
+  let pinged = 0;
+  let disconnected = 0;
+  let lastKey: unknown = undefined;
+
+  do {
+    const res = await params.dynamo.send(
+      new ScanCommand({
+        TableName: params.tables.Connections,
+        ...(lastKey !== undefined ? { ExclusiveStartKey: lastKey as never } : {}),
+      }),
+    );
+    lastKey = res.LastEvaluatedKey;
+    for (const item of res.Items ?? []) {
+      scanned++;
+      const row = item as { connectionId?: unknown; idleSince?: unknown };
+      const connId = row.connectionId;
+      const idleSince = row.idleSince;
+      if (typeof connId !== 'string' || typeof idleSince !== 'number') continue;
+      const idleFor = now - idleSince;
+
+      if (idleFor >= disconnectAfter) {
+        // Silent past the PONG window: tear down. cleanupConnection is
+        // idempotent and tolerates the row being concurrently removed
+        // by `$disconnect` or the sweeper.
+        await cleanupConnection(params.dynamo, params.tables, connId, params.managementApi);
+        disconnected++;
+        continue;
+      }
+
+      if (idleFor >= pingIntervalMs) {
+        // managementApi === null means the PING path is a silent no-op
+        // (e.g. the sweeper-style unit tests). We do not count it as a
+        // pinged connection because no bytes went out.
+        if (params.managementApi === null) continue;
+        const token = makeToken();
+        const line: RawLine = { text: `PING :${token}` };
+        const data = `${line.text}\r\n`;
+        try {
+          await params.managementApi.postToConnection({ ConnectionId: connId, Data: data });
+        } catch (err: unknown) {
+          if (err instanceof GoneException || isGone(err)) {
+            // The socket is gone but the row is still there. Reap it
+            // directly so the client's silent death doesn't have to
+            // wait for the next sweeper cycle.
+            await cleanupConnection(params.dynamo, params.tables, connId, params.managementApi);
+            // The PING attempt counts: the Lambda did the work of
+            // deciding to ping, even though the send threw. The row
+            // is also counted as disconnected by the cleanup path, but
+            // we only bump `disconnected` from the idle-threshold
+            // branch above; the gone-cleanup is reported via `pinged`
+            // so callers can tell the two cases apart.
+            pinged++;
+            continue;
+          }
+          throw err;
+        }
+        // Stamp the row so subsequent passes can distinguish "PING sent,
+        // awaiting PONG" from "freshly idle, never pinged" if a future
+        // revision wants to avoid duplicate PINGs. Today the Lambda
+        // simply re-pings on every fire; the stamp is bookkeeping for
+        // observers (and tests).
+        await markPingSent(params.dynamo, params.tables.Connections, connId, now);
+        pinged++;
+      }
+    }
+  } while (lastKey !== undefined);
+
+  return { scanned, pinged, disconnected };
+}
+
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+
+/** Default token source — Node 20 Lambda runtime exposes `crypto.randomUUID` globally. */
+function defaultToken(): string {
+  return randomUUID();
+}
+
+/** Stamps `pingSentAt = now` on the connection row (side-channel attribute). */
+async function markPingSent(
+  dynamo: DynamoDBDocumentClient,
+  connectionsTable: string,
+  connId: ConnId,
+  now: number,
+): Promise<void> {
+  await dynamo.send(
+    new UpdateCommand({
+      TableName: connectionsTable,
+      Key: { connectionId: connId },
+      UpdateExpression: 'SET pingSentAt = :t',
+      ExpressionAttributeValues: { ':t': now },
+    }),
+  );
+}
+
+/** 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';
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Initial ConnectionState for a fresh `$connect` invocation.
+ *
+ * Centralised so the `$connect` handler and the test harness construct
+ * the same canonical pre-registration state.
+ */
+
+import { type ConnectionState, createConnection } from '@serverless-ircd/irc-core';
+
+/** Builds the canonical pre-registration state for `connectionId`. */
+export function createInitialConnectionState(connectionId: string, now: number): ConnectionState {
+  return createConnection({ id: connectionId, connectedSince: now });
+}

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

@@ -0,0 +1,84 @@
+/**
+ * `$sweeper` handler — Lambda entry invoked on a fixed EventBridge
+ * schedule. Scans `Connections` for rows whose `idleSince` is older
+ * than a TTL threshold and runs {@link cleanupConnection} on each.
+ *
+ * Catches connections that vanished without API Gateway ever emitting
+ * `$disconnect` (mobile backgrounding, NAT timeouts, client crashes).
+ * The DynamoDB TTL on `idleSince` also expires those rows eventually,
+ * but TTL reaping is eventual (up to ~48h) and does NOT clean up the
+ * matching `ChannelMembers` / `Nicks` rows — the sweeper does, via
+ * the same idempotent teardown path used on `$disconnect`.
+ *
+ * Threshold default matches the APIGW WebSocket 2-hour hard cap: any
+ * connection idle for ≥2h is definitionally gone (APIGW itself will
+ * have closed the socket). PING timers handle the shorter-window
+ * liveness checks; this is the long-tail backstop.
+ */
+
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { ScanCommand } from '@aws-sdk/lib-dynamodb';
+import { cleanupConnection } from '../aws-runtime.js';
+import type { TablesConfig } from '../tables.js';
+
+/**
+ * Default stale threshold — twice the APIGW WebSocket 2-hour hard cap
+ * would be excessive; we use the cap itself. A connection idle for two
+ * hours cannot still have an open socket (APIGW enforces the cap).
+ */
+export const DEFAULT_STALE_AFTER_MS = 2 * 60 * 60 * 1000;
+
+/** Parameters accepted by {@link handleSweep}. */
+export interface SweepParams {
+  dynamo: DynamoDBDocumentClient;
+  tables: TablesConfig;
+  /** Wall-clock "now" (default: `Date.now()`). */
+  now?: number;
+  /** A connection is stale when `idleSince < now - staleAfterMs`. */
+  staleAfterMs?: number;
+}
+
+/** Result returned by {@link handleSweep}. */
+export interface SweepResult {
+  /** Total rows examined (post-pagination sum). */
+  scanned: number;
+  /** Rows torn down this pass. */
+  swept: number;
+}
+
+/**
+ * Scans `Connections` and tears down every row past the staleness
+ * threshold. Idempotent: running twice sweeps 0 the second time
+ * (cleanupConnection tolerates missing rows).
+ */
+export async function handleSweep(params: SweepParams): Promise<SweepResult> {
+  const now = params.now ?? Date.now();
+  const staleAfterMs = params.staleAfterMs ?? DEFAULT_STALE_AFTER_MS;
+  const cutoff = now - staleAfterMs;
+
+  let scanned = 0;
+  let swept = 0;
+  let lastKey: unknown = undefined;
+
+  do {
+    const res = await params.dynamo.send(
+      new ScanCommand({
+        TableName: params.tables.Connections,
+        ...(lastKey !== undefined ? { ExclusiveStartKey: lastKey as never } : {}),
+      }),
+    );
+    lastKey = res.LastEvaluatedKey;
+    for (const item of res.Items ?? []) {
+      scanned++;
+      const row = item as { connectionId?: string; idleSince?: number };
+      const idleSince = row.idleSince;
+      if (typeof idleSince !== 'number' || idleSince >= cutoff) continue;
+      const connId = row.connectionId;
+      if (typeof connId !== 'string') continue;
+      await cleanupConnection(params.dynamo, params.tables, connId, null);
+      swept++;
+    }
+  } while (lastKey !== undefined);
+
+  return { scanned, swept };
+}

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

@@ -0,0 +1,74 @@
+/**
+ * @serverless-ircd/aws-adapter — entry point.
+ *
+ * Exports accumulate as the TDD cycles land. The CDK-coupled `TABLE_DEFS`
+ * lives at `@serverless-ircd/aws-adapter/cdk-table-defs` so the Lambda
+ * bundle does not pull in `aws-cdk-lib`.
+ */
+
+export { AwsRuntime } from './aws-runtime.js';
+export type {
+  AwsRuntimeHandlers,
+  AwsRuntimeOptions,
+  PostToConnection,
+} from './aws-runtime.js';
+export { cleanupConnection } from './aws-runtime.js';
+export { TABLE_KEYS, TABLE_NAMES, tablesConfigFromNames } from './tables.js';
+export type { TableName, TablesConfig } from './tables.js';
+export { createDynamoDocumentClient } from './dynamo.js';
+export {
+  DynamoAccountStore,
+  type HashedAccountCredential,
+  hashAccountCredential,
+  loadDynamoAccountStore,
+} from './dynamo-account-store.js';
+export { bindAccountStore, putAccountCredential, resolveAccountStore } from './account-store.js';
+export {
+  loadServerConfigFromLambdaEnv,
+  type LambdaConfigEnv,
+} from './config-loader.js';
+export {
+  CONNECTION_VERSION,
+  marshalChannelMember,
+  marshalChannelMeta,
+  marshalConnection,
+  marshalNick,
+  unmarshalChannelMember,
+  unmarshalChannelMeta,
+  unmarshalConnection,
+  unmarshalNick,
+} from './serialize.js';
+export type {
+  MarshalledChannelMember,
+  MarshalledChannelMeta,
+  MarshalledConnection,
+  MarshalledNick,
+} from './serialize.js';
+
+// Lambda handler entry — exported so `apps/aws-stack`'s NodejsFunction and
+// downstream tooling can import from a single package surface.
+export {
+  handler,
+  dispatch,
+  buildDepsFromEnv,
+  pingCheckerHandler,
+  sweeperHandler,
+  handlePingCheck,
+  handleSweep,
+  DEFAULT_PING_INTERVAL_MS,
+  DEFAULT_PONG_TIMEOUT_MS,
+  DEFAULT_STALE_AFTER_MS,
+  __resetHandlerCacheForTests,
+} from './handlers/index.js';
+export type {
+  ConnectEvent,
+  DefaultEvent,
+  DisconnectEvent,
+  HandlerDeps,
+  LambdaResponse,
+  PingCheckParams,
+  PingCheckResult,
+  SweepParams,
+  SweepResult,
+  WebSocketEvent,
+} from './handlers/index.js';

package/packages/aws-adapter/src/message-store.ts

@@ -0,0 +1,34 @@
+/**
+ * Chat-history store construction for the AWS adapter.
+ *
+ * Centralises `MessageStore` creation so the actor-construction sites
+ * (`handleDefault`) bind a single helper rather than constructing the
+ * store inline. The v1 implementation is an in-memory ring buffer
+ * (`InMemoryMessageStore`); a DynamoDB-backed persistent variant (new
+ * `Messages` table, partition key `chan`, sort key `time`, GSI on
+ * `msgid`) is a documented follow-up — swapping it in means replacing
+ * this one function.
+ *
+ * The in-memory v1 store is scoped to the Lambda execution context:
+ * it persists across warm invocations (via the memoised `HandlerDeps`)
+ * but is lost on cold start. Within a single multi-line `$default`
+ * frame (PRIVMSG + CHATHISTORY joined by `\r\n`) recording and
+ * playback work fully end-to-end.
+ */
+
+import {
+  InMemoryMessageStore,
+  type MessageStore,
+  type ParsedServerConfig,
+} from '@serverless-ircd/irc-core';
+
+/**
+ * Constructs the chat-history store for a deployment.
+ *
+ * @param _serverConfig Reserved for the future persistent variant
+ *   (retention cap, table-name resolution); the in-memory v1 impl
+ *   uses the `InMemoryMessageStore` default retention.
+ */
+export function bindMessageStore(_serverConfig?: ParsedServerConfig): MessageStore {
+  return new InMemoryMessageStore();
+}