quidproquo-actionprocessor-awslambda 0.1.2 → 0.1.3

package/lib/esm/getActionProcessor/core/metric/getMetricPutActionProcessor.js

@@ -0,0 +1,43 @@
+import { actionResult, MetricActionType, MetricUnit, qpqCoreUtils, } from 'quidproquo-core';
+// Emits the metric as a CloudWatch Embedded Metric Format (EMF) log line: CloudWatch
+// extracts metrics from the function's log stream - no api calls, no extra IAM, no
+// latency on the story. Cost: each unique metricName x dimension-combination is one
+// custom metric (~$0.30/mo) - the standard dimensions are service/environment(/feature),
+// so keep payload dimensions low-cardinality (never per-user / per-request ids).
+const getProcessMetricPut = (qpqConfig) => {
+    // The namespace is the deployed app instance - app/environment(/feature) - mirroring how
+    // every qpq resource name embeds the deployment identity. Apps sharing an account can't
+    // merge same-named metrics, per-developer feature sandboxes (e.g. qpq/docgen/development/jane)
+    // never pollute mainline, and dimensions are reserved for slices WITHIN the deployment
+    // (service + caller-supplied).
+    const application = qpqCoreUtils.getApplicationName(qpqConfig);
+    const environment = qpqCoreUtils.getApplicationModuleEnvironment(qpqConfig);
+    const feature = qpqCoreUtils.getApplicationModuleFeature(qpqConfig);
+    const namespace = `qpq/${application}/${environment}${feature ? `/${feature}` : ''}`;
+    const service = qpqCoreUtils.getApplicationModuleName(qpqConfig);
+    return async ({ metricName, value, unit, dimensions }) => {
+        const allDimensions = {
+            service,
+            ...dimensions,
+        };
+        const emf = {
+            _aws: {
+                Timestamp: Date.now(),
+                CloudWatchMetrics: [
+                    {
+                        Namespace: namespace,
+                        Dimensions: [Object.keys(allDimensions)],
+                        Metrics: [{ Name: metricName, Unit: unit ?? MetricUnit.count }],
+                    },
+                ],
+            },
+            ...allDimensions,
+            [metricName]: value,
+        };
+        console.log(JSON.stringify(emf));
+        return actionResult(void 0);
+    };
+};
+export const getMetricPutActionProcessor = async (qpqConfig) => ({
+    [MetricActionType.Put]: getProcessMetricPut(qpqConfig),
+});

package/lib/esm/getActionProcessor/core/metric/index.d.ts

@@ -0,0 +1,2 @@
+import { ActionProcessorListResolver } from 'quidproquo-core';
+export declare const getMetricActionProcessor: ActionProcessorListResolver;

package/lib/esm/getActionProcessor/core/metric/index.js

@@ -0,0 +1,4 @@
+import { getMetricPutActionProcessor } from './getMetricPutActionProcessor';
+export const getMetricActionProcessor = async (qpqConfig, dynamicModuleLoader) => ({
+    ...(await getMetricPutActionProcessor(qpqConfig, dynamicModuleLoader)),
+});

package/lib/esm/lambdas/dynamicModuleLoader/dynamicModuleLoader.js

@@ -1,5 +1,12 @@
-// @ts-expect-error - Special webpack file injected
-import { qpqDynamicModuleLoader } from 'quidproquo-dynamic-loader';
+// @ts-expect-error - injected at build time by QpqPlugin (webpack virtual module)
+import { qpqConfig, qpqDynamicModuleLoader } from 'quidproquo-dynamic-loader';
+import { loadFederatedStory } from '../../logic/federatedModuleStore';
 export const dynamicModuleLoader = async (qpqFunctionRuntime) => {
+    // Tier 1: federated. undefined means "nothing published for this runtime" -> fall through.
+    const federatedStory = await loadFederatedStory(qpqConfig, qpqFunctionRuntime);
+    if (federatedStory !== undefined) {
+        return federatedStory;
+    }
+    // Tier 2: the statically bundled story (or a fail-fast throw for a thin shell).
     return qpqDynamicModuleLoader(qpqFunctionRuntime);
 };

package/lib/esm/logic/apiGateway/getApiKeyValue.d.ts

@@ -0,0 +1 @@
+export declare const getApiKeyValue: (region: string, apiKeyId: string) => Promise<string | undefined>;

package/lib/esm/logic/apiGateway/getApiKeyValue.js

@@ -0,0 +1,12 @@
+import { APIGatewayClient, GetApiKeyCommand } from '@aws-sdk/client-api-gateway';
+import { createAwsClient } from '../createAwsClient';
+// Fetch a single api key's value by id - keys are read individually (not listed) so the
+// IAM grant can be scoped per-key with tag conditions rather than the /apikeys collection.
+export const getApiKeyValue = async (region, apiKeyId) => {
+    const apiGatewayClient = createAwsClient(APIGatewayClient, { region });
+    const res = await apiGatewayClient.send(new GetApiKeyCommand({
+        apiKey: apiKeyId,
+        includeValue: true,
+    }));
+    return res.value;
+};

package/lib/esm/logic/federatedModuleStore/FederatedModuleLoadError.d.ts

@@ -0,0 +1,10 @@
+export declare enum FederatedModuleLoadErrorCode {
+    unsupportedStoreUrl = "unsupportedStoreUrl",
+    manifestInvalid = "manifestInvalid",
+    containerLoadFailed = "containerLoadFailed",
+    storyNotExported = "storyNotExported"
+}
+export declare class FederatedModuleLoadError extends Error {
+    readonly code: FederatedModuleLoadErrorCode;
+    constructor(code: FederatedModuleLoadErrorCode, message: string);
+}

package/lib/esm/logic/federatedModuleStore/FederatedModuleLoadError.js

@@ -0,0 +1,23 @@
+// Discriminable failures raised inside loadFederatedStory. All of them are ultimately
+// caught there and turned into a fall-back-to-bundled (with a warning) - they exist so
+// logs/backoff can tell WHY a store didn't load, not to crash the request.
+export var FederatedModuleLoadErrorCode;
+(function (FederatedModuleLoadErrorCode) {
+    // Store URL wasn't s3:// or file:// (a config/env mistake).
+    FederatedModuleLoadErrorCode["unsupportedStoreUrl"] = "unsupportedStoreUrl";
+    // manifest.json parsed but is missing required fields (bad/partial publish).
+    FederatedModuleLoadErrorCode["manifestInvalid"] = "manifestInvalid";
+    // A version's files downloaded but the entry didn't expose a valid MF container.
+    FederatedModuleLoadErrorCode["containerLoadFailed"] = "containerLoadFailed";
+    // The manifest exposed the module, but it didn't export the requested story name
+    // (e.g. a story was renamed in the remote but the manifest still lists it).
+    FederatedModuleLoadErrorCode["storyNotExported"] = "storyNotExported";
+})(FederatedModuleLoadErrorCode || (FederatedModuleLoadErrorCode = {}));
+export class FederatedModuleLoadError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'FederatedModuleLoadError';
+    }
+}

package/lib/esm/logic/federatedModuleStore/FederatedModuleStoreManifest.d.ts

@@ -0,0 +1,8 @@
+export interface FederatedModuleStoreManifest {
+    containerName: string;
+    service: string;
+    hash: string;
+    entry: string;
+    files: string[];
+    exposes: Record<string, string>;
+}

package/lib/esm/logic/federatedModuleStore/FederatedModuleStoreManifest.js

@@ -0,0 +1 @@
+export {};

package/lib/esm/logic/federatedModuleStore/index.d.ts

@@ -0,0 +1,4 @@
+export * from './FederatedModuleLoadError';
+export * from './FederatedModuleStoreManifest';
+export * from './loadFederatedStory';
+export * from './sharedPackages';

package/lib/esm/logic/federatedModuleStore/index.js

@@ -0,0 +1,4 @@
+export * from './FederatedModuleLoadError';
+export * from './FederatedModuleStoreManifest';
+export * from './loadFederatedStory';
+export * from './sharedPackages';

package/lib/esm/logic/federatedModuleStore/loadFederatedStory.d.ts

@@ -0,0 +1,3 @@
+import { QPQConfig, QpqFunctionRuntime } from 'quidproquo-core';
+export declare const resetFederatedModuleStoreCache: () => void;
+export declare const loadFederatedStory: <T = any>(qpqConfig: QPQConfig, qpqFunctionRuntime: QpqFunctionRuntime) => Promise<T | undefined>;

package/lib/esm/logic/federatedModuleStore/loadFederatedStory.js

@@ -0,0 +1,246 @@
+import { qpqConfigAwsUtils } from 'quidproquo-config-aws';
+import * as quidproquoCore from 'quidproquo-core';
+import { getFederatedKeyFromQpqFunctionRuntime, qpqCoreUtils } from 'quidproquo-core';
+import * as quidproquoWebserver from 'quidproquo-webserver';
+import * as fs from 'fs';
+import { createRequire } from 'module';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { init, loadRemote, registerRemotes } from '@module-federation/enhanced/runtime';
+import { createAwsClient } from '../createAwsClient';
+import { FederatedModuleLoadError, FederatedModuleLoadErrorCode } from './FederatedModuleLoadError';
+import { FEDERATED_SHARED_PACKAGE_NAMES } from './sharedPackages';
+// How long a resolved state is served before the manifest is re-checked for a new
+// version. Overridable per service (defineFederatedModuleStore recheckMs -> this env).
+// Lower = faster pickup of new publishes at the cost of one small S3 GET per container
+// per interval. The re-check runs in the BACKGROUND so it never blocks a request.
+const DEFAULT_RECHECK_MS = 60_000;
+const getRecheckMs = () => {
+    const raw = process.env.federatedCodeStoreRecheckMs;
+    const parsed = raw ? parseInt(raw, 10) : NaN;
+    return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_RECHECK_MS;
+};
+let resolvedState;
+let recheckAfter = 0;
+let inflightResolve;
+let hostInitialised = false;
+// Test seam - forces the next call to re-resolve the store from env.
+export const resetFederatedModuleStoreCache = () => {
+    resolvedState = undefined;
+    recheckAfter = 0;
+    inflightResolve = undefined;
+};
+// ── Transport ────────────────────────────────────────────────────────────────
+// Returns a function that reads a path RELATIVE to the store (e.g. 'manifest.json'
+// or '<hash>/remoteEntry.js'). Two backends: s3:// for real deploys, file:// for
+// local/dev and tests. The store URL already includes the per-service prefix, so
+// callers pass only the in-service relative path.
+const getFileFetcher = (storeUrl, qpqConfig) => {
+    if (storeUrl.startsWith('s3://')) {
+        const url = new URL(storeUrl);
+        const bucketName = url.host;
+        const keyPrefix = url.pathname.replace(/^\/|\/$/g, '');
+        const region = qpqConfigAwsUtils.getApplicationModuleDeployRegion(qpqConfig);
+        // Pin the owner so a same-name bucket in another account can't be squatted to
+        // serve code we'd then require() with the service role's credentials.
+        const expectedBucketOwner = qpqConfigAwsUtils.getApplicationModuleDeployAccountId(qpqConfig);
+        const s3Client = createAwsClient(S3Client, { region });
+        return async (relativePath) => {
+            const response = await s3Client.send(new GetObjectCommand({
+                Bucket: bucketName,
+                Key: keyPrefix ? `${keyPrefix}/${relativePath}` : relativePath,
+                ExpectedBucketOwner: expectedBucketOwner,
+            }));
+            const bytes = await response.Body?.transformToByteArray();
+            if (!bytes) {
+                throw new FederatedModuleLoadError(FederatedModuleLoadErrorCode.containerLoadFailed, `empty response reading [${relativePath}]`);
+            }
+            return Buffer.from(bytes);
+        };
+    }
+    if (storeUrl.startsWith('file://')) {
+        const baseDirectory = fileURLToPath(storeUrl.endsWith('/') ? storeUrl : `${storeUrl}/`);
+        return async (relativePath) => fs.promises.readFile(path.join(baseDirectory, relativePath));
+    }
+    throw new FederatedModuleLoadError(FederatedModuleLoadErrorCode.unsupportedStoreUrl, `unsupported federated code store url [${storeUrl}]`);
+};
+// "Nothing published yet" is a legitimate not-found: the manifest key is absent
+// (NoSuchKey/NotFound) or the store bucket isn't created yet, which happens normally
+// when a lambda cold-starts between deploy phases (NoSuchBucket). We do NOT include
+// AccessDenied: a permission failure is a real misconfiguration and must surface (as a
+// warning, and be retried) rather than masquerade as 'not published'.
+const isManifestNotFoundError = (error) => {
+    const name = error?.name || '';
+    const code = error?.code || '';
+    return ['NoSuchKey', 'NotFound', 'NoSuchBucket'].includes(name) || code === 'ENOENT';
+};
+// ── Module-federation shared scope ───────────────────────────────────────────
+// The host provides the framework packages to the container's share scope so remote
+// story code resolves the SAME module instances as the bundled runtime. The package
+// list is shared with the remote build so the two can't drift (see sharedPackages).
+const SHARED_LIBS = {
+    'quidproquo-core': quidproquoCore,
+    'quidproquo-webserver': quidproquoWebserver,
+};
+const getHostSharedModules = () => Object.fromEntries(FEDERATED_SHARED_PACKAGE_NAMES.map((name) => [
+    name,
+    {
+        version: '0.0.0',
+        lib: () => SHARED_LIBS[name],
+        shareConfig: { singleton: true, requiredVersion: false },
+    },
+]));
+const ensureHostInitialised = () => {
+    if (hostInitialised) {
+        return;
+    }
+    init({
+        name: 'qpq_federated_host',
+        remotes: [],
+        shared: getHostSharedModules(),
+    });
+    hostInitialised = true;
+};
+// ── Version loading ──────────────────────────────────────────────────────────
+// Downloads a manifest's files (atomically) and registers the container with the MF
+// runtime under a HASH-UNIQUE remote name, so loadRemote can't serve a previous
+// version's module from its cache when the hash changes. Returns the runtime name.
+// This is the step that actually puts a new version's code into effect.
+const loadStoreVersion = async (getFile, manifest) => {
+    const cacheRoot = process.env.federatedCodeStoreCacheDir || '/tmp/qpq-federated-code';
+    const versionDirectory = path.join(cacheRoot, manifest.containerName, manifest.hash);
+    await fs.promises.mkdir(versionDirectory, { recursive: true });
+    await Promise.all(manifest.files.map(async (file) => {
+        const localPath = path.join(versionDirectory, file);
+        // Files are immutable under their hash dir AND only ever appear via the atomic
+        // rename below, so an existing file is always complete and valid - this is what
+        // lets a re-check of an unchanged version skip re-downloading.
+        if (fs.existsSync(localPath)) {
+            return;
+        }
+        const data = await getFile(`${manifest.hash}/${file}`);
+        await fs.promises.mkdir(path.dirname(localPath), { recursive: true });
+        // Write to a temp name then rename: rename is atomic on the same filesystem, so a
+        // crash/timeout mid-write never leaves a truncated file that a later invocation
+        // would trust via the existsSync check above.
+        const tempPath = `${localPath}.${process.pid}.tmp`;
+        await fs.promises.writeFile(tempPath, data);
+        await fs.promises.rename(tempPath, localPath);
+    }));
+    const entryPath = path.join(versionDirectory, manifest.entry);
+    const containerRequire = createRequire(entryPath);
+    const containerModule = containerRequire(entryPath);
+    const container = containerModule[manifest.containerName] ?? containerModule.default ?? containerModule;
+    if (typeof container?.get !== 'function' || typeof container?.init !== 'function') {
+        throw new FederatedModuleLoadError(FederatedModuleLoadErrorCode.containerLoadFailed, `[${manifest.entry}] does not export a module federation container named [${manifest.containerName}]`);
+    }
+    // entryGlobalName is the container's real (build-time) library name; the registered
+    // remote name is hash-unique so each version is a distinct loadRemote key.
+    globalThis[manifest.containerName] = container;
+    ensureHostInitialised();
+    const runtimeName = `${manifest.containerName}__${manifest.hash}`;
+    registerRemotes([
+        {
+            name: runtimeName,
+            entry: entryPath,
+            type: 'global',
+            entryGlobalName: manifest.containerName,
+        },
+    ]);
+    return runtimeName;
+};
+// ── Probe & resolve (the caching state machine) ──────────────────────────────
+// Reads the manifest and decides the current state. If the hash is unchanged from what
+// we already loaded, keeps the existing container (no re-sync). Not-found -> unavailable.
+const probeStore = async (qpqConfig, storeUrl, current) => {
+    const getFile = getFileFetcher(storeUrl, qpqConfig);
+    let manifest;
+    try {
+        manifest = JSON.parse((await getFile('manifest.json')).toString('utf8'));
+    }
+    catch (error) {
+        if (isManifestNotFoundError(error)) {
+            console.log(`federated code store [${storeUrl}] has no manifest - using bundled modules`);
+            return { available: false };
+        }
+        throw error;
+    }
+    if (!manifest?.containerName ||
+        !manifest?.hash ||
+        !manifest?.entry ||
+        !Array.isArray(manifest?.files) ||
+        typeof manifest?.exposes !== 'object' ||
+        manifest.exposes === null) {
+        throw new FederatedModuleLoadError(FederatedModuleLoadErrorCode.manifestInvalid, `invalid manifest in federated code store [${storeUrl}]`);
+    }
+    if (current?.available && current.manifest.hash === manifest.hash) {
+        return current;
+    }
+    const runtimeName = await loadStoreVersion(getFile, manifest);
+    return { available: true, manifest, runtimeName };
+};
+// Resolves the store, re-checking the manifest after the recheck interval. The re-check
+// runs in the background: a stale-but-usable state is served immediately so a request
+// never blocks on S3; only the very first resolve (no state yet) awaits.
+const resolveStore = (qpqConfig, storeUrl) => {
+    if (resolvedState && Date.now() < recheckAfter) {
+        return Promise.resolve(resolvedState);
+    }
+    if (!inflightResolve) {
+        inflightResolve = probeStore(qpqConfig, storeUrl, resolvedState)
+            .then((state) => {
+            resolvedState = state;
+            recheckAfter = Date.now() + getRecheckMs();
+            return state;
+        })
+            .catch((error) => {
+            // Back off and keep serving whatever we had (or unavailable). Surfaced as a
+            // warning so real errors (e.g. AccessDenied) are visible, not silent.
+            console.warn('federated code store check failed - keeping current modules', error);
+            recheckAfter = Date.now() + getRecheckMs();
+            resolvedState = resolvedState ?? { available: false };
+            return resolvedState;
+        })
+            .finally(() => {
+            inflightResolve = undefined;
+        });
+    }
+    // Serve the stale state instantly while the refresh happens; only block if we have
+    // nothing yet.
+    return resolvedState ? Promise.resolve(resolvedState) : inflightResolve;
+};
+// ── Public entry ─────────────────────────────────────────────────────────────
+// Called by dynamicModuleLoader for every story load. Returns the story function, or
+// undefined to signal "use the bundled module" (no store, nothing published, runtime
+// not exposed, or any error - availability always wins over federation).
+export const loadFederatedStory = async (qpqConfig, qpqFunctionRuntime) => {
+    const storeUrl = process.env.federatedCodeStoreUrl;
+    if (!storeUrl) {
+        return undefined;
+    }
+    try {
+        const storeState = await resolveStore(qpqConfig, storeUrl);
+        if (!storeState.available) {
+            return undefined;
+        }
+        const federatedKey = getFederatedKeyFromQpqFunctionRuntime(qpqFunctionRuntime);
+        const exposePath = storeState.manifest.exposes[federatedKey];
+        if (!exposePath) {
+            console.warn(`federated code store has no module for [${federatedKey}] - using the bundled module`);
+            return undefined;
+        }
+        const remoteModule = await loadRemote(`${storeState.runtimeName}/${exposePath}`);
+        const storyName = qpqCoreUtils.getStoryNameFromQpqFunctionRuntime(qpqFunctionRuntime);
+        const story = remoteModule?.[storyName];
+        if (!story) {
+            throw new FederatedModuleLoadError(FederatedModuleLoadErrorCode.storyNotExported, `story [${storyName}] is not exported from federated module [${exposePath}]`);
+        }
+        return story;
+    }
+    catch (error) {
+        // Availability first: a broken store must never take the service down
+        console.warn('federated module load failed - using the bundled module', error);
+        return undefined;
+    }
+};

package/lib/esm/logic/federatedModuleStore/sharedPackages.d.ts

@@ -0,0 +1 @@
+export declare const FEDERATED_SHARED_PACKAGE_NAMES: readonly ["quidproquo-core", "quidproquo-webserver"];

package/lib/esm/logic/federatedModuleStore/sharedPackages.js

@@ -0,0 +1,7 @@
+// The framework packages the lambda host provides to the module-federation share
+// scope, so a federated remote resolves the SAME module instances as the host
+// (instanceof checks and module-level state stay coherent). Single source of truth
+// for BOTH the host runtime (loadFederatedStory getHostSharedModules) and the
+// remote build (quidproquo-deploy-webpack getWebpackConfigForQpqRemote) — the two
+// lists must never drift, or the remote would silently bundle its own copy.
+export const FEDERATED_SHARED_PACKAGE_NAMES = ['quidproquo-core', 'quidproquo-webserver'];

package/lib/esm/logic/index.d.ts

@@ -1 +1,2 @@
 export * from './cognito';
+export * from './federatedModuleStore';

package/lib/esm/logic/index.js

@@ -1 +1,2 @@
 export * from './cognito';
+export * from './federatedModuleStore';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quidproquo-actionprocessor-awslambda",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "",
   "main": "./lib/commonjs/index.js",
   "module": "./lib/esm/index.js",
@@ -35,6 +35,7 @@
   "dependencies": {
     "@ai-sdk/amazon-bedrock": "^5.0.11",
     "@aws-sdk/client-acm": "^3.744.0",
+    "@module-federation/enhanced": "0.18.2",
     "@aws-sdk/client-api-gateway": "^3.744.0",
     "@aws-sdk/client-apigatewaymanagementapi": "^3.744.0",
     "@aws-sdk/client-cloudformation": "^3.744.0",
@@ -59,10 +60,10 @@
     "lodash": "^4.17.21",
     "node-cache": "^5.1.2",
     "node-match-path": "^0.6.3",
-    "quidproquo-actionprocessor-js": "0.1.2",
-    "quidproquo-config-aws": "0.1.2",
-    "quidproquo-core": "0.1.2",
-    "quidproquo-webserver": "0.1.2"
+    "quidproquo-actionprocessor-js": "0.1.3",
+    "quidproquo-config-aws": "0.1.3",
+    "quidproquo-core": "0.1.3",
+    "quidproquo-webserver": "0.1.3"
   },
   "devDependencies": {
     "@types/busboy": "^1.5.0",
@@ -70,7 +71,7 @@
     "@types/lodash": "^4.14.194",
     "@types/node": "^22.13.13",
     "esbuild": "^0.25.8",
-    "quidproquo-tsconfig": "0.1.2",
+    "quidproquo-tsconfig": "0.1.3",
     "typescript": "^5.8.2"
   }
 }

package/lib/commonjs/logic/apiGateway/getApiKeys.d.ts

@@ -1,2 +0,0 @@
-import { ApiKey } from 'quidproquo-webserver';
-export declare const getApiKeys: (region: string, ...keyNames: string[]) => Promise<ApiKey[]>;

package/lib/esm/logic/apiGateway/getApiKeys.d.ts

@@ -1,2 +0,0 @@
-import { ApiKey } from 'quidproquo-webserver';
-export declare const getApiKeys: (region: string, ...keyNames: string[]) => Promise<ApiKey[]>;

package/lib/esm/logic/apiGateway/getApiKeys.js

@@ -1,17 +0,0 @@
-import { APIGatewayClient, GetApiKeysCommand } from '@aws-sdk/client-api-gateway';
-import { createAwsClient } from '../createAwsClient';
-export const getApiKeys = async (region, ...keyNames) => {
-    const apiGatewayClient = createAwsClient(APIGatewayClient, { region });
-    const input = {
-        includeValues: true,
-        limit: 500,
-    };
-    const res = await apiGatewayClient.send(new GetApiKeysCommand(input));
-    return (res.items
-        ?.filter((i) => keyNames.indexOf(i.name) >= 0)
-        .map((i) => ({
-        name: i.name,
-        value: i.value,
-        description: i.description,
-    })) || []);
-};