@friggframework/core 2.0.0--canary.652.b14f3b5.0 → 2.0.0--canary.654.42e42b2.0

package/core/invocation-scope.js

@@ -0,0 +1,224 @@
+const { runInContext } = 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: usage first and unbounded, then one deadline for the rest.
+    await flushUsageRollup(usageRollup, eventSummary, shouldUseDatabase);
+
+    const flushes = [];
+    if (isTelemetryEnabled(telemetry)) {
+        flushes.push((signal) => flushTelemetry(telemetry, { signal }));
+    }
+    if (hasFlushableSinks()) {
+        flushes.push((signal) => flushSinks({ signal }));
+    }
+    if (!flushes.length) return;
+
+    const deadline = Math.min(
+        flushTimeoutMs,
+        remainingTimeMs(context) - FLUSH_MARGIN_MS
+    );
+    if (!(deadline > 0)) return;
+    await 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({ log: { ...(fields || {}) } }, async () => {
+        try {
+            return await fn();
+        } finally {
+            try {
+                await flushInvocation({
+                    telemetry,
+                    usageRollup,
+                    eventSummary,
+                    shouldUseDatabase,
+                    flushTimeoutMs,
+                    context,
+                });
+            } catch (_) {
+                // A flush must never change the handler result.
+            }
+        }
+    });
+}
+
+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(
+        {
+            log: {
+                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 { addDeniedKeys } = require('../../logs/redact');
 
 /**
  * Core encryption schema (immutable - cannot be overridden by custom schemas)
@@ -120,6 +121,7 @@ function registerCustomSchema(schema) {
     }
 
     customSchema = { ...schema };
+    addDeniedKeys(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) {
         }
     }
 
+    addDeniedKeys(fields);
     return [...new Set(fields)];
 }
 

package/errors/fetch-error.js

@@ -1,82 +1,65 @@
 const { BaseError } = require('./base-error');
-const { stripIndent } = require('common-tags');
-
-// TODO hide header values
+const { redactUrl, scrubString } = require('../logs/redact');
 
 // Parameters names here are based on fetch.  See:
 // https://developer.mozilla.org/en-US/docs/Web/API/fetch
 
-class FetchError extends BaseError {
-    response = null;
-
-    constructor(options = {}) {
-        const { resource, init, response, responseBody } = options;
-        const method = init?.method ?? 'GET';
-        let initText = init
-            ? init.body instanceof URLSearchParams
-                ? (() => {
-                    init.body = init.body.toString();
-                    return JSON.stringify({ init }, null, 2);
-                })()
-                : JSON.stringify({ init }, null, 2)
-            : '';
-
-        let responseBodyText = '<response body is unavailable>';
-        if (typeof responseBody === 'string') {
-            responseBodyText = responseBody;
-        } else if (responseBody) {
-            responseBodyText = JSON.stringify(responseBody, null, 2);
-        }
-
-        const responseHeaders = {};
-        if (response?.headers) {
-            for (const [key, value] of response.headers) {
-                responseHeaders[key] = value;
-            }
-        }
-
-        let responseHeaderText = response
-            ? JSON.stringify({ headers: responseHeaders }, null, 2)
-            : '';
+function resourceUrl(resource) {
+    if (resource === undefined || resource === null) return '';
+    if (typeof resource === 'object' && typeof resource.url === 'string') {
+        return redactUrl(resource.url);
+    }
+    return redactUrl(resource);
+}
 
-        // sanitize error reporting
-        if (process.env.STAGE !== 'dev') {
-            initText = false;
-            responseHeaderText = false;
-            responseBodyText = false;
-        }
+function causeLabel(cause) {
+    if (!cause || typeof cause !== 'object') return '';
+    const label = cause.code ?? cause.name;
+    return label === undefined || label === null ? '' : scrubString(String(label));
+}
 
-        const messageParts = [
-            stripIndent`
-                -----------------------------------------------------
-                An error ocurred while fetching an external resource.
-                -----------------------------------------------------
-                >>> Request Details >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-                ${method} ${resource}
-            `,
-            initText,
-            stripIndent`
-                <<< Response Details <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
-                ${response?.status} ${response?.statusText}
-            `,
-            responseHeaderText,
-            responseBodyText,
-            stripIndent`
-                -----------------------------------------------------
-                Stack Trace:
-            `,
-        ];
+function buildMessage({ method, url, response, cause }) {
+    const outcome = response
+        ? response.status === undefined || response.status === null
+            ? ''
+            : String(response.status)
+        : causeLabel(cause);
+    return [method, url, outcome].filter(Boolean).join(' ');
+}
 
-        super(messageParts.filter(Boolean).join('\n'));
+class FetchError extends BaseError {
+    constructor({ resource, init, response, cause, responseBody, body } = {}) {
+        const method = String(init?.method ?? 'GET').toUpperCase();
+        const url = resourceUrl(resource);
+        super(
+            buildMessage({ method, url, response, cause }),
+            cause ? { cause } : undefined
+        );
 
-        this.response = response;
         this.statusCode = response?.status;
+        this.method = method;
+        this.url = url;
+        Object.defineProperty(this, 'response', {
+            value: response ?? null,
+            enumerable: false,
+            writable: true,
+            configurable: true,
+        });
+        Object.defineProperty(this, 'body', {
+            value: responseBody ?? body,
+            enumerable: false,
+            writable: true,
+            configurable: true,
+        });
     }
 
     static async create(options = {}) {
         const { response } = options;
-        let responseBody = response?.bodyUsed ? null : await response?.text();
-        if (!responseBody && options.body) responseBody = options.body;
+        let responseBody =
+            response && !response.bodyUsed && typeof response.text === 'function'
+                ? await response.text()
+                : null;
+        if (!responseBody) responseBody = options.responseBody ?? options.body;
         return new FetchError({ ...options, responseBody });
     }
 }

package/handlers/app-definition-loader.js

@@ -2,13 +2,53 @@ const { findNearestBackendPackageJson } = require('@friggframework/core/utils');
 const path = require('node:path');
 const fs = require('fs-extra');
 const { resolveTelemetryConfig } = require('../telemetry/telemetry-config');
+const { addDeniedKeys } = require('../logs/redact');
+const { getLogger } = require('../logs');
+const {
+    extractCredentialFieldsFromModules,
+} = require('../database/encryption/encryption-schema-registry');
+const {
+    getModulesDefinitionFromIntegrationClasses,
+} = require('../integrations/utils/map-integration-dto');
+
+// Handlers without a database never load the encryption registry, so the
+// credential leaf keys are registered for redaction here too.
+const warnedIgnoredKeys = new Set();
+
+function warnIgnoredKeys(ignored) {
+    for (const key of ignored) {
+        if (warnedIgnoredKeys.has(key)) continue;
+        warnedIgnoredKeys.add(key);
+        getLogger('frigg.logger').warn(
+            'Credential field name is a record field; it stays visible in logs',
+            { eventName: 'frigg.logger.denied_key_ignored', key }
+        );
+    }
+}
+
+function registerCredentialLogKeys(appDefinition, integrations) {
+    try {
+        const fields = extractCredentialFieldsFromModules(
+            getModulesDefinitionFromIntegrationClasses(integrations)
+        );
+        warnIgnoredKeys(addDeniedKeys(fields));
+    } catch {
+        // An odd integration shape must not stop the app from loading.
+    }
+    const schema = appDefinition.encryption?.schema;
+    if (schema && typeof schema === 'object') {
+        for (const config of Object.values(schema)) {
+            warnIgnoredKeys(addDeniedKeys(config?.fields));
+        }
+    }
+}
 
 /**
  * Loads the App definition from the nearest backend package
  * @function loadAppDefinition
  * @description Searches for the nearest backend package.json, loads the corresponding index.js file,
  * and extracts the application definition containing integrations and user configuration.
- * @returns {{integrations: Array<object>, userConfig: object | null, adminScripts: Array<object>, reports: Array<object>, admin: object, telemetry: object}} An object containing the application definition.
+ * @returns {{integrations: Array<object>, userConfig: object | null, adminScripts: Array<object>, reports: Array<object>, admin: object, telemetry: object, logging: object | null}} An object containing the application definition.
  * @throws {Error} Throws error if backend package.json cannot be found.
  * @throws {Error} Throws error if index.js file cannot be found in the backend directory.
  * @example
@@ -36,8 +76,11 @@ function loadAppDefinition() {
         adminScripts = [],
         reports = [],
         admin = {},
+        logging = null,
     } = appDefinition;
 
+    registerCredentialLogKeys(appDefinition, integrations);
+
     // Degrade consistently: an invalid telemetry block must never take down a
     // router bundle that loads the app definition at module scope (telemetry is
     // never allowed to break a handler). The singletons apply the same
@@ -59,7 +102,15 @@ function loadAppDefinition() {
         };
     }
 
-    return { integrations, userConfig, adminScripts, reports, admin, telemetry };
+    return {
+        integrations,
+        userConfig,
+        adminScripts,
+        reports,
+        admin,
+        telemetry,
+        logging,
+    };
 }
 
 module.exports = {

package/handlers/app-handler-helpers.js

@@ -1,10 +1,13 @@
-const { createHandler, flushDebugLog } = require('@friggframework/core');
+const { createHandler } = require('@friggframework/core');
+const { getLogger } = require('../logs');
 const express = require('express');
 const bodyParser = require('body-parser');
 const cors = require('cors');
 const Boom = require('@hapi/boom');
 const serverlessHttp = require('serverless-http');
 
+const log = getLogger('frigg.http');
+
 const createApp = (applyMiddleware) => {
     const app = express();
 
@@ -21,7 +24,7 @@ const createApp = (applyMiddleware) => {
 
     if (applyMiddleware) applyMiddleware(app);
 
-    // Handle sending error response and logging server errors to console
+    // The express boundary: send the error response and log it one time.
     app.use((err, req, res, next) => {
         const boomError = err.isBoom ? err : Boom.boomify(err);
         const {
@@ -29,10 +32,19 @@ const createApp = (applyMiddleware) => {
         } = boomError;
 
         if (statusCode >= 500) {
-            flushDebugLog(boomError);
+            log.error('Request failed', {
+                eventName: 'frigg.http.request_failed',
+                statusCode,
+                error: boomError,
+            });
             res.status(statusCode).json({ error: 'Internal Server Error' });
         } else {
-            console.warn(`[Frigg] ${req.method} ${req.path} -> ${statusCode}: ${err.message}`);
+            // A client error needs no stack; the logger scrubs the reason.
+            log.warn('Request rejected', {
+                eventName: 'frigg.http.request_rejected',
+                statusCode,
+                reason: boomError.message,
+            });
             res.status(statusCode).json({ error: err.message });
         }
     });

package/handlers/database-migration-handler.js

@@ -24,6 +24,9 @@
 
 const { execFile } = require('child_process');
 const path = require('path');
+const { getLogger } = require('../logs');
+
+const log = getLogger('frigg.database.migration');
 
 /**
  * Execute Prisma migration command
@@ -153,7 +156,13 @@ exports.handler = async (event, context) => {
     console.log('='.repeat(60));
     console.log('Database Migration Handler');
     console.log('='.repeat(60));
-    console.log('Event:', JSON.stringify(event, null, 2));
+    log.info('Database migration invoked', {
+        eventName: 'frigg.database.migration.invoked',
+        migrationId: event.migrationId,
+        dbType: process.env.DB_TYPE,
+        targetStage: process.env.STAGE,
+        action: event.command || 'deploy',
+    });
     console.log('Context:', JSON.stringify({
         functionName: context.functionName,
         functionVersion: context.functionVersion,

package/handlers/routers/websocket.js

@@ -1,5 +1,8 @@
 const { createHandler } = require('@friggframework/core');
 const { createWebsocketConnectionRepository } = require('../../database/websocket-connection-repository-factory');
+const { getLogger } = require('../../logs');
+
+const log = getLogger('frigg.websocket');
 
 const websocketConnectionRepository = createWebsocketConnectionRepository();
 
@@ -11,10 +14,16 @@ const handleWebSocketConnection = async (event, context) => {
             try {
                 const connectionId = event.requestContext.connectionId;
                 await websocketConnectionRepository.createConnection(connectionId);
-                console.log(`Stored new connection: ${connectionId}`);
+                log.info('Stored new connection', {
+                    eventName: 'frigg.websocket.connected',
+                    connectionId,
+                });
                 return { statusCode: 200, body: 'Connected.' };
             } catch (error) {
-                console.error('Error storing connection:', error);
+                log.error('Error storing connection', {
+                    eventName: 'frigg.websocket.connect_failed',
+                    error,
+                });
                 return { statusCode: 500, body: 'Error connecting.' };
             }
 
@@ -23,17 +32,28 @@ const handleWebSocketConnection = async (event, context) => {
             try {
                 const connectionId = event.requestContext.connectionId;
                 await websocketConnectionRepository.deleteConnection(connectionId);
-                console.log(`Removed connection: ${connectionId}`);
+                log.info('Removed connection', {
+                    eventName: 'frigg.websocket.disconnected',
+                    connectionId,
+                });
                 return { statusCode: 200, body: 'Disconnected.' };
             } catch (error) {
-                console.error('Error removing connection:', error);
+                log.error('Error removing connection', {
+                    eventName: 'frigg.websocket.disconnect_failed',
+                    error,
+                });
                 return { statusCode: 500, body: 'Error disconnecting.' };
             }
 
         case 'MESSAGE':
             // Handle incoming message
-            const message = JSON.parse(event.body);
-            console.log('Received message:', message);
+            // Parsed only to keep the old failure on a body that is not JSON.
+            JSON.parse(event.body);
+            log.info('Received message', {
+                eventName: 'frigg.websocket.message_received',
+                connectionId: event.requestContext.connectionId,
+                bodyLength: event.body?.length ?? 0,
+            });
 
             // Process the message and send a response
             const responseMessage = { message: 'Message received' };