@friggframework/devtools 2.0.0--canary.461.849e166.0 → 2.0.0--canary.474.aa465e4.0

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

@@ -1,16 +1,23 @@
 /**
  * Integration Builder
- * 
+ *
  * Domain Layer - Hexagonal Architecture
- * 
+ *
  * Responsible for:
- * - Creating SQS queues for each integration
+ * - Creating SQS queues for each integration (CloudFormation resources)
+ * - Creating InternalErrorQueue (dead letter queue)
+ * - Creating Lambda function definitions (serverless template code)
  * - Creating queue worker Lambda functions
  * - Creating webhook handler functions
  * - Configuring integration-specific routes and handlers
+ *
+ * Uses ownership-based architecture to support both stack-managed
+ * and externally-provided SQS queues.
  */
 
 const { InfrastructureBuilder, ValidationResult } = require('../shared/base-builder');
+const IntegrationResourceResolver = require('./integration-resolver');
+const { createEmptyDiscoveryResult, ResourceOwnership } = require('../shared/types');
 
 class IntegrationBuilder extends InfrastructureBuilder {
     constructor() {
@@ -22,6 +29,10 @@ class IntegrationBuilder extends InfrastructureBuilder {
         return Array.isArray(appDefinition.integrations) && appDefinition.integrations.length > 0;
     }
 
+    getDependencies() {
+        return []; // No dependencies - integrations can run independently
+    }
+
     validate(appDefinition) {
         const result = new ValidationResult();
 
@@ -45,7 +56,7 @@ class IntegrationBuilder extends InfrastructureBuilder {
     }
 
     /**
-     * Build integration infrastructure
+     * Build integration infrastructure using ownership-based architecture
      */
     async build(appDefinition, discoveredResources) {
         console.log(`\n[${this.name}] Configuring integrations...`);
@@ -56,9 +67,123 @@ class IntegrationBuilder extends InfrastructureBuilder {
             resources: {},
             environment: {},
             custom: {},
+            iamStatements: [],
         };
 
-        const functionPackageConfig = {
+        // Get structured discovery result
+        const discovery = discoveredResources._structured || this.convertFlatDiscoveryToStructured(discoveredResources);
+
+        // Use IntegrationResourceResolver to make ownership decisions
+        const resolver = new IntegrationResourceResolver();
+        const decisions = resolver.resolveAll(appDefinition, discovery);
+
+        console.log('\n  📋 Resource Ownership Decisions:');
+        console.log(`     InternalErrorQueue: ${decisions.internalErrorQueue.ownership} - ${decisions.internalErrorQueue.reason}`);
+
+        // Log per-integration decisions
+        Object.keys(decisions.integrations).forEach(integrationName => {
+            const queueDecision = decisions.integrations[integrationName].queue;
+            console.log(`     ${integrationName}Queue: ${queueDecision.ownership} - ${queueDecision.reason}`);
+        });
+
+        // Build resources based on ownership decisions
+        await this.buildFromDecisions(decisions, appDefinition, result);
+
+        console.log(`[${this.name}] ✅ Integration configuration completed`);
+        return result;
+    }
+
+    /**
+     * Convert flat discovery to structured discovery
+     * Provides backwards compatibility
+     */
+    convertFlatDiscoveryToStructured(flatDiscovery) {
+        const discovery = createEmptyDiscoveryResult();
+
+        if (!flatDiscovery) {
+            return discovery;
+        }
+
+        // Check if resources are from CloudFormation stack
+        if (flatDiscovery.fromCloudFormationStack) {
+            discovery.fromCloudFormation = true;
+            discovery.stackName = flatDiscovery.stackName || 'assumed-stack';
+
+            // Add stack-managed resources from existingLogicalIds
+            const existingLogicalIds = flatDiscovery.existingLogicalIds || [];
+            existingLogicalIds.forEach(logicalId => {
+                let resourceType = '';
+                let physicalId = '';
+
+                // Determine resource type and physical ID
+                if (logicalId === 'InternalErrorQueue') {
+                    resourceType = 'AWS::SQS::Queue';
+                    physicalId = flatDiscovery.internalErrorQueueUrl;
+                } else if (logicalId.endsWith('Queue')) {
+                    // Integration-specific queue (e.g., SlackQueue, HubspotQueue)
+                    resourceType = 'AWS::SQS::Queue';
+                    const integrationName = logicalId.replace('Queue', '').toLowerCase();
+                    physicalId = flatDiscovery[`${integrationName}QueueUrl`];
+                }
+
+                if (physicalId && typeof physicalId === 'string') {
+                    discovery.stackManaged.push({
+                        logicalId,
+                        physicalId,
+                        resourceType
+                    });
+                }
+            });
+        }
+
+        return discovery;
+    }
+
+    /**
+     * Build integration resources based on ownership decisions
+     */
+    async buildFromDecisions(decisions, appDefinition, result) {
+        // Create InternalErrorQueue if ownership = STACK
+        const shouldCreateInternalErrorQueue = decisions.internalErrorQueue.ownership === ResourceOwnership.STACK;
+
+        if (shouldCreateInternalErrorQueue) {
+            console.log('  → Creating InternalErrorQueue in stack');
+            this.createInternalErrorQueue(result);
+        } else {
+            console.log('  → Using external InternalErrorQueue');
+            this.useExternalInternalErrorQueue(decisions.internalErrorQueue, result);
+        }
+
+        // Create Lambda function definitions and queue resources for each integration
+        const functionPackageConfig = this.createFunctionPackageConfig();
+
+        for (const integration of appDefinition.integrations) {
+            const integrationName = integration.Definition.name;
+            const queueDecision = decisions.integrations[integrationName].queue;
+
+            console.log(`\n    Adding integration: ${integrationName}`);
+
+            // Create Lambda function definitions (serverless template code)
+            await this.createFunctionDefinitions(integration, functionPackageConfig, result);
+
+            // Create or reference SQS queue based on ownership decision
+            const shouldCreateQueue = queueDecision.ownership === ResourceOwnership.STACK;
+
+            if (shouldCreateQueue) {
+                console.log(`      ✓ Creating ${integrationName}Queue in stack`);
+                this.createIntegrationQueue(integrationName, result);
+            } else {
+                console.log(`      ✓ Using external ${integrationName}Queue`);
+                this.useExternalIntegrationQueue(integrationName, queueDecision, result);
+            }
+        }
+    }
+
+    /**
+     * Create function package exclusion configuration
+     */
+    createFunctionPackageConfig() {
+        return {
             exclude: [
                 // Exclude AWS SDK (provided by Lambda runtime)
                 'node_modules/aws-sdk/**',
@@ -118,106 +243,155 @@ class IntegrationBuilder extends InfrastructureBuilder {
                 '**/.swarm/**',
             ],
         };
+    }
 
-        for (const integration of appDefinition.integrations) {
-            const integrationName = integration.Definition.name;
-            const queueReference = `${integrationName.charAt(0).toUpperCase() + integrationName.slice(1)}Queue`;
-            const queueName = `\${self:service}--\${self:provider.stage}-${queueReference}`;
-
-            console.log(`    Adding integration: ${integrationName}`);
-
-            // Add webhook handler if enabled (BEFORE catch-all proxy route)
-            // CRITICAL: Webhook routes must be defined before the catch-all {proxy+} route
-            // to ensure proper route matching in AWS API Gateway/HTTP API
-            const webhookConfig = integration.Definition.webhooks;
-            if (webhookConfig && (webhookConfig === true || webhookConfig.enabled === true)) {
-                const webhookFunctionName = `${integrationName}Webhook`;
-
-                result.functions[webhookFunctionName] = {
-                    handler: `node_modules/@friggframework/core/handlers/routers/integration-webhook-routers.handlers.${integrationName}Webhook.handler`,
-                    skipEsbuild: true,  // Nested exports in node_modules - skip esbuild bundling
-                    package: functionPackageConfig,
-                    events: [
-                        {
-                            httpApi: {
-                                path: `/api/${integrationName}-integration/webhooks`,
-                                method: 'POST',
-                            },
-                        },
-                        {
-                            httpApi: {
-                                path: `/api/${integrationName}-integration/webhooks/{integrationId}`,
-                                method: 'POST',
-                            },
-                        },
-                    ],
-                };
-                console.log(`      + Webhook handler enabled`);
-            }
+    /**
+     * Create Lambda function definitions for an integration
+     * These are serverless framework template function definitions
+     */
+    async createFunctionDefinitions(integration, functionPackageConfig, result) {
+        const integrationName = integration.Definition.name;
+
+        // Add webhook handler if enabled (BEFORE catch-all proxy route)
+        // CRITICAL: Webhook routes must be defined before the catch-all {proxy+} route
+        // to ensure proper route matching in AWS API Gateway/HTTP API
+        const webhookConfig = integration.Definition.webhooks;
+        if (webhookConfig && (webhookConfig === true || webhookConfig.enabled === true)) {
+            const webhookFunctionName = `${integrationName}Webhook`;
 
-            // Create HTTP API handler for integration (catch-all route AFTER webhooks)
-            result.functions[integrationName] = {
-                handler: `node_modules/@friggframework/core/handlers/routers/integration-defined-routers.handlers.${integrationName}.handler`,
+            result.functions[webhookFunctionName] = {
+                handler: `node_modules/@friggframework/core/handlers/routers/integration-webhook-routers.handlers.${integrationName}Webhook.handler`,
                 skipEsbuild: true,  // Nested exports in node_modules - skip esbuild bundling
                 package: functionPackageConfig,
                 events: [
                     {
                         httpApi: {
-                            path: `/api/${integrationName}-integration/{proxy+}`,
-                            method: 'ANY',
+                            path: `/api/${integrationName}-integration/webhooks`,
+                            method: 'POST',
+                        },
+                    },
+                    {
+                        httpApi: {
+                            path: `/api/${integrationName}-integration/webhooks/{integrationId}`,
+                            method: 'POST',
                         },
                     },
                 ],
             };
+            console.log(`      ✓ Webhook handler function defined`);
+        }
 
-            // Create SQS Queue for integration
-            result.resources[queueReference] = {
-                Type: 'AWS::SQS::Queue',
-                Properties: {
-                    QueueName: `\${self:custom.${queueReference}}`,
-                    MessageRetentionPeriod: 60,
-                    VisibilityTimeout: 1800,
-                    RedrivePolicy: {
-                        maxReceiveCount: 1,
-                        deadLetterTargetArn: {
-                            'Fn::GetAtt': ['InternalErrorQueue', 'Arn'],
-                        },
+        // Create HTTP API handler for integration (catch-all route AFTER webhooks)
+        result.functions[integrationName] = {
+            handler: `node_modules/@friggframework/core/handlers/routers/integration-defined-routers.handlers.${integrationName}.handler`,
+            skipEsbuild: true,  // Nested exports in node_modules - skip esbuild bundling
+            package: functionPackageConfig,
+            events: [
+                {
+                    httpApi: {
+                        path: `/api/${integrationName}-integration/{proxy+}`,
+                        method: 'ANY',
                     },
                 },
-            };
+            ],
+        };
+        console.log(`      ✓ HTTP handler function defined`);
 
-            // Create Queue Worker function
-            const queueWorkerName = `${integrationName}QueueWorker`;
-            result.functions[queueWorkerName] = {
-                handler: `node_modules/@friggframework/core/handlers/workers/integration-defined-workers.handlers.${integrationName}.queueWorker`,
-                skipEsbuild: true,  // Nested exports in node_modules - skip esbuild bundling
-                package: functionPackageConfig,
-                reservedConcurrency: 5,
-                events: [
-                    {
-                        sqs: {
-                            arn: { 'Fn::GetAtt': [queueReference, 'Arn'] },
-                            batchSize: 1,
-                        },
+        // Create Queue Worker function
+        const queueWorkerName = `${integrationName}QueueWorker`;
+        result.functions[queueWorkerName] = {
+            handler: `node_modules/@friggframework/core/handlers/workers/integration-defined-workers.handlers.${integrationName}.queueWorker`,
+            skipEsbuild: true,  // Nested exports in node_modules - skip esbuild bundling
+            package: functionPackageConfig,
+            reservedConcurrency: 5,
+            events: [
+                {
+                    sqs: {
+                        arn: { 'Fn::GetAtt': [`${this.capitalizeFirst(integrationName)}Queue`, 'Arn'] },
+                        batchSize: 1,
                     },
-                ],
-                timeout: 900,  // 15 minutes max for queue workers (Lambda maximum)
-            };
+                },
+            ],
+            timeout: 900,  // 15 minutes max for queue workers (Lambda maximum)
+        };
+        console.log(`      ✓ Queue worker function defined`);
+    }
 
-            // Add queue URL to environment
-            result.environment[`${integrationName.toUpperCase()}_QUEUE_URL`] = {
-                Ref: queueReference,
-            };
+    /**
+     * Create InternalErrorQueue CloudFormation resource
+     */
+    createInternalErrorQueue(result) {
+        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
+            },
+        };
 
-            result.custom[queueReference] = queueName;
-        }
+        console.log('  ✓ Created InternalErrorQueue resource');
+    }
 
-        console.log(`  ✅ Configured ${appDefinition.integrations.length} integrations`);
-        console.log(`[${this.name}] ✅ Integration configuration completed`);
+    /**
+     * Use external InternalErrorQueue
+     */
+    useExternalInternalErrorQueue(decision, result) {
+        // Add ARN to environment for Lambda functions
+        result.environment.INTERNAL_ERROR_QUEUE_ARN = decision.physicalId;
 
-        return result;
+        console.log(`  ✓ Using external InternalErrorQueue: ${decision.physicalId}`);
+    }
+
+    /**
+     * Create integration-specific SQS queue CloudFormation resource
+     */
+    createIntegrationQueue(integrationName, result) {
+        const queueReference = `${this.capitalizeFirst(integrationName)}Queue`;
+        const queueName = `\${self:service}--\${self:provider.stage}-${queueReference}`;
+
+        result.resources[queueReference] = {
+            Type: 'AWS::SQS::Queue',
+            Properties: {
+                QueueName: `\${self:custom.${queueReference}}`,
+                MessageRetentionPeriod: 60,
+                VisibilityTimeout: 1800,
+                RedrivePolicy: {
+                    maxReceiveCount: 1,
+                    deadLetterTargetArn: {
+                        'Fn::GetAtt': ['InternalErrorQueue', 'Arn'],
+                    },
+                },
+            },
+        };
+
+        // Add queue URL to environment
+        result.environment[`${integrationName.toUpperCase()}_QUEUE_URL`] = {
+            Ref: queueReference,
+        };
+
+        // Add queue name to custom section
+        result.custom[queueReference] = queueName;
+
+        console.log(`  ✓ Created ${queueReference} resource`);
+    }
+
+    /**
+     * Use external integration queue
+     */
+    useExternalIntegrationQueue(integrationName, decision, result) {
+        // Add queue URL to environment for Lambda functions
+        result.environment[`${integrationName.toUpperCase()}_QUEUE_URL`] = decision.physicalId;
+
+        console.log(`  ✓ Using external queue: ${decision.physicalId}`);
+    }
+
+    /**
+     * Capitalize first letter of string (e.g., 'slack' -> 'Slack')
+     */
+    capitalizeFirst(str) {
+        return str.charAt(0).toUpperCase() + str.slice(1);
     }
 }
 
 module.exports = { IntegrationBuilder };
-

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

@@ -0,0 +1,170 @@
+/**
+ * Integration Resource Resolver
+ *
+ * Domain Layer - Hexagonal Architecture
+ *
+ * Responsible for resolving ownership decisions for integration infrastructure:
+ * - SQS queues per integration
+ *
+ * Follows the ownership-based architecture pattern:
+ * - STACK: Create/manage resources in CloudFormation stack
+ * - EXTERNAL: Use existing resources by physical ID
+ * - AUTO: Intelligent decision based on discovery
+ */
+
+const BaseResourceResolver = require('../shared/base-resolver');
+const { ResourceOwnership } = require('../shared/types/resource-ownership');
+
+class IntegrationResourceResolver extends BaseResourceResolver {
+    /**
+     * Resolve ownership for all integration resources
+     * @param {Object} appDefinition - Application definition
+     * @param {Object} discovery - Structured discovery result
+     * @returns {Object} Ownership decisions for all integration resources
+     */
+    resolveAll(appDefinition, discovery) {
+        const integrations = appDefinition.integrations || [];
+        const decisions = {
+            // Shared resources used by all integrations
+            internalErrorQueue: this.resolveInternalErrorQueue(appDefinition, discovery),
+            // Per-integration queues
+            integrations: {},
+        };
+
+        // Resolve ownership for each integration's SQS queue
+        integrations.forEach(integration => {
+            const integrationName = integration.Definition?.name;
+            if (!integrationName) {
+                return; // Skip invalid integrations
+            }
+
+            decisions.integrations[integrationName] = {
+                queue: this.resolveQueue(integrationName, appDefinition, discovery),
+            };
+        });
+
+        return decisions;
+    }
+
+    /**
+     * Resolve ownership for the shared InternalErrorQueue (dead letter queue)
+     * @param {Object} appDefinition - Application definition
+     * @param {Object} discovery - Structured discovery result
+     * @returns {Object} Ownership decision for InternalErrorQueue
+     */
+    resolveInternalErrorQueue(appDefinition, discovery) {
+        const userIntent = appDefinition.integrations?.ownership?.internalErrorQueue || ResourceOwnership.AUTO;
+        const queueLogicalId = 'InternalErrorQueue';
+        const inStack = this.isInStack(queueLogicalId, discovery);
+
+        // STACK: User wants this in the CloudFormation stack
+        if (userIntent === ResourceOwnership.STACK) {
+            const stackResource = inStack ? this.findInStack(queueLogicalId, discovery) : null;
+            return this.createStackDecision(
+                stackResource?.physicalId || null,
+                inStack
+                    ? `Found ${queueLogicalId} in CloudFormation stack`
+                    : `Will create ${queueLogicalId} in stack`
+            );
+        }
+
+        // EXTERNAL: User wants to use an existing queue
+        if (userIntent === ResourceOwnership.EXTERNAL) {
+            const queueArn = appDefinition.integrations?.internalErrorQueue?.arn;
+            if (!queueArn) {
+                throw new Error(
+                    'InternalErrorQueue configured with ownership=external but integrations.internalErrorQueue.arn not provided'
+                );
+            }
+            return this.createExternalDecision(
+                queueArn,
+                `Using external InternalErrorQueue ARN: ${queueArn}`
+            );
+        }
+
+        // AUTO: Intelligent decision based on discovery
+        if (inStack) {
+            const stackResource = this.findInStack(queueLogicalId, discovery);
+            return this.createStackDecision(
+                stackResource.physicalId,
+                `Found ${queueLogicalId} in CloudFormation stack - will include definition (idempotent)`
+            );
+        }
+
+        // Default: Create in stack
+        return this.createStackDecision(
+            null,
+            `No existing ${queueLogicalId} found - will create in stack`
+        );
+    }
+
+    /**
+     * Resolve ownership for an integration's SQS queue
+     * @param {string} integrationName - Name of the integration (e.g., 'slack')
+     * @param {Object} appDefinition - Application definition
+     * @param {Object} discovery - Structured discovery result
+     * @returns {Object} Ownership decision for the queue
+     */
+    resolveQueue(integrationName, appDefinition, discovery) {
+        // Check for explicit ownership configuration
+        const integration = appDefinition.integrations?.find(
+            i => i.Definition?.name === integrationName
+        );
+        const userIntent = integration?.ownership?.queue || ResourceOwnership.AUTO;
+
+        // Queue logical ID follows pattern: ${IntegrationName}Queue (e.g., SlackQueue)
+        const queueLogicalId = `${this.capitalizeFirst(integrationName)}Queue`;
+        const inStack = this.isInStack(queueLogicalId, discovery);
+
+        // STACK: User wants this in the CloudFormation stack
+        if (userIntent === ResourceOwnership.STACK) {
+            const stackResource = inStack ? this.findInStack(queueLogicalId, discovery) : null;
+            return this.createStackDecision(
+                stackResource?.physicalId || null,
+                inStack
+                    ? `Found ${queueLogicalId} in CloudFormation stack`
+                    : `Will create ${queueLogicalId} in stack`
+            );
+        }
+
+        // EXTERNAL: User wants to use an existing queue
+        if (userIntent === ResourceOwnership.EXTERNAL) {
+            const queueUrl = integration?.queue?.url;
+            if (!queueUrl) {
+                throw new Error(
+                    `Integration '${integrationName}' configured with ownership=external but queue.url not provided`
+                );
+            }
+            return this.createExternalDecision(
+                queueUrl,
+                `Using external queue URL: ${queueUrl}`
+            );
+        }
+
+        // AUTO: Intelligent decision based on discovery
+        if (inStack) {
+            const stackResource = this.findInStack(queueLogicalId, discovery);
+            return this.createStackDecision(
+                stackResource.physicalId,
+                `Found ${queueLogicalId} in CloudFormation stack - will include definition (idempotent)`
+            );
+        }
+
+        // Default: Create in stack
+        return this.createStackDecision(
+            null,
+            `No existing ${queueLogicalId} found - will create in stack`
+        );
+    }
+
+    /**
+     * Capitalize first letter of string (e.g., 'slack' -> 'Slack')
+     * @param {string} str - String to capitalize
+     * @returns {string} Capitalized string
+     */
+    capitalizeFirst(str) {
+        return str.charAt(0).toUpperCase() + str.slice(1);
+    }
+}
+
+module.exports = IntegrationResourceResolver;