@friggframework/core 2.0.0-next.112 → 2.0.0-next.114

package/core/create-handler.js

@@ -2,7 +2,16 @@
 // REMOVING FOR NOW UNTIL WE ADD WEBPACK BACK IN
 // require('source-map-support').install();
 
-const { initDebugLog, flushDebugLog } = require('../logs');
+const { getLogger, toSanitizedSurrogate } = require('../logs');
+const {
+    summarizeLambdaEvent,
+    toScopeInvocation,
+    toRequestDetails,
+} = require('../logs/summarize-event');
+const {
+    runInvocationScope,
+    DEFAULT_FLUSH_TIMEOUT_MS,
+} = require('./invocation-scope');
 const { secretsToEnv } = require('./secrets-to-env');
 const { parametersToEnv } = require('./parameters-to-env');
 const {
@@ -11,123 +20,7 @@ const {
     getPluginTelemetrySubscribers,
 } = require('../telemetry/telemetry-runtime');
 
-// Bounds the tail latency telemetry adds to every warm invocation. Kept low so
-// an unreachable OTLP endpoint (e.g. a VPC Lambda with no NAT/egress) costs at
-// most this, not multiple seconds. Override with OTEL_FLUSH_TIMEOUT_MS.
-const DEFAULT_FLUSH_TIMEOUT_MS =
-    Number(process.env.OTEL_FLUSH_TIMEOUT_MS) || 500;
-
-/**
- * Fold the invocation's buffered usage counters into the durable store, then
- * clear the buffer. On an SQS redelivery (ApproximateReceiveCount > 1) we
- * DISCARD rather than flush — the prior delivery already counted, and the usage
- * accuracy contract is "approximate, skip obvious redeliveries". Fully guarded.
- */
-async function flushUsageRollup(subscriber, eventSummary, shouldUseDatabase) {
-    if (!subscriber) return;
-    try {
-        // Persisting usage requires a DB connection. DB-free handlers (e.g. the
-        // webhook-receipt route) never called connectPrisma, so drop the buffer
-        // instead of issuing a connectionless Prisma write.
-        if (!shouldUseDatabase) {
-            subscriber.discard();
-            return;
-        }
-        // Discard only when EVERY record in the batch is a redelivery. The buffer
-        // is invocation-scoped (not per-message), so discarding on *any*
-        // redelivery would drop the fresh records' counts too (silent
-        // under-count). For a mixed batch we flush: preserving fresh counts and
-        // at worst re-counting the one redelivered record is strictly better than
-        // losing fresh data for an approximate store. (Integration queue workers
-        // are batchSize:1 today, so a batch is all-or-nothing; this keeps it
-        // correct if batchSize is ever raised.)
-        const records = Array.isArray(eventSummary?.records)
-            ? eventSummary.records
-            : [];
-        const allRedelivered =
-            records.length > 0 &&
-            records.every((r) => Number(r.receiveCount) > 1);
-        if (allRedelivered) {
-            subscriber.discard();
-        } else {
-            await subscriber.flush();
-        }
-    } catch (_) {
-        // Usage rollup must never break the handler.
-    }
-}
-
-/**
- * Flush telemetry before the Lambda container freezes. Because
- * `callbackWaitsForEmptyEventLoop=false` (below) stops the event loop the moment
- * the handler returns, OTel's timer-driven batch processors would never fire —
- * so spans/metrics must be flushed synchronously here. Bounded by a timeout so a
- * stalled exporter can never block the response, and fully guarded so a flush
- * failure never breaks the handler.
- */
-async function flushTelemetry(telemetry, timeoutMs) {
-    try {
-        if (
-            !telemetry ||
-            typeof telemetry.isEnabled !== 'function' ||
-            !telemetry.isEnabled()
-        ) {
-            return;
-        }
-        let timer;
-        const deadline = new Promise((resolve) => {
-            timer = setTimeout(resolve, timeoutMs);
-        });
-        try {
-            await Promise.race([
-                Promise.resolve(telemetry.forceFlush()),
-                deadline,
-            ]);
-        } finally {
-            clearTimeout(timer);
-        }
-    } catch (_) {
-        // Telemetry flush must never break the handler.
-    }
-}
-
-// Best-effort extraction of correlation identifiers from a Lambda event.
-// For SQS: pulls messageIds + parsed event/processId/integrationId from each
-// record body. For HTTP: pulls method+path. Never throws.
-const summarizeLambdaEvent = (event) => {
-    if (!event) return {};
-    if (Array.isArray(event.Records)) {
-        return {
-            source: 'sqs',
-            records: event.Records.map((r) => {
-                let parsed = {};
-                try {
-                    const body = JSON.parse(r.body);
-                    parsed = {
-                        event: body?.event,
-                        processId: body?.data?.processId,
-                        integrationId: body?.data?.integrationId,
-                    };
-                } catch {
-                    // ignore unparseable bodies
-                }
-                return {
-                    messageId: r.messageId,
-                    receiveCount: r.attributes?.ApproximateReceiveCount,
-                    ...parsed,
-                };
-            }),
-        };
-    }
-    if (event.httpMethod || event.requestContext?.http) {
-        return {
-            source: 'http',
-            method: event.httpMethod || event.requestContext?.http?.method,
-            path: event.path || event.rawPath,
-        };
-    }
-    return { source: 'other' };
-};
+const log = getLogger('frigg.handler');
 
 const createHandler = (optionByName = {}) => {
     const {
@@ -157,95 +50,102 @@ const createHandler = (optionByName = {}) => {
         // no-op after the first invocation.
         getPluginTelemetrySubscribers();
 
-        try {
-            console.info(`[createHandler] ${eventName}: handler entry`, {
-                eventName,
-                awsRequestId: context?.awsRequestId,
-                ...eventSummary,
-            });
-
-            initDebugLog(eventName, event);
+        const scopeFields = {
+            requestId: context?.awsRequestId,
+            handlerName: eventName,
+            method: eventSummary.method,
+            route: eventSummary.route,
+            routeKey: eventSummary.routeKey,
+            invocation: toScopeInvocation(eventSummary),
+        };
+        // Path, query keys and header names go only on the entry and failure
+        // records; the logger adds them to the scope's invocation.
+        const requestDetails = toRequestDetails(eventSummary);
 
-            const requestMethod = event.httpMethod;
-            const requestPath = event.path;
-            if (requestMethod && requestPath) {
-                console.info(`${requestMethod} ${requestPath}`);
-            }
+        return runInvocationScope(
+            scopeFields,
+            async () => {
+                try {
+                    log.info('Handler invoked', {
+                        eventName: 'frigg.handler.invoked',
+                        invocation: requestDetails,
+                    });
 
-            // If enabled (i.e. if SECRET_ARN is set in process.env) Fetch secrets from AWS Secrets Manager, and set them as environment variables.
-            await secretsToEnv();
+                    // If enabled (i.e. if SECRET_ARN is set in process.env) Fetch secrets from AWS Secrets Manager, and set them as environment variables.
+                    await secretsToEnv();
 
-            // If enabled (i.e. if SSM_PARAMETER_PREFIX and FRIGG_SSM_OFFLOADED_KEYS are set) fetch offloaded params from SSM Parameter Store into process.env.
-            await parametersToEnv();
+                    // If enabled (i.e. if SSM_PARAMETER_PREFIX and FRIGG_SSM_OFFLOADED_KEYS are set) fetch offloaded params from SSM Parameter Store into process.env.
+                    await parametersToEnv();
 
-            // Lazy-required so DB-free handlers never load the Prisma client.
-            if (shouldUseDatabase) {
-                const { connectPrisma } = require('../database/prisma');
-                await connectPrisma();
-            }
+                    // Lazy-required so DB-free handlers never load the Prisma client.
+                    if (shouldUseDatabase) {
+                        const { connectPrisma } = require('../database/prisma');
+                        await connectPrisma();
+                    }
 
-            // Helps reuse the database connection.  Lowers response times.
-            context.callbackWaitsForEmptyEventLoop = false;
-
-            // Run the Lambda
-            return await method(event, context);
-        } catch (error) {
-            flushDebugLog(error);
-
-            // Don't leak implementation details to end users.
-            if (isUserFacingResponse) {
-                // Allow client-safe errors to pass through with their actual message
-                if (error.isClientSafe === true) {
-                    const statusCode = error.statusCode || 400;
-                    return {
-                        statusCode,
-                        body: JSON.stringify({
-                            error: error.message,
-                        }),
-                    };
-                }
+                    // Helps reuse the database connection.  Lowers response times.
+                    context.callbackWaitsForEmptyEventLoop = false;
+
+                    // Run the Lambda
+                    return await method(event, context);
+                } catch (error) {
+                    // Allow client-safe errors to pass through with their actual message
+                    if (isUserFacingResponse && error.isClientSafe === true) {
+                        const statusCode = error.statusCode || 400;
+                        log.warn('Request rejected', {
+                            eventName: 'frigg.handler.rejected',
+                            statusCode,
+                            error,
+                        });
+                        return {
+                            statusCode,
+                            body: JSON.stringify({
+                                error: error.message,
+                            }),
+                        };
+                    }
 
-                // Hide other errors with generic message
-                return {
-                    statusCode: 500,
-                    body: JSON.stringify({
-                        error: 'An Internal Error Occurred',
-                    }),
-                };
-            }
+                    // Server-to-server: halt errors succeed and won't be
+                    // retried, so the halt itself is the failure record.
+                    if (!isUserFacingResponse && error.isHaltError === true) {
+                        log.error('Handler halted', {
+                            eventName: 'frigg.handler.halted',
+                            invocation: requestDetails,
+                            error,
+                        });
+                        return;
+                    }
 
-            // Handle server-to-server responses.
-
-            // Halt errors are logged but suceed and won't be retried.
-            // Log explicitly — silent suppression here previously made stuck
-            // messages invisible to observability tooling. Include
-            // eventSummary so operators can correlate across concurrent
-            // invocations (processId / messageIds / HTTP path).
-            if (error.isHaltError === true) {
-                console.warn(
-                    `[createHandler] ${eventName}: halt error suppressed (no retry)`,
-                    {
-                        eventName,
-                        errorName: error.name,
-                        errorMessage: error.message,
-                        statusCode: error.statusCode,
-                        ...eventSummary,
+                    log.error('Handler failed', {
+                        eventName: 'frigg.handler.failed',
+                        invocation: requestDetails,
+                        error,
+                    });
+
+                    // Don't leak implementation details to end users.
+                    if (isUserFacingResponse) {
+                        return {
+                            statusCode: 500,
+                            body: JSON.stringify({
+                                error: 'An Internal Error Occurred',
+                            }),
+                        };
                     }
-                );
-                return;
-            }
 
-            // Here we can just rethrow and let AWS build the response.
-            throw error;
-        } finally {
-            // Flush telemetry + usage before the container freezes.
-            await flushTelemetry(activeTelemetry, flushTimeoutMs);
-            await flushUsageRollup(
-                activeUsageRollup,
+                    // The Lambda runtime writes a rethrown error itself, so
+                    // rethrow a sanitized copy (ADR-048 §6 item 11).
+                    throw toSanitizedSurrogate(error);
+                }
+            },
+            {
+                telemetry: activeTelemetry,
+                usageRollup: activeUsageRollup,
                 eventSummary,
-                shouldUseDatabase
-            );
-        }
+                shouldUseDatabase,
+                flushTimeoutMs,
+                context,
+            }
+        );
     };
 };
 

package/core/index.js

@@ -2,5 +2,12 @@ const { Delegate } = require('./Delegate');
 const { Worker } = require('./Worker');
 const { loadInstalledModules } = require('./load-installed-modules');
 const { createHandler } = require('./create-handler');
+const { runInvocationScope } = require('./invocation-scope');
 
-module.exports = { Delegate, Worker, loadInstalledModules, createHandler };
+module.exports = {
+    Delegate,
+    Worker,
+    loadInstalledModules,
+    createHandler,
+    runInvocationScope,
+};

package/core/invocation-scope.js

@@ -0,0 +1,225 @@
+const { runInContext, LOGGER_SCOPE_KEY } = require('../logs/context');
+const { summarizeMessageBody } = require('../logs/summarize-event');
+const { flushSinks, hasFlushableSinks } = require('../logs/logger-runtime');
+
+// Bounds the tail latency telemetry adds to every warm invocation. Kept low so
+// an unreachable OTLP endpoint (e.g. a VPC Lambda with no NAT/egress) costs at
+// most this, not multiple seconds. Override with OTEL_FLUSH_TIMEOUT_MS.
+const DEFAULT_FLUSH_TIMEOUT_MS =
+    Number(process.env.OTEL_FLUSH_TIMEOUT_MS) || 500;
+
+// Time kept back from the Lambda deadline, so a slow flush never becomes a
+// Lambda timeout.
+const FLUSH_MARGIN_MS = 50;
+
+// setTimeout fires at once for a delay above this.
+const MAX_TIMER_MS = 2 ** 31 - 1;
+
+/**
+ * Fold the invocation's buffered usage counters into the durable store, then
+ * clear the buffer. On an SQS redelivery (ApproximateReceiveCount > 1) we
+ * DISCARD rather than flush — the prior delivery already counted, and the usage
+ * accuracy contract is "approximate, skip obvious redeliveries". Fully guarded.
+ */
+async function flushUsageRollup(subscriber, eventSummary, shouldUseDatabase) {
+    if (!subscriber) return;
+    try {
+        // Persisting usage requires a DB connection. DB-free handlers (e.g. the
+        // webhook-receipt route) never called connectPrisma, so drop the buffer
+        // instead of issuing a connectionless Prisma write.
+        if (!shouldUseDatabase) {
+            subscriber.discard();
+            return;
+        }
+        // Discard only when EVERY record in the batch is a redelivery. The buffer
+        // is invocation-scoped (not per-message), so discarding on *any*
+        // redelivery would drop the fresh records' counts too (silent
+        // under-count). For a mixed batch we flush: preserving fresh counts and
+        // at worst re-counting the one redelivered record is strictly better than
+        // losing fresh data for an approximate store. (Integration queue workers
+        // are batchSize:1 today, so a batch is all-or-nothing; this keeps it
+        // correct if batchSize is ever raised.)
+        const records = Array.isArray(eventSummary?.records)
+            ? eventSummary.records
+            : [];
+        const allRedelivered =
+            records.length > 0 &&
+            records.every((r) => Number(r.receiveCount) > 1);
+        if (allRedelivered) {
+            subscriber.discard();
+        } else {
+            await subscriber.flush();
+        }
+    } catch (_) {
+        // Usage rollup must never break the handler.
+    }
+}
+
+function isTelemetryEnabled(telemetry) {
+    try {
+        return Boolean(
+            telemetry &&
+                typeof telemetry.isEnabled === 'function' &&
+                telemetry.isEnabled()
+        );
+    } catch (_) {
+        return false;
+    }
+}
+
+/**
+ * Flush telemetry before the Lambda container freezes. Because
+ * `callbackWaitsForEmptyEventLoop=false` stops the event loop the moment the
+ * handler returns, OTel's timer-driven batch processors would never fire — so
+ * spans/metrics must be flushed here. No timer of its own: the caller bounds it
+ * with `withDeadline`. Fully guarded, so a flush failure never breaks the
+ * handler.
+ */
+async function flushTelemetry(telemetry, { signal } = {}) {
+    if (!isTelemetryEnabled(telemetry) || signal?.aborted) return;
+    try {
+        await telemetry.forceFlush();
+    } catch (_) {
+        // Telemetry flush must never break the handler.
+    }
+}
+
+/**
+ * Run `fn(signal)` for at most `ms`. Owns the only timer and clears it when the
+ * work settles. Aborts the signal at the deadline. Never rejects, and a late
+ * rejection of the work is swallowed.
+ */
+function withDeadline(ms, fn) {
+    const controller = new AbortController();
+    return new Promise((resolve) => {
+        let timer;
+        const finish = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+        timer = setTimeout(() => {
+            controller.abort();
+            finish();
+        }, Math.min(ms, MAX_TIMER_MS));
+        let work;
+        try {
+            work = Promise.resolve(fn(controller.signal));
+        } catch (_) {
+            work = Promise.resolve();
+        }
+        work.then(finish, finish);
+    });
+}
+
+function remainingTimeMs(context) {
+    try {
+        const remaining = context?.getRemainingTimeInMillis?.();
+        return typeof remaining === 'number' ? remaining : Infinity;
+    } catch (_) {
+        return Infinity;
+    }
+}
+
+async function flushInvocation({
+    telemetry,
+    usageRollup,
+    eventSummary,
+    shouldUseDatabase,
+    flushTimeoutMs,
+    context,
+}) {
+    // ADR-048 §11: the deadline is fixed at flush start. The usage rollup
+    // emits no telemetry, so it runs in parallel with no bound of its own.
+    const deadline = Math.min(
+        flushTimeoutMs,
+        remainingTimeMs(context) - FLUSH_MARGIN_MS
+    );
+    await Promise.all([
+        flushUsageRollup(usageRollup, eventSummary, shouldUseDatabase),
+        flushBounded(telemetry, deadline),
+    ]);
+}
+
+function flushBounded(telemetry, deadline) {
+    const flushes = [];
+    if (isTelemetryEnabled(telemetry)) {
+        flushes.push((signal) => flushTelemetry(telemetry, { signal }));
+    }
+    if (hasFlushableSinks()) {
+        flushes.push((signal) => flushSinks({ signal }));
+    }
+    if (!flushes.length || !(deadline > 0)) return undefined;
+    return withDeadline(deadline, (signal) =>
+        Promise.allSettled(flushes.map((flush) => flush(signal)))
+    );
+}
+
+/**
+ * Open the logger scope for one invocation, run `fn` inside it, then flush.
+ * `fields` (requestId, handlerName, method, route, routeKey, invocation, ...)
+ * go into the scope's logger sub-object and never reach the telemetry bus.
+ */
+async function runInvocationScope(fields, fn, opts = {}) {
+    const {
+        telemetry,
+        usageRollup,
+        eventSummary,
+        shouldUseDatabase = true,
+        flushTimeoutMs = DEFAULT_FLUSH_TIMEOUT_MS,
+        context,
+    } = opts;
+    return runInContext({ [LOGGER_SCOPE_KEY]: { ...(fields || {}) } }, async () => {
+        try {
+            return await fn();
+        } finally {
+            // Every step is guarded, so a flush never changes the result.
+            await flushInvocation({
+                telemetry,
+                usageRollup,
+                eventSummary,
+                shouldUseDatabase,
+                flushTimeoutMs,
+                context,
+            });
+        }
+    });
+}
+
+function toCount(value) {
+    const count = Number(value);
+    return value !== undefined && value !== null && Number.isFinite(count)
+        ? count
+        : undefined;
+}
+
+/**
+ * Open the logger scope for one SQS message: messageId, receiveCount and the
+ * Frigg ids the body carries. No flush; the invocation scope owns that.
+ */
+function runMessageScope(record, fn) {
+    const { event, processId, integrationId } = summarizeMessageBody(
+        record?.body
+    );
+    return runInContext(
+        {
+            [LOGGER_SCOPE_KEY]: {
+                messageId: record?.messageId,
+                receiveCount: toCount(record?.attributes?.ApproximateReceiveCount),
+                integrationEvent: event,
+                processId,
+                integrationId,
+            },
+        },
+        fn
+    );
+}
+
+module.exports = {
+    runInvocationScope,
+    runMessageScope,
+    withDeadline,
+    flushTelemetry,
+    flushUsageRollup,
+    FLUSH_MARGIN_MS,
+    DEFAULT_FLUSH_TIMEOUT_MS,
+};

package/core/secrets-to-env.js

@@ -1,5 +1,9 @@
+const { getLogger } = require('../logs');
+
+const log = getLogger('frigg.core.secrets');
+
 const getSecretValue = async () => {
-    console.log('Fetching secrets...');
+    log.debug('Fetching secrets', { eventName: 'frigg.core.secrets.fetching' });
 
     const httpPort = process.env.PARAMETERS_SECRETS_EXTENSION_HTTP_PORT || 2773;
     const url = `http://localhost:${httpPort}/secretsmanager/get?secretId=${encodeURIComponent(
@@ -15,10 +19,7 @@ const getSecretValue = async () => {
     const response = await fetch(url, options);
 
     if (!response.ok) {
-        const json = await response.json().catch((err) => err.message);
-        console.error('Invalid response - response:', JSON.stringify(response));
-        console.error('Invalid response - json:', json);
-        throw new Error(`Invalid ${response.status} response`);
+        throw new Error(`Secrets fetch failed with ${response.status}`);
     }
 
     const result = await response.json();
@@ -44,7 +45,7 @@ const secretsToEnv = async () => {
     if (!process.env.SECRET_ARN) {
         return;
     }
-    console.log('Secrets to env');
+    log.debug('Secrets to env', { eventName: 'frigg.core.secrets.to_env' });
 
     try {
         const secrets = await getSecretValue();

package/database/config.js

@@ -125,16 +125,9 @@ let cachedDbType = null;
  */
 const PRISMA_LOG_LEVEL = process.env.PRISMA_LOG_LEVEL || 'error,warn';
 
-/**
- * Enable Prisma query logging for performance monitoring
- * @type {boolean}
- */
-const PRISMA_QUERY_LOGGING = process.env.PRISMA_QUERY_LOGGING === 'true';
-
 module.exports = {
     getDatabaseType, // Export for testing and direct use
     PRISMA_LOG_LEVEL,
-    PRISMA_QUERY_LOGGING,
 };
 
 /**

package/database/encryption/README.md

@@ -680,7 +680,11 @@ The encryption system uses **fail-fast error handling**:
 
 ### Logging Configuration
 
-Configure log verbosity with `FRIGG_LOG_LEVEL`:
+`FRIGG_LOG_LEVEL` is the one Frigg log level. The level rules, the record
+fields and the redaction rules are in the
+[Logging guide](../../../../docs/guides/LOGGING.md). The encryption logger
+still writes text lines through `console` with the same level names until it
+moves to the structured logger (ADR-048, incremental adoption).
 
 ```bash
 # Production (minimal logging)

package/database/encryption/encryption-schema-registry.js

@@ -9,6 +9,7 @@
  */
 
 const { logger } = require('./logger');
+const { registerDeniedKeys } = require('../../logs/denied-keys');
 
 /**
  * Core encryption schema (immutable - cannot be overridden by custom schemas)
@@ -120,6 +121,7 @@ function registerCustomSchema(schema) {
     }
 
     customSchema = { ...schema };
+    registerDeniedKeys(Object.values(schema).flatMap((config) => config.fields));
     logger.info(
         `Registered custom encryption schema for models: ${Object.keys(customSchema).join(', ')}`
     );
@@ -149,6 +151,7 @@ function extractCredentialFieldsFromModules(moduleDefinitions) {
         }
     }
 
+    registerDeniedKeys(fields);
     return [...new Set(fields)];
 }
 

package/database/encryption/logger.js

@@ -17,9 +17,12 @@ class EncryptionLogger {
         this.minLevel = this._getMinLevel();
     }
 
+    // FRIGG_LOG_LEVEL also takes TRACE and FATAL (ADR-048); this logger has
+    // no such levels, so they map to its nearest ones.
     _getMinLevel() {
-        const level = process.env.FRIGG_LOG_LEVEL || 'INFO';
-        return LOG_LEVELS[level.toUpperCase()] ?? LOG_LEVELS.INFO;
+        const level = (process.env.FRIGG_LOG_LEVEL || 'INFO').trim().toUpperCase();
+        const mapped = { TRACE: 'DEBUG', FATAL: 'ERROR' }[level] ?? level;
+        return LOG_LEVELS[mapped] ?? LOG_LEVELS.INFO;
     }
 
     _shouldLog(level) {