serverless-ircd 0.3.0 → 0.5.0

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

@@ -19,10 +19,15 @@ import {
   type IdFactory,
   type MessageStore,
   type MotdProvider,
+  type MtlsIdentityProvider,
+  type NickHistoryStore,
   type ParsedServerConfig,
+  type ServerConfig,
   SystemClock,
   UuidIdFactory,
+  type WsFrameMode,
   createConnection,
+  frameToLines,
 } from '@serverless-ircd/irc-core';
 import { type ActorChannelAccess, ConnectionActor } from '@serverless-ircd/irc-server';
 import { AwsRuntime, type AwsRuntimeHandlers, type PostToConnection } from '../aws-runtime.js';
@@ -31,8 +36,18 @@ import {
   type MarshalledConnection,
   unmarshalConnection,
 } from '../serialize.js';
+import { AwsStats } from '../stats.js';
 import type { TablesConfig } from '../tables.js';
 
+/**
+ * Wall-clock timestamp captured at this Lambda isolate's first module load
+ * (cold start). Used as the `uptimeStartedAt` anchor for {@link AwsStats}
+ * so `STATS u` reports uptime for the current isolate. A deployment-wide
+ * uptime would require a persistent record (future work); for now each
+ * isolate reports its own.
+ */
+const LAMBDA_STARTUP_AT = Date.now();
+
 /** Parameters accepted by {@link handleDefault}. */
 export interface DefaultParams {
   dynamo: DynamoDBDocumentClient;
@@ -53,6 +68,30 @@ export interface DefaultParams {
    * — preserves the behaviour of callers that have not opted in.
    */
   accounts?: AccountStore;
+  /**
+   * mTLS client-cert identity source for SASL EXTERNAL. When omitted the
+   * actor runs with `ctx.mtlsIdentity` undefined so `AUTHENTICATE EXTERNAL`
+   * fails with `904` — preserves the behaviour of callers that have not
+   * opted in.
+   *
+   * AWS APIGW custom-domain mTLS setup:
+   * 1. Upload a PEM trust store to S3 (the CA bundle clients must present).
+   * 2. Create a custom domain with `mutualTlsAuthentication` pointing at the
+   *    S3 trust store URI.
+   * 3. Map the custom domain to the WebSocket API stage.
+   * 4. The `$connect` event's `requestContext.identity.clientCertSubjectDN`
+   *    carries the verified cert subject — capture it at connect time and
+   *    persist it alongside the connection row, then construct an
+   *    {@link MtlsIdentityProvider} that resolves it by connection ID.
+   */
+  mtlsIdentity?: MtlsIdentityProvider;
+  /**
+   * Nick-history source for the `WHOWAS` command. When omitted the actor
+   * runs with `ctx.history` undefined so `WHOWAS` always returns
+   * `406`+`369` — preserves the behaviour of callers that have not opted
+   * in. A DynamoDB-backed persistent variant is a documented follow-up.
+   */
+  history?: NickHistoryStore;
   managementApi: ApiGatewayManagementApi | PostToConnection | null;
   /** Injected for tests; defaults to {@link SystemClock}. */
   clock?: Clock;
@@ -60,6 +99,12 @@ export interface DefaultParams {
   ids?: IdFactory;
   /** Optional management endpoint URL used when constructing a default client. */
   managementEndpoint?: string;
+  /**
+   * Config-reload source for `REHASH`. When omitted the runtime's
+   * `reloadConfig` rejects so the actor emits a graceful error-suffixed
+   * `382` and retains the prior config.
+   */
+  configLoader?: () => Promise<ServerConfig>;
 }
 
 /**
@@ -86,6 +131,12 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
   const persisted = result.Item as unknown as MarshalledConnection;
   const state = unmarshalConnection(persisted);
 
+  // Recover the IRCv3 WebSocket frame mode persisted at `$connect`.
+  // Absent = legacy (no subprotocol negotiated). Drives both the inbound
+  // line-framing transport (spec: one IRC message per frame, never split)
+  // and the outbound delivery shape (spec: one postToConnection per line).
+  const wsMode: WsFrameMode = persisted.wsMode ?? 'legacy';
+
   // Mark this frame's activity.
   state.lastSeen = clock.now();
 
@@ -98,8 +149,13 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
       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).
+      // No-op: a Lambda `$default` invocation cannot close its own APIGW
+      // socket. The canonical teardown is the `$disconnect` route (which
+      // fires when APIGW observes the close) plus the sweeper/ping-checker
+      // for connections that vanish without one. The actor's state
+      // mutations (nick release, roster deltas) are persisted below before
+      // this invocation returns, so the eventual `$disconnect` completes
+      // the fanout. See docs/AWS-Deployment.md §14.1.
     },
     snapshot: () => state,
   };
@@ -110,6 +166,7 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
     handlers,
     managementApi: params.managementApi,
     clock,
+    ...(params.configLoader !== undefined ? { configLoader: params.configLoader } : {}),
   });
 
   const channelAccess = new LambdaChannelAccess(runtime, clock.now());
@@ -119,11 +176,24 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
     runtime,
     channels: channelAccess,
     serverConfig: params.serverConfig,
+    configSource: 'Secrets Manager',
     clock,
     ids,
     motd: params.motd,
+    transport: { feed: (chunk) => frameToLines(chunk, wsMode) },
+    // AwsStats Scans Connections + ChannelMeta for LUSERS/STATS.
+    // `uptimeStartedAt` is captured at the Lambda's cold start so `STATS u`
+    // reports per-isolate uptime; a deployment-wide uptime would require a
+    // persistent record (future work).
+    stats: new AwsStats({
+      dynamo: params.dynamo,
+      tables: params.tables,
+      uptimeStartedAt: LAMBDA_STARTUP_AT,
+    }),
     ...(params.messages !== undefined ? { messages: params.messages } : {}),
     ...(params.accounts !== undefined ? { accounts: params.accounts } : {}),
+    ...(params.mtlsIdentity !== undefined ? { mtlsIdentity: params.mtlsIdentity } : {}),
+    ...(params.history !== undefined ? { history: params.history } : {}),
   });
 
   try {
@@ -139,13 +209,12 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
   await persistState(params.dynamo, params.tables, params.connectionId, state, clock.now());
 
   // In production, deliver outbound bytes back to the caller via APIGW.
+  // Spec-mode connections (text/binary.ircv3.net) receive exactly one IRC
+  // line per `postToConnection` (no trailing CRLF); legacy connections
+  // receive every line CRLF-joined in a single message.
   if (params.managementApi !== null && outbound.length > 0) {
-    const data = outbound.join('\r\n');
     try {
-      await params.managementApi.postToConnection({
-        ConnectionId: params.connectionId,
-        Data: data,
-      });
+      await postOutbound(params.managementApi, params.connectionId, outbound, wsMode);
     } catch {
       // The handler still returns 200 — the actor's mutations are
       // persisted; the caller just didn't see the reply this frame.
@@ -154,6 +223,28 @@ export async function handleDefault(params: DefaultParams): Promise<{ statusCode
   return { statusCode: 200 };
 }
 
+/**
+ * Delivers `lines` to `connectionId` via APIGW according to `mode`:
+ *   - `legacy` — all lines joined with `\r\n` in a single `postToConnection`.
+ *   - `spec-text` / `spec-binary` — one `postToConnection` per line, no
+ *     trailing CRLF (the IRCv3 WebSocket contract: one IRC message per
+ *     WebSocket message).
+ */
+async function postOutbound(
+  api: ApiGatewayManagementApi | PostToConnection,
+  connectionId: string,
+  lines: string[],
+  mode: WsFrameMode,
+): Promise<void> {
+  if (mode === 'legacy') {
+    await api.postToConnection({ ConnectionId: connectionId, Data: lines.join('\r\n') });
+    return;
+  }
+  for (const line of lines) {
+    await api.postToConnection({ ConnectionId: connectionId, Data: line });
+  }
+}
+
 /**
  * Writes the actor's mutated `state` back to the Connections row.
  *

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

@@ -16,10 +16,14 @@ import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
 import {
   type AccountStore,
   EmptyMotdProvider,
+  InMemoryNickHistoryStore,
   type MessageStore,
   type MotdProvider,
+  type NickHistoryStore,
   type ParsedServerConfig,
+  type ServerConfig,
   StaticMotdProvider,
+  SystemClock,
 } from '@serverless-ircd/irc-core';
 import { resolveAccountStore } from '../account-store.js';
 import { type LambdaConfigEnv, loadServerConfigFromLambdaEnv } from '../config-loader.js';
@@ -29,6 +33,13 @@ import { TABLE_KEYS, type TablesConfig } from '../tables.js';
 import { handleConnect } from './connect.js';
 import { handleDefault } from './default.js';
 import { handleDisconnect } from './disconnect.js';
+import {
+  type NlbStreamEvent,
+  type NlbStreamParams,
+  type NlbStreamResponse,
+  deriveNlbConnectionId,
+  handleNlbStream,
+} from './nlb-stream.js';
 import {
   DEFAULT_PING_INTERVAL_MS,
   DEFAULT_PONG_TIMEOUT_MS,
@@ -50,7 +61,20 @@ export interface WebSocketEvent {
     connectionId: string;
     domainName?: string;
     stage?: string;
+    /**
+     * Source IP of the connecting client. APIGW populates
+     * `requestContext.identity.sourceIp` on every `$connect`. Carried on
+     * the event type so the (currently deferred) per-IP admission gate
+     * can consume it without reshaping the handler signature.
+     */
+    identity?: { sourceIp?: string };
   };
+  /**
+   * Request headers. APIGW populates `event.headers` on every route; the
+   * `$connect` upgrade carries the client's `Sec-WebSocket-Protocol` offer
+   * here so the handler can negotiate the IRCv3 subprotocol.
+   */
+  headers?: Record<string, string>;
   body?: string;
 }
 
@@ -58,6 +82,12 @@ export interface WebSocketEvent {
 export interface LambdaResponse {
   statusCode: number;
   body?: string;
+  /**
+   * Response headers. The `$connect` route sets `Sec-WebSocket-Protocol`
+   * to echo the agreed IRCv3 subprotocol back to the client; the CDK
+   * integration-response maps it onto the WebSocket handshake.
+   */
+  headers?: Record<string, string>;
 }
 
 /** Injectable dependencies. Tests construct one of these to bypass env loading. */
@@ -81,13 +111,31 @@ export interface HandlerDeps {
    * configured (the default) so `ctx.accounts` stays unset.
    */
   accounts?: AccountStore;
+  /**
+   * Nick-history source bound to every actor. Constructed once per cold
+   * start (memoised via {@link cachedDeps}) as an in-memory store so it
+   * survives across warm Lambda invocations. A DynamoDB-backed persistent
+   * variant is a documented follow-up.
+   */
+  history?: NickHistoryStore;
+  /**
+   * Config-reload source for `REHASH` — re-invokes the Lambda env config
+   * loader (Secrets Manager / SSM / env vars). Bound once per cold start;
+   * each `REHASH` re-reads the live env so rotated oper creds / MOTD take
+   * effect without a redeploy. When omitted the actor's graceful failure
+   * path applies (error-suffixed `382`).
+   */
+  configLoader?: () => Promise<ServerConfig>;
 }
 
 /**
  * Strongly-typed event discriminated by routeKey. Useful for tests that
  * construct events directly.
  */
-export type ConnectEvent = { requestContext: { routeKey: '$connect'; connectionId: string } };
+export type ConnectEvent = {
+  requestContext: { routeKey: '$connect'; connectionId: string };
+  headers?: Record<string, string>;
+};
 export type DisconnectEvent = {
   requestContext: { routeKey: '$disconnect'; connectionId: string };
 };
@@ -132,14 +180,25 @@ export const handler = async (event: WebSocketEvent): Promise<LambdaResponse> =>
 export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promise<LambdaResponse> {
   const connId = event.requestContext.connectionId;
   switch (event.requestContext.routeKey) {
-    case '$connect':
-      await handleConnect({
+    case '$connect': {
+      const outcome = await handleConnect({
         dynamo: deps.dynamo,
         tables: deps.tables,
         connectionId: connId,
         serverConfig: deps.serverConfig,
+        secWebSocketProtocol: event.headers?.['Sec-WebSocket-Protocol'] ?? null,
       });
-      return { statusCode: 200 };
+      if (outcome.admitted) {
+        if (outcome.subprotocol !== null) {
+          return {
+            statusCode: 200,
+            headers: { 'Sec-WebSocket-Protocol': outcome.subprotocol },
+          };
+        }
+        return { statusCode: 200 };
+      }
+      return { statusCode: outcome.statusCode, body: outcome.reason };
+    }
 
     case '$disconnect':
       await handleDisconnect({
@@ -165,6 +224,8 @@ export async function dispatch(event: WebSocketEvent, deps: HandlerDeps): Promis
           motd: deps.motd,
           messages: deps.messages,
           ...(deps.accounts !== undefined ? { accounts: deps.accounts } : {}),
+          ...(deps.history !== undefined ? { history: deps.history } : {}),
+          ...(deps.configLoader !== undefined ? { configLoader: deps.configLoader } : {}),
           managementApi: deps.managementApi,
         });
         return result;
@@ -245,6 +306,43 @@ export {
   type SweepResult,
 };
 
+/**
+ * Lambda entry for the NLB TCP+TLS streaming target. Wired
+ * to the NLB target group in the CDK stack. Shares the cached
+ * {@link HandlerDeps} with the wss {@link handler} — same tables, same
+ * config, same management API (when available). Each NLB client chunk
+ * arrives as one invocation; the handler returns the outbound bytes for
+ * the NLB to stream back over the held-open TCP connection.
+ */
+export async function nlbStreamHandler(event: NlbStreamEvent): Promise<NlbStreamResponse> {
+  if (cachedDeps === undefined) {
+    if (cachedDepsPromise === undefined) {
+      cachedDepsPromise = buildDepsFromEnv();
+    }
+    cachedDeps = await cachedDepsPromise;
+    cachedDepsPromise = undefined;
+  }
+  const deps = cachedDeps;
+  return handleNlbStream(event, {
+    dynamo: deps.dynamo,
+    tables: deps.tables,
+    serverConfig: deps.serverConfig,
+    motd: deps.motd,
+    messages: deps.messages,
+    managementApi: deps.managementApi,
+    ...(deps.accounts !== undefined ? { accounts: deps.accounts } : {}),
+    ...(deps.history !== undefined ? { history: deps.history } : {}),
+  });
+}
+
+export {
+  handleNlbStream,
+  deriveNlbConnectionId,
+  type NlbStreamEvent,
+  type NlbStreamParams,
+  type NlbStreamResponse,
+};
+
 /**
  * Builds a {@link HandlerDeps} from the current `process.env`.
  *
@@ -267,7 +365,12 @@ export async function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): Pr
   }
   const motd = cfg.motdLines.length > 0 ? new StaticMotdProvider(cfg.motdLines) : EmptyMotdProvider;
   const messages = bindMessageStore(cfg);
+  const history = new InMemoryNickHistoryStore(SystemClock);
   const accounts = await resolveAccountStore(dynamo, tables.Accounts, cfg);
+  // REHASH reload source: re-read the live env so a rotated oper password
+  // or MOTD takes effect on the next REHASH without a redeploy.
+  const configLoader = async (): Promise<ServerConfig> =>
+    loadServerConfigFromLambdaEnv(env as LambdaConfigEnv);
   return {
     dynamo,
     tables,
@@ -275,6 +378,8 @@ export async function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): Pr
     motd,
     managementApi,
     messages,
+    history,
+    configLoader,
     ...(accounts !== undefined ? { accounts } : {}),
   };
 }