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

package/core/Worker.js

@@ -20,15 +20,45 @@ class Worker {
         const records = get(params, 'Records');
         const batchItemFailures = [];
 
+        console.log(
+            `[Worker] run: processing ${records.length} record(s)`
+        );
+
         for (const record of records) {
+            // Log record entry with SQS-provided attributes useful for tracing
+            // delivery history (ApproximateReceiveCount for retries, etc.).
+            let parsedEvent;
+            try {
+                parsedEvent = JSON.parse(record.body)?.event;
+            } catch {
+                parsedEvent = undefined;
+            }
+            console.log(`[Worker] record begin`, {
+                messageId: record.messageId,
+                event: parsedEvent,
+                receiveCount: record.attributes?.ApproximateReceiveCount,
+            });
+
             try {
                 const runParams = JSON.parse(record.body);
                 this._validateParams(runParams);
                 await this._run(runParams, context);
+                console.log(`[Worker] record success`, {
+                    messageId: record.messageId,
+                    event: runParams?.event,
+                });
             } catch (error) {
                 if (error.isHaltError) {
                     // HaltError means "discard this message, don't retry".
                     // Treat as success so SQS deletes it from the queue.
+                    // Logged explicitly — silent discards made prod debugging
+                    // extremely hard; keep this visible.
+                    console.warn(`[Worker] record halted (discarded, no retry)`, {
+                        messageId: record.messageId,
+                        event: parsedEvent,
+                        reason: error.message,
+                        statusCode: error.statusCode,
+                    });
                     continue;
                 }
                 console.error(`[Worker] Failed to process record ${record.messageId}:`, error);
@@ -36,6 +66,12 @@ class Worker {
             }
         }
 
+        if (batchItemFailures.length > 0) {
+            console.warn(
+                `[Worker] run: returning ${batchItemFailures.length} batchItemFailure(s) of ${records.length}`
+            );
+        }
+
         return { batchItemFailures };
     }
 

package/core/create-handler.js

@@ -5,6 +5,45 @@
 const { initDebugLog, flushDebugLog } = require('../logs');
 const { secretsToEnv } = require('./secrets-to-env');
 
+// Best-effort extraction of correlation identifiers from a Lambda event.
+// For SQS: pulls messageIds + parsed event/processId/integrationId from each
+// record body. For HTTP: pulls method+path. Never throws.
+const summarizeLambdaEvent = (event) => {
+    if (!event) return {};
+    if (Array.isArray(event.Records)) {
+        return {
+            source: 'sqs',
+            records: event.Records.map((r) => {
+                let parsed = {};
+                try {
+                    const body = JSON.parse(r.body);
+                    parsed = {
+                        event: body?.event,
+                        processId: body?.data?.processId,
+                        integrationId: body?.data?.integrationId,
+                    };
+                } catch {
+                    // ignore unparseable bodies
+                }
+                return {
+                    messageId: r.messageId,
+                    receiveCount: r.attributes?.ApproximateReceiveCount,
+                    ...parsed,
+                };
+            }),
+        };
+    }
+    if (event.httpMethod || event.requestContext?.http) {
+        return {
+            source: 'http',
+            method:
+                event.httpMethod || event.requestContext?.http?.method,
+            path: event.path || event.rawPath,
+        };
+    }
+    return { source: 'other' };
+};
+
 const createHandler = (optionByName = {}) => {
     const {
         eventName = 'Event',
@@ -17,7 +56,18 @@ const createHandler = (optionByName = {}) => {
     }
 
     return async (event, context) => {
+        const eventSummary = summarizeLambdaEvent(event);
+
         try {
+            console.info(
+                `[createHandler] ${eventName}: handler entry`,
+                {
+                    eventName,
+                    awsRequestId: context?.awsRequestId,
+                    ...eventSummary,
+                }
+            );
+
             initDebugLog(eventName, event);
 
             const requestMethod = event.httpMethod;
@@ -62,7 +112,21 @@ const createHandler = (optionByName = {}) => {
             // Handle server-to-server responses.
 
             // Halt errors are logged but suceed and won't be retried.
+            // Log explicitly — silent suppression here previously made stuck
+            // messages invisible to observability tooling. Include
+            // eventSummary so operators can correlate across concurrent
+            // invocations (processId / messageIds / HTTP path).
             if (error.isHaltError === true) {
+                console.warn(
+                    `[createHandler] ${eventName}: halt error suppressed (no retry)`,
+                    {
+                        eventName,
+                        errorName: error.name,
+                        errorMessage: error.message,
+                        statusCode: error.statusCode,
+                        ...eventSummary,
+                    }
+                );
                 return;
             }
 

package/handlers/backend-utils.js

@@ -141,8 +141,17 @@ const loadIntegrationForProcess = async (processId, integrationClass) => {
 };
 
 const createQueueWorker = (integrationClass) => {
+    const integrationName = integrationClass.Definition.name;
+
     class QueueWorker extends Worker {
         async _run(params, context) {
+            const logCtx = {
+                integration: integrationName,
+                event: params.event,
+                processId: params.data?.processId,
+                integrationId: params.data?.integrationId,
+            };
+
             try {
                 let integrationInstance;
 
@@ -150,29 +159,46 @@ const createQueueWorker = (integrationClass) => {
                 // then integrationId (for ANY event type that needs hydration),
                 // fallback to unhydrated instance
                 if (params.data?.processId) {
+                    console.log(
+                        `[QueueWorker] hydrating by processId`,
+                        logCtx
+                    );
                     integrationInstance = await loadIntegrationForProcess(
                         params.data.processId,
                         integrationClass
                     );
+                    console.log(`[QueueWorker] hydrated`, {
+                        ...logCtx,
+                        integrationStatus: integrationInstance?.status,
+                        hydratedIntegrationId: integrationInstance?.id,
+                    });
                     if (['DISABLED', 'ERROR'].includes(integrationInstance?.status)) {
                         console.warn(
-                            `[${integrationClass.Definition.name}] Integration for process ${params.data.processId} is ${integrationInstance.status}. Discarding ${params.event} message.`
+                            `[${integrationName}] Integration for process ${params.data.processId} is ${integrationInstance.status}. Discarding ${params.event} message.`
                         );
                         return;
                     }
                 } else if (params.data?.integrationId) {
+                    console.log(
+                        `[QueueWorker] hydrating by integrationId`,
+                        logCtx
+                    );
                     integrationInstance = await loadIntegrationForWebhook(
                         params.data.integrationId
                     );
                     if (!integrationInstance) {
                         console.warn(
-                            `[${integrationClass.Definition.name}] Integration ${params.data.integrationId} no longer exists. Discarding ${params.event} message.`
+                            `[${integrationName}] Integration ${params.data.integrationId} no longer exists. Discarding ${params.event} message.`
                         );
                         return;
                     }
+                    console.log(`[QueueWorker] hydrated`, {
+                        ...logCtx,
+                        integrationStatus: integrationInstance?.status,
+                    });
                     if (['DISABLED', 'ERROR'].includes(integrationInstance.status)) {
                         console.warn(
-                            `[${integrationClass.Definition.name}] Integration ${params.data.integrationId} is ${integrationInstance.status}. Discarding ${params.event} message.`
+                            `[${integrationName}] Integration ${params.data.integrationId} is ${integrationInstance.status}. Discarding ${params.event} message.`
                         );
                         return;
                     }
@@ -181,6 +207,10 @@ const createQueueWorker = (integrationClass) => {
                     // There will be cases where we need to use helpers that the api modules can export.
                     // Like for HubSpot, the answer is to do a reverse lookup for the integration by the entity external ID (HubSpot Portal ID),
                     // and then you'll have the integration ID available to hydrate from.
+                    console.log(
+                        `[QueueWorker] no processId/integrationId — running dry instance`,
+                        logCtx
+                    );
                     integrationInstance = new integrationClass();
                 }
 
@@ -188,14 +218,17 @@ const createQueueWorker = (integrationClass) => {
                     integrationInstance
                 );
 
-                return await dispatcher.dispatchJob({
+                console.log(`[QueueWorker] dispatching ${params.event}`, logCtx);
+                const result = await dispatcher.dispatchJob({
                     event: params.event,
                     data: params.data,
                     context: context,
                 });
+                console.log(`[QueueWorker] ${params.event} dispatched ok`, logCtx);
+                return result;
             } catch (error) {
                 console.error(
-                    `Error in ${params.event} for ${integrationClass.Definition.name}:`,
+                    `Error in ${params.event} for ${integrationName}:`,
                     error
                 );
 
@@ -207,7 +240,12 @@ const createQueueWorker = (integrationClass) => {
                 if (status && status >= 400 && status < 500 && status !== 408 && status !== 429) {
                     error.isHaltError = true;
                     console.warn(
-                        `[${integrationClass.Definition.name}] Permanent ${status} error for ${params.event} — message will be discarded (no retry)`
+                        `[${integrationName}] Permanent ${status} error for ${params.event} — message will be discarded (no retry)`,
+                        {
+                            ...logCtx,
+                            errorName: error.name,
+                            errorMessage: error.message,
+                        }
                     );
                 }
 

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0-next.79",
+    "version": "2.0.0-next.80",
     "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-next.79",
-        "@friggframework/prettier-config": "2.0.0-next.79",
-        "@friggframework/test": "2.0.0-next.79",
+        "@friggframework/eslint-config": "2.0.0-next.80",
+        "@friggframework/prettier-config": "2.0.0-next.80",
+        "@friggframework/test": "2.0.0-next.80",
         "@prisma/client": "^6.17.0",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -80,5 +80,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "b2a04b537ad3efb6206d14862f5dff5053829c73"
+    "gitHead": "7a66dfcb02143941411ff26aaee866afc1473df8"
 }

package/queues/queuer-util.js

@@ -18,13 +18,88 @@ const awsConfigOptions = () => {
 
 const sqs = new SQSClient(awsConfigOptions());
 
+// Best-effort extraction of the logical event/processId/integrationId from a
+// JSON message body. Used only for log correlation — never throws.
+const summarizeMessageBody = (bodyStr) => {
+    try {
+        const parsed = JSON.parse(bodyStr);
+        return {
+            event: parsed?.event,
+            processId: parsed?.data?.processId,
+            integrationId: parsed?.data?.integrationId,
+        };
+    } catch {
+        return {};
+    }
+};
+
+// Inspect SendMessageBatchResult for partial failures and log them.
+// AWS SendMessageBatch can succeed at the HTTP level while individual entries
+// are rejected (KMS errors, per-entry throttling, service errors). Callers that
+// don't inspect result.Failed silently lose those messages. This logs the
+// details — including the logical event/processId of the failed entry — so
+// the loss is visible and correlatable in CloudWatch.
+const inspectBatchResult = (result, queueUrl, buffer) => {
+    const bufferSize = buffer.length;
+    const failedCount = result?.Failed?.length ?? 0;
+    const successCount = result?.Successful?.length ?? 0;
+
+    // Index buffer by Id so we can attach event/processId to failures.
+    const bufferById = new Map(buffer.map((b) => [b.Id, b]));
+
+    if (failedCount > 0) {
+        console.error(
+            `[QueuerUtil] SendMessageBatch partial failure: ${failedCount}/${bufferSize} failed`,
+            {
+                queueUrl,
+                bufferSize,
+                successCount,
+                failedCount,
+                failed: result.Failed.map((f) => {
+                    const bufEntry = bufferById.get(f.Id);
+                    const summary = bufEntry
+                        ? summarizeMessageBody(bufEntry.MessageBody)
+                        : {};
+                    return {
+                        Id: f.Id,
+                        Code: f.Code,
+                        SenderFault: f.SenderFault,
+                        Message: f.Message,
+                        ...summary,
+                    };
+                }),
+            }
+        );
+    } else if (successCount > 0) {
+        // Include a compact per-entry summary so operators can correlate
+        // "which send contained which logical message" during incident triage.
+        const entries = result.Successful.map((s) => {
+            const bufEntry = bufferById.get(s.Id);
+            const summary = bufEntry
+                ? summarizeMessageBody(bufEntry.MessageBody)
+                : {};
+            return { MessageId: s.MessageId, ...summary };
+        });
+        console.log(
+            `[QueuerUtil] SendMessageBatch ok: ${successCount}/${bufferSize} to ${queueUrl}`,
+            { entries }
+        );
+    }
+
+    return result;
+};
+
 const QueuerUtil = {
     send: async (message, queueUrl) => {
         const command = new SendMessageCommand({
             MessageBody: JSON.stringify(message),
             QueueUrl: queueUrl,
         });
-        return sqs.send(command);
+        const result = await sqs.send(command);
+        console.log(
+            `[QueuerUtil] SendMessage ok: MessageId=${result?.MessageId} to ${queueUrl}`
+        );
+        return result;
     },
 
     batchSend: async (entries = [], queueUrl) => {
@@ -42,7 +117,8 @@ const QueuerUtil = {
                     Entries: buffer,
                     QueueUrl: queueUrl,
                 });
-                await sqs.send(command);
+                const result = await sqs.send(command);
+                inspectBatchResult(result, queueUrl, buffer);
                 // Purge the buffer
                 buffer.splice(0, buffer.length);
             }
@@ -54,7 +130,8 @@ const QueuerUtil = {
                 Entries: buffer,
                 QueueUrl: queueUrl,
             });
-            return sqs.send(command);
+            const result = await sqs.send(command);
+            return inspectBatchResult(result, queueUrl, buffer);
         }
 
         // If we're exact... just return an empty object for now