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

package/telemetry/telemetry-runtime.js

@@ -0,0 +1,164 @@
+// The process composition root for telemetry: one shared state, per-part lazy
+// getters, one atomic reset — replacing three separate singleton module caches
+// (telemetry / usage-rollup / plugin-subscribers) that previously had to be
+// reset together in the right order. Bus identity across the parts is guaranteed
+// by construction: the rollup and plugin subscribers attach to the same
+// getTelemetry() instance reached through this module's own closure.
+
+const { createTelemetry } = require('./telemetry-service');
+const { NoOpTelemetry } = require('./no-op-telemetry');
+const loggerRuntime = require('../logs/logger-runtime');
+
+const UNSET = Symbol('unset');
+
+function newState() {
+    return { telemetry: null, usageRollup: UNSET, pluginSubscribers: UNSET };
+}
+let state = newState();
+
+function loadTelemetryConfig() {
+    // Lazy-required to avoid a load-time cycle with the handlers layer.
+    const { loadAppDefinition } = require('../handlers/app-definition-loader');
+    return loadAppDefinition();
+}
+
+function activeSpanContext() {
+    const telemetry = state.telemetry;
+    return telemetry && typeof telemetry.getActiveSpanContext === 'function'
+        ? telemetry.getActiveSpanContext()
+        : null;
+}
+
+// resetLoggerForTests clears the provider, so check on every call.
+function ensureSpanContextProvider() {
+    if (loggerRuntime.getSpanContextProvider() !== activeSpanContext) {
+        loggerRuntime.setSpanContextProvider(activeSpanContext);
+    }
+}
+
+/**
+ * The process telemetry service. Created lazily on first use and reused for the
+ * life of the Lambda container, so the OTel SDK initialises at most once per cold
+ * start. Never throws — any failure falls back to the no-op.
+ */
+function getTelemetry() {
+    ensureSpanContextProvider();
+    if (state.telemetry) return state.telemetry;
+    try {
+        const { telemetry = {} } = loadTelemetryConfig();
+        const stage = process.env.STAGE || process.env.NODE_ENV || 'production';
+        state.telemetry = createTelemetry({
+            exporter: telemetry.exporter,
+            sampleRatio: telemetry.sampleRatio,
+            resource: { service: process.env.FRIGG_STACK || 'frigg', stage },
+        });
+    } catch (_) {
+        state.telemetry = new NoOpTelemetry();
+    }
+    return state.telemetry;
+}
+
+/**
+ * The process usage-rollup subscriber, wired to getTelemetry()'s bus. Returns
+ * null when usage is disabled (no Definition.usage opt-in and no North Star) or
+ * the app definition can't load. Never throws — the warn lets operators tell
+ * "usage off" from "usage broken" (e.g. unresolved DB_TYPE).
+ */
+function getUsageRollupSubscriber() {
+    if (state.usageRollup !== UNSET) return state.usageRollup;
+    state.usageRollup = null;
+    try {
+        const { computeTrackedMetrics } = require('../usage/tracked-metrics');
+        const {
+            northStarKeys,
+            createNorthStarDerivationSubscriber,
+        } = require('./north-star');
+        const { integrations = [], telemetry = {} } = loadTelemetryConfig();
+
+        // Track both Definition.usage opt-ins and any North Star counter keys,
+        // so a derived North Star persists even without an explicit usage decl.
+        const trackedMetrics = computeTrackedMetrics(integrations);
+        for (const key of northStarKeys(telemetry.northStar)) {
+            trackedMetrics.add(key);
+        }
+        if (trackedMetrics.size === 0) return state.usageRollup;
+
+        const {
+            createUsageRepository,
+        } = require('../usage/repositories/usage-repository-factory');
+        const {
+            createUsageRollupSubscriber,
+        } = require('./usage-rollup-subscriber');
+        const telemetryService = getTelemetry(); // same memo → shared bus
+
+        state.usageRollup = createUsageRollupSubscriber({
+            telemetry: telemetryService,
+            usageRepository: createUsageRepository(),
+            trackedMetrics,
+        });
+
+        // North Star derived-from-trace: emits the North Star counter when a
+        // configured signal matches; the emission flows to the rollup above.
+        if (telemetry.northStar) {
+            createNorthStarDerivationSubscriber({
+                telemetry: telemetryService,
+                northStar: telemetry.northStar,
+            });
+        }
+    } catch (error) {
+        console.warn(
+            `[Frigg][usage] rollup disabled: ${error && error.message}`
+        );
+        state.usageRollup = null;
+    }
+    return state.usageRollup;
+}
+
+/**
+ * Adopter-declared telemetry subscribers, wired to getTelemetry()'s bus once per
+ * cold start. Independent of the usage rollup (adopter taps wire even when no
+ * integration declares Definition.usage). Never throws.
+ */
+function getPluginTelemetrySubscribers() {
+    if (state.pluginSubscribers !== UNSET) return state.pluginSubscribers;
+    state.pluginSubscribers = [];
+    try {
+        const { wireTelemetrySubscribers } = require('./plugin-subscribers');
+        const { telemetry = {} } = loadTelemetryConfig();
+        const subscribers = telemetry.subscribers || [];
+        if (subscribers.length === 0) return state.pluginSubscribers;
+
+        state.pluginSubscribers = wireTelemetrySubscribers({
+            telemetry: getTelemetry(),
+            subscribers,
+        });
+    } catch (error) {
+        console.warn(
+            `[Frigg][telemetry] plugin subscribers disabled: ${
+                error && error.message
+            }`
+        );
+        state.pluginSubscribers = [];
+    }
+    return state.pluginSubscribers;
+}
+
+/** Test-only: reset the whole runtime — no stale cross-memo states possible. */
+function resetTelemetryRuntimeForTests() {
+    state = newState();
+}
+
+/** Test-only: install a telemetry service; dependent memos clear atomically. */
+function setTelemetryForTests(telemetry) {
+    state = newState();
+    state.telemetry = telemetry;
+    ensureSpanContextProvider();
+}
+
+module.exports = {
+    getTelemetry,
+    getUsageRollupSubscriber,
+    getPluginTelemetrySubscribers,
+    resetTelemetryRuntimeForTests,
+    setTelemetryForTests,
+};

package/telemetry/telemetry-service.js

@@ -0,0 +1,52 @@
+const { NoOpTelemetry } = require('./no-op-telemetry');
+const { createTelemetryEventBus } = require('./telemetry-event-bus');
+
+/**
+ * @typedef {object} TelemetryService The vendor-neutral telemetry port. Both
+ * NoOpTelemetry and OtelTelemetry implement it (duck-typed; the bound wrapper
+ * from bindTelemetryContext is a plain object that also satisfies it):
+ *   count(name, value?, attributes?, context?) · event(name, attributes?, context?)
+ *   span(name, fn) · startSpan(name?) · withContext(context, fn)
+ *   on(eventType, cb) · forceFlush() · shutdown() · isEnabled()
+ *   getActiveSpanContext() → { traceId, spanId, traceFlags } | null
+ */
+
+/**
+ * Determine whether an exporter descriptor means "emit nothing".
+ * Absent config or `{ type: 'none' }` (or `'noop'`) → no-op.
+ */
+function isNoOpExporter(exporter) {
+    if (!exporter) return true;
+    const type = exporter.type;
+    return !type || type === 'none' || type === 'noop';
+}
+
+/**
+ * Create the vendor-neutral telemetry service — the adapter selector. Integration
+ * code uses the returned instance (`this.telemetry`) and never imports a backend
+ * SDK. With no exporter configured it returns `NoOpTelemetry` (loads zero OTel);
+ * a real exporter lazily constructs `OtelTelemetry`.
+ *
+ * @param {object} [options]
+ * @param {object} [options.exporter] Exporter descriptor, e.g. `{ type: 'otlp', endpoint }`.
+ * @param {object} [options.resource] Resource attributes, e.g. `{ service, stage }`.
+ * @param {number} [options.sampleRatio] Parent-based sampling ratio (0..1).
+ * @param {object} [options.bus] Event bus to reuse (defaults to a fresh one).
+ */
+function createTelemetry(options = {}) {
+    // The internal event stream is always on and independent of OTel export:
+    // the usage rollup + plugin taps must work even when
+    // the OTel exporter is a no-op. The bus is pure JS, so this does not load
+    // any OTel module on the no-op path.
+    const bus = options.bus || createTelemetryEventBus();
+
+    if (isNoOpExporter(options.exporter)) {
+        return new NoOpTelemetry({ bus });
+    }
+
+    // Lazy-required so the no-op path never loads the OTel SDK.
+    const { OtelTelemetry } = require('./otel-telemetry');
+    return new OtelTelemetry({ ...options, bus });
+}
+
+module.exports = { createTelemetry, isNoOpExporter };

package/telemetry/usage-rollup-subscriber.js

@@ -0,0 +1,116 @@
+const { computeUsageWindows } = require('../usage/usage-windows');
+
+const WEBHOOK_EVENT_NAMES = new Set(['ON_WEBHOOK']);
+
+/**
+ * Framework auto-signal metric names → the canonical usage key they feed.
+ * Resolvers receive (attributes, context) and may return null to
+ * decline. Handler invocations map by event: USER_ACTION → user_actions; the
+ * DB-connected `ON_WEBHOOK` queue dispatch → webhooks.received (per-integration,
+ * and where a durable write is actually possible — the HTTP receipt handler is
+ * DB-free so its buffer is discarded).
+ */
+const METRIC_TO_CANONICAL = {
+    'frigg.apimodule.requests': () => 'api.requests',
+    'frigg.handler.invocations': (attrs, ctx) => {
+        if (attrs && attrs.event === 'USER_ACTION') return 'user_actions';
+        if (ctx && WEBHOOK_EVENT_NAMES.has(ctx.event_name)) {
+            return 'webhooks.received';
+        }
+        return null;
+    },
+};
+
+/**
+ * The built-in usage-rollup subscriber. Subscribes to the
+ * telemetry event bus and folds *declared* counters (canonical or custom) into
+ * the durable usage store. It buffers within an invocation and writes on
+ * `flush()` (no timers — Lambda-safe), or drops the buffer on `discard()` for an
+ * SQS redelivery so at-least-once delivery does not double-count (approximate
+ * accuracy contract).
+ *
+ * Attribution: high-cardinality ids never ride metric labels, so integrationId
+ * comes from the bus-only `context` (populated from the ambient handler context)
+ * and otherwise falls back to the bounded integration_type.
+ */
+function createUsageRollupSubscriber({
+    telemetry,
+    usageRepository,
+    trackedMetrics = new Set(),
+    now = () => new Date(),
+}) {
+    // Buffer key is a JSON tuple [integrationId, integrationType, metric, window]
+    // — collision-proof for developer-defined custom keys / names.
+    let buffer = new Map();
+
+    function resolveUsageKey(name, attributes, context) {
+        if (trackedMetrics.has(name)) return name;
+        const resolver = METRIC_TO_CANONICAL[name];
+        const canonical = resolver ? resolver(attributes || {}, context) : null;
+        return canonical && trackedMetrics.has(canonical) ? canonical : null;
+    }
+
+    function onMetric(payload) {
+        try {
+            const { name, value = 1, attributes = {}, context } = payload;
+            const metric = resolveUsageKey(name, attributes, context);
+            if (!metric) return;
+
+            const integrationType =
+                context?.integrationType || attributes.integration_type || null;
+            if (!integrationType) return; // cannot attribute — skip
+
+            const integrationId = context?.integrationId || integrationType;
+
+            for (const window of computeUsageWindows(now())) {
+                const key = JSON.stringify([
+                    integrationId,
+                    integrationType,
+                    metric,
+                    window,
+                ]);
+                buffer.set(key, (buffer.get(key) || 0) + value);
+            }
+        } catch (_) {
+            // Rollup must never break emission.
+        }
+    }
+
+    const unsubscribe = telemetry.on('metric', onMetric);
+
+    async function flush() {
+        if (buffer.size === 0) return;
+        const pending = buffer;
+        buffer = new Map();
+        for (const [key, value] of pending) {
+            const [integrationId, integrationType, metric, window] =
+                JSON.parse(key);
+            try {
+                await usageRepository.increment({
+                    integrationId,
+                    integrationType,
+                    metric,
+                    window,
+                    value,
+                });
+            } catch (_) {
+                // A single failed write must not abort the rest of the flush.
+            }
+        }
+    }
+
+    function discard() {
+        buffer = new Map();
+    }
+
+    return {
+        flush,
+        discard,
+        unsubscribe,
+        get bufferSize() {
+            return buffer.size;
+        },
+    };
+}
+
+module.exports = { createUsageRollupSubscriber, METRIC_TO_CANONICAL };

package/token/repositories/token-repository-documentdb.js

@@ -0,0 +1,137 @@
+const { prisma } = require('../../database/prisma');
+const bcrypt = require('bcryptjs');
+const {
+    toObjectId,
+    fromObjectId,
+    findMany,
+    findOne,
+    insertOne,
+    deleteOne,
+    deleteMany,
+} = require('../../database/documentdb-utils');
+const { TokenRepositoryInterface } = require('./token-repository-interface');
+const { ClientSafeError } = require('../../errors');
+
+const BCRYPT_ROUNDS = 10;
+
+class TokenRepositoryDocumentDB extends TokenRepositoryInterface {
+    constructor() {
+        super();
+        this.prisma = prisma;
+    }
+
+    async createTokenWithExpire(userId, rawToken, minutes) {
+        const tokenHash = await bcrypt.hash(rawToken, BCRYPT_ROUNDS);
+        const expires = new Date(Date.now() + minutes * 60000);
+        const now = new Date();
+        const document = {
+            token: tokenHash,
+            expires,
+            userId: toObjectId(userId),
+            created: now,
+        };
+        const insertedId = await insertOne(this.prisma, 'Token', document);
+        const created = await findOne(this.prisma, 'Token', {
+            _id: insertedId,
+        });
+        return this._mapToken(created);
+    }
+
+    async validateAndGetToken(tokenObj) {
+        const objectId = toObjectId(tokenObj.id);
+        if (!objectId) {
+            throw new ClientSafeError(
+                'Invalid Token: Token does not exist',
+                401
+            );
+        }
+        const record = await findOne(this.prisma, 'Token', { _id: objectId });
+        if (!record) {
+            throw new ClientSafeError(
+                'Invalid Token: Token does not exist',
+                401
+            );
+        }
+        const isValid = await bcrypt.compare(tokenObj.token, record.token);
+        if (!isValid) {
+            throw new ClientSafeError(
+                'Invalid Token: Token does not match',
+                401
+            );
+        }
+        if (record.expires && new Date(record.expires) < new Date()) {
+            throw new ClientSafeError('Invalid Token: Token is expired', 401);
+        }
+        return this._mapToken(record);
+    }
+
+    async findTokenById(tokenId) {
+        const objectId = toObjectId(tokenId);
+        if (!objectId) return null;
+        const record = await findOne(this.prisma, 'Token', { _id: objectId });
+        return record ? this._mapToken(record) : null;
+    }
+
+    async findTokensByUserId(userId) {
+        const objectId = toObjectId(userId);
+        const filter = objectId ? { userId: objectId } : {};
+        const records = await findMany(this.prisma, 'Token', filter);
+        return records.map((record) => this._mapToken(record));
+    }
+
+    async deleteToken(tokenId) {
+        const objectId = toObjectId(tokenId);
+        if (!objectId) return { acknowledged: true, deletedCount: 0 };
+        const result = await deleteOne(this.prisma, 'Token', { _id: objectId });
+        const deleted = result?.n ?? 0;
+        return { acknowledged: true, deletedCount: deleted };
+    }
+
+    async deleteExpiredTokens() {
+        const result = await deleteMany(this.prisma, 'Token', {
+            expires: { $lt: new Date() },
+        });
+        const deleted = result?.n ?? 0;
+        return { acknowledged: true, deletedCount: deleted };
+    }
+
+    async deleteTokensByUserId(userId) {
+        const objectId = toObjectId(userId);
+        if (!objectId) return { acknowledged: true, deletedCount: 0 };
+        const result = await deleteMany(this.prisma, 'Token', {
+            userId: objectId,
+        });
+        const deleted = result?.n ?? 0;
+        return { acknowledged: true, deletedCount: deleted };
+    }
+
+    createJSONToken(token, rawToken) {
+        return JSON.stringify({
+            id: token.id,
+            token: rawToken,
+        });
+    }
+
+    createBase64BufferToken(token, rawToken) {
+        const jsonVal = this.createJSONToken(token, rawToken);
+        return Buffer.from(jsonVal).toString('base64');
+    }
+
+    getJSONTokenFromBase64BufferToken(buffer) {
+        const tokenStr = Buffer.from(buffer.trim(), 'base64').toString('ascii');
+        return JSON.parse(tokenStr);
+    }
+
+    _mapToken(record) {
+        if (!record) return null;
+        return {
+            id: fromObjectId(record._id),
+            token: record.token,
+            expires: record.expires ? new Date(record.expires) : null,
+            userId: fromObjectId(record.userId),
+            created: record.created ? new Date(record.created) : null,
+        };
+    }
+}
+
+module.exports = { TokenRepositoryDocumentDB };

package/token/repositories/token-repository-factory.js

@@ -0,0 +1,40 @@
+const { TokenRepositoryMongo } = require('./token-repository-mongo');
+const { TokenRepositoryPostgres } = require('./token-repository-postgres');
+const {
+    TokenRepositoryDocumentDB,
+} = require('./token-repository-documentdb');
+const config = require('../../database/config');
+
+/**
+ * Token Repository Factory
+ * Creates the appropriate repository adapter based on database type
+ *
+ * @returns {TokenRepositoryInterface} Configured repository adapter
+ */
+function createTokenRepository() {
+    const dbType = config.DB_TYPE;
+
+    switch (dbType) {
+        case 'mongodb':
+            return new TokenRepositoryMongo();
+
+        case 'postgresql':
+            return new TokenRepositoryPostgres();
+
+        case 'documentdb':
+            return new TokenRepositoryDocumentDB();
+
+        default:
+            throw new Error(
+                `Unsupported database type: ${dbType}. Supported values: 'mongodb', 'documentdb', 'postgresql'`
+            );
+    }
+}
+
+module.exports = {
+    createTokenRepository,
+    // Export adapters for direct testing
+    TokenRepositoryMongo,
+    TokenRepositoryPostgres,
+    TokenRepositoryDocumentDB,
+};

package/token/repositories/token-repository-interface.js

@@ -0,0 +1,131 @@
+/**
+ * Token Repository Interface
+ * Abstract base class defining the contract for token persistence adapters
+ *
+ * This follows the Port in Hexagonal Architecture:
+ * - Domain layer depends on this abstraction
+ * - Concrete adapters implement this interface
+ * - Use cases receive repositories via dependency injection
+ *
+ * Note: Currently, Token model has identical structure across MongoDB and PostgreSQL,
+ * so TokenRepository serves both. This interface exists for consistency and
+ * future-proofing if database-specific implementations become needed.
+ *
+ * @abstract
+ */
+class TokenRepositoryInterface {
+    /**
+     * Create token with expiration
+     *
+     * @param {string|number} userId - User ID
+     * @param {string} rawToken - Raw unhashed token
+     * @param {number} minutes - Minutes until expiration
+     * @returns {Promise<Object>} Created token object
+     * @abstract
+     */
+    async createTokenWithExpire(userId, rawToken, minutes) {
+        throw new Error(
+            'Method createTokenWithExpire must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Validate and get token
+     *
+     * @param {Object} tokenObj - Token object with id and token
+     * @returns {Promise<Object>} Validated token object
+     * @abstract
+     */
+    async validateAndGetToken(tokenObj) {
+        throw new Error(
+            'Method validateAndGetToken must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Find token by ID
+     *
+     * @param {string|number} tokenId - Token ID
+     * @returns {Promise<Object|null>} Token object or null
+     * @abstract
+     */
+    async findTokenById(tokenId) {
+        throw new Error('Method findTokenById must be implemented by subclass');
+    }
+
+    /**
+     * Find all tokens for a user
+     *
+     * @param {string|number} userId - User ID
+     * @returns {Promise<Array>} Array of token objects
+     * @abstract
+     */
+    async findTokensByUserId(userId) {
+        throw new Error(
+            'Method findTokensByUserId must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Delete token by ID
+     *
+     * @param {string|number} tokenId - Token ID
+     * @returns {Promise<boolean>} True if deleted
+     * @abstract
+     */
+    async deleteToken(tokenId) {
+        throw new Error('Method deleteToken must be implemented by subclass');
+    }
+
+    /**
+     * Delete expired tokens
+     *
+     * @returns {Promise<number>} Number of deleted tokens
+     * @abstract
+     */
+    async deleteExpiredTokens() {
+        throw new Error(
+            'Method deleteExpiredTokens must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Delete all tokens for a user
+     *
+     * @param {string|number} userId - User ID
+     * @returns {Promise<number>} Number of deleted tokens
+     * @abstract
+     */
+    async deleteTokensByUserId(userId) {
+        throw new Error(
+            'Method deleteTokensByUserId must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Create base64 buffer token
+     *
+     * @param {Object} token - Token object
+     * @param {string} rawToken - Raw token
+     * @returns {string} Base64 encoded token
+     */
+    createBase64BufferToken(token, rawToken) {
+        throw new Error(
+            'Method createBase64BufferToken must be implemented by subclass'
+        );
+    }
+
+    /**
+     * Get JSON token from base64 buffer token
+     *
+     * @param {string} base64Token - Base64 encoded token
+     * @returns {Object} Decoded token object
+     */
+    getJSONTokenFromBase64BufferToken(base64Token) {
+        throw new Error(
+            'Method getJSONTokenFromBase64BufferToken must be implemented by subclass'
+        );
+    }
+}
+
+module.exports = { TokenRepositoryInterface };