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

package/logs/sinks.js

@@ -0,0 +1,93 @@
+const fs = require('node:fs');
+const { deepFreeze } = require('./record');
+
+const DEFAULT_MAX_RETRIES = 10;
+const MAX_SLEEP_MS = 20;
+
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+
+function defaultWriteStderr(line) {
+    fs.writeSync(2, line);
+}
+
+function safeCode(code) {
+    return String(code ?? 'UNKNOWN').replace(/[^A-Za-z0-9_]/g, '').slice(0, 32) || 'UNKNOWN';
+}
+
+function createStdoutSink({
+    fd = 1,
+    writeSync = fs.writeSync,
+    writeStderr = defaultWriteStderr,
+    sleep = sleepSync,
+    maxRetries = DEFAULT_MAX_RETRIES,
+} = {}) {
+    const reportFailure = (code) => {
+        try {
+            writeStderr(`frigg.logger.write_failed code=${safeCode(code)}\n`);
+        } catch {
+            // Nothing is left to report to.
+        }
+    };
+
+    return {
+        name: 'stdout',
+        write(record) {
+            let buffer;
+            try {
+                buffer = Buffer.from(`${JSON.stringify(record)}\n`);
+            } catch {
+                reportFailure('SERIALIZE');
+                return;
+            }
+            let offset = 0;
+            let retries = 0;
+            // EAGAIN and a zero-byte write share one bounded retry budget.
+            const retry = () => {
+                if (retries >= maxRetries) {
+                    reportFailure('EAGAIN');
+                    return false;
+                }
+                retries += 1;
+                sleep(Math.min(retries, MAX_SLEEP_MS));
+                return true;
+            };
+            while (offset < buffer.length) {
+                let written;
+                try {
+                    written = writeSync(fd, buffer, offset, buffer.length - offset);
+                } catch (error) {
+                    if (error?.code !== 'EAGAIN') {
+                        reportFailure(error?.code);
+                        return;
+                    }
+                    if (!retry()) return;
+                    continue;
+                }
+                if (written > 0) offset += written;
+                else if (!retry()) return;
+            }
+        },
+    };
+}
+
+function createMemorySink({ install = true } = {}) {
+    const records = [];
+    const sink = {
+        name: 'memory',
+        records,
+        write(record) {
+            records.push(deepFreeze(JSON.parse(JSON.stringify(record))));
+        },
+        clear() {
+            records.length = 0;
+        },
+    };
+    if (install) {
+        require('./logger-runtime').setSinks([sink]);
+    }
+    return sink;
+}
+
+module.exports = { createStdoutSink, createMemorySink };

package/logs/summarize-event.js

@@ -0,0 +1,163 @@
+const { redactUrl } = require('./redact');
+
+// Best-effort extraction of the logical event/processId/integrationId from a
+// JSON message body: `data.*` first, then the top level. Used only for log
+// correlation. Never throws.
+function summarizeMessageBody(bodyStr) {
+    try {
+        const parsed = JSON.parse(bodyStr);
+        return {
+            event: parsed?.event,
+            processId: parsed?.data?.processId ?? parsed?.processId,
+            integrationId: parsed?.data?.integrationId ?? parsed?.integrationId,
+        };
+    } catch {
+        return {};
+    }
+}
+
+function objectKeys(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? Object.keys(value)
+        : [];
+}
+
+function rawQueryKeys(rawQueryString) {
+    if (typeof rawQueryString !== 'string' || !rawQueryString) return [];
+    try {
+        return [...new URLSearchParams(rawQueryString).keys()];
+    } catch {
+        return [];
+    }
+}
+
+function unique(list) {
+    return [...new Set(list)];
+}
+
+// The route template keeps ids out of the field: REST v1 `resource`, or the
+// path part of an HTTP API v2 `routeKey` such as `GET /api/{id}`.
+function routeTemplate(event, path) {
+    if (typeof event.resource === 'string' && event.resource) {
+        return event.resource;
+    }
+    if (typeof event.routeKey === 'string') {
+        const space = event.routeKey.indexOf(' ');
+        if (space > 0) return event.routeKey.slice(space + 1);
+    }
+    return path;
+}
+
+function summarizeHttp(event) {
+    const path = event.path || event.rawPath;
+    const summary = {
+        source: 'http',
+        method: event.httpMethod || event.requestContext?.http?.method,
+        path,
+        route: routeTemplate(event, path),
+        queryKeys: unique([
+            ...objectKeys(event.queryStringParameters),
+            ...objectKeys(event.multiValueQueryStringParameters),
+            ...rawQueryKeys(event.rawQueryString),
+        ]),
+        headerNames: unique(
+            [...objectKeys(event.headers), ...objectKeys(event.multiValueHeaders)].map(
+                (name) => name.toLowerCase()
+            )
+        ),
+    };
+    if (typeof event.routeKey === 'string' && event.routeKey) {
+        summary.routeKey = event.routeKey;
+    }
+    return summary;
+}
+
+// Best-effort extraction of correlation identifiers from a Lambda event.
+// For SQS: messageIds plus the parsed event/processId/integrationId of each
+// record body. For HTTP: method, route, query keys and header names. Never
+// throws and never returns a body, a query value or a header value.
+function summarizeLambdaEvent(event) {
+    try {
+        if (!event || typeof event !== 'object') return {};
+        if (Array.isArray(event.Records)) {
+            return {
+                source: 'sqs',
+                records: event.Records.map((r) => ({
+                    messageId: r?.messageId,
+                    receiveCount: r?.attributes?.ApproximateReceiveCount,
+                    ...summarizeMessageBody(r?.body),
+                })),
+            };
+        }
+        if (event.httpMethod || event.requestContext?.http) {
+            return summarizeHttp(event);
+        }
+        return { source: 'other' };
+    } catch {
+        return { source: 'other' };
+    }
+}
+
+// The bounded form that goes into the logger scope: no per-record array.
+function toScopeInvocation(summary) {
+    if (!summary || typeof summary !== 'object' || !summary.source) {
+        return { source: 'other' };
+    }
+    if (summary.source === 'sqs') {
+        return {
+            source: 'sqs',
+            recordCount: Array.isArray(summary.records) ? summary.records.length : 0,
+        };
+    }
+    if (summary.source === 'http') {
+        const invocation = {
+            source: 'http',
+            method: summary.method,
+            route: summary.route,
+        };
+        if (summary.routeKey) invocation.routeKey = summary.routeKey;
+        return invocation;
+    }
+    return { source: summary.source };
+}
+
+// Per-request detail for the entry and failure records, never for the
+// scope. A raw path can hold a token, so it goes through redactUrl.
+function toRequestDetails(summary) {
+    if (!summary || summary.source !== 'http') return {};
+    return {
+        path: redactUrl(summary.path ?? ''),
+        queryKeys: summary.queryKeys ?? [],
+        headerNames: summary.headerNames ?? [],
+    };
+}
+
+// The full redacted request summary (ADR-048 §6: it goes under `invocation`).
+function toRequestInvocation(summary) {
+    return { ...toScopeInvocation(summary), ...toRequestDetails(summary) };
+}
+
+// The same shape from an express request, for the express error boundary.
+function summarizeExpressRequest(req) {
+    try {
+        if (!req || typeof req !== 'object') return { source: 'http' };
+        return {
+            source: 'http',
+            method: req.method,
+            path: redactUrl(req.path ?? ''),
+            queryKeys: objectKeys(req.query),
+            headerNames: unique(objectKeys(req.headers).map((name) => name.toLowerCase())),
+        };
+    } catch {
+        return { source: 'http' };
+    }
+}
+
+module.exports = {
+    summarizeLambdaEvent,
+    summarizeMessageBody,
+    toScopeInvocation,
+    toRequestDetails,
+    toRequestInvocation,
+    summarizeExpressRequest,
+};

package/{module-plugin → modules}/index.js

@@ -1,25 +1,15 @@
-const { Credential } = require('./credential');
-const { EntityManager } = require('./entity-manager');
-const { Entity } = require('./entity');
-const { ModuleManager } = require('./manager');
 const { ApiKeyRequester } = require('./requester/api-key');
 const { BasicAuthRequester } = require('./requester/basic');
 const { OAuth2Requester } = require('./requester/oauth-2');
 const { Requester } = require('./requester/requester');
 const { ModuleConstants } = require('./ModuleConstants');
 const { ModuleFactory } = require('./module-factory');
-const { Auther } = require('./auther');
 
 module.exports = {
-    Credential,
-    EntityManager,
-    Entity,
-    ModuleManager,
     ApiKeyRequester,
     BasicAuthRequester,
     OAuth2Requester,
     Requester,
     ModuleConstants,
     ModuleFactory,
-    Auther
 };

package/modules/module-factory.js

@@ -0,0 +1,56 @@
+// todo: remove this file
+
+const { Module } = require('./module');
+
+/**
+ * Acts as a factory for fully-hydrated domain Module instances.
+ * Provides methods to retrieve and construct Module objects with their associated
+ * entity and definition.
+ */
+class ModuleFactory {
+    /**
+     * @param {Object} params - Configuration parameters.
+     * @param {import('./repositories/module-repository-interface').ModuleRepositoryInterface} params.moduleRepository - Repository for module data operations.
+     * @param {Array<Object>} params.moduleDefinitions - Array of module definitions.
+     */
+    constructor({ moduleRepository, moduleDefinitions }) {
+        this.moduleRepository = moduleRepository;
+        this.moduleDefinitions = moduleDefinitions;
+    }
+
+    async getModuleInstance(entityId, userId) {
+        const entity = await this.moduleRepository.findEntityById(
+            entityId,
+            userId
+        );
+
+        if (!entity) {
+            throw new Error(`Entity ${entityId} not found`);
+        }
+
+        if (entity.userId !== userId) {
+            throw new Error(
+                `Entity ${entityId} does not belong to user ${userId}`
+            );
+        }
+
+        const moduleName = entity.moduleName;
+        const moduleDefinition = this.moduleDefinitions.find((def) => {
+            return moduleName === def.moduleName;
+        });
+
+        if (!moduleDefinition) {
+            throw new Error(
+                `Module definition not found for module: ${moduleName}`
+            );
+        }
+
+        return new Module({
+            userId,
+            entity,
+            definition: moduleDefinition,
+        });
+    }
+}
+
+module.exports = { ModuleFactory };

package/modules/module.js

@@ -0,0 +1,320 @@
+const { Delegate } = require('../core');
+const _ = require('lodash');
+const { getLogger } = require('../logs');
+const { ModuleConstants } = require('./ModuleConstants');
+const {
+    createCredentialRepository,
+} = require('../credential/repositories/credential-repository-factory');
+const {
+    createModuleRepository,
+} = require('./repositories/module-repository-factory');
+
+// todo: this class should be a Domain class, and the Delegate function is preventing us from
+// doing that, we probably have to get rid of the Delegate class as well as the event based
+// calls since they go against the Domain Driven Design principles (eg. a domain class should not call repository methods or use cases)
+class Module extends Delegate {
+    //todo: entity should be replaced with actual entity properties
+    /**
+     *
+     * @param {Object} params
+     * @param {Object} params.definition The definition of the Api Module
+     * @param {string} params.userId The user id
+     * @param {Object} params.entity The entity record from the database
+     * @param {string} [params.state] Optional OAuth state value forwarded to the API client (round-trips through the OAuth provider).
+     */
+    constructor({ definition, userId = null, entity: entityObj = null, state = null }) {
+        super({ definition, userId, entity: entityObj });
+
+        this.validateDefinition(definition);
+
+        this.userId = userId;
+        this.entity = entityObj;
+        this.credential = entityObj?.credential;
+        this.definition = definition;
+        this.name = this.definition.moduleName;
+        this.logger = getLogger(`module.${this.name ?? 'unknown'}`).child(() => ({
+            entityId: this.entity?.id,
+            credentialId:
+                this.credential?.id ??
+                (typeof this.credential === 'string'
+                    ? this.credential
+                    : undefined),
+        }));
+        this.modelName = this.definition.modelName;
+        this.apiClass = this.definition.API;
+
+        this.credentialRepository = createCredentialRepository();
+        this.moduleRepository = createModuleRepository();
+
+        // Module → parent delegate (typically IntegrationBase) events
+        this.DLGT_CREDENTIAL_INVALIDATED = 'CREDENTIAL_INVALIDATED';
+        this.delegateTypes.push(this.DLGT_CREDENTIAL_INVALIDATED);
+        this.DLGT_CREDENTIAL_VALIDATED = 'CREDENTIAL_VALIDATED';
+        this.delegateTypes.push(this.DLGT_CREDENTIAL_VALIDATED);
+
+        Object.assign(this, this.definition.requiredAuthMethods);
+
+        const apiParams = {
+            ...this.definition.env,
+            delegate: this,
+            logger: this.logger,
+            ...(state ? { state } : {}),
+            ...(this.credential?.data
+                ? this.apiParamsFromCredential(this.credential.data)
+                : {}), // Handle case when credential is undefined
+            ...this.apiParamsFromEntity(this.entity),
+        };
+        this.api = new this.apiClass(apiParams);
+    }
+
+    getName() {
+        return this.name;
+    }
+
+    getEntityOptions() {
+        return this.definition.getEntityOptions();
+    }
+
+    async refreshEntityOptions(options) {
+        await this.definition.refreshEntityOptions(options);
+        return this.getEntityOptions();
+    }
+
+    apiParamsFromCredential(credential) {
+        return _.pick(credential, ...this.apiPropertiesToPersist?.credential);
+    }
+
+    apiParamsFromEntity(entity) {
+        return _.pick(entity, ...this.apiPropertiesToPersist?.entity);
+    }
+
+    validateAuthorizationRequirements() {
+        const requirements = this.getAuthorizationRequirements();
+        let valid = true;
+        if (
+            ['oauth1', 'oauth2'].includes(requirements.type) &&
+            !requirements.url
+        ) {
+            valid = false;
+        }
+        return valid;
+    }
+
+    getAuthorizationRequirements(params) {
+        return this.api.getAuthorizationRequirements();
+    }
+
+    async testAuth() {
+        let validAuth = false;
+        try {
+            if (await this.testAuthRequest(this.api)) validAuth = true;
+        } catch (e) {
+            this.logger.warn('testAuth failed', {
+                eventName: `${this.logger.name}.test_auth_failed`,
+                error: e,
+            });
+        }
+        return validAuth;
+    }
+
+    async onTokenUpdate() {
+        const credentialDetails = await this.getCredentialDetails(
+            this.api,
+            this.userId
+        );
+        const apiParams = this.apiParamsFromCredential(this.api);
+
+        if (!apiParams.refresh_token && this.api.isRefreshable) {
+            this.logger.warn('No refresh_token in apiParams', {
+                eventName: `${this.logger.name}.refresh_token_missing`,
+            });
+        }
+
+        Object.assign(credentialDetails.details, apiParams);
+        credentialDetails.details.authIsValid = true;
+
+        const persisted = await this.credentialRepository.upsertCredential(
+            credentialDetails
+        );
+        this.credential = persisted;
+
+        if (this.credential?.id) {
+            try {
+                await this.notify(this.DLGT_CREDENTIAL_VALIDATED, {
+                    credentialId: this.credential.id,
+                    moduleName: this.name,
+                });
+            } catch (err) {
+                this.logger.error('Failed to propagate CREDENTIAL_VALIDATED', {
+                    eventName: `${this.logger.name}.credential_validated_propagation_failed`,
+                    error: err,
+                });
+            }
+        }
+    }
+
+    async receiveNotification(notifier, delegateString, object = null) {
+        if (delegateString === this.api.DLGT_TOKEN_UPDATE) {
+            await this.onTokenUpdate();
+        } else if (delegateString === this.api.DLGT_TOKEN_DEAUTHORIZED) {
+            await this.deauthorize();
+        } else if (delegateString === this.api.DLGT_INVALID_AUTH) {
+            await this.markCredentialsInvalid(object);
+        } else if (delegateString === this.api.DLGT_CREDENTIAL_RELOAD) {
+            return this.reloadCredential();
+        }
+    }
+
+    /**
+     * Re-reads the credential row from the database. The requester can then
+     * adopt a concurrent invocation's refresh and does not race it.
+     * @returns {Promise<Object|null>} The persisted token fields, or null
+     *   when no credential row is available. The requester treats null as
+     *   "nothing to adopt" and continues with its own refresh.
+     */
+    async reloadCredential() {
+        if (!this.credential?.id) return null;
+        const freshFromDatabase =
+            await this.credentialRepository.findCredentialById(
+                this.credential.id
+            );
+        if (!freshFromDatabase) return null;
+        this.credential = freshFromDatabase;
+        return this.apiParamsFromCredential(freshFromDatabase);
+    }
+
+    async markCredentialsInvalid(diagnosticInfo = null) {
+        if (!this.credential) return;
+
+        if (!this.credential.id) return;
+
+        if (diagnosticInfo) {
+            this.logger.warn('Credentials rejected', {
+                eventName: `${this.logger.name}.credentials_rejected`,
+                statusCode: diagnosticInfo.statusCode,
+                error: diagnosticInfo,
+            });
+        }
+
+        await this.credentialRepository.updateAuthenticationStatus(
+            this.credential.id,
+            false
+        );
+
+        // Keep the in-memory snapshot consistent so that callers can read the
+        // updated state without another fetch.
+        this.credential.authIsValid = false;
+
+        // Propagate upward so a parent delegate (e.g. IntegrationBase) can
+        // react — for instance by flipping Integration.status to DISABLED.
+        // Delegate.notify is a silent no-op when this.delegate is null, so
+        // Module instances constructed outside of an Integration context
+        // (e.g. during ProcessAuthorizationCallback) remain unaffected.
+        //
+        // Best-effort: this method is invoked from the OAuth2Requester 401
+        // refresh catch block, which depends on us NOT throwing. A DB hiccup
+        // in the downstream status flip must not alter refreshAuth's
+        // documented `return false` contract. The credential has already
+        // been persisted as invalid; integrations left un-flipped can be
+        // recovered by the next retry or by operator intervention.
+        try {
+            await this.notify(this.DLGT_CREDENTIAL_INVALIDATED, {
+                credentialId: this.credential.id,
+                moduleName: this.name,
+                ...(diagnosticInfo && {
+                    reason: diagnosticInfo.message,
+                    statusCode: diagnosticInfo.statusCode,
+                }),
+            });
+        } catch (err) {
+            this.logger.error('Failed to propagate CREDENTIAL_INVALIDATED', {
+                eventName: `${this.logger.name}.credential_invalidated_propagation_failed`,
+                error: err,
+            });
+        }
+    }
+
+    async deauthorize() {
+        //todo: Check if this is correct, we're instantiating a new api without params (credentials, tokens, etc...)
+        this.api = new this.apiClass();
+        this.api.logger = this.logger;
+
+        // Remove persisted credential (if any)
+        if (this.entity?.credential) {
+            const credentialId =
+                this.entity.credential.id || this.entity.credential;
+
+            // Delete credential via repository
+            await this.credentialRepository.deleteCredentialById(credentialId);
+            this.credential = undefined;
+
+            // Unset credential reference on the Entity document
+            const entityId = this.entity.id;
+            if (entityId) {
+                await this.moduleRepository.unsetCredential(entityId);
+            }
+
+            // Keep in-memory snapshot consistent
+            this.entity.credential = undefined;
+        }
+    }
+
+    // todo: check if all these props are still up to date
+    validateDefinition(definition) {
+        if (!definition) {
+            throw new Error('Module definition is required');
+        }
+        if (!definition.moduleName) {
+            throw new Error('Module definition requires moduleName');
+        }
+        if (!definition.API) {
+            throw new Error('Module definition requires API class');
+        }
+        if (!definition.requiredAuthMethods) {
+            throw new Error('Module definition requires requiredAuthMethods');
+        } else {
+            if (
+                definition.API.requesterType ===
+                    ModuleConstants.authType.oauth2 &&
+                !definition.requiredAuthMethods.getToken
+            ) {
+                throw new Error(
+                    'Module definition requires requiredAuthMethods.getToken'
+                );
+            }
+            if (!definition.requiredAuthMethods.getEntityDetails) {
+                throw new Error(
+                    'Module definition requires requiredAuthMethods.getEntityDetails'
+                );
+            }
+            if (!definition.requiredAuthMethods.getCredentialDetails) {
+                throw new Error(
+                    'Module definition requires requiredAuthMethods.getCredentialDetails'
+                );
+            }
+            if (!definition.requiredAuthMethods.apiPropertiesToPersist) {
+                throw new Error(
+                    'Module definition requires requiredAuthMethods.apiPropertiesToPersist'
+                );
+            } else if (definition.Credential) {
+                for (const prop of definition.requiredAuthMethods
+                    .apiPropertiesToPersist?.credential) {
+                    if (
+                        !definition.Credential.schema.paths.hasOwnProperty(prop)
+                    ) {
+                        throw new Error(
+                            `Module definition requires Credential schema to have property ${prop}`
+                        );
+                    }
+                }
+            }
+            if (!definition.requiredAuthMethods.testAuthRequest) {
+                throw new Error(
+                    'Module definition requires requiredAuthMethods.testAuth'
+                );
+            }
+        }
+    }
+}
+
+module.exports = { Module };