@friggframework/devtools 2.0.0-next.75 → 2.0.0-next.76

package/infrastructure/domains/integration/integration-builder.js

@@ -145,20 +145,20 @@ class IntegrationBuilder extends InfrastructureBuilder {
      * Build integration resources based on ownership decisions
      */
     async buildFromDecisions(decisions, appDefinition, result, usePrismaLayer = true) {
+        // Create package config first — needed by all Lambda functions including DLQ processor
+        const functionPackageConfig = this.createFunctionPackageConfig(usePrismaLayer);
+
         // Create InternalErrorQueue if ownership = STACK
         const shouldCreateInternalErrorQueue = decisions.internalErrorQueue.ownership === ResourceOwnership.STACK;
 
         if (shouldCreateInternalErrorQueue) {
             console.log('  → Creating InternalErrorQueue in stack');
-            this.createInternalErrorQueue(result);
+            this.createInternalErrorQueue(result, functionPackageConfig);
         } else {
             console.log('  → Using external InternalErrorQueue');
-            this.useExternalInternalErrorQueue(decisions.internalErrorQueue, result);
+            this.useExternalInternalErrorQueue(decisions.internalErrorQueue, result, functionPackageConfig);
         }
 
-        // Create Lambda function definitions and queue resources for each integration
-        const functionPackageConfig = this.createFunctionPackageConfig(usePrismaLayer);
-
         for (const integration of appDefinition.integrations) {
             const integrationName = integration.Definition.name;
             const queueDecision = decisions.integrations[integrationName].queue;
@@ -316,6 +316,7 @@ class IntegrationBuilder extends InfrastructureBuilder {
                     sqs: {
                         arn: { 'Fn::GetAtt': [`${this.capitalizeFirst(integrationName)}Queue`, 'Arn'] },
                         batchSize: 1,
+                        functionResponseType: 'ReportBatchItemFailures',
                     },
                 },
             ],
@@ -327,29 +328,87 @@ class IntegrationBuilder extends InfrastructureBuilder {
     /**
      * Create InternalErrorQueue CloudFormation resource
      */
-    createInternalErrorQueue(result) {
+    createInternalErrorQueue(result, functionPackageConfig) {
         result.resources.InternalErrorQueue = {
             Type: 'AWS::SQS::Queue',
             Properties: {
                 QueueName: '${self:service}-${self:provider.stage}-InternalErrorQueue',
                 MessageRetentionPeriod: 1209600, // 14 days
-                VisibilityTimeout: 300, // 5 minutes for error processing
+                VisibilityTimeout: 300, // 5 minutes — must be >= 6x DLQ processor Lambda timeout (30s × 6 = 180s)
             },
         };
 
+        this.createDLQObservability(result, functionPackageConfig, {
+            'Fn::GetAtt': ['InternalErrorQueue', 'Arn'],
+        }, {
+            'Fn::GetAtt': ['InternalErrorQueue', 'QueueName'],
+        });
+
         console.log('  ✓ Created InternalErrorQueue resource');
     }
 
     /**
      * Use external InternalErrorQueue
      */
-    useExternalInternalErrorQueue(decision, result) {
+    useExternalInternalErrorQueue(decision, result, functionPackageConfig) {
         // Add ARN to environment for Lambda functions
         result.environment.INTERNAL_ERROR_QUEUE_ARN = decision.physicalId;
 
+        // Extract queue name from ARN for CloudWatch dimensions
+        const arnParts = decision.physicalId.split(':');
+        const queueName = arnParts[arnParts.length - 1];
+
+        this.createDLQObservability(result, functionPackageConfig, decision.physicalId, queueName);
+
         console.log(`  ✓ Using external InternalErrorQueue: ${decision.physicalId}`);
     }
 
+    /**
+     * Create DLQ observability resources (alarm + processor Lambda).
+     * Called for both stack-owned and external InternalErrorQueues.
+     */
+    createDLQObservability(result, functionPackageConfig, queueArn, queueName) {
+        // CloudWatch Alarm: fires when any message lands in the DLQ
+        result.resources.DLQMessageAlarm = {
+            Type: 'AWS::CloudWatch::Alarm',
+            Properties: {
+                AlarmDescription: 'Messages in dead-letter queue — integration queue processing failures',
+                Namespace: 'AWS/SQS',
+                MetricName: 'ApproximateNumberOfMessagesVisible',
+                Statistic: 'Maximum',
+                Threshold: 500,
+                ComparisonOperator: 'GreaterThanThreshold',
+                EvaluationPeriods: 1,
+                Period: 300,
+                AlarmActions: [{ Ref: 'InternalErrorBridgeTopic' }],
+                Dimensions: [
+                    { Name: 'QueueName', Value: queueName },
+                ],
+            },
+        };
+
+        // DLQ processor Lambda: logs failed messages with structured context
+        result.functions.dlqProcessor = {
+            handler: 'node_modules/@friggframework/core/handlers/workers/dlq-processor.dlqProcessor',
+            skipEsbuild: true,
+            package: functionPackageConfig,
+            reservedConcurrency: 1,
+            timeout: 30,
+            events: [
+                {
+                    sqs: {
+                        arn: queueArn,
+                        batchSize: 10,
+                        functionResponseType: 'ReportBatchItemFailures',
+                    },
+                },
+            ],
+        };
+
+        console.log('  ✓ Created DLQ CloudWatch alarm');
+        console.log('  ✓ Created DLQ processor Lambda');
+    }
+
     /**
      * Create integration-specific SQS queue CloudFormation resource
      */
@@ -361,10 +420,10 @@ class IntegrationBuilder extends InfrastructureBuilder {
             Type: 'AWS::SQS::Queue',
             Properties: {
                 QueueName: `\${self:custom.${queueReference}}`,
-                MessageRetentionPeriod: 60,
+                MessageRetentionPeriod: 345600, // 4 days (SQS default)
                 VisibilityTimeout: 1800,
                 RedrivePolicy: {
-                    maxReceiveCount: 1,
+                    maxReceiveCount: 3,
                     deadLetterTargetArn: {
                         'Fn::GetAtt': ['InternalErrorQueue', 'Arn'],
                     },

package/infrastructure/domains/integration/integration-builder.test.js

@@ -186,7 +186,7 @@ describe('IntegrationBuilder', () => {
 
             const result = await integrationBuilder.build(appDefinition, {});
 
-            expect(result.resources.TestQueue.Properties.MessageRetentionPeriod).toBe(60);
+            expect(result.resources.TestQueue.Properties.MessageRetentionPeriod).toBe(345600);
             expect(result.resources.TestQueue.Properties.VisibilityTimeout).toBe(1800);
         });
 
@@ -200,7 +200,7 @@ describe('IntegrationBuilder', () => {
             const result = await integrationBuilder.build(appDefinition, {});
 
             expect(result.resources.TestQueue.Properties.RedrivePolicy).toEqual({
-                maxReceiveCount: 1,
+                maxReceiveCount: 3,
                 deadLetterTargetArn: {
                     'Fn::GetAtt': ['InternalErrorQueue', 'Arn'],
                 },
@@ -233,6 +233,7 @@ describe('IntegrationBuilder', () => {
                     sqs: {
                         arn: { 'Fn::GetAtt': ['TestQueue', 'Arn'] },
                         batchSize: 1,
+                        functionResponseType: 'ReportBatchItemFailures',
                     },
                 },
             ]);
@@ -343,6 +344,112 @@ describe('IntegrationBuilder', () => {
             expect(result.functions['my-integration']).toBeDefined();
             expect(result.functions['my-integrationQueueWorker']).toBeDefined();
         });
+
+        // ============================================================
+        // Theory-proving tests: demonstrate current dangerous config
+        // These tests document the root cause of the Modern Midstay bug
+        // where POST_CREATE_SETUP messages were silently lost.
+        // ============================================================
+
+        it('THEORY: MessageRetentionPeriod is too short for delayed messages', async () => {
+            // POST_CREATE_SETUP uses DelaySeconds=35.
+            // With MessageRetentionPeriod=60, the message is only visible
+            // for 25 seconds before SQS silently deletes it.
+            // Messages that expire are NOT sent to DLQ — they vanish.
+            const appDefinition = {
+                integrations: [{ Definition: { name: 'test' } }],
+            };
+
+            const result = await integrationBuilder.build(appDefinition, {});
+            const retention = result.resources.TestQueue.Properties.MessageRetentionPeriod;
+
+            // The max SQS DelaySeconds is 900. Retention must comfortably
+            // exceed this to ensure delayed messages are never silently lost.
+            // Current value (60) fails this check.
+            expect(retention).toBeGreaterThan(900);
+        });
+
+        it('THEORY: maxReceiveCount=1 means zero retries on transient failures', async () => {
+            // A single transient error (network blip, cold start timeout,
+            // rate limit) sends the message straight to DLQ with no retry.
+            const appDefinition = {
+                integrations: [{ Definition: { name: 'test' } }],
+            };
+
+            const result = await integrationBuilder.build(appDefinition, {});
+            const maxReceiveCount = result.resources.TestQueue.Properties.RedrivePolicy.maxReceiveCount;
+
+            // Should allow at least 2 retries (maxReceiveCount >= 3)
+            expect(maxReceiveCount).toBeGreaterThanOrEqual(3);
+        });
+
+        it('THEORY: SQS event source should enable ReportBatchItemFailures', async () => {
+            // Without this, Lambda can't tell SQS which specific messages
+            // failed — it's all-or-nothing for the entire invocation.
+            const appDefinition = {
+                integrations: [{ Definition: { name: 'test' } }],
+            };
+
+            const result = await integrationBuilder.build(appDefinition, {});
+            const sqsEvent = result.functions.testQueueWorker.events[0].sqs;
+
+            expect(sqsEvent.functionResponseType).toBe('ReportBatchItemFailures');
+        });
+    });
+
+    describe('DLQ Observability', () => {
+        it('should create a CloudWatch alarm for DLQ message depth', async () => {
+            const appDefinition = {
+                integrations: [{ Definition: { name: 'test' } }],
+            };
+
+            const result = await integrationBuilder.build(appDefinition, {});
+
+            expect(result.resources.DLQMessageAlarm).toBeDefined();
+            expect(result.resources.DLQMessageAlarm.Type).toBe('AWS::CloudWatch::Alarm');
+            expect(result.resources.DLQMessageAlarm.Properties.MetricName).toBe('ApproximateNumberOfMessagesVisible');
+            expect(result.resources.DLQMessageAlarm.Properties.ComparisonOperator).toBe('GreaterThanThreshold');
+            expect(result.resources.DLQMessageAlarm.Properties.Threshold).toBe(500);
+        });
+
+        it('should wire alarm to InternalErrorBridgeTopic for notifications', async () => {
+            const appDefinition = {
+                integrations: [{ Definition: { name: 'test' } }],
+            };
+
+            const result = await integrationBuilder.build(appDefinition, {});
+
+            expect(result.resources.DLQMessageAlarm.Properties.AlarmActions).toEqual([
+                { Ref: 'InternalErrorBridgeTopic' },
+            ]);
+        });
+
+        it('should create a DLQ processor Lambda triggered by InternalErrorQueue', async () => {
+            const appDefinition = {
+                integrations: [{ Definition: { name: 'test' } }],
+            };
+
+            const result = await integrationBuilder.build(appDefinition, {});
+
+            expect(result.functions.dlqProcessor).toBeDefined();
+            expect(result.functions.dlqProcessor.events[0].sqs.arn).toEqual({
+                'Fn::GetAtt': ['InternalErrorQueue', 'Arn'],
+            });
+            expect(result.functions.dlqProcessor.events[0].sqs.functionResponseType).toBe('ReportBatchItemFailures');
+        });
+
+        it('DLQ processor should have skipEsbuild, short timeout, and low concurrency', async () => {
+            const appDefinition = {
+                integrations: [{ Definition: { name: 'test' } }],
+            };
+
+            const result = await integrationBuilder.build(appDefinition, {});
+
+            expect(result.functions.dlqProcessor.skipEsbuild).toBe(true);
+            expect(result.functions.dlqProcessor.package).toBeDefined();
+            expect(result.functions.dlqProcessor.timeout).toBeLessThanOrEqual(60);
+            expect(result.functions.dlqProcessor.reservedConcurrency).toBe(1);
+        });
     });
 
     describe('getDependencies()', () => {
@@ -503,8 +610,9 @@ describe('IntegrationBuilder', () => {
 
             const functionKeys = Object.keys(result.functions);
 
-            // Expected order: webhook, integration, queueWorker
+            // Expected order: dlqProcessor (from InternalErrorQueue), webhook, integration, queueWorker
             expect(functionKeys).toEqual([
+                'dlqProcessor',
                 'testWebhook',
                 'test',
                 'testQueueWorker',

package/infrastructure/infrastructure-composer.test.js

@@ -1148,10 +1148,10 @@ describe('composeServerlessDefinition', () => {
                 Type: 'AWS::SQS::Queue',
                 Properties: {
                     QueueName: '${self:custom.TestIntegrationQueue}',
-                    MessageRetentionPeriod: 60,
+                    MessageRetentionPeriod: 345600,
                     VisibilityTimeout: 1800,
                     RedrivePolicy: {
-                        maxReceiveCount: 1,
+                        maxReceiveCount: 3,
                         deadLetterTargetArn: {
                             'Fn::GetAtt': ['InternalErrorQueue', 'Arn']
                         }
@@ -1168,7 +1168,8 @@ describe('composeServerlessDefinition', () => {
                         arn: {
                             'Fn::GetAtt': ['TestIntegrationQueue', 'Arn']
                         },
-                        batchSize: 1
+                        batchSize: 1,
+                        functionResponseType: 'ReportBatchItemFailures'
                     }
                 }],
                 timeout: 600

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@friggframework/devtools",
   "prettier": "@friggframework/prettier-config",
-  "version": "2.0.0-next.75",
+  "version": "2.0.0-next.76",
   "bin": {
     "frigg": "./frigg-cli/index.js"
   },
@@ -25,9 +25,9 @@
     "@babel/eslint-parser": "^7.18.9",
     "@babel/parser": "^7.25.3",
     "@babel/traverse": "^7.25.3",
-    "@friggframework/core": "2.0.0-next.75",
-    "@friggframework/schemas": "2.0.0-next.75",
-    "@friggframework/test": "2.0.0-next.75",
+    "@friggframework/core": "2.0.0-next.76",
+    "@friggframework/schemas": "2.0.0-next.76",
+    "@friggframework/test": "2.0.0-next.76",
     "@hapi/boom": "^10.0.1",
     "@inquirer/prompts": "^5.3.8",
     "axios": "^1.7.2",
@@ -55,8 +55,8 @@
     "validate-npm-package-name": "^5.0.0"
   },
   "devDependencies": {
-    "@friggframework/eslint-config": "2.0.0-next.75",
-    "@friggframework/prettier-config": "2.0.0-next.75",
+    "@friggframework/eslint-config": "2.0.0-next.76",
+    "@friggframework/prettier-config": "2.0.0-next.76",
     "aws-sdk-client-mock": "^4.1.0",
     "aws-sdk-client-mock-jest": "^4.1.0",
     "jest": "^30.1.3",
@@ -88,5 +88,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "d8b091ab80329d8d8ed22c019d120f3122419bb9"
+  "gitHead": "5f03113234df57301443502f2751f1864dd44e73"
 }