serverless-ircd 0.1.0 → 0.3.0

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

@@ -0,0 +1,330 @@
+/**
+ * `$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 AccountStore,
+  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;
+  /**
+   * SASL account verification source. When omitted the actor runs with
+   * `ctx.accounts` undefined so `AUTHENTICATE PLAIN` fails with `904`
+   * — preserves the behaviour of callers that have not opted in.
+   */
+  accounts?: AccountStore;
+  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 } : {}),
+    ...(params.accounts !== undefined ? { accounts: params.accounts } : {}),
+  });
+
+  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,48 @@
+/**
+ * `$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, the nick
+ * reservation if any, and broadcasts a `QUIT` line to every peer sharing
+ * a channel with the disconnecting connection. Idempotent: every step
+ * tolerates a missing row.
+ */
+
+import type { ApiGatewayManagementApi } from '@aws-sdk/client-apigatewaymanagementapi';
+import type { DynamoDBDocumentClient } from '@aws-sdk/lib-dynamodb';
+import { type PostToConnection, 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;
+  /**
+   * Backend used to push the `QUIT` fanout to peers. `null` skips the
+   * fanout (the socket is already gone, but peers still need the QUIT
+   * line so their rosters prune the ghost member).
+   */
+  managementApi?: ApiGatewayManagementApi | PostToConnection | null;
+  /**
+   * QUIT reason advertised to peers on fanout. Defaults to
+   * `'Client Quit'` (the same default the QUIT reducer uses when a
+   * client sends `QUIT` with no reason).
+   */
+  quitMessage?: string;
+}
+
+/**
+ * Cleans up the connection state and broadcasts QUIT to shared-channel
+ * peers. 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,
+    params.managementApi ?? null,
+    params.quitMessage,
+  );
+}

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

@@ -0,0 +1,293 @@
+/**
+ * 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 {
+  type AccountStore,
+  EmptyMotdProvider,
+  type MessageStore,
+  type MotdProvider,
+  type ParsedServerConfig,
+  StaticMotdProvider,
+} from '@serverless-ircd/irc-core';
+import { resolveAccountStore } from '../account-store.js';
+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;
+  /**
+   * SASL account verification source bound to every actor. Constructed
+   * once per cold start (memoised via {@link cachedDeps}) so it survives
+   * across warm Lambda invocations. `undefined` when no accounts are
+   * configured (the default) so `ctx.accounts` stays unset.
+   */
+  accounts?: AccountStore;
+}
+
+/**
+ * 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;
+
+/**
+ * In-flight cold-start build. `buildDepsFromEnv` is async (it scans the
+ * `Accounts` DynamoDB table for SASL credentials), so under concurrent
+ * warm-up two events could race past the `cachedDeps` check and each
+ * trigger a full scan. Memoising the promise guarantees the scan runs
+ * exactly once per cold start.
+ */
+let cachedDepsPromise: Promise<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) {
+    if (cachedDepsPromise === undefined) {
+      cachedDepsPromise = buildDepsFromEnv();
+    }
+    cachedDeps = await cachedDepsPromise;
+    cachedDepsPromise = undefined;
+  }
+  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,
+        quitMessage: deps.serverConfig.quitMessage,
+      });
+      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,
+          ...(deps.accounts !== undefined ? { accounts: deps.accounts } : {}),
+          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;
+  cachedDepsPromise = 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) {
+    if (cachedDepsPromise === undefined) {
+      cachedDepsPromise = buildDepsFromEnv();
+    }
+    cachedDeps = await cachedDepsPromise;
+    cachedDepsPromise = undefined;
+  }
+  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) {
+    if (cachedDepsPromise === undefined) {
+      cachedDepsPromise = buildDepsFromEnv();
+    }
+    cachedDeps = await cachedDepsPromise;
+    cachedDepsPromise = undefined;
+  }
+  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. Async because it scans the `Accounts` DynamoDB table
+ * (via {@link resolveAccountStore}) to pre-load SASL credentials at cold
+ * start — the {@link AccountStore} port is synchronous, so the scan must
+ * complete before any reducer calls `verify`.
+ */
+export async function buildDepsFromEnv(env: NodeJS.ProcessEnv = process.env): Promise<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);
+  const accounts = await resolveAccountStore(dynamo, tables.Accounts, cfg);
+  return {
+    dynamo,
+    tables,
+    serverConfig: cfg,
+    motd,
+    managementApi,
+    messages,
+    ...(accounts !== undefined ? { accounts } : {}),
+  };
+}
+
+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;
+}