@friggframework/core 2.0.0-next.12 → 2.0.0-next.120

package/logs/context.js

@@ -0,0 +1,109 @@
+const { AsyncLocalStorage } = require('node:async_hooks');
+
+const LOGGER_SCOPE_KEY = 'log';
+const INTEGRATION_KEYS = ['integrationId', 'integrationType', 'userId', 'version'];
+
+// Shared across jest module registries and nested core copies.
+const STORE_KEY = Symbol.for('@friggframework/core.logs.context');
+
+function als() {
+    if (!globalThis[STORE_KEY]) {
+        globalThis[STORE_KEY] = new AsyncLocalStorage();
+    }
+    return globalThis[STORE_KEY];
+}
+
+function isPlainObject(value) {
+    if (value === null || typeof value !== 'object') return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+
+function freezeCopy(value) {
+    if (Array.isArray(value)) {
+        return Object.freeze(value.map(freezeCopy));
+    }
+    if (isPlainObject(value)) {
+        const copy = {};
+        for (const key of Object.keys(value)) {
+            copy[key] = freezeCopy(value[key]);
+        }
+        return Object.freeze(copy);
+    }
+    return value;
+}
+
+function assignDefined(target, source) {
+    for (const key of Object.keys(source)) {
+        if (source[key] !== undefined) target[key] = source[key];
+    }
+    return target;
+}
+
+function mergeStores(outer, inner) {
+    const merged = { ...(outer || {}) };
+    if (!inner || typeof inner !== 'object') return freezeCopy(merged);
+    for (const key of Object.keys(inner)) {
+        const value = inner[key];
+        if (value === undefined) continue;
+        if (key === LOGGER_SCOPE_KEY && isPlainObject(value)) {
+            merged[key] = assignDefined({ ...(merged[key] || {}) }, value);
+            continue;
+        }
+        merged[key] = value;
+    }
+    return freezeCopy(merged);
+}
+
+function runInContext(context, fn) {
+    const storage = als();
+    return storage.run(mergeStores(storage.getStore(), context), fn);
+}
+
+function getContext() {
+    return als().getStore() ?? null;
+}
+
+// The store is frozen per scope, so one scope object per store is enough.
+const EMPTY_SCOPE = Object.freeze({});
+const scopeByStore = new WeakMap();
+
+function getLoggerScope() {
+    const store = getContext();
+    if (!store) return EMPTY_SCOPE;
+    let scope = scopeByStore.get(store);
+    if (!scope) {
+        scope = {};
+        for (const key of INTEGRATION_KEYS) {
+            if (store[key] !== undefined) scope[key] = store[key];
+        }
+        // A set (hydrated) id beats a logger-only one, e.g. from a URL or a
+        // message body; a null id leaves the logger-only value in place.
+        const loggerKeys = store[LOGGER_SCOPE_KEY];
+        if (isPlainObject(loggerKeys)) {
+            for (const [key, value] of Object.entries(loggerKeys)) {
+                if (scope[key] === undefined || scope[key] === null) {
+                    scope[key] = value;
+                }
+            }
+        }
+        scope = Object.freeze(scope);
+        scopeByStore.set(store, scope);
+    }
+    return scope;
+}
+
+function hasOnlyLoggerKeys(store) {
+    if (!store || typeof store !== 'object') return false;
+    const keys = Object.keys(store);
+    return keys.length > 0 && keys.every((key) => key === LOGGER_SCOPE_KEY);
+}
+
+module.exports = {
+    LOGGER_SCOPE_KEY,
+    runInContext,
+    getContext,
+    getLoggerScope,
+    hasOnlyLoggerKeys,
+    isPlainObject,
+};

package/logs/contract-keys.js

@@ -0,0 +1,67 @@
+// Field names of the record contract (ADR-048 §3). A leaf: no requires.
+
+const REQUIRED_KEYS = ['timestamp', 'level', 'message', 'logger'];
+const RESOURCE_KEYS = ['appName', 'stage'];
+const TRACE_KEYS = ['trace_id', 'span_id', 'trace_flags'];
+const DROPPED_KEYS_FIELD = 'droppedKeys';
+const OWNED_KEYS = new Set([
+    ...REQUIRED_KEYS,
+    ...RESOURCE_KEYS,
+    ...TRACE_KEYS,
+    DROPPED_KEYS_FIELD,
+]);
+
+// Set by the scope builders (logs/context.js, core/invocation-scope.js,
+// core/create-handler.js) and the Module and IntegrationBase bindings.
+const SCOPE_KEYS = [
+    'integrationId',
+    'integrationType',
+    'userId',
+    'version',
+    'entityId',
+    'credentialId',
+    'requestId',
+    'messageId',
+    'receiveCount',
+    'processId',
+    'integrationEvent',
+    'handlerName',
+    'method',
+    'route',
+    'routeKey',
+    'invocation',
+];
+
+const CONTRACT_KEYS = [
+    ...new Set([...OWNED_KEYS, ...SCOPE_KEYS, 'eventName', 'statusCode', 'error']),
+];
+
+const RESERVED_KEYS = new Set([
+    'tenantId',
+    'type',
+    'time',
+    'record',
+    'errorType',
+    'errorMessage',
+    'stackTrace',
+    'service',
+    'env',
+    'host',
+    'source',
+    'status',
+    'severity',
+]);
+
+const PAYLOAD_KEYS = new Set(['body', 'rawBody', 'payload', 'response']);
+
+module.exports = {
+    REQUIRED_KEYS,
+    RESOURCE_KEYS,
+    TRACE_KEYS,
+    DROPPED_KEYS_FIELD,
+    OWNED_KEYS,
+    SCOPE_KEYS,
+    CONTRACT_KEYS,
+    RESERVED_KEYS,
+    PAYLOAD_KEYS,
+};

package/logs/debug-shims.js

@@ -0,0 +1,46 @@
+const util = require('node:util');
+const { getLogger } = require('./logger');
+const { getContext } = require('./context');
+const {
+    summarizeLambdaEvent,
+    toRequestInvocation,
+} = require('./summarize-event');
+
+// Deprecated. Kept for one major version; use getLogger or this.logger.
+const LEGACY_LOGGER_NAME = 'frigg.legacy';
+const FORMAT_DIRECTIVE = /%[sdifjoOc%]/;
+
+const legacy = () => getLogger(LEGACY_LOGGER_NAME);
+
+function debug(...messages) {
+    if (!messages.length) return;
+    const log = legacy();
+    if (!log.isLevelEnabled('DEBUG')) return;
+    const index = messages.findIndex((m) => typeof m === 'string');
+    if (index === 0 && FORMAT_DIRECTIVE.test(messages[0])) {
+        log.debug(util.format(...messages));
+        return;
+    }
+    const message = index === -1 ? '' : messages[index];
+    const args = messages.filter((_, i) => i !== index);
+    log.debug(message, args.length ? { args } : undefined);
+}
+
+function initDebugLog(...initMessages) {
+    if (getContext()?.log) return;
+    const log = legacy();
+    if (!log.isLevelEnabled('DEBUG')) return;
+    const event = initMessages.find((m) => m && typeof m === 'object');
+    log.debug('Debug log initialized', {
+        invocation: toRequestInvocation(summarizeLambdaEvent(event)),
+    });
+}
+
+function flushDebugLog(error) {
+    legacy().error('Unhandled error', {
+        eventName: 'frigg.legacy.error',
+        error: error || new Error('flushDebugLog called with empty error'),
+    });
+}
+
+module.exports = { debug, initDebugLog, flushDebugLog };

package/logs/denied-keys.js

@@ -0,0 +1,21 @@
+const { addDeniedKeys } = require('./redact');
+const { getLogger } = require('./logger');
+
+const warnedKeys = new Set();
+
+// addDeniedKeys plus one WARN per record-contract key it had to skip, so a
+// credential field named like a record field is visible wherever it is set.
+function registerDeniedKeys(keys) {
+    const ignored = addDeniedKeys(keys);
+    for (const key of ignored) {
+        if (warnedKeys.has(key)) continue;
+        warnedKeys.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 }
+        );
+    }
+    return ignored;
+}
+
+module.exports = { registerDeniedKeys };

package/logs/index.js

@@ -1,7 +1,18 @@
-const {debug, initDebugLog, flushDebugLog} = require('./logger');
+const { getLogger } = require('./logger');
+const { createMemorySink } = require('./sinks');
+const { resetLoggerForTests } = require('./logger-runtime');
+const { serializeError, toSanitizedSurrogate } = require('./serialize');
+const { redactValue } = require('./redact');
+const { debug, initDebugLog, flushDebugLog } = require('./debug-shims');
 
 module.exports = {
+    getLogger,
+    createMemorySink,
+    resetLoggerForTests,
+    serializeError,
+    redactValue,
+    toSanitizedSurrogate,
     debug,
     initDebugLog,
-    flushDebugLog
-}
+    flushDebugLog,
+};

package/logs/jest-logger-setup.js

@@ -0,0 +1,25 @@
+const { createMemorySink } = require('./sinks');
+const { resetLoggerForTests, takeViolationsForTests } = require('./logger-runtime');
+const { toContainNoSecretWindow } = require('./__fixtures__/matchers');
+
+expect.extend({ toContainNoSecretWindow });
+
+const resetToMemory = () =>
+    resetLoggerForTests({
+        level: 'TRACE',
+        sinks: [createMemorySink({ install: false })],
+        trackViolations: true,
+    });
+
+// Also at load: records written at require time must not reach fd 1.
+resetToMemory();
+
+beforeEach(resetToMemory);
+
+afterEach(() => {
+    const violations = takeViolationsForTests();
+    if (violations.length) {
+        const list = violations.map((v) => `${v.level} ${v.logger}: ${v.message}`).join('\n');
+        throw new Error(`frigg.* records at WARN or above need an eventName:\n${list}`);
+    }
+});

package/logs/levels.js

@@ -0,0 +1,71 @@
+const LEVELS = Object.freeze({
+    TRACE: 10,
+    DEBUG: 20,
+    INFO: 30,
+    WARN: 40,
+    ERROR: 50,
+    FATAL: 60,
+});
+
+const LEVEL_NAMES = Object.freeze(Object.keys(LEVELS));
+const DEFAULT_LEVEL = 'INFO';
+const MAX_ECHO_LENGTH = 32;
+
+function parseLevel(value) {
+    if (typeof value !== 'string') return null;
+    const name = value.trim().toUpperCase();
+    return Object.prototype.hasOwnProperty.call(LEVELS, name) ? name : null;
+}
+
+function isSet(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+
+function isLocalRun(env) {
+    if (env.STAGE === 'local') return true;
+    const offline = String(env.IS_OFFLINE ?? '').trim().toLowerCase();
+    return offline === 'true' || offline === '1';
+}
+
+function lessVerbose(a, b) {
+    return LEVELS[a] >= LEVELS[b] ? a : b;
+}
+
+function resolveLevel(env = {}) {
+    const warnings = [];
+    let level;
+
+    if (isSet(env.FRIGG_LOG_LEVEL)) {
+        level = parseLevel(env.FRIGG_LOG_LEVEL);
+        if (!level) {
+            level = DEFAULT_LEVEL;
+            warnings.push({
+                eventName: 'frigg.logger.invalid_level',
+                message: 'Unknown FRIGG_LOG_LEVEL, using INFO',
+                fields: {
+                    received: env.FRIGG_LOG_LEVEL.trim().slice(0, MAX_ECHO_LENGTH),
+                    allowed: LEVEL_NAMES,
+                },
+            });
+        }
+    } else if (env.DEBUG_VERBOSE === '1' || isLocalRun(env)) {
+        level = 'DEBUG';
+    } else {
+        level = DEFAULT_LEVEL;
+    }
+
+    const awsLevel = parseLevel(env.AWS_LAMBDA_LOG_LEVEL);
+    if (awsLevel && awsLevel !== level) {
+        const effective = lessVerbose(level, awsLevel);
+        warnings.push({
+            eventName: 'frigg.logger.level_conflict',
+            message: 'FRIGG_LOG_LEVEL and AWS_LAMBDA_LOG_LEVEL differ, using the less verbose level',
+            fields: { friggLevel: level, awsLevel, effectiveLevel: effective },
+        });
+        level = effective;
+    }
+
+    return { level, warnings };
+}
+
+module.exports = { LEVELS, LEVEL_NAMES, DEFAULT_LEVEL, parseLevel, resolveLevel };

package/logs/logger-runtime.js

@@ -0,0 +1,137 @@
+const { LEVELS, parseLevel, resolveLevel } = require('./levels');
+
+// On globalThis so jest.resetModules and nested core copies share one state.
+const STATE_KEY = Symbol.for('@friggframework/core.logs');
+
+function state() {
+    if (!globalThis[STATE_KEY]) {
+        globalThis[STATE_KEY] = {
+            config: null,
+            levelOverride: null,
+            sinks: null,
+            spanContextProvider: null,
+            warned: new Set(),
+            inLog: false,
+            trackViolations: false,
+            violations: [],
+        };
+    }
+    return globalThis[STATE_KEY];
+}
+
+function readEnv(name) {
+    const value = process.env[name];
+    return typeof value === 'string' && value !== '' ? value : undefined;
+}
+
+function getConfig() {
+    const s = state();
+    if (!s.config) {
+        const resolved = s.levelOverride
+            ? { level: s.levelOverride, warnings: [] }
+            : resolveLevel(process.env);
+        s.config = {
+            level: resolved.level,
+            threshold: LEVELS[resolved.level],
+            appName: readEnv('FRIGG_STACK'),
+            stage: readEnv('STAGE'),
+            pendingWarnings: resolved.warnings,
+        };
+    }
+    return s.config;
+}
+
+function takeConfigWarnings() {
+    const s = state();
+    const config = getConfig();
+    const pending = config.pendingWarnings.splice(0);
+    return pending.filter((warning) => {
+        if (s.warned.has(warning.eventName)) return false;
+        s.warned.add(warning.eventName);
+        return true;
+    });
+}
+
+function getSinks() {
+    const s = state();
+    if (!s.sinks) {
+        s.sinks = [require('./sinks').createStdoutSink()];
+    }
+    return s.sinks;
+}
+
+function setSinks(sinks) {
+    state().sinks = Array.isArray(sinks) ? [...sinks] : null;
+}
+
+function hasFlushableSinks() {
+    return getSinks().some((sink) => typeof sink.flush === 'function');
+}
+
+async function flushSinks({ signal } = {}) {
+    await Promise.allSettled(
+        getSinks()
+            .filter((sink) => typeof sink.flush === 'function')
+            .map(async (sink) => sink.flush({ signal }))
+    );
+}
+
+function setSpanContextProvider(provider) {
+    state().spanContextProvider = typeof provider === 'function' ? provider : null;
+}
+
+function getSpanContextProvider() {
+    return state().spanContextProvider;
+}
+
+function getSpanContext() {
+    const provider = state().spanContextProvider;
+    if (!provider) return null;
+    try {
+        const ctx = provider();
+        if (ctx && typeof ctx.traceId === 'string' && typeof ctx.spanId === 'string') {
+            return ctx;
+        }
+    } catch {
+        // A broken provider must not break logging.
+    }
+    return null;
+}
+
+// Off in production, so a warm container never grows this list.
+function recordViolation(violation) {
+    const s = state();
+    if (s.trackViolations) s.violations.push(violation);
+}
+
+function takeViolationsForTests() {
+    return state().violations.splice(0);
+}
+
+function resetLoggerForTests({ level, sinks, trackViolations } = {}) {
+    const s = state();
+    s.config = null;
+    s.levelOverride = parseLevel(level);
+    setSinks(sinks);
+    s.spanContextProvider = null;
+    s.warned.clear();
+    s.violations.length = 0;
+    s.inLog = false;
+    if (typeof trackViolations === 'boolean') s.trackViolations = trackViolations;
+}
+
+module.exports = {
+    state,
+    getConfig,
+    takeConfigWarnings,
+    getSinks,
+    setSinks,
+    hasFlushableSinks,
+    flushSinks,
+    setSpanContextProvider,
+    getSpanContextProvider,
+    getSpanContext,
+    recordViolation,
+    takeViolationsForTests,
+    resetLoggerForTests,
+};