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

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,38 @@ const { findNearestBackendPackageJson } = require('@friggframework/core/utils');
 const path = require('node:path');
 const fs = require('fs-extra');
 const { resolveTelemetryConfig } = require('../telemetry/telemetry-config');
+const { registerDeniedKeys } = require('../logs/denied-keys');
+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.
+function registerCredentialLogKeys(appDefinition, integrations) {
+    try {
+        extractCredentialFieldsFromModules(
+            getModulesDefinitionFromIntegrationClasses(integrations)
+        );
+    } 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)) {
+            registerDeniedKeys(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 +61,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 +87,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,14 @@
-const { createHandler, flushDebugLog } = require('@friggframework/core');
+const { createHandler } = require('@friggframework/core');
+const { getLogger } = require('../logs');
+const { summarizeExpressRequest } = require('../logs/summarize-event');
 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 +25,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 +33,20 @@ const createApp = (applyMiddleware) => {
         } = boomError;
 
         if (statusCode >= 500) {
-            flushDebugLog(boomError);
+            log.error('Request failed', {
+                eventName: 'frigg.http.request_failed',
+                statusCode,
+                invocation: summarizeExpressRequest(req),
+                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/backend-utils.js

@@ -1,4 +1,5 @@
 const { Router } = require('express');
+const { runInContext, LOGGER_SCOPE_KEY } = require('../logs/context');
 const { Worker } = require('@friggframework/core');
 const {
     IntegrationEventDispatcher,
@@ -19,6 +20,7 @@ const {
 const {
     getModulesDefinitionFromIntegrationClasses,
 } = require('../integrations/utils/map-integration-dto');
+const { processNotFound } = require('../integrations/use-cases/process-errors');
 
 const loadRouterFromObject = (IntegrationClass, routerObject) => {
     const router = Router();
@@ -37,12 +39,11 @@ const loadRouterFromObject = (IntegrationClass, routerObject) => {
             const dispatcher = new IntegrationEventDispatcher(
                 integrationInstance
             );
-            const result = await dispatcher.dispatchHttp({
-                event,
-                req,
-                res,
-                next,
-            });
+            // Logs only: a route :integrationId is unauthenticated input.
+            const result = await runInContext(
+                { [LOGGER_SCOPE_KEY]: { integrationId: req.params?.integrationId } },
+                () => dispatcher.dispatchHttp({ event, req, res, next })
+            );
             res.json(result);
         } catch (error) {
             next(error);
@@ -149,7 +150,7 @@ const loadIntegrationForProcess = async (processId, integrationClass) => {
     const process = await processRepository.findById(processId);
 
     if (!process) {
-        throw new Error(`Process not found: ${processId}`);
+        throw processNotFound(`Process not found: ${processId}`);
     }
 
     const instance = await getIntegrationInstance.execute(
@@ -164,7 +165,7 @@ const createQueueWorker = (integrationClass) => {
     const integrationName = integrationClass.Definition.name;
 
     class QueueWorker extends Worker {
-        async _run(params, context) {
+        async _run(params, context, delivery) {
             const logCtx = {
                 integration: integrationName,
                 event: params.event,
@@ -254,6 +255,7 @@ const createQueueWorker = (integrationClass) => {
                     event: params.event,
                     data: params.data,
                     context: context,
+                    delivery,
                 });
                 console.log(
                     `[QueueWorker] ${params.event} dispatched ok`,
@@ -273,11 +275,6 @@ const createQueueWorker = (integrationClass) => {
                     return;
                 }
 
-                console.error(
-                    `Error in ${params.event} for ${integrationName}:`,
-                    error
-                );
-
                 // 4xx HTTP errors are permanent — the requester already
                 // attempted token refresh (401) and backoff (429/5xx).
                 // By the time a 4xx reaches here, retrying won't help.

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/integration-event-dispatcher.js

@@ -18,9 +18,9 @@ class IntegrationEventDispatcher {
         );
     }
 
-    async dispatchJob({ event, data, context }) {
+    async dispatchJob({ event, data, context, delivery }) {
         return this._dispatch(event, (instance, handler) =>
-            handler.call(instance, { data, context })
+            handler.call(instance, { data, context, delivery })
         );
     }
 

package/handlers/routers/integration-webhook-routers.js

@@ -1,6 +1,7 @@
 const { createAppHandler } = require('./../app-handler-helpers');
 const { loadAppDefinition } = require('../app-definition-loader');
 const { Router } = require('express');
+const { runInContext, LOGGER_SCOPE_KEY } = require('../../logs/context');
 const {
     IntegrationEventDispatcher,
 } = require('../integration-event-dispatcher');
@@ -55,12 +56,18 @@ for (const IntegrationClass of integrationClasses) {
             const dispatcher = new IntegrationEventDispatcher(
                 integrationInstance
             );
-            await dispatcher.dispatchHttp({
-                event: 'WEBHOOK_RECEIVED',
-                req,
-                res,
-                next,
-            });
+            // Logs only: the id comes from an unauthenticated URL, so it must
+            // not reach the telemetry context that drives usage attribution.
+            await runInContext(
+                { [LOGGER_SCOPE_KEY]: { integrationId: req.params.integrationId } },
+                () =>
+                    dispatcher.dispatchHttp({
+                        event: 'WEBHOOK_RECEIVED',
+                        req,
+                        res,
+                        next,
+                    })
+            );
         } catch (error) {
             next(error);
         }

package/handlers/routers/websocket.js

@@ -1,5 +1,8 @@
 const { createHandler } = require('@friggframework/core');
-const { createWebsocketConnectionRepository } = require('../../database/websocket-connection-repository-factory');
+const { createWebsocketConnectionRepository } = require('../../websocket/repositories/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' };

package/handlers/workers/db-migration.js

@@ -55,6 +55,9 @@ const {
 
 // Inject prisma-runner as dependency
 const prismaRunner = require('../../database/utils/prisma-runner');
+const { getLogger } = require('../../logs');
+
+const log = getLogger('frigg.database.migration');
 
 // Use S3 repository for migration status tracking (no User table dependency)
 const bucketName = process.env.S3_BUCKET_NAME || process.env.MIGRATION_STATUS_BUCKET;
@@ -144,7 +147,6 @@ exports.handler = async (event, context) => {
     console.log('========================================');
     console.log('Database Migration Lambda Started');
     console.log('========================================');
-    console.log('Event:', JSON.stringify(event, null, 2));
     console.log('Context:', JSON.stringify({
         requestId: context.requestId,
         functionName: context.functionName,
@@ -157,6 +159,15 @@ exports.handler = async (event, context) => {
     // Check for action parameter (direct invocation for status checks)
     const action = event.action || 'migrate'; // Default to migration
 
+    // targetStage, not stage: the record's own stage field would win.
+    log.info('Database migration invoked', {
+        eventName: 'frigg.database.migration.invoked',
+        migrationId,
+        dbType,
+        targetStage: stage,
+        action,
+    });
+
     // Handle checkStatus action
     if (action === 'checkStatus') {
         console.log(`\n========================================`);

package/handlers/workers/dlq-processor.js

@@ -5,6 +5,18 @@
  * This handler MUST NOT throw. If it throws, the message goes back to
  * the DLQ and creates an infinite loop. All errors are caught and logged.
  */
+const crypto = require('node:crypto');
+const { getLogger } = require('../../logs');
+const {
+    summarizeLambdaEvent,
+    toScopeInvocation,
+} = require('../../logs/summarize-event');
+const {
+    runInvocationScope,
+    runMessageScope,
+} = require('../../core/invocation-scope');
+
+const log = getLogger('frigg.queue.dlq');
 
 function extractQueueName(eventSourceARN) {
     if (!eventSourceARN) return 'UNKNOWN';
@@ -12,50 +24,64 @@ function extractQueueName(eventSourceARN) {
     return parts[parts.length - 1] || 'UNKNOWN';
 }
 
-function parseMessageBody(body) {
+// The body can hold credentials, so only its size and digest are logged.
+function describeBody(body) {
+    const text = typeof body === 'string' ? body : String(body ?? '');
+    let parsed = true;
     try {
-        const parsed = JSON.parse(body);
-        return {
-            event: parsed.event || 'UNKNOWN',
-            integrationId: parsed.data?.integrationId || null,
-            processId: parsed.data?.processId || null,
-            data: parsed.data,
-        };
-    } catch (error) {
-        console.warn('[DLQ] Failed to parse message body', { error: error.message, body });
-        return {
-            event: 'UNKNOWN',
-            integrationId: null,
-            processId: null,
-            rawBody: body,
-        };
+        JSON.parse(text);
+    } catch {
+        parsed = false;
     }
+    return {
+        parsed,
+        bodyLength: Buffer.byteLength(text),
+        bodySha256: crypto.createHash('sha256').update(text).digest('hex'),
+    };
 }
 
-async function dlqProcessor(event) {
+function logRecord(record) {
+    const { parsed, ...body } = describeBody(record.body);
+    if (!parsed) {
+        log.warn('DLQ message body is not JSON', {
+            eventName: 'frigg.queue.dlq.body_unparsed',
+            ...body,
+        });
+    }
+    // messageId, receiveCount and the body ids come from the message scope.
+    log.error('Message reached the DLQ', {
+        eventName: 'frigg.queue.dlq.message_failed',
+        sentTimestamp: record.attributes?.SentTimestamp,
+        sourceQueue: extractQueueName(record.eventSourceARN),
+        ...body,
+    });
+}
+
+async function dlqProcessor(event, context) {
     if (!event?.Records?.length) return { batchItemFailures: [] };
 
-    for (const record of event.Records) {
-        try {
-            const parsed = parseMessageBody(record.body);
-
-            console.error('[DLQ] Failed message', {
-                messageId: record.messageId,
-                event: parsed.event,
-                integrationId: parsed.integrationId,
-                processId: parsed.processId,
-                receiveCount: record.attributes?.ApproximateReceiveCount,
-                sentTimestamp: record.attributes?.SentTimestamp,
-                sourceQueue: extractQueueName(record.eventSourceARN),
-                ...(parsed.rawBody !== undefined && { rawBody: parsed.rawBody }),
-            });
-        } catch (error) {
-            console.error('[DLQ] Error processing DLQ record', {
-                messageId: record.messageId,
-                error: error.message,
-            });
-        }
-    }
+    await runInvocationScope(
+        {
+            requestId: context?.awsRequestId,
+            handlerName: 'dlqProcessor',
+            invocation: toScopeInvocation(summarizeLambdaEvent(event)),
+        },
+        async () => {
+            for (const record of event.Records) {
+                await runMessageScope(record, async () => {
+                    try {
+                        logRecord(record);
+                    } catch (error) {
+                        log.error('DLQ record failed', {
+                            eventName: 'frigg.queue.dlq.record_failed',
+                            error,
+                        });
+                    }
+                });
+            }
+        },
+        { shouldUseDatabase: false, context }
+    );
 
     return { batchItemFailures: [] };
 }

package/index.js

@@ -11,6 +11,7 @@ const {
     Worker,
     loadInstalledModules,
     createHandler,
+    runInvocationScope,
 } = require('./core/index');
 const {
     prisma,
@@ -78,7 +79,17 @@ const {
 } = require('./telemetry/index');
 const { createUsageRepository } = require('./usage/index');
 const { TimeoutCatcher } = require('./lambda/index');
-const { debug, initDebugLog, flushDebugLog } = require('./logs/index');
+const {
+    getLogger,
+    createMemorySink,
+    resetLoggerForTests,
+    serializeError,
+    redactValue,
+    toSanitizedSurrogate,
+    debug,
+    initDebugLog,
+    flushDebugLog,
+} = require('./logs/index');
 const {
     Credential,
     Entity,
@@ -108,6 +119,7 @@ module.exports = {
     Worker,
     loadInstalledModules,
     createHandler,
+    runInvocationScope,
 
     // database
     prisma,
@@ -175,6 +187,12 @@ module.exports = {
     TimeoutCatcher,
 
     // logs
+    getLogger,
+    createMemorySink,
+    resetLoggerForTests,
+    serializeError,
+    redactValue,
+    toSanitizedSurrogate,
     debug,
     initDebugLog,
     flushDebugLog,