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

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

package/logs/record.js

@@ -0,0 +1,276 @@
+const { LEVELS } = require('./levels');
+const { serializeValue, serializeError, isError } = require('./serialize');
+const { isPlainObject } = require('./context');
+const {
+    RESOURCE_KEYS,
+    DROPPED_KEYS_FIELD,
+    OWNED_KEYS,
+    RESERVED_KEYS,
+    PAYLOAD_KEYS,
+} = require('./contract-keys');
+
+const MAX_RECORD_BYTES = 16 * 1024;
+const DEFAULT_LOGGER_NAME = 'frigg.unknown';
+
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        for (const key of Object.keys(value)) deepFreeze(value[key]);
+        Object.freeze(value);
+    }
+    return value;
+}
+
+function readFields(source) {
+    const result = {};
+    if (!source || typeof source !== 'object') return result;
+    let keys;
+    try {
+        keys = Object.keys(source);
+    } catch {
+        return result;
+    }
+    for (const key of keys) {
+        try {
+            result[key] = source[key];
+        } catch {
+            result[key] = '[Getter threw]';
+        }
+    }
+    return result;
+}
+
+// Returns the message text. An Error message is serialized once; when the
+// call site has no `error`, that result becomes the record's `error`.
+function buildMessage(message, callSite) {
+    if (typeof message === 'string') {
+        return { text: serializeValue(message) };
+    }
+    if (message === undefined || message === null) return { text: '' };
+    if (isError(message)) {
+        const error = serializeError(message);
+        const text = typeof error?.message === 'string' ? error.message : '';
+        if (callSite.error !== undefined) return { text };
+        callSite.error = message;
+        return { text, error };
+    }
+    if (callSite.value === undefined) callSite.value = message;
+    return { text: '[non-string message]' };
+}
+
+const INVOCATION_KEY = 'invocation';
+
+// A boundary adds request detail to the scope's invocation; scope keys win.
+function extendInvocation(scoped, detail) {
+    const merged = { ...scoped };
+    for (const key of Object.keys(detail)) {
+        if (!(key in merged)) merged[key] = detail[key];
+    }
+    return merged;
+}
+
+function traceFields(spanContext) {
+    if (
+        !spanContext ||
+        typeof spanContext.traceId !== 'string' ||
+        typeof spanContext.spanId !== 'string'
+    ) {
+        return {};
+    }
+    const flags = Number(spanContext.traceFlags) || 0;
+    return {
+        trace_id: spanContext.traceId,
+        span_id: spanContext.spanId,
+        trace_flags: (flags & 0xff).toString(16).padStart(2, '0'),
+    };
+}
+
+function sameValue(a, b) {
+    if (a === b) return true;
+    return (
+        typeof a === 'object' &&
+        typeof b === 'object' &&
+        JSON.stringify(a) === JSON.stringify(b)
+    );
+}
+
+function byteLength(record) {
+    return Buffer.byteLength(JSON.stringify(record));
+}
+
+function isDroppedKey(key, dropPayloads) {
+    return (
+        OWNED_KEYS.has(key) ||
+        RESERVED_KEYS.has(key) ||
+        (dropPayloads && PAYLOAD_KEYS.has(key))
+    );
+}
+
+// Filters and serializes one source. `error` is serialized on its own, once
+// (or taken from `preSerializedError`), and never walked by serializeValue.
+function prepareSource(source, dropPayloads, preSerializedError) {
+    const accepted = {};
+    const keys = [];
+    const dropped = [];
+    let rawError;
+    for (const [key, value] of Object.entries(source)) {
+        if (value === undefined || value === null) continue;
+        if (isDroppedKey(key, dropPayloads)) {
+            dropped.push(key);
+            continue;
+        }
+        keys.push(key);
+        if (key === 'error') rawError = value;
+        else accepted[key] = value;
+    }
+    // One pass over the object, so key rules (denied keys, digests,
+    // headers, OAuth shapes) apply to top-level fields too.
+    const safe = serializeValue(accepted);
+    const entries = [];
+    for (const key of keys) {
+        const value =
+            key === 'error'
+                ? preSerializedError ?? serializeError(rawError)
+                : safe?.[key];
+        if (value !== undefined && value !== null) entries.push([key, value]);
+    }
+    return { entries, dropped };
+}
+
+// The scope object is frozen and shared by every record of one scope.
+const preparedScopes = new WeakMap();
+
+function prepareScope(scope, dropPayloads) {
+    if (!scope || typeof scope !== 'object') return { entries: [], dropped: [] };
+    let byLevel = preparedScopes.get(scope);
+    if (!byLevel) {
+        byLevel = {};
+        preparedScopes.set(scope, byLevel);
+    }
+    const slot = dropPayloads ? 'info' : 'debug';
+    if (!byLevel[slot]) byLevel[slot] = prepareSource(scope, dropPayloads);
+    return byLevel[slot];
+}
+
+function buildRecord({
+    level,
+    logger,
+    message,
+    fields,
+    bindings,
+    scope,
+    spanContext,
+    resource = {},
+    now = new Date(),
+} = {}) {
+    const dropPayloads = LEVELS[level] >= LEVELS.INFO;
+    // log.error('msg', err): own props of an Error (axios config, request) must not become fields.
+    const callSite = readFields(isError(fields) ? { error: fields } : fields);
+    const built = buildMessage(message, callSite);
+    const record = {
+        timestamp: now.toISOString(),
+        level,
+        message: built.text,
+        logger: typeof logger === 'string' && logger ? logger : DEFAULT_LOGGER_NAME,
+    };
+    for (const key of RESOURCE_KEYS) {
+        if (typeof resource[key] === 'string' && resource[key]) {
+            record[key] = resource[key];
+        }
+    }
+    Object.assign(record, traceFields(spanContext));
+
+    const dropped = new Set();
+    const callSiteKeys = [];
+    // Call-site keys merged into the scope invocation; the size cap must reach them too.
+    const invocationDetailKeys = [];
+    const place = ({ entries, dropped: droppedHere }, isCallSite) => {
+        for (const key of droppedHere) dropped.add(key);
+        for (const [key, value] of entries) {
+            if (Object.prototype.hasOwnProperty.call(record, key)) {
+                if (
+                    key === INVOCATION_KEY &&
+                    isPlainObject(record[key]) &&
+                    isPlainObject(value)
+                ) {
+                    const merged = extendInvocation(record[key], value);
+                    if (isCallSite) {
+                        for (const detailKey of Object.keys(value)) {
+                            if (!(detailKey in record[key])) invocationDetailKeys.push(detailKey);
+                        }
+                    }
+                    record[key] = merged;
+                } else if (!sameValue(record[key], value)) {
+                    // A repeat of the winning value is no conflict.
+                    dropped.add(key);
+                }
+                continue;
+            }
+            record[key] = value;
+            if (isCallSite) callSiteKeys.push(key);
+        }
+    };
+    place(prepareScope(scope, dropPayloads), false);
+    place(prepareSource(bindings || {}, dropPayloads), false);
+    place(prepareSource(callSite, dropPayloads, built.error), true);
+
+    const setDroppedKeys = () => {
+        delete record[DROPPED_KEYS_FIELD];
+        if (dropped.size) record[DROPPED_KEYS_FIELD] = [...dropped];
+    };
+    setDroppedKeys();
+    let size = byteLength(record);
+
+    if (size > MAX_RECORD_BYTES) {
+        const candidates = [
+            ...callSiteKeys
+                .filter((key) => key !== 'error')
+                .map((key) => ({
+                    name: key,
+                    value: record[key],
+                    remove: () => delete record[key],
+                })),
+            ...invocationDetailKeys.map((key) => ({
+                name: `${INVOCATION_KEY}.${key}`,
+                value: record[INVOCATION_KEY][key],
+                remove: () => {
+                    const rest = { ...record[INVOCATION_KEY] };
+                    delete rest[key];
+                    record[INVOCATION_KEY] = rest;
+                },
+            })),
+        ];
+        const bySize = candidates
+            .map((candidate) => [candidate, Buffer.byteLength(JSON.stringify(candidate.value))])
+            .sort((a, b) => b[1] - a[1]);
+        for (const [candidate] of bySize) {
+            candidate.remove();
+            dropped.add(candidate.name);
+            setDroppedKeys();
+            size = byteLength(record);
+            if (size <= MAX_RECORD_BYTES) break;
+        }
+    }
+    for (const part of ['stack', 'cause']) {
+        if (
+            size > MAX_RECORD_BYTES &&
+            record.error &&
+            typeof record.error === 'object' &&
+            record.error[part] !== undefined
+        ) {
+            const { [part]: _removed, ...rest } = record.error;
+            record.error = rest;
+            size = byteLength(record);
+        }
+    }
+
+    return deepFreeze(record);
+}
+
+module.exports = {
+    buildRecord,
+    deepFreeze,
+    MAX_RECORD_BYTES,
+    RESERVED_KEYS,
+    PAYLOAD_KEYS,
+    DEFAULT_LOGGER_NAME,
+};