@friggframework/core 2.0.0--canary.608.4bec88a.0 → 2.0.0--canary.608.e6b65ff.0

package/handlers/workers/user-action-worker.js

@@ -1,6 +1,5 @@
 const { Worker } = require('../../core/Worker');
-// Direct path (not the package index) to avoid a circular require: index.js
-// re-exports this module.
+// Direct path (not the package index) avoids a circular require.
 const { createHandler } = require('../../core/create-handler');
 const {
     GetIntegrationInstance,
@@ -17,21 +16,11 @@ const {
 } = require('../../integrations/utils/map-integration-dto');
 
 /**
- * App-level worker for events dispatched with `dispatch: 'queue'`.
- *
- * A single Lambda serves every integration: messages arrive on the FIFO queue
- * serialized per `MessageGroupId = integrationId`, so concurrent mutations for
- * one integration run one-at-a-time. The worker re-hydrates the integration by
- * id + owning user and runs `instance.send(event, data)` — byte-identical to
- * the in-process (sync) path it replaces.
- *
- * Failure handling:
- *  - missing ids / un-hydratable / id mismatch → HaltError (discard, no retry)
- *  - handler throw → record ERROR status + a warning message, then rethrow so
- *    SQS retries and ultimately routes to the FIFO DLQ.
- *
- * DISABLED/ERROR integrations are NOT discarded — these are user-initiated
- * mutations (including ERROR recovery), unlike webhook/cron traffic.
+ * App-level worker for `dispatch: 'queue'` events. One Lambda serves every
+ * integration; the FIFO queue serializes per integrationId. Re-hydrates by id +
+ * owning user, then runs `instance.send(event, data)` (identical to the sync path).
+ * Terminal failures discard; everything else retries → FIFO DLQ. DISABLED/ERROR
+ * integrations are still processed (these are user-initiated mutations).
  */
 class UserActionWorker extends Worker {
     constructor({ getIntegrationInstance } = {}) {
@@ -66,8 +55,6 @@ class UserActionWorker extends Worker {
     }
 
     async _run(params) {
-        // Routing metadata is at the envelope top level; `data` is the exact
-        // handler payload (byte-identical to the sync path).
         const { event, data = {}, integrationId, userId, requestId } = params;
         const logCtx = { event, integrationId, userId, requestId };
 
@@ -89,11 +76,8 @@ class UserActionWorker extends Worker {
                 userId
             );
         } catch (error) {
-            // Discard ONLY terminal failures (gone / not owned / unknown class)
-            // — no retry can ever succeed. Transient failures (DB blip, Prisma
-            // timeout, KMS throttle during credential decrypt) are NOT marked
-            // terminal, so they retry and ultimately reach the FIFO DLQ instead
-            // of being silently dropped.
+            // Only terminal failures discard; transient ones (DB/Prisma/KMS
+            // blips) retry → FIFO DLQ rather than being silently dropped.
             if (error.isTerminal) {
                 error.isHaltError = true;
                 console.warn(
@@ -151,10 +135,8 @@ class UserActionWorker extends Worker {
     }
 }
 
-// Wrap in createHandler so the Lambda gets the same runtime setup as every
-// other DB-touching worker: secretsToEnv() (SECRET_ARN injection), connectPrisma()
-// (+ Mongo schema init), and callbackWaitsForEmptyEventLoop=false. The method's
-// return value ({ batchItemFailures }) passes through for ReportBatchItemFailures.
+// createHandler gives the Lambda the standard worker setup (secretsToEnv,
+// connectPrisma, callbackWaitsForEmptyEventLoop) and passes the result through.
 const userActionQueueWorker = createHandler({
     eventName: 'UserActionQueueWorker',
     isUserFacingResponse: false,

package/integrations/integration-base.js

@@ -31,9 +31,7 @@ const constantsToBeMigrated = {
         LIFE_CYCLE_EVENT: 'LIFE_CYCLE_EVENT',
         USER_ACTION: 'USER_ACTION',
     },
-    // Per-event dispatch mode. 'sync' (default) runs the handler in-process and
-    // returns its result; 'queue' routes the event through the framework-owned
-    // FIFO queue, serialized by integrationId, returning a 202 ack.
+    // 'sync' runs in-process (default); 'queue' routes through the FIFO queue.
     dispatch: {
         SYNC: 'sync',
         QUEUE: 'queue',
@@ -529,11 +527,8 @@ class IntegrationBase {
             ...this.events,
         };
 
-        // Apply Definition.eventDispatch onto the resolved handler entries. This
-        // lets a default lifecycle event (e.g. ON_UPDATE) be marked 'queue'
-        // without re-declaring its handler. An inline `dispatch` on the event
-        // entry always wins; unknown event names are ignored (a typo stays sync
-        // rather than crashing initialize()).
+        // Definition.eventDispatch marks default events; inline dispatch wins,
+        // unknown names are ignored.
         const eventDispatch = this.constructor.Definition?.eventDispatch || {};
         for (const [eventName, mode] of Object.entries(eventDispatch)) {
             if (this.on[eventName] && this.on[eventName].dispatch === undefined) {

package/integrations/use-cases/create-integration.js

@@ -72,9 +72,6 @@ class CreateIntegration {
             modules,
         });
 
-        // ON_CREATE runs in-process by default. Routed through the dispatch
-        // helper so an integration can opt into dispatch:'queue' if desired;
-        // when queued, an ack is returned instead of the DTO.
         await integrationInstance.initialize();
         const outcome = await dispatchIntegrationEvent({
             instance: integrationInstance,

package/integrations/use-cases/dispatch-integration-event.js

@@ -3,16 +3,10 @@ const { QueuerUtil } = require('../../queues');
 
 const SCHEMA_VERSION = 1;
 
-// Default lifecycle events that MUTATE and are routed through this helper, so
-// they may be queued. Read-shaped defaults (GET_*/REFRESH_*/WEBHOOK_RECEIVED)
-// must never be queued — a queued read would return a 202 ack instead of the
-// data the caller expects. ON_DELETE is intentionally excluded: deletion is
-// dispatched directly (and the record is gone immediately after), so a queued
-// worker re-hydrating by id would discard it as terminal.
+// ON_DELETE is excluded: it dispatches directly and the record is gone before a
+// queued worker could re-hydrate it. Custom (non-default) events are mutating.
 const MUTATING_DEFAULT_EVENTS = new Set(['ON_CREATE', 'ON_UPDATE']);
 
-// Custom user actions (events not present in defaultEvents) are mutating by
-// intent; only default events are filtered against the allowlist above.
 function isMutatingEvent(instance, event) {
     if (!instance.defaultEvents || !instance.defaultEvents[event]) {
         return true;
@@ -20,22 +14,9 @@ function isMutatingEvent(instance, event) {
     return MUTATING_DEFAULT_EVENTS.has(event);
 }
 
-/**
- * Central producer decision for dispatching an integration event.
- *
- * If the event opts into `dispatch: 'queue'`, is a mutating event, and the
- * framework queue is configured, the event is enqueued on the app-level FIFO
- * queue (serialized per integrationId) and a `{ queued }` ack is returned.
- * Otherwise the handler runs in-process and its result is returned. When the
- * queue URL is missing we degrade gracefully to in-process execution.
- *
- * @param {Object} args
- * @param {Object} args.instance - Initialized integration instance (has `on`, `id`, `send`).
- * @param {string} args.event - Event name to dispatch.
- * @param {Object} args.data - Payload passed to the handler / placed in the envelope.
- * @param {string} args.userId - Owning user id (used by the worker to re-hydrate).
- * @returns {Promise<{queued:true, messageId:string, requestId:string} | {result:any}>}
- */
+// Enqueues the event (returning a { queued } ack) when it opts into
+// dispatch:'queue' and the queue is configured; otherwise runs it in-process
+// and returns the result. Missing queue URL degrades to in-process.
 async function dispatchIntegrationEvent({ instance, event, data, userId }) {
     const mode = instance.on?.[event]?.dispatch;
     const queueUrl = process.env.USER_ACTION_QUEUE_URL;
@@ -51,9 +32,7 @@ async function dispatchIntegrationEvent({ instance, event, data, userId }) {
 
     if (eligible && queueUrl) {
         const requestId = uuid();
-        // Routing metadata lives at the envelope top level (alongside event),
-        // NOT inside `data`. `data` stays the exact handler payload the sync
-        // path passes, so the worker's send(event, data) is byte-identical.
+        // Routing metadata at the top level keeps `data` identical to the sync path.
         const envelope = {
             schemaVersion: SCHEMA_VERSION,
             event,

package/integrations/use-cases/get-integration-instance.js

@@ -34,7 +34,7 @@ class GetIntegrationInstance {
             const error = new Error(
                 `No integration found by the ID of ${integrationId}`
             );
-            // Terminal: the integration does not exist — no retry can succeed.
+            // isTerminal → the queue worker discards these (no retry can succeed).
             error.isTerminal = true;
             throw error;
         }
@@ -49,7 +49,6 @@ class GetIntegrationInstance {
             const error = new Error(
                 `No integration class found for type: ${integrationRecord.config.type}`
             );
-            // Terminal: the integration type is not registered — no retry helps.
             error.isTerminal = true;
             throw error;
         }
@@ -58,7 +57,6 @@ class GetIntegrationInstance {
             const error = new Error(
                 `Integration ${integrationId} does not belong to User ${userId}`
             );
-            // Terminal: ownership mismatch — no retry can succeed.
             error.isTerminal = true;
             throw error;
         }

package/integrations/use-cases/update-integration.js

@@ -82,10 +82,6 @@ class UpdateIntegration {
             modules,
         });
 
-        // 5. Complete async initialization and dispatch the update event.
-        // When ON_UPDATE is marked dispatch:'queue', the update is enqueued
-        // (serialized per integration) and an ack is returned; otherwise it
-        // runs in-process and the updated DTO is returned (unchanged behavior).
         await integrationInstance.initialize();
         const outcome = await dispatchIntegrationEvent({
             instance: integrationInstance,

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.608.4bec88a.0",
+    "version": "2.0.0--canary.608.e6b65ff.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -38,9 +38,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.608.4bec88a.0",
-        "@friggframework/prettier-config": "2.0.0--canary.608.4bec88a.0",
-        "@friggframework/test": "2.0.0--canary.608.4bec88a.0",
+        "@friggframework/eslint-config": "2.0.0--canary.608.e6b65ff.0",
+        "@friggframework/prettier-config": "2.0.0--canary.608.e6b65ff.0",
+        "@friggframework/test": "2.0.0--canary.608.e6b65ff.0",
         "@prisma/client": "^6.19.3",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -80,5 +80,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "4bec88a53c1c12df8f84aac9b2eeb6b23ba04c05"
+    "gitHead": "e6b65ff3bf4a3b3e7777a1f2a6cf1cecd24bedd7"
 }

package/queues/queuer-util.js

@@ -90,11 +90,8 @@ const inspectBatchResult = (result, queueUrl, buffer) => {
 };
 
 const QueuerUtil = {
-    // `messageGroupId`/`messageDeduplicationId` are only used for FIFO queues.
-    // Standard sends omit them, so the command is byte-identical to before.
-    // FIFO queues require a deduplication id whenever ContentBasedDeduplication
-    // is off — we default to a uuid so every send is treated as distinct (two
-    // distinct requests with identical bodies must both run, not be dropped).
+    // FIFO-only: default a unique dedup id so identical bodies aren't dropped.
+    // Standard sends pass no opts and stay unchanged.
     send: async (message, queueUrl, { messageGroupId, messageDeduplicationId } = {}) => {
         const command = new SendMessageCommand({
             MessageBody: JSON.stringify(message),