@friggframework/core 2.0.0-next.80 → 2.0.0-next.82

package/integrations/use-cases/update-process-metrics.js

@@ -1,37 +1,28 @@
-/** 
- TODO:
- This implementation contains a race condition in the `execute` method. When multiple concurrent processes call this method on the same process record, they'll each read the current state, modify it independently, and then save - potentially overwriting each other's changes.
-
-For example:
-```
-Thread 1: reads process with totalSynced=100
-Thread 2: reads process with totalSynced=100
-Thread 1: adds 50 → writes totalSynced=150
-Thread 2: adds 30 → writes totalSynced=130 (overwrites Thread 1's update!)
-```
-
-Consider implementing one of these patterns:
-1. Database transactions with row locking
-2. Optimistic concurrency control with version numbers
-3. Atomic update operations (e.g., `$inc` in MongoDB)
-4. A FIFO queue for process updates (as described in the PROCESS_MANAGEMENT_QUEUE_SPEC.md)
-
-The current approach will lead to lost updates and inconsistent metrics during concurrent processing.
-
- */
-
 /**
  * UpdateProcessMetrics Use Case
  *
- * Updates process metrics, calculates aggregates, and computes estimated completion time.
- * Optionally broadcasts progress via WebSocket service if provided.
+ * Updates process metrics atomically via
+ * `processRepository.applyProcessUpdate`. This is the race-safe
+ * replacement for the original read-modify-write implementation — the
+ * long-standing TODO about lost updates under concurrent writers is
+ * now resolved.
+ *
+ * Split into two phases:
  *
- * Design Philosophy:
- * - Metrics are cumulative (add to existing counts)
- * - Performance metrics calculated automatically (duration, records/sec)
- * - ETA computed based on current progress
- * - Error history limited to last 100 entries
- * - WebSocket broadcasting is optional (DI pattern)
+ *   1. Atomic phase — counters and bounded error history. Uses
+ *      $inc / $push+$slice (Mongo/DocumentDB) or jsonb_set with
+ *      arithmetic expressions (Postgres) in a single UPDATE ... RETURNING
+ *      so concurrent callers serialize at the DB layer.
+ *
+ *   2. Derived-fields phase — duration, recordsPerSecond,
+ *      estimatedCompletion. Computed from the post-atomic snapshot and
+ *      written via the legacy (non-atomic) `update()` method.
+ *      Intentionally best-effort: under concurrent writers they reflect
+ *      "whichever handler wrote last" — the same semantics they had
+ *      before and all they've ever guaranteed. Preserved for backward
+ *      compatibility with consumers (UI, WebSocket listeners).
+ *
+ * Optionally broadcasts progress via WebSocket service if provided.
  *
  * @example
  * const updateMetrics = new UpdateProcessMetrics({ processRepository, websocketService });
@@ -60,15 +51,14 @@ class UpdateProcessMetrics {
      * Execute the use case to update process metrics
      * @param {string} processId - Process ID to update
      * @param {Object} metricsUpdate - Metrics to add/update
-     * @param {number} [metricsUpdate.processed=0] - Number of records processed in this batch
-     * @param {number} [metricsUpdate.success=0] - Number of successful records
-     * @param {number} [metricsUpdate.errors=0] - Number of failed records
+     * @param {number} [metricsUpdate.processed=0] - Records processed in this batch
+     * @param {number} [metricsUpdate.success=0] - Successful records
+     * @param {number} [metricsUpdate.errors=0] - Failed records
      * @param {Array} [metricsUpdate.errorDetails=[]] - Error details array
      * @returns {Promise<Object>} Updated process record
      * @throws {Error} If process not found or update fails
      */
     async execute(processId, metricsUpdate) {
-        // Validate inputs
         if (!processId || typeof processId !== 'string') {
             throw new Error('processId must be a non-empty string');
         }
@@ -76,87 +66,103 @@ class UpdateProcessMetrics {
             throw new Error('metricsUpdate must be an object');
         }
 
-        // Retrieve current process
-        const process = await this.processRepository.findById(processId);
-        if (!process) {
-            throw new Error(`Process not found: ${processId}`);
-        }
-
-        // Get current context and results
-        const context = process.context || {};
-        const results = process.results || { aggregateData: {} };
-
-        // Initialize nested objects if not present
-        if (!results.aggregateData) {
-            results.aggregateData = {};
-        }
-
-        // Update context counters (cumulative)
-        context.processedRecords =
-            (context.processedRecords || 0) + (metricsUpdate.processed || 0);
+        // Phase 1: atomic increments + bounded error history.
+        const increment = {};
+        const processed = metricsUpdate.processed || 0;
+        const success = metricsUpdate.success || 0;
+        const errors = metricsUpdate.errors || 0;
+        if (processed) increment['context.processedRecords'] = processed;
+        if (success) increment['results.aggregateData.totalSynced'] = success;
+        if (errors) increment['results.aggregateData.totalFailed'] = errors;
 
-        // Update results aggregates (cumulative)
-        results.aggregateData.totalSynced =
-            (results.aggregateData.totalSynced || 0) +
-            (metricsUpdate.success || 0);
-        results.aggregateData.totalFailed =
-            (results.aggregateData.totalFailed || 0) +
-            (metricsUpdate.errors || 0);
-
-        // Append error details (limited to last 100)
+        const pushSlice = {};
         if (
-            metricsUpdate.errorDetails &&
+            Array.isArray(metricsUpdate.errorDetails) &&
             metricsUpdate.errorDetails.length > 0
         ) {
-            results.aggregateData.errors = [
-                ...(results.aggregateData.errors || []),
-                ...metricsUpdate.errorDetails,
-            ].slice(-100); // Keep only last 100 errors
+            pushSlice['results.aggregateData.errors'] = {
+                values: metricsUpdate.errorDetails,
+                keepLast: 100,
+            };
         }
 
-        // Calculate performance metrics
-        const startTime = new Date(context.startTime || process.createdAt);
-        const elapsed = Date.now() - startTime.getTime();
-        results.aggregateData.duration = elapsed;
-
-        if (elapsed > 0 && context.processedRecords > 0) {
-            results.aggregateData.recordsPerSecond =
-                context.processedRecords / (elapsed / 1000);
-        } else {
-            results.aggregateData.recordsPerSecond = 0;
-        }
+        const hasAtomicWork =
+            Object.keys(increment).length > 0 ||
+            Object.keys(pushSlice).length > 0;
 
-        // Calculate ETA if we know total
-        if (context.totalRecords > 0 && context.processedRecords > 0) {
-            const remaining = context.totalRecords - context.processedRecords;
-            if (results.aggregateData.recordsPerSecond > 0) {
-                const etaMs =
-                    (remaining / results.aggregateData.recordsPerSecond) * 1000;
-                const eta = new Date(Date.now() + etaMs);
-                context.estimatedCompletion = eta.toISOString();
-            }
-        }
-
-        // Prepare updates
-        const updates = {
-            context,
-            results,
-        };
-
-        // Persist updates
         let updatedProcess;
         try {
-            updatedProcess = await this.processRepository.update(
-                processId,
-                updates
-            );
+            if (hasAtomicWork) {
+                updatedProcess = await this.processRepository.applyProcessUpdate(
+                    processId,
+                    { increment, pushSlice }
+                );
+            } else {
+                // All-zero update (e.g., empty batch) — nothing to persist;
+                // just read current state for the derived-fields pass.
+                updatedProcess = await this.processRepository.findById(
+                    processId
+                );
+            }
         } catch (error) {
             throw new Error(
                 `Failed to update process metrics: ${error.message}`
             );
         }
 
-        // Broadcast progress via WebSocket (if service provided)
+        if (!updatedProcess) {
+            throw new Error(`Process not found: ${processId}`);
+        }
+
+        // Phase 2: derived metrics (non-atomic, best-effort). Preserved
+        // for backward compatibility — these were always stale under
+        // concurrent writers even before this refactor.
+        const context = updatedProcess.context || {};
+        const results = updatedProcess.results || { aggregateData: {} };
+        if (!results.aggregateData) results.aggregateData = {};
+
+        if (context.processedRecords > 0 || context.totalRecords > 0) {
+            const startTime = new Date(
+                context.startTime || updatedProcess.createdAt
+            );
+            const elapsed = Date.now() - startTime.getTime();
+            results.aggregateData.duration = elapsed;
+
+            if (elapsed > 0 && context.processedRecords > 0) {
+                results.aggregateData.recordsPerSecond =
+                    context.processedRecords / (elapsed / 1000);
+            } else {
+                results.aggregateData.recordsPerSecond = 0;
+            }
+
+            if (context.totalRecords > 0 && context.processedRecords > 0) {
+                const remaining =
+                    context.totalRecords - context.processedRecords;
+                if (results.aggregateData.recordsPerSecond > 0) {
+                    const etaMs =
+                        (remaining / results.aggregateData.recordsPerSecond) *
+                        1000;
+                    const eta = new Date(Date.now() + etaMs);
+                    context.estimatedCompletion = eta.toISOString();
+                }
+            }
+
+            try {
+                updatedProcess = await this.processRepository.update(
+                    processId,
+                    { context, results }
+                );
+            } catch (error) {
+                // Derived-field write failures are NON-FATAL — atomic
+                // counters from phase 1 already landed. Log and return the
+                // post-atomic snapshot.
+                console.error(
+                    '[UpdateProcessMetrics] derived-fields write failed (non-fatal):',
+                    error.message
+                );
+            }
+        }
+
         if (this.websocketService) {
             await this._broadcastProgress(updatedProcess);
         }
@@ -167,7 +173,6 @@ class UpdateProcessMetrics {
     /**
      * Broadcast progress update via WebSocket
      * @private
-     * @param {Object} process - Updated process record
      */
     async _broadcastProgress(process) {
         try {
@@ -192,7 +197,6 @@ class UpdateProcessMetrics {
                 },
             });
         } catch (error) {
-            // Log but don't fail the update if WebSocket broadcast fails
             console.error('Failed to broadcast process progress:', error);
         }
     }

package/integrations/use-cases/update-process-state.js

@@ -54,30 +54,69 @@ class UpdateProcessState {
             throw new Error('contextUpdates must be an object');
         }
 
-        // Retrieve current process
-        const process = await this.processRepository.findById(processId);
-        if (!process) {
-            throw new Error(`Process not found: ${processId}`);
-        }
+        // Route through the atomic path when the repo supports it AND we
+        // have context keys to set. The atomic path writes the state
+        // column + the context field-sets in one DB round trip without
+        // read-modify-write, so a concurrent counter bump from
+        // UpdateProcessMetrics can't clobber our flags (e.g. `fetchDone`)
+        // or vice versa.
+        //
+        // Each context update key becomes a `set` at path
+        // `context.<key>` — matching the prior semantics of a shallow
+        // top-level merge (sub-objects were and still are replaced
+        // whole, not deep-merged).
+        const hasContextKeys =
+            contextUpdates && Object.keys(contextUpdates).length > 0;
 
-        // Prepare updates
-        const updates = {
-            state: newState,
-        };
-
-        // Merge context updates if provided
-        if (contextUpdates && Object.keys(contextUpdates).length > 0) {
-            updates.context = {
-                ...process.context,
-                ...contextUpdates,
-            };
+        if (
+            hasContextKeys &&
+            typeof this.processRepository.applyProcessUpdate === 'function'
+        ) {
+            const set = {};
+            for (const [key, value] of Object.entries(contextUpdates)) {
+                set[`context.${key}`] = value;
+            }
+            try {
+                const updated = await this.processRepository.applyProcessUpdate(
+                    processId,
+                    { set, newState }
+                );
+                if (!updated) {
+                    throw new Error(`Process not found: ${processId}`);
+                }
+                return updated;
+            } catch (error) {
+                throw new Error(
+                    `Failed to update process state: ${error.message}`
+                );
+            }
         }
 
-        // Persist updates
+        // Legacy path (no contextUpdates or repo lacks applyProcessUpdate):
+        // preserve the original read-merge-write semantics for backward
+        // compatibility with any custom repos. Wrap the full read+write
+        // in try/catch so a findById error surfaces under the same
+        // "Failed to update process state" message as a write failure.
         try {
-            const updatedProcess = await this.processRepository.update(processId, updates);
-            return updatedProcess;
+            const process = await this.processRepository.findById(processId);
+            if (!process) {
+                throw new Error(`Process not found: ${processId}`);
+            }
+
+            const updates = { state: newState };
+            if (hasContextKeys) {
+                updates.context = {
+                    ...process.context,
+                    ...contextUpdates,
+                };
+            }
+
+            return await this.processRepository.update(processId, updates);
         } catch (error) {
+            // Re-throw "Process not found" as-is; wrap other errors.
+            if (error.message && error.message.startsWith('Process not found')) {
+                throw error;
+            }
             throw new Error(`Failed to update process state: ${error.message}`);
         }
     }

package/modules/module.js

@@ -20,8 +20,9 @@ class Module extends Delegate {
      * @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 }) {
+    constructor({ definition, userId = null, entity: entityObj = null, state = null }) {
         super({ definition, userId, entity: entityObj });
 
         this.validateDefinition(definition);
@@ -46,6 +47,7 @@ class Module extends Delegate {
         const apiParams = {
             ...this.definition.env,
             delegate: this,
+            ...(state ? { state } : {}),
             ...(this.credential?.data
                 ? this.apiParamsFromCredential(this.credential.data)
                 : {}), // Handle case when credential is undefined

package/modules/requester/requester.js

@@ -3,6 +3,8 @@ const { Delegate } = require('../../core');
 const { FetchError } = require('../../errors');
 const { get } = require('../../assertions');
 
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+
 class Requester extends Delegate {
     constructor(params) {
         super(params);
@@ -13,6 +15,30 @@ class Requester extends Delegate {
         this.delegateTypes.push(this.DLGT_INVALID_AUTH);
         this.agent = get(params, 'agent', null);
 
+        // Per-attempt HTTP timeout. Without this the framework called fetch()
+        // with no AbortController and no timeout — a silently-hung TCP
+        // connection (server accepts but never responds) blocked the calling
+        // promise forever, cascading into stalled batches, stalled syncs,
+        // and worker-lambda timeouts.
+        //
+        // Configuration precedence:
+        //   1. Instance param:   new Requester({ requestTimeoutMs: 30_000 })
+        //   2. Class static:     static requestTimeoutMs = 30_000
+        //   3. Default:          DEFAULT_REQUEST_TIMEOUT_MS (60s)
+        //
+        // Pass 0 (or null) to disable the timeout entirely — reserved for
+        // test doubles and documented long-running endpoints.
+        // Intentionally NOT using `get(params, ...)` here — the Frigg
+        // `get` helper throws RequiredPropertyError if the key is missing
+        // and no default is provided, which would collide with the fall-
+        // through to the class-level static override.
+        const instanceTimeout = params?.requestTimeoutMs;
+        this.requestTimeoutMs =
+            instanceTimeout !== undefined && instanceTimeout !== null
+                ? instanceTimeout
+                : this.constructor.requestTimeoutMs ??
+                  DEFAULT_REQUEST_TIMEOUT_MS;
+
         // Allow passing in the fetch function
         // Instance methods can use this.fetch without differentiating
         this.fetch = get(params, 'fetch', fetch);
@@ -48,52 +74,134 @@ class Requester extends Delegate {
 
         if (this.agent) options.agent = this.agent;
 
-        let response;
+        // Per-attempt timeout — fresh AbortController per call so the retry
+        // recursion (with its own backoff sleeps) always gets a clean
+        // signal. Timer is cleared in the finally block regardless of
+        // outcome.
+        const timeoutMs = this.requestTimeoutMs;
+        const controller = timeoutMs > 0 ? new AbortController() : null;
+        const timeoutHandle = controller
+            ? setTimeout(() => controller.abort(), timeoutMs)
+            : null;
+        const fetchOptions = controller
+            ? { ...options, signal: controller.signal }
+            : options;
+
+        // Timer must stay active through body consumption. node-fetch v2
+        // resolves the fetch() promise when headers arrive, not when the
+        // body is fully read — so a server that sends headers and then
+        // stalls the body would still hang parsedBody() or
+        // FetchError.create()'s response.text() call. We clear the timer
+        // only after the body is fully consumed (success path) or
+        // deliberately before each recursive retry so the new attempt
+        // starts with its own fresh timer.
+        let timerCleared = false;
+        const clearRequestTimer = () => {
+            if (!timerCleared && timeoutHandle) {
+                clearTimeout(timeoutHandle);
+                timerCleared = true;
+            }
+        };
+
         try {
-            response = await this.fetch(encodedUrl, options);
-        } catch (e) {
-            if (e.code === 'ECONNRESET' && i < this.backOff.length) {
+            let response;
+            try {
+                response = await this.fetch(encodedUrl, fetchOptions);
+            } catch (e) {
+                // AbortController fires AbortError (name) / ETIMEDOUT-shaped
+                // errors (type on node-fetch) when we hit the timeout. No
+                // retry on timeout: a slow endpoint is a downstream problem,
+                // and each retry would wait another `timeoutMs` before giving
+                // up — amplifying the hang into a per-record multi-minute
+                // stall at batch scale.
+                const isTimeout =
+                    e?.name === 'AbortError' || e?.type === 'aborted';
+                if (e?.code === 'ECONNRESET' && i < this.backOff.length) {
+                    clearRequestTimer();
+                    const delay = this.backOff[i] * 1000;
+                    await new Promise((resolve) =>
+                        setTimeout(resolve, delay)
+                    );
+                    return this._request(url, options, i + 1);
+                }
+                const fetchError = await FetchError.create({
+                    resource: encodedUrl,
+                    init: options,
+                    responseBody: isTimeout
+                        ? `Request timed out after ${timeoutMs}ms`
+                        : e,
+                });
+                if (isTimeout) {
+                    // Flag + machine-readable fields so callers can
+                    // distinguish a timeout from a generic network error
+                    // without parsing the message (which FetchError
+                    // sanitizes outside of STAGE=dev).
+                    fetchError.isTimeout = true;
+                    fetchError.timeoutMs = timeoutMs;
+                }
+                throw fetchError;
+            }
+
+            const { status } = response;
+
+            // If the status is retriable and there are back off requests left, retry the request
+            if ((status === 429 || status >= 500) && i < this.backOff.length) {
+                clearRequestTimer();
                 const delay = this.backOff[i] * 1000;
                 await new Promise((resolve) => setTimeout(resolve, delay));
                 return this._request(url, options, i + 1);
-            }
-            throw await FetchError.create({
-                resource: encodedUrl,
-                init: options,
-                responseBody: e,
-            });
-        }
-        const { status } = response;
-
-        // If the status is retriable and there are back off requests left, retry the request
-        if ((status === 429 || status >= 500) && i < this.backOff.length) {
-            const delay = this.backOff[i] * 1000;
-            await new Promise((resolve) => setTimeout(resolve, delay));
-            return this._request(url, options, i + 1);
-        } else if (status === 401) {
-            if (!this.isRefreshable || this.refreshCount > 0) {
-                await this.notify(this.DLGT_INVALID_AUTH);
-            } else {
-                this.refreshCount++;
-                const refreshSucceeded = await this.refreshAuth();
-                if (refreshSucceeded) {
-                    return this._request(url, options, i + 1);
+            } else if (status === 401) {
+                if (!this.isRefreshable || this.refreshCount > 0) {
+                    await this.notify(this.DLGT_INVALID_AUTH);
+                } else {
+                    this.refreshCount++;
+                    const refreshSucceeded = await this.refreshAuth();
+                    if (refreshSucceeded) {
+                        clearRequestTimer();
+                        return this._request(url, options, i + 1);
+                    }
                 }
             }
-        }
 
-        // If the error wasn't retried, throw.
-        if (status >= 400) {
-            throw await FetchError.create({
-                resource: encodedUrl,
-                init: options,
-                response,
-            });
+            // If the error wasn't retried, throw. FetchError.create reads
+            // the response body (response.text()) — timer must still be
+            // alive to catch a stalled body stream.
+            if (status >= 400) {
+                const fetchError = await FetchError.create({
+                    resource: encodedUrl,
+                    init: options,
+                    response,
+                });
+                throw this._maybeFlagTimeoutDuringBodyRead(
+                    fetchError,
+                    timeoutMs
+                );
+            }
+
+            // parsedBody consumes the response body stream. If the server
+            // stalls mid-stream the timer (still armed) aborts it.
+            return options.returnFullRes
+                ? response
+                : await this.parsedBody(response);
+        } catch (e) {
+            // If the abort fired during body consumption, node-fetch emits
+            // the error as an AbortError on the body stream. Surface the
+            // same isTimeout flag callers use for header-phase timeouts.
+            throw this._maybeFlagTimeoutDuringBodyRead(e, timeoutMs);
+        } finally {
+            clearRequestTimer();
         }
+    }
 
-        return options.returnFullRes
-            ? response
-            : await this.parsedBody(response);
+    _maybeFlagTimeoutDuringBodyRead(err, timeoutMs) {
+        if (!err || typeof err !== 'object') return err;
+        if (err.isTimeout) return err;
+        const isAbort =
+            err.name === 'AbortError' || err.type === 'aborted';
+        if (!isAbort) return err;
+        err.isTimeout = true;
+        err.timeoutMs = timeoutMs;
+        return err;
     }
 
     async _get(options) {

package/modules/use-cases/get-module-instance-from-type.js

@@ -13,8 +13,10 @@ class GetModuleInstanceFromType {
      * Retrieve a Module instance for a given user and entity/module type.
      * @param {string} userId
      * @param {string} type – human-readable module/entity type (e.g. "Hubspot")
+     * @param {Object} [options]
+     * @param {string} [options.state] – optional OAuth state value to be forwarded to the API client (round-trips through the OAuth provider).
      */
-    async execute(userId, type) {
+    async execute(userId, type, options = {}) {
         const moduleDefinition = this.moduleDefinitions.find(
             (def) => def.getName() === type
         );
@@ -24,6 +26,7 @@ class GetModuleInstanceFromType {
         return new Module({
             userId,
             definition: moduleDefinition,
+            state: options.state,
         });
     }
 }