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

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,
+};

package/logs/logger.js

@@ -1,65 +1,157 @@
-const util = require('util');
+const { LEVELS, parseLevel } = require('./levels');
+const { getLoggerScope } = require('./context');
+const runtime = require('./logger-runtime');
+const { buildRecord, DEFAULT_LOGGER_NAME } = require('./record');
 
-// Except in some outlier circumstances, for example steam or event error handlers, this should be the only place that calls `console.*`.  That way, this file can be modified to log everything properly on a variety of platforms because all the logging code is here in one place.
-/* eslint-disable no-console */
+const LOGGER_OWN_NAME = 'frigg.logger';
 
-const logs = [];
-let flushCalled = false;
-
-function debug(...messages) {
-    if (messages.length) {
-        const date = new Date();
-        const text = util.format.apply(null, messages);
+function copyBindings(bindings, into = {}) {
+    if (!bindings || typeof bindings !== 'object') return into;
+    for (const key of Object.keys(bindings)) {
+        try {
+            into[key] = bindings[key];
+        } catch {
+            // A throwing getter drops only that binding.
+        }
+    }
+    return into;
+}
 
-        if (process.env.DEBUG_VERBOSE === '1') {
-            console.debug(date, text);
-        } else {
-            logs.push({ date, text });
+// One plain object per record. Static sources were copied at child() time.
+function evaluateBindings(sources) {
+    const merged = {};
+    for (const source of sources) {
+        if (typeof source !== 'function') {
+            Object.assign(merged, source);
+            continue;
         }
+        let value;
+        try {
+            value = source();
+        } catch {
+            continue;
+        }
+        copyBindings(value, merged);
     }
+    return merged;
+}
+
+function isFriggViolation(record) {
+    return (
+        record.logger.startsWith('frigg.') &&
+        LEVELS[record.level] >= LEVELS.WARN &&
+        !record.eventName
+    );
 }
 
-function initDebugLog(...initMessages) {
-    flushCalled = false;
+class Logger {
+    constructor(name, bindingSources = []) {
+        this.name = name;
+        this._bindingSources = bindingSources;
+    }
 
-    // Hacky but fast way to empty an array.
-    logs.length = 0;
+    trace(message, fields) {
+        this._log('TRACE', message, fields);
+    }
 
-    // Log initial event
-    debug(...initMessages);
-}
+    debug(message, fields) {
+        this._log('DEBUG', message, fields);
+    }
+
+    info(message, fields) {
+        this._log('INFO', message, fields);
+    }
+
+    warn(message, fields) {
+        this._log('WARN', message, fields);
+    }
+
+    error(message, fields) {
+        this._log('ERROR', message, fields);
+    }
+
+    fatal(message, fields) {
+        this._log('FATAL', message, fields);
+    }
+
+    child(bindings) {
+        const source = typeof bindings === 'function' ? bindings : copyBindings(bindings);
+        return new Logger(this.name, [...this._bindingSources, source]);
+    }
 
-function flushDebugLog(error) {
-    if (flushCalled) {
-        console.debug(
-            'Another error was encountered while handling the same request or event!  All debug messages are included again in this output as well.'
-        );
+    isLevelEnabled(level) {
+        try {
+            const name = parseLevel(level);
+            return name !== null && LEVELS[name] >= runtime.getConfig().threshold;
+        } catch {
+            return false;
+        }
     }
 
-    flushCalled = true;
+    _log(level, message, fields) {
+        const state = runtime.state();
+        if (state.inLog) return;
+        try {
+            const config = runtime.getConfig();
+            emitConfigWarnings();
+            if (LEVELS[level] < config.threshold) return;
+            // Set before fields, bindings and sinks run: any of them may log.
+            state.inLog = true;
 
-    // Output unless in verbose mode.  In verbose mode, these will already have been output so we don't want to output the messages twice.
-    if (process.env.DEBUG_VERBOSE !== '1') {
-        if (logs?.length > 0) {
-            for (const { date, text } of logs) {
-                console.debug(date, text);
+            const record = buildRecord({
+                level,
+                logger: this.name,
+                message,
+                fields,
+                bindings: evaluateBindings(this._bindingSources),
+                scope: getLoggerScope(),
+                spanContext: runtime.getSpanContext(),
+                resource: { appName: config.appName, stage: config.stage },
+            });
+            if (isFriggViolation(record)) {
+                runtime.recordViolation({
+                    logger: record.logger,
+                    level: record.level,
+                    message: record.message,
+                });
             }
+            writeToSinks(record);
+        } catch {
+            // The logger never throws.
+        } finally {
+            state.inLog = false;
         }
     }
+}
 
-    if (!error) {
-        error = new Error('flushDebugLog called with empty error');
+function writeToSinks(record) {
+    for (const sink of runtime.getSinks()) {
+        try {
+            sink.write(record);
+        } catch {
+            // One failing sink must not stop the others.
+        }
     }
+}
 
-    console.error(error);
+function emitConfigWarnings() {
+    const warnings = runtime.takeConfigWarnings();
+    if (!warnings.length) return;
+    const logger = getLogger(LOGGER_OWN_NAME);
+    for (const warning of warnings) {
+        logger.warn(warning.message, {
+            ...warning.fields,
+            eventName: warning.eventName,
+        });
+    }
+}
 
-    let { cause: parentError } = error;
+const loggers = new Map();
 
-    while (parentError) {
-        console.error('(Caused By)-------------------------');
-        console.error(parentError);
-        parentError = parentError.cause;
-    }
+function getLogger(name) {
+    const key = typeof name === 'string' && name ? name : DEFAULT_LOGGER_NAME;
+    if (!loggers.has(key)) loggers.set(key, new Logger(key));
+    return loggers.get(key);
 }
 
-module.exports = { debug, initDebugLog, flushDebugLog };
+module.exports = { Logger, getLogger };