@friggframework/core 2.0.0-next.102 → 2.0.0-next.103

package/telemetry/no-op-telemetry.js

@@ -0,0 +1,67 @@
+const { createTelemetryEventBus } = require('./telemetry-event-bus');
+const {
+    runWithTelemetryContext,
+    mergeTelemetryContext,
+} = require('./telemetry-context');
+
+/**
+ * No-op telemetry adapter: the default when no exporter is configured, so
+ * telemetry "rides for free". Imports **zero** OpenTelemetry packages (guarded by
+ * a require-graph test) — the no-op path never loads the OTel SDK, protecting
+ * Lambda cold-start. The internal event bus is still active: `count`/`event` are
+ * mirrored onto it so the durable usage rollup + plugin taps work even with
+ * export off (emitting to a bus with no subscribers is cheap).
+ */
+class NoOpTelemetry {
+    constructor({ bus = createTelemetryEventBus() } = {}) {
+        this._bus = bus;
+    }
+
+    count(name, value = 1, attributes = {}, context) {
+        const merged = mergeTelemetryContext(context);
+        const payload = { name, value, attributes };
+        if (merged) payload.context = merged;
+        this._bus.emit('metric', payload);
+    }
+
+    event(name, attributes = {}, context) {
+        const merged = mergeTelemetryContext(context);
+        const payload = { name, attributes };
+        if (merged) payload.context = merged;
+        this._bus.emit('event', payload);
+    }
+
+    async span(_name, fn) {
+        return typeof fn === 'function' ? fn() : undefined;
+    }
+
+    startSpan() {
+        return {
+            setAttributes() {},
+            setAttribute() {},
+            recordException() {},
+            setStatus() {},
+            end() {},
+        };
+    }
+
+    async withContext(context, fn) {
+        return runWithTelemetryContext(context, () =>
+            typeof fn === 'function' ? fn() : undefined
+        );
+    }
+
+    on(eventType, callback) {
+        return this._bus.on(eventType, callback);
+    }
+
+    async forceFlush() {}
+
+    async shutdown() {}
+
+    isEnabled() {
+        return false;
+    }
+}
+
+module.exports = { NoOpTelemetry };

package/telemetry/north-star.js

@@ -0,0 +1,103 @@
+/**
+ * Adopter North Star metric. A North Star simply references
+ * a usage-counter key (canonical or custom); its value is then read like any
+ * other counter via `frigg.usage.getTotalsByDimension({ metric: northStarKey })`. It is
+ * populated either by (a) direct emission of that counter, or (b) derived from a
+ * framework trace signal — this module implements (b) as a small bus subscriber
+ * that emits the North Star counter when a configured signal matches.
+ */
+
+/** Resolve the North Star counter entry for an integration type (byType wins). */
+function resolveNorthStarEntry(northStar, integrationType) {
+    if (!northStar) return null;
+    return (
+        (northStar.byType && northStar.byType[integrationType]) ||
+        northStar.default ||
+        null
+    );
+}
+
+/** The set of counter keys any North Star references — added to trackedMetrics. */
+function northStarKeys(northStar) {
+    const keys = new Set();
+    if (!northStar) return keys;
+    if (northStar.default?.name) keys.add(northStar.default.name);
+    for (const entry of Object.values(northStar.byType || {})) {
+        if (entry?.name) keys.add(entry.name);
+    }
+    return keys;
+}
+
+function matchesDeriveFrom(
+    deriveFrom,
+    { name, attributes = {}, context = {} }
+) {
+    if (!deriveFrom) return false;
+
+    if (deriveFrom.userAction) {
+        const rule = deriveFrom.userAction;
+        return (
+            name === 'frigg.handler.invocations' &&
+            attributes.event === 'USER_ACTION' &&
+            (!rule.action || context.event_name === rule.action)
+        );
+    }
+
+    if (deriveFrom.apiRequest) {
+        const rule = deriveFrom.apiRequest;
+        return (
+            name === 'frigg.apimodule.requests' &&
+            (!rule.method || attributes.method === rule.method) &&
+            (!rule.endpoint ||
+                (typeof context.url === 'string' &&
+                    context.url.includes(rule.endpoint)))
+        );
+    }
+
+    return false;
+}
+
+/**
+ * Subscribe to the bus and emit the North Star counter whenever a configured
+ * `deriveFrom` signal matches (config-only, no integration code). The emitted
+ * counter flows back through the bus to the usage rollup like any other metric.
+ */
+function createNorthStarDerivationSubscriber({ telemetry, northStar }) {
+    if (!telemetry || !northStar) return { unsubscribe() {} };
+
+    // Hoisted — the referenced-key set is fixed for the life of the subscriber.
+    const keys = northStarKeys(northStar);
+
+    function onMetric(payload) {
+        try {
+            // Never react to a North Star counter's own emission (no loop).
+            if (keys.has(payload.name)) return;
+
+            const integrationType =
+                payload.context?.integrationType ||
+                payload.attributes?.integration_type ||
+                null;
+            const entry = resolveNorthStarEntry(northStar, integrationType);
+            if (!entry || !entry.deriveFrom) return;
+            if (!matchesDeriveFrom(entry.deriveFrom, payload)) return;
+
+            telemetry.count(
+                entry.name,
+                1,
+                integrationType ? { integration_type: integrationType } : {},
+                payload.context
+            );
+        } catch (_) {
+            // Derivation must never break emission.
+        }
+    }
+
+    const unsubscribe = telemetry.on('metric', onMetric);
+    return { unsubscribe };
+}
+
+module.exports = {
+    resolveNorthStarEntry,
+    northStarKeys,
+    createNorthStarDerivationSubscriber,
+};

package/telemetry/otel-telemetry.js

@@ -0,0 +1,213 @@
+const otelApi = require('@opentelemetry/api');
+const {
+    BasicTracerProvider,
+    BatchSpanProcessor,
+    ParentBasedSampler,
+    TraceIdRatioBasedSampler,
+    AlwaysOnSampler,
+} = require('@opentelemetry/sdk-trace-base');
+const {
+    MeterProvider,
+    PeriodicExportingMetricReader,
+} = require('@opentelemetry/sdk-metrics');
+const { resourceFromAttributes } = require('@opentelemetry/resources');
+const { resolveExporter } = require('./exporters');
+const { createTelemetryEventBus } = require('./telemetry-event-bus');
+const {
+    runWithTelemetryContext,
+    mergeTelemetryContext,
+} = require('./telemetry-context');
+
+const TRACER_NAME = 'frigg';
+const METRIC_EXPORT_INTERVAL_MS =
+    Number(process.env.OTEL_METRIC_EXPORT_INTERVAL_MS) || 60000;
+
+/**
+ * Register an AsyncLocalStorage-backed OTel context manager once per process.
+ * Without it `BasicTracerProvider` uses the Noop context manager, so
+ * `startActiveSpan` never sets an active context — spans would be unparented
+ * roots, `getActiveSpan()` always undefined, and baggage inert. Guarded so
+ * repeated telemetry construction (tests) doesn't re-register.
+ */
+let contextManagerRegistered = false;
+function ensureContextManager() {
+    if (contextManagerRegistered) return;
+    contextManagerRegistered = true;
+    try {
+        const {
+            AsyncLocalStorageContextManager,
+        } = require('@opentelemetry/context-async-hooks');
+        const manager = new AsyncLocalStorageContextManager();
+        manager.enable();
+        otelApi.context.setGlobalContextManager(manager);
+    } catch (_) {
+        // If registration fails, traces are flat but usage attribution (which
+        // rides the separate telemetry-context ALS) is unaffected.
+    }
+}
+
+/**
+ * OpenTelemetry-backed telemetry adapter. Constructed only when a real exporter
+ * is configured (`createTelemetry` returns the no-op otherwise). `BatchSpanProcessor`
+ * is used uniformly — spans are delivered by the bounded `forceFlush()` the Lambda
+ * handler awaits before the container freezes (`callbackWaitsForEmptyEventLoop=false`),
+ * never by background timers.
+ */
+class OtelTelemetry {
+    constructor({
+        exporter,
+        resource = {},
+        sampleRatio,
+        bus = createTelemetryEventBus(),
+    } = {}) {
+        ensureContextManager();
+        const { traceExporter, metricExporter } = resolveExporter(exporter);
+
+        const resourceAttrs = { 'service.name': resource.service || 'frigg' };
+        if (resource.stage) {
+            resourceAttrs['deployment.environment'] = resource.stage;
+            resourceAttrs.stage = resource.stage;
+        }
+        if (resource.appName) resourceAttrs.appName = resource.appName;
+        const res = resourceFromAttributes(resourceAttrs);
+
+        const sampler =
+            typeof sampleRatio === 'number' && sampleRatio < 1
+                ? new ParentBasedSampler({
+                      root: new TraceIdRatioBasedSampler(sampleRatio),
+                  })
+                : new AlwaysOnSampler();
+
+        this._tracerProvider = new BasicTracerProvider({
+            resource: res,
+            sampler,
+            spanProcessors: traceExporter
+                ? [new BatchSpanProcessor(traceExporter)]
+                : [],
+        });
+
+        const metricReader = metricExporter
+            ? new PeriodicExportingMetricReader({
+                  exporter: metricExporter,
+                  exportIntervalMillis: METRIC_EXPORT_INTERVAL_MS,
+              })
+            : null;
+        this._meterProvider = new MeterProvider({
+            resource: res,
+            readers: metricReader ? [metricReader] : [],
+        });
+
+        this._bus = bus;
+        this._tracer = this._tracerProvider.getTracer(TRACER_NAME);
+        this._meter = this._meterProvider.getMeter(TRACER_NAME);
+        // One instrument instance per metric name — OTel requires it, and
+        // re-creating a counter would drop data points.
+        this._counters = new Map();
+    }
+
+    _getCounter(name) {
+        if (!this._counters.has(name)) {
+            this._counters.set(name, this._meter.createCounter(name));
+        }
+        return this._counters.get(name);
+    }
+
+    count(name, value = 1, attributes = {}, context) {
+        try {
+            this._getCounter(name).add(value, attributes);
+        } catch (_) {
+            // Telemetry must never break the wrapped path.
+        }
+        // Mirror onto the internal stream for the usage rollup + plugin taps; the
+        // bus context (incl. high-cardinality ids) rides the bus only, never the
+        // OTel metric attributes.
+        const merged = mergeTelemetryContext(context);
+        const payload = { name, value, attributes };
+        if (merged) payload.context = merged;
+        this._bus.emit('metric', payload);
+    }
+
+    event(name, attributes = {}, context) {
+        try {
+            const active = otelApi.trace.getActiveSpan();
+            if (active) active.addEvent(name, attributes);
+        } catch (_) {}
+        const merged = mergeTelemetryContext(context);
+        const payload = { name, attributes };
+        if (merged) payload.context = merged;
+        this._bus.emit('event', payload);
+    }
+
+    startSpan(name, options) {
+        return this._tracer.startSpan(name, options);
+    }
+
+    async span(name, fn, options = {}) {
+        return this._tracer.startActiveSpan(name, options, async (span) => {
+            try {
+                const result =
+                    typeof fn === 'function' ? await fn(span) : undefined;
+                span.setStatus({ code: otelApi.SpanStatusCode.OK });
+                return result;
+            } catch (err) {
+                span.recordException(err);
+                span.setStatus({
+                    code: otelApi.SpanStatusCode.ERROR,
+                    message: err && err.message,
+                });
+                throw err;
+            } finally {
+                span.end();
+            }
+        });
+    }
+
+    /**
+     * Run `fn` with the given identifiers on (a) the AsyncLocalStorage telemetry
+     * context — which the usage rollup reads to attribute emissions per-integration
+     * on ANY path — and (b) OTel baggage for trace propagation. High-cardinality
+     * ids ride here, never on metric labels.
+     */
+    async withContext(attributes = {}, fn) {
+        const entries = {};
+        for (const [key, value] of Object.entries(attributes)) {
+            if (value !== undefined && value !== null) {
+                entries[key] = { value: String(value) };
+            }
+        }
+        const baggage = otelApi.propagation.createBaggage(entries);
+        const ctx = otelApi.propagation.setBaggage(
+            otelApi.context.active(),
+            baggage
+        );
+        return runWithTelemetryContext(attributes, () =>
+            otelApi.context.with(ctx, () =>
+                typeof fn === 'function' ? fn() : undefined
+            )
+        );
+    }
+
+    on(eventType, callback) {
+        return this._bus.on(eventType, callback);
+    }
+
+    async forceFlush() {
+        await Promise.allSettled([
+            this._tracerProvider.forceFlush(),
+            this._meterProvider.forceFlush(),
+        ]);
+    }
+
+    async shutdown() {
+        await Promise.allSettled([
+            this._tracerProvider.shutdown(),
+            this._meterProvider.shutdown(),
+        ]);
+    }
+
+    isEnabled() {
+        return true;
+    }
+}
+
+module.exports = { OtelTelemetry };

package/telemetry/plugin-subscribers.js

@@ -0,0 +1,77 @@
+/**
+ * Declarative plugin/extension telemetry taps.
+ *
+ * The built-in usage rollup and North Star derivation subscribe to the telemetry
+ * bus in framework code; this lets an ADOPTER subscribe declaratively from the
+ * app definition (`Definition.telemetry.subscribers: [...]`) — forward to a
+ * custom sink, compute aggregates, persist counters — without writing wiring code.
+ *
+ * A subscriber is one of:
+ *   - a **factory** `fn(telemetry)` that registers itself (e.g. calls
+ *     `telemetry.on('metric', ...)`) and MAY return an unsubscribe function; or
+ *   - a **declarative object** `{ event?: 'metric'|'event', handler(payload, eventType) }`
+ *     — when `event` is omitted the handler receives both metric and event payloads.
+ *
+ * Every attach and every handler invocation is guarded so a misbehaving
+ * subscriber can never break emission, its siblings, or a handler (mirrors the
+ * bus's own per-subscriber isolation).
+ *
+ * @param {object} params
+ * @param {object} params.telemetry Telemetry service exposing `on(eventType, cb)`.
+ * @param {Array<Function|{event?: string, handler: Function}>} [params.subscribers]
+ * @returns {Array<Function>} unsubscribe functions for the wired subscribers.
+ */
+const EVENT_TYPES = ['metric', 'event'];
+
+function wireTelemetrySubscribers({ telemetry, subscribers = [] } = {}) {
+    if (
+        !telemetry ||
+        typeof telemetry.on !== 'function' ||
+        !Array.isArray(subscribers)
+    ) {
+        return [];
+    }
+
+    const unsubscribes = [];
+
+    for (const subscriber of subscribers) {
+        try {
+            if (typeof subscriber === 'function') {
+                const off = subscriber(telemetry);
+                if (typeof off === 'function') unsubscribes.push(off);
+                continue;
+            }
+
+            if (subscriber && typeof subscriber.handler === 'function') {
+                const events = subscriber.event
+                    ? [subscriber.event]
+                    : EVENT_TYPES;
+                for (const eventType of events) {
+                    const off = telemetry.on(eventType, (payload) => {
+                        try {
+                            subscriber.handler(payload, eventType);
+                        } catch (error) {
+                            console.warn(
+                                `[Frigg][telemetry] subscriber handler for "${eventType}" threw: ${
+                                    error && error.message
+                                }`
+                            );
+                        }
+                    });
+                    if (typeof off === 'function') unsubscribes.push(off);
+                }
+            }
+        } catch (error) {
+            // A single bad subscriber must never break wiring of the others.
+            console.warn(
+                `[Frigg][telemetry] failed to wire a telemetry subscriber: ${
+                    error && error.message
+                }`
+            );
+        }
+    }
+
+    return unsubscribes;
+}
+
+module.exports = { wireTelemetrySubscribers };

package/telemetry/telemetry-config.js

@@ -0,0 +1,120 @@
+/**
+ * Resolves and validates the telemetry section of an app definition
+ * into a normalized config the TelemetryService and
+ * usage rollup consume: `{ exporter, northStar, sampleRatio }`.
+ *
+ * Exporter default is keyed off STAGE: only a genuinely LOCAL run (STAGE=local)
+ * gets `console` (visible, free); every deployed stage — including `dev` —
+ * defaults to `none`. `dev` is a deployed AWS stage, and `console` there would
+ * write full spans to CloudWatch by default (cost + a data-exposure surface).
+ * Adopters opt into `console`/`otlp` explicitly for deployed stages.
+ */
+const VALID_EXPORTER_TYPES = [
+    'none',
+    'noop',
+    'console',
+    'otlp',
+    'honeycomb',
+    'datadog',
+];
+
+function normalizeExporterConfig(exporter, stage) {
+    if (!exporter) {
+        return stage === 'local' ? { type: 'console' } : { type: 'none' };
+    }
+
+    // Pre-built exporter instances (tests / advanced adopters) bypass type checks.
+    if (exporter.traceExporter || exporter.metricExporter) {
+        return exporter;
+    }
+
+    if (!VALID_EXPORTER_TYPES.includes(exporter.type)) {
+        throw new Error(
+            `[Frigg][telemetry] invalid exporter type "${exporter.type}". ` +
+                `Supported: ${VALID_EXPORTER_TYPES.join(', ')}`
+        );
+    }
+    return exporter;
+}
+
+// Fraction of TRACES exported (0..1, default 1) — a cost knob wired to the OTel
+// sampler in otel-telemetry. Does NOT thin usage counters; those stay exact.
+function resolveSampleRatio(sampleRatio) {
+    if (sampleRatio === undefined || sampleRatio === null) return 1;
+    if (
+        typeof sampleRatio !== 'number' ||
+        Number.isNaN(sampleRatio) ||
+        sampleRatio < 0 ||
+        sampleRatio > 1
+    ) {
+        throw new Error(
+            `[Frigg][telemetry] sampleRatio must be a number in [0,1], got ${sampleRatio}`
+        );
+    }
+    return sampleRatio;
+}
+
+function validateNorthStarEntry(entry, where) {
+    if (!entry || typeof entry.name !== 'string' || !entry.name) {
+        throw new Error(
+            `[Frigg][telemetry] northStar.${where} must reference a counter { name }`
+        );
+    }
+}
+
+/**
+ * Adopter-declared telemetry subscribers. Each is either a factory
+ * function `fn(telemetry)` or a declarative `{ event?, handler }` object. Kept as
+ * an array so `wireTelemetrySubscribers` can attach them to the bus at runtime.
+ */
+function resolveSubscribers(subscribers) {
+    if (subscribers === undefined || subscribers === null) return [];
+    if (!Array.isArray(subscribers)) {
+        throw new Error(
+            '[Frigg][telemetry] subscribers must be an array of functions or { handler } objects'
+        );
+    }
+    for (const subscriber of subscribers) {
+        const ok =
+            typeof subscriber === 'function' ||
+            (subscriber && typeof subscriber.handler === 'function');
+        if (!ok) {
+            throw new Error(
+                '[Frigg][telemetry] each subscriber must be a function or an object with a handler function'
+            );
+        }
+    }
+    return subscribers;
+}
+
+function resolveNorthStar(northStar) {
+    if (!northStar) return null;
+    if (northStar.default) validateNorthStarEntry(northStar.default, 'default');
+    if (northStar.byType) {
+        for (const [type, entry] of Object.entries(northStar.byType)) {
+            validateNorthStarEntry(entry, `byType.${type}`);
+        }
+    }
+    return northStar;
+}
+
+/**
+ * @param {object} appDefinition The backend `Definition` export.
+ * @param {object} [ctx]
+ * @param {string} [ctx.stage] Deployment stage (defaults to STAGE/NODE_ENV).
+ * @returns {{ exporter: object, northStar: object|null, sampleRatio: number }}
+ */
+function resolveTelemetryConfig(appDefinition = {}, ctx = {}) {
+    const stage =
+        ctx.stage || process.env.STAGE || process.env.NODE_ENV || 'production';
+    const telemetry = appDefinition.telemetry || {};
+
+    return {
+        exporter: normalizeExporterConfig(telemetry.exporter, stage),
+        northStar: resolveNorthStar(telemetry.northStar),
+        sampleRatio: resolveSampleRatio(telemetry.sampleRatio),
+        subscribers: resolveSubscribers(telemetry.subscribers),
+    };
+}
+
+module.exports = { resolveTelemetryConfig };

package/telemetry/telemetry-context.js

@@ -0,0 +1,40 @@
+const { AsyncLocalStorage } = require('node:async_hooks');
+
+/**
+ * Ambient telemetry context. A single process-wide AsyncLocalStorage
+ * holds the standard identifiers ({integrationId, integrationType, userId,
+ * version, ...}) for the duration of a handler, set once at the handler seam via
+ * `telemetry.withContext(...)`. Any emission during that async scope — including
+ * deep calls like an API-module request — reads the ambient context, so the
+ * usage rollup can attribute counters per-integration WITHOUT threading context
+ * through every call and WITHOUT relying on OTel baggage (which does not exist
+ * on the no-op path). This is the propagation mechanism the plan intended.
+ *
+ * Only bus-payload `context` is populated from here; high-cardinality ids never
+ * touch OTel metric labels.
+ */
+const store = new AsyncLocalStorage();
+
+function runWithTelemetryContext(context, fn) {
+    return store.run(context || {}, fn);
+}
+
+function getTelemetryContextStore() {
+    return store.getStore() || null;
+}
+
+/**
+ * Merge the ambient context with an explicit per-call context (explicit keys
+ * win, e.g. a request `url`). Returns undefined when there is nothing to attach.
+ */
+function mergeTelemetryContext(explicit) {
+    const ambient = store.getStore();
+    if (!ambient && !explicit) return undefined;
+    return { ...(ambient || {}), ...(explicit || {}) };
+}
+
+module.exports = {
+    runWithTelemetryContext,
+    getTelemetryContextStore,
+    mergeTelemetryContext,
+};

package/telemetry/telemetry-event-bus.js

@@ -0,0 +1,58 @@
+/**
+ * TelemetryEventBus — the internal event stream telemetry flows onto.
+ * Plugins/extensions and the built-in usage rollup
+ * subscribe here; it is deliberately independent of OTel export (Decision 7),
+ * so usage counters persist even when the OTel exporter is a no-op.
+ *
+ * This is intentionally a **synchronous** in-process fan-out (Frigg runs one
+ * invocation per Lambda container): a plain subscriber list with per-subscriber
+ * `try/catch` so a misbehaving subscriber can never break emission or its
+ * siblings. No queue/backpressure machinery — emission volume is bounded by a
+ * single invocation's work.
+ *
+ * ## Public event contract (semver-stable)
+ * Event types and their payload shapes:
+ *   - `'metric'` → `{ name: string, value: number, attributes: object, context?: object }`
+ *   - `'event'`  → `{ name: string, attributes: object, context?: object }`
+ * `attributes` are the bounded OTel metric labels. `context` (present when an
+ * ambient telemetry context is active) carries the high-cardinality identifiers
+ * — {integrationId, integrationType, userId, version, ...} plus per-call extras
+ * like a request `url` — which the usage rollup reads for attribution. Those ids
+ * NEVER appear in `attributes` (Cardinality note).
+ */
+function createTelemetryEventBus() {
+    /** @type {Map<string, Set<Function>>} */
+    const subscribers = new Map();
+
+    function on(eventType, callback) {
+        if (!subscribers.has(eventType)) {
+            subscribers.set(eventType, new Set());
+        }
+        const set = subscribers.get(eventType);
+        set.add(callback);
+        return function off() {
+            set.delete(callback);
+        };
+    }
+
+    function emit(eventType, payload) {
+        const set = subscribers.get(eventType);
+        if (!set || set.size === 0) return;
+        for (const callback of set) {
+            try {
+                callback(payload);
+            } catch (error) {
+                // A subscriber must never break emission or its siblings.
+                console.warn(
+                    `[Frigg][telemetry] subscriber for "${eventType}" threw: ${
+                        error && error.message
+                    }`
+                );
+            }
+        }
+    }
+
+    return { on, emit };
+}
+
+module.exports = { createTelemetryEventBus };