serverless-ircd 0.1.0 → 0.2.0

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

@@ -0,0 +1,248 @@
+/**
+ * Lambda handler entry point.
+ *
+ * Dispatches on `event.requestContext.routeKey` to the per-route handlers:
+ *   - `$connect`    → persist a fresh Connections row.
+ *   - `$disconnect` → tear down the connection + clean up memberships.
+ *   - `$default`    → run the actor over `event.body` and persist state.
+ *
+ * The handler reads its config from `process.env` (SERVER_NAME, NETWORK_NAME,
+ * MOTD, table-name vars) via {@link loadServerConfigFromLambdaEnv}. Tests
+ * can inject a fully-formed {@link HandlerDeps} to bypass env loading.
+ */
+
+import { ApiGatewayManagementApi } from '@aws-sdk/client-apigatewaymanagementapi';
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import {
+  EmptyMotdProvider,
+  type MessageStore,
+  type MotdProvider,
+  type ParsedServerConfig,
+  StaticMotdProvider,
+} from '@serverless-ircd/irc-core';
+import { type LambdaConfigEnv, loadServerConfigFromLambdaEnv } from '../config-loader.js';
+import { createDynamoDocumentClient } from '../dynamo.js';
+import { bindMessageStore } from '../message-store.js';
+import { TABLE_KEYS, type TablesConfig } from '../tables.js';
+import { handleConnect } from './connect.js';
+import { handleDefault } from './default.js';
+import { handleDisconnect } from './disconnect.js';
+import {
+  DEFAULT_PING_INTERVAL_MS,
+  DEFAULT_PONG_TIMEOUT_MS,
+  type PingCheckParams,
+  type PingCheckResult,
+  handlePingCheck,
+} from './ping-checker.js';
+import {
+  DEFAULT_STALE_AFTER_MS,
+  type SweepParams,
+  type SweepResult,
+  handleSweep,
+} from './sweeper.js';
+
+/** API Gateway WebSocket event shape (the bits the handler reads). */
+export interface WebSocketEvent {
+  requestContext: {
+    routeKey: string;
+    connectionId: string;
+    domainName?: string;
+    stage?: string;
+  };
+  body?: string;
+}
+
+/** Lambda response shape. */
+export interface LambdaResponse {
+  statusCode: number;
+  body?: string;
+}
+
+/** Injectable dependencies. Tests construct one of these to bypass env loading. */
+export interface HandlerDeps {
+  dynamo: DynamoDBDocumentClient;
+  tables: TablesConfig;
+  serverConfig: ParsedServerConfig;
+  motd: MotdProvider;
+  managementApi: ApiGatewayManagementApi | null;
+  /**
+   * Chat-history persistence source bound to every actor. Constructed
+   * once per cold start (memoised via {@link cachedDeps}) so it survives
+   * across warm Lambda invocations. The v1 impl is in-memory; a
+   * DynamoDB-backed variant is a documented follow-up.
+   */
+  messages: MessageStore;
+}
+
+/**
+ * Strongly-typed event discriminated by routeKey. Useful for tests that
+ * construct events directly.
+ */
+export type ConnectEvent = { requestContext: { routeKey: '$connect'; connectionId: string } };
+export type DisconnectEvent = {
+  requestContext: { routeKey: '$disconnect'; connectionId: string };
+};
+export type DefaultEvent = {
+  requestContext: { routeKey: '$default'; connectionId: string };
+  body: string;
+};
+
+/** Memoised `HandlerDeps`; built on the first cold-start invocation. */
+let cachedDeps: HandlerDeps | undefined;
+
+/**
+ * The Lambda entry point. Routes on `event.requestContext.routeKey`.
+ *
+ * Cold-start path reads `process.env` for config + table names. Warm
+ * invocations reuse the cached {@link HandlerDeps}.
+ */
+export const handler = async (event: WebSocketEvent): Promise<LambdaResponse> => {
+  if (cachedDeps === undefined) {
+    cachedDeps = buildDepsFromEnv();
+  }
+  const deps = cachedDeps;
+  return dispatch(event, deps);
+};
+
+/**
+ * Pure dispatcher — exported for unit tests that inject deps directly.
+ */
+export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promise<LambdaResponse> {
+  const connId = event.requestContext.connectionId;
+  switch (event.requestContext.routeKey) {
+    case '$connect':
+      await handleConnect({
+        dynamo: deps.dynamo,
+        tables: deps.tables,
+        connectionId: connId,
+        serverConfig: deps.serverConfig,
+      });
+      return { statusCode: 200 };
+
+    case '$disconnect':
+      await handleDisconnect({
+        dynamo: deps.dynamo,
+        tables: deps.tables,
+        connectionId: connId,
+        managementApi: deps.managementApi,
+      });
+      return { statusCode: 200 };
+
+    case '$default':
+      if (event.body === undefined) {
+        return { statusCode: 400, body: 'empty body' };
+      }
+      {
+        const result = await handleDefault({
+          dynamo: deps.dynamo,
+          tables: deps.tables,
+          connectionId: connId,
+          body: event.body,
+          serverConfig: deps.serverConfig,
+          motd: deps.motd,
+          messages: deps.messages,
+          managementApi: deps.managementApi,
+        });
+        return result;
+      }
+
+    default:
+      // Unknown routeKey — should never happen (APIGW only forwards the
+      // three routes above). Return 200 so APIGW doesn't retry.
+      return { statusCode: 200 };
+  }
+}
+
+/**
+ * Resets the cached {@link HandlerDeps}. Used by tests that mutate env
+ * between cases.
+ */
+export function __resetHandlerCacheForTests(): void {
+  cachedDeps = undefined;
+}
+
+/**
+ * Lambda entry for the gone-connection sweeper. Wired to an EventBridge
+ * schedule in the CDK stack (`rate(5 minutes)`). Shares the cached
+ * {@link HandlerDeps} with {@link handler} — same tables, same config,
+ * no `managementApi` needed (the socket is, by definition, gone).
+ *
+ * `_event` is the EventBridge scheduled-event payload; we ignore it
+ * (the sweeper reads authoritative state from DynamoDB, not the event).
+ */
+export async function sweeperHandler(_event: unknown): Promise<SweepResult> {
+  if (cachedDeps === undefined) {
+    cachedDeps = buildDepsFromEnv();
+  }
+  const deps = cachedDeps;
+  return handleSweep({ dynamo: deps.dynamo, tables: deps.tables });
+}
+
+/**
+ * Lambda entry for the idle / PING checker. Wired to an EventBridge
+ * schedule in the CDK stack (`rate(1 minute)`). Shares the cached
+ * {@link HandlerDeps} with {@link handler} — same tables, same config,
+ * same `managementApi` (needed to push `PING` bytes back to the idle
+ * client via `postToConnection`).
+ *
+ * `_event` is the EventBridge scheduled-event payload; we ignore it
+ * (the checker reads authoritative state from DynamoDB, not the event).
+ */
+export async function pingCheckerHandler(_event: unknown): Promise<PingCheckResult> {
+  if (cachedDeps === undefined) {
+    cachedDeps = buildDepsFromEnv();
+  }
+  const deps = cachedDeps;
+  return handlePingCheck({
+    dynamo: deps.dynamo,
+    tables: deps.tables,
+    managementApi: deps.managementApi,
+  });
+}
+
+export {
+  DEFAULT_PING_INTERVAL_MS,
+  DEFAULT_PONG_TIMEOUT_MS,
+  DEFAULT_STALE_AFTER_MS,
+  handlePingCheck,
+  handleSweep,
+  type PingCheckParams,
+  type PingCheckResult,
+  type SweepParams,
+  type SweepResult,
+};
+
+/**
+ * Builds a {@link HandlerDeps} from the current `process.env`.
+ *
+ * Exposed so tests can construct production-shaped deps without re-running
+ * the env parsing.
+ */
+export function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): HandlerDeps {
+  const cfg = loadServerConfigFromLambdaEnv(env as LambdaConfigEnv);
+  const tables = tablesConfigFromEnv(env);
+  const region = typeof env.AWS_REGION === 'string' ? env.AWS_REGION : undefined;
+  const dynamo =
+    region !== undefined ? createDynamoDocumentClient({ region }) : createDynamoDocumentClient({});
+  let managementApi: ApiGatewayManagementApi | null = null;
+  const managementUrl = typeof env.MANAGEMENT_URL === 'string' ? env.MANAGEMENT_URL : undefined;
+  if (managementUrl !== undefined) {
+    managementApi = new ApiGatewayManagementApi({ endpoint: managementUrl });
+  }
+  const motd = cfg.motdLines.length > 0 ? new StaticMotdProvider(cfg.motdLines) : EmptyMotdProvider;
+  const messages = bindMessageStore(cfg);
+  return { dynamo, tables, serverConfig: cfg, motd, managementApi, messages };
+}
+
+function tablesConfigFromEnv(env: NodeJS.ProcessEnv): TablesConfig {
+  const out = {} as TablesConfig;
+  for (const logical of Object.keys(TABLE_KEYS) as Array<keyof typeof TABLE_KEYS>) {
+    const envName = `${logical.toUpperCase()}_TABLE`;
+    const physical = env[envName];
+    if (typeof physical !== 'string') {
+      throw new Error(`Missing env var ${envName} (table name for ${logical})`);
+    }
+    out[logical] = physical;
+  }
+  return out;
+}

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,67 @@
+/**
+ * @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 {
+  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();
+}