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

package/logs/serialize.js

@@ -0,0 +1,329 @@
+const {
+    isDeniedNormalized,
+    isDigestNormalized,
+    isOAuthCallbackShapeNormalized,
+    normalizeKey,
+    redactUrl,
+    scrubString,
+} = require('./redact');
+
+const MAX_DEPTH = 6;
+const MAX_CAUSE_DEPTH = 3;
+const MAX_STRING = 2048;
+const MAX_AGGREGATE_ERRORS = 10;
+const HEADER_KEYS = new Set(['headers', 'multivalueheaders', 'rawheaders']);
+
+function attempt(fn, fallback) {
+    try {
+        return fn();
+    } catch {
+        return fallback;
+    }
+}
+
+function cutString(value) {
+    if (value.length <= MAX_STRING) return value;
+    const suffix = `…[truncated:${value.length}]`;
+    return value.slice(0, MAX_STRING - suffix.length) + suffix;
+}
+
+function cleanString(value, normalizedKey = '') {
+    return cutString(
+        scrubString(value, { allowHex: isDigestNormalized(normalizedKey) })
+    );
+}
+
+function isError(value) {
+    return attempt(
+        () =>
+            value instanceof Error ||
+            Object.prototype.toString.call(value) === '[object Error]',
+        false
+    );
+}
+
+function isHeadersLike(value) {
+    if (typeof Headers !== 'undefined' && value instanceof Headers) return true;
+    return (
+        !(value instanceof Map) &&
+        typeof value.get === 'function' &&
+        typeof value.has === 'function' &&
+        typeof value.forEach === 'function' &&
+        typeof value.entries === 'function'
+    );
+}
+
+function headerNames(value) {
+    if (value === null || value === undefined) return value;
+    if (typeof value !== 'object') return '[REDACTED]';
+    if (value instanceof Map) return [...value.keys()].map(String);
+    if (Array.isArray(value)) {
+        if (value.every((entry) => typeof entry === 'string')) {
+            return value.filter((_entry, i) => i % 2 === 0);
+        }
+        return value.every(Array.isArray)
+            ? value.map((entry) => cleanString(String(entry[0])))
+            : '[REDACTED]';
+    }
+    if (isHeadersLike(value)) {
+        const names = [];
+        value.forEach((_v, name) => names.push(String(name)));
+        return names;
+    }
+    return Object.keys(value);
+}
+
+function walkObject(value, depth, seen) {
+    const keys = Object.keys(value);
+    const normalizedKeys = keys.map(normalizeKey);
+    const dropAll = isOAuthCallbackShapeNormalized(normalizedKeys);
+    const out = {};
+    for (let i = 0; i < keys.length; i += 1) {
+        const key = keys[i];
+        const normalized = normalizedKeys[i];
+        if (dropAll || isDeniedNormalized(normalized)) {
+            out[key] = '[REDACTED]';
+            continue;
+        }
+        let child;
+        try {
+            child = value[key];
+        } catch {
+            out[key] = '[Getter threw]';
+            continue;
+        }
+        if (HEADER_KEYS.has(normalized)) {
+            out[key] = attempt(() => headerNames(child), '[Unserializable]');
+            continue;
+        }
+        const result = walk(child, depth + 1, seen, normalized);
+        if (result !== undefined) out[key] = result;
+    }
+    return out;
+}
+
+function walkContainer(value, depth, seen) {
+    if (value instanceof Map) {
+        const out = {};
+        for (const [k, v] of value) {
+            const key = String(k);
+            const normalized = normalizeKey(key);
+            if (isDeniedNormalized(normalized)) {
+                out[key] = '[REDACTED]';
+                continue;
+            }
+            const result = walk(v, depth + 1, seen, normalized);
+            if (result !== undefined) out[key] = result;
+        }
+        return out;
+    }
+    if (value instanceof Set) {
+        return [...value].map((v) => walk(v, depth + 1, seen) ?? null);
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => walk(v, depth + 1, seen) ?? null);
+    }
+    if (isHeadersLike(value)) return headerNames(value);
+    return walkObject(value, depth, seen);
+}
+
+function walkSpecial(value) {
+    if (value instanceof Date) {
+        return Number.isNaN(value.getTime())
+            ? 'Invalid Date'
+            : value.toISOString();
+    }
+    if (value instanceof URL) return redactUrl(value);
+    if (value instanceof URLSearchParams) {
+        return [...value.keys()].map((k) => `${k}=REDACTED`).join('&');
+    }
+    if (Buffer.isBuffer(value)) return { type: 'Buffer', length: value.length };
+    if (ArrayBuffer.isView(value)) {
+        return {
+            type: value.constructor?.name ?? 'TypedArray',
+            length: value.byteLength,
+        };
+    }
+    if (value instanceof ArrayBuffer) {
+        return { type: 'ArrayBuffer', length: value.byteLength };
+    }
+    if (value instanceof RegExp) return cleanString(String(value));
+    if (
+        (value._bsontype === 'ObjectId' || value._bsontype === 'ObjectID') &&
+        typeof value.toHexString === 'function'
+    ) {
+        return value.toHexString();
+    }
+    return undefined;
+}
+
+function walk(value, depth, seen, normalizedKey) {
+    switch (typeof value) {
+        case 'string':
+            return cleanString(value, normalizedKey);
+        case 'number':
+            return Number.isFinite(value) ? value : String(value);
+        case 'boolean':
+            return value;
+        case 'bigint':
+            return value.toString();
+        case 'undefined':
+        case 'symbol':
+        case 'function':
+            return undefined;
+        default:
+            break;
+    }
+    if (value === null) return null;
+    if (isError(value)) return serializeErrorAt(value, 0, new WeakSet());
+    if (seen.has(value)) return '[Circular]';
+    if (depth >= MAX_DEPTH) return '[Depth]';
+    try {
+        const special = walkSpecial(value);
+        if (special !== undefined) return special;
+        seen.add(value);
+        try {
+            return walkContainer(value, depth, seen);
+        } finally {
+            seen.delete(value);
+        }
+    } catch {
+        return '[Unserializable]';
+    }
+}
+
+function serializeValue(value, { depth = 0 } = {}) {
+    try {
+        return walk(value, depth, new WeakSet());
+    } catch {
+        return '[Unserializable]';
+    }
+}
+
+function errorType(err) {
+    const ctorName = attempt(() => err.constructor?.name, undefined);
+    const name = attempt(() => err.name, undefined);
+    if (typeof ctorName === 'string' && ctorName && ctorName !== 'Error') {
+        return ctorName;
+    }
+    if (typeof name === 'string' && name) return name;
+    return ctorName || 'Error';
+}
+
+function lastParagraph(message) {
+    const paragraphs = message
+        .split(/\n\s*\n/)
+        .map((p) => p.trim())
+        .filter(Boolean);
+    return paragraphs[paragraphs.length - 1] ?? '';
+}
+
+function errorStatus(err) {
+    const status = attempt(
+        () => err.statusCode ?? err.status ?? err.response?.status,
+        undefined
+    );
+    if (typeof status === 'number' && Number.isFinite(status)) return status;
+    if (typeof status === 'string' && status) return cleanString(status);
+    return undefined;
+}
+
+function errorCode(err) {
+    const code = attempt(() => err.code, undefined);
+    if (typeof code === 'number' && Number.isFinite(code)) return code;
+    if (typeof code === 'string' && code) return cleanString(code);
+    return undefined;
+}
+
+function errorStack(err, type, message) {
+    const stack = attempt(() => err.stack, undefined);
+    if (typeof stack !== 'string') return undefined;
+    const frames = stack.split('\n').filter((line) => /^\s*at\s/.test(line));
+    return cutString(
+        [`${type}: ${message}`, ...frames.map((f) => scrubString(f))].join('\n')
+    );
+}
+
+function nested(value, depth, seen) {
+    if (depth > MAX_CAUSE_DEPTH) return '[Depth]';
+    if (value !== null && typeof value === 'object' && seen.has(value)) {
+        return '[Circular]';
+    }
+    return serializeErrorAt(value, depth, seen);
+}
+
+function nonErrorMessage(value) {
+    if (value === null || typeof value !== 'object') {
+        return cleanString(attempt(() => String(value), '[Unserializable]'));
+    }
+    const message = attempt(() => value.message, undefined);
+    if (typeof message === 'string') return cleanString(message);
+    return cutString(
+        attempt(() => JSON.stringify(serializeValue(value)), '[Unserializable]')
+    );
+}
+
+function serializeErrorAt(err, depth, seen) {
+    if (!isError(err)) {
+        return { type: 'NonError', message: nonErrorMessage(err) };
+    }
+    seen.add(err);
+    const type = cutString(scrubString(errorType(err)));
+    const rawMessage = attempt(() => err.message, '');
+    let message = typeof rawMessage === 'string' ? rawMessage : String(rawMessage);
+    if (type.startsWith('PrismaClient')) message = lastParagraph(message);
+    message = cleanString(message);
+
+    const out = { type, message };
+    const code = errorCode(err);
+    if (code !== undefined) out.code = code;
+    const status = errorStatus(err);
+    if (status !== undefined) out.status = status;
+    const stack = errorStack(err, type, message);
+    if (stack !== undefined) out.stack = stack;
+
+    const cause = attempt(() => err.cause, undefined);
+    if (cause !== undefined && cause !== null) {
+        out.cause = nested(cause, depth + 1, seen);
+    }
+
+    const errors = attempt(() => err.errors, undefined);
+    if (type === 'AggregateError' && Array.isArray(errors)) {
+        out.errors = errors
+            .slice(0, MAX_AGGREGATE_ERRORS)
+            .map((e) => nested(e, depth + 1, seen));
+    }
+    return out;
+}
+
+function serializeError(err) {
+    try {
+        return serializeErrorAt(err, 0, new WeakSet());
+    } catch {
+        return { type: 'Error', message: '[Unserializable]' };
+    }
+}
+
+function toSanitizedSurrogate(err) {
+    const serialized = serializeError(err);
+    const surrogate = new Error(serialized.message);
+    surrogate.name =
+        serialized.type === 'NonError' ? 'Error' : serialized.type;
+    surrogate.stack =
+        serialized.stack ?? `${surrogate.name}: ${serialized.message}`;
+    if (serialized.code !== undefined) surrogate.code = serialized.code;
+    if (serialized.status !== undefined) {
+        surrogate.statusCode = serialized.status;
+    }
+    return surrogate;
+}
+
+module.exports = {
+    isError,
+    serializeValue,
+    serializeError,
+    toSanitizedSurrogate,
+    MAX_DEPTH,
+    MAX_CAUSE_DEPTH,
+    MAX_STRING,
+};

package/logs/sinks.js

@@ -0,0 +1,93 @@
+const fs = require('node:fs');
+const { deepFreeze } = require('./record');
+
+const DEFAULT_MAX_RETRIES = 10;
+const MAX_SLEEP_MS = 20;
+
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function defaultWriteStderr(line) {
+    fs.writeSync(2, line);
+}
+
+function safeCode(code) {
+    return String(code ?? 'UNKNOWN').replace(/[^A-Za-z0-9_]/g, '').slice(0, 32) || 'UNKNOWN';
+}
+
+function createStdoutSink({
+    fd = 1,
+    writeSync = fs.writeSync,
+    writeStderr = defaultWriteStderr,
+    sleep = sleepSync,
+    maxRetries = DEFAULT_MAX_RETRIES,
+} = {}) {
+    const reportFailure = (code) => {
+        try {
+            writeStderr(`frigg.logger.write_failed code=${safeCode(code)}\n`);
+        } catch {
+            // Nothing is left to report to.
+        }
+    };
+
+    return {
+        name: 'stdout',
+        write(record) {
+            let buffer;
+            try {
+                buffer = Buffer.from(`${JSON.stringify(record)}\n`);
+            } catch {
+                reportFailure('SERIALIZE');
+                return;
+            }
+            let offset = 0;
+            let retries = 0;
+            // EAGAIN and a zero-byte write share one bounded retry budget.
+            const retry = () => {
+                if (retries >= maxRetries) {
+                    reportFailure('EAGAIN');
+                    return false;
+                }
+                retries += 1;
+                sleep(Math.min(retries, MAX_SLEEP_MS));
+                return true;
+            };
+            while (offset < buffer.length) {
+                let written;
+                try {
+                    written = writeSync(fd, buffer, offset, buffer.length - offset);
+                } catch (error) {
+                    if (error?.code !== 'EAGAIN') {
+                        reportFailure(error?.code);
+                        return;
+                    }
+                    if (!retry()) return;
+                    continue;
+                }
+                if (written > 0) offset += written;
+                else if (!retry()) return;
+            }
+        },
+    };
+}
+
+function createMemorySink({ install = true } = {}) {
+    const records = [];
+    const sink = {
+        name: 'memory',
+        records,
+        write(record) {
+            records.push(deepFreeze(JSON.parse(JSON.stringify(record))));
+        },
+        clear() {
+            records.length = 0;
+        },
+    };
+    if (install) {
+        require('./logger-runtime').setSinks([sink]);
+    }
+    return sink;
+}
+
+module.exports = { createStdoutSink, createMemorySink };

package/logs/summarize-event.js

@@ -0,0 +1,163 @@
+const { redactUrl } = require('./redact');
+
+// Best-effort extraction of the logical event/processId/integrationId from a
+// JSON message body: `data.*` first, then the top level. Used only for log
+// correlation. Never throws.
+function summarizeMessageBody(bodyStr) {
+    try {
+        const parsed = JSON.parse(bodyStr);
+        return {
+            event: parsed?.event,
+            processId: parsed?.data?.processId ?? parsed?.processId,
+            integrationId: parsed?.data?.integrationId ?? parsed?.integrationId,
+        };
+    } catch {
+        return {};
+    }
+}
+
+function objectKeys(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? Object.keys(value)
+        : [];
+}
+
+function rawQueryKeys(rawQueryString) {
+    if (typeof rawQueryString !== 'string' || !rawQueryString) return [];
+    try {
+        return [...new URLSearchParams(rawQueryString).keys()];
+    } catch {
+        return [];
+    }
+}
+
+function unique(list) {
+    return [...new Set(list)];
+}
+
+// The route template keeps ids out of the field: REST v1 `resource`, or the
+// path part of an HTTP API v2 `routeKey` such as `GET /api/{id}`.
+function routeTemplate(event, path) {
+    if (typeof event.resource === 'string' && event.resource) {
+        return event.resource;
+    }
+    if (typeof event.routeKey === 'string') {
+        const space = event.routeKey.indexOf(' ');
+        if (space > 0) return event.routeKey.slice(space + 1);
+    }
+    return path;
+}
+
+function summarizeHttp(event) {
+    const path = event.path || event.rawPath;
+    const summary = {
+        source: 'http',
+        method: event.httpMethod || event.requestContext?.http?.method,
+        path,
+        route: routeTemplate(event, path),
+        queryKeys: unique([
+            ...objectKeys(event.queryStringParameters),
+            ...objectKeys(event.multiValueQueryStringParameters),
+            ...rawQueryKeys(event.rawQueryString),
+        ]),
+        headerNames: unique(
+            [...objectKeys(event.headers), ...objectKeys(event.multiValueHeaders)].map(
+                (name) => name.toLowerCase()
+            )
+        ),
+    };
+    if (typeof event.routeKey === 'string' && event.routeKey) {
+        summary.routeKey = event.routeKey;
+    }
+    return summary;
+}
+
+// Best-effort extraction of correlation identifiers from a Lambda event.
+// For SQS: messageIds plus the parsed event/processId/integrationId of each
+// record body. For HTTP: method, route, query keys and header names. Never
+// throws and never returns a body, a query value or a header value.
+function summarizeLambdaEvent(event) {
+    try {
+        if (!event || typeof event !== 'object') return {};
+        if (Array.isArray(event.Records)) {
+            return {
+                source: 'sqs',
+                records: event.Records.map((r) => ({
+                    messageId: r?.messageId,
+                    receiveCount: r?.attributes?.ApproximateReceiveCount,
+                    ...summarizeMessageBody(r?.body),
+                })),
+            };
+        }
+        if (event.httpMethod || event.requestContext?.http) {
+            return summarizeHttp(event);
+        }
+        return { source: 'other' };
+    } catch {
+        return { source: 'other' };
+    }
+}
+
+// The bounded form that goes into the logger scope: no per-record array.
+function toScopeInvocation(summary) {
+    if (!summary || typeof summary !== 'object' || !summary.source) {
+        return { source: 'other' };
+    }
+    if (summary.source === 'sqs') {
+        return {
+            source: 'sqs',
+            recordCount: Array.isArray(summary.records) ? summary.records.length : 0,
+        };
+    }
+    if (summary.source === 'http') {
+        const invocation = {
+            source: 'http',
+            method: summary.method,
+            route: summary.route,
+        };
+        if (summary.routeKey) invocation.routeKey = summary.routeKey;
+        return invocation;
+    }
+    return { source: summary.source };
+}
+
+// Per-request detail for the entry and failure records, never for the
+// scope. A raw path can hold a token, so it goes through redactUrl.
+function toRequestDetails(summary) {
+    if (!summary || summary.source !== 'http') return {};
+    return {
+        path: redactUrl(summary.path ?? ''),
+        queryKeys: summary.queryKeys ?? [],
+        headerNames: summary.headerNames ?? [],
+    };
+}
+
+// The full redacted request summary (ADR-048 §6: it goes under `invocation`).
+function toRequestInvocation(summary) {
+    return { ...toScopeInvocation(summary), ...toRequestDetails(summary) };
+}
+
+// The same shape from an express request, for the express error boundary.
+function summarizeExpressRequest(req) {
+    try {
+        if (!req || typeof req !== 'object') return { source: 'http' };
+        return {
+            source: 'http',
+            method: req.method,
+            path: redactUrl(req.path ?? ''),
+            queryKeys: objectKeys(req.query),
+            headerNames: unique(objectKeys(req.headers).map((name) => name.toLowerCase())),
+        };
+    } catch {
+        return { source: 'http' };
+    }
+}
+
+module.exports = {
+    summarizeLambdaEvent,
+    summarizeMessageBody,
+    toScopeInvocation,
+    toRequestDetails,
+    toRequestInvocation,
+    summarizeExpressRequest,
+};

package/modules/module.js

@@ -1,6 +1,6 @@
 const { Delegate } = require('../core');
 const _ = require('lodash');
-const { flushDebugLog } = require('../logs');
+const { getLogger } = require('../logs');
 const { ModuleConstants } = require('./ModuleConstants');
 const {
     createCredentialRepository,
@@ -32,6 +32,14 @@ class Module extends Delegate {
         this.credential = entityObj?.credential;
         this.definition = definition;
         this.name = this.definition.moduleName;
+        this.logger = getLogger(`module.${this.name ?? 'unknown'}`).child(() => ({
+            entityId: this.entity?.id,
+            credentialId:
+                this.credential?.id ??
+                (typeof this.credential === 'string'
+                    ? this.credential
+                    : undefined),
+        }));
         this.modelName = this.definition.modelName;
         this.apiClass = this.definition.API;
 
@@ -49,6 +57,7 @@ class Module extends Delegate {
         const apiParams = {
             ...this.definition.env,
             delegate: this,
+            logger: this.logger,
             ...(state ? { state } : {}),
             ...(this.credential?.data
                 ? this.apiParamsFromCredential(this.credential.data)
@@ -100,7 +109,10 @@ class Module extends Delegate {
         try {
             if (await this.testAuthRequest(this.api)) validAuth = true;
         } catch (e) {
-            flushDebugLog(e);
+            this.logger.warn('testAuth failed', {
+                eventName: `${this.logger.name}.test_auth_failed`,
+                error: e,
+            });
         }
         return validAuth;
     }
@@ -113,9 +125,9 @@ class Module extends Delegate {
         const apiParams = this.apiParamsFromCredential(this.api);
 
         if (!apiParams.refresh_token && this.api.isRefreshable) {
-            console.warn(
-                `[Frigg] No refresh_token in apiParams for module ${this.name}.`
-            );
+            this.logger.warn('No refresh_token in apiParams', {
+                eventName: `${this.logger.name}.refresh_token_missing`,
+            });
         }
 
         Object.assign(credentialDetails.details, apiParams);
@@ -133,10 +145,10 @@ class Module extends Delegate {
                     moduleName: this.name,
                 });
             } catch (err) {
-                console.error(
-                    `[Frigg] Failed to propagate CREDENTIAL_VALIDATED for module ${this.name}:`,
-                    err?.message || err
-                );
+                this.logger.error('Failed to propagate CREDENTIAL_VALIDATED', {
+                    eventName: `${this.logger.name}.credential_validated_propagation_failed`,
+                    error: err,
+                });
             }
         }
     }
@@ -177,12 +189,11 @@ class Module extends Delegate {
         if (!this.credential.id) return;
 
         if (diagnosticInfo) {
-            console.error(
-                `[Frigg] Module ${this.name} credentials rejected (status ${
-                    diagnosticInfo.statusCode ?? '?'
-                }):`,
-                diagnosticInfo.message ?? diagnosticInfo
-            );
+            this.logger.warn('Credentials rejected', {
+                eventName: `${this.logger.name}.credentials_rejected`,
+                statusCode: diagnosticInfo.statusCode,
+                error: diagnosticInfo,
+            });
         }
 
         await this.credentialRepository.updateAuthenticationStatus(
@@ -216,16 +227,17 @@ class Module extends Delegate {
                 }),
             });
         } catch (err) {
-            console.error(
-                `[Frigg] Failed to propagate CREDENTIAL_INVALIDATED for module ${this.name}:`,
-                err?.message || err
-            );
+            this.logger.error('Failed to propagate CREDENTIAL_INVALIDATED', {
+                eventName: `${this.logger.name}.credential_invalidated_propagation_failed`,
+                error: err,
+            });
         }
     }
 
     async deauthorize() {
         //todo: Check if this is correct, we're instantiating a new api without params (credentials, tokens, etc...)
         this.api = new this.apiClass();
+        this.api.logger = this.logger;
 
         // Remove persisted credential (if any)
         if (this.entity?.credential) {
@@ -234,6 +246,7 @@ class Module extends Delegate {
 
             // Delete credential via repository
             await this.credentialRepository.deleteCredentialById(credentialId);
+            this.credential = undefined;
 
             // Unset credential reference on the Entity document
             const entityId = this.entity.id;