@friggframework/core 2.0.0-next.12 → 2.0.0-next.120

package/handlers/workers/db-migration.js

@@ -0,0 +1,438 @@
+/**
+ * Database Migration Lambda Handler
+ *
+ * Lambda function that runs Prisma database migrations from within the VPC,
+ * enabling CI/CD pipelines to migrate databases without requiring public access.
+ *
+ * This handler uses the prisma-runner utilities from @friggframework/core,
+ * ensuring consistency with the `frigg db:setup` command.
+ *
+ * Environment Variables Required:
+ * - DATABASE_URL: Database connection string (automatically set from Secrets Manager)
+ * - DB_TYPE: Database type ('postgresql', 'mongodb', or 'documentdb')
+ * - STAGE: Deployment stage (determines migration command: 'dev' or 'deploy')
+ *
+ * Invocation:
+ *   aws lambda invoke \
+ *     --function-name my-app-production-dbMigrate \
+ *     --region us-east-1 \
+ *     response.json
+ *
+ * Success Response:
+ *   {
+ *     "statusCode": 200,
+ *     "body": {
+ *       "success": true,
+ *       "message": "Database migration completed successfully",
+ *       "dbType": "postgresql",
+ *       "stage": "production",
+ *       "migrationCommand": "deploy"
+ *     }
+ *   }
+ *
+ * Error Response:
+ *   {
+ *     "statusCode": 500,
+ *     "body": {
+ *       "success": false,
+ *       "error": "Migration failed: ...",
+ *       "stack": "Error: ..."
+ *     }
+ *   }
+ */
+
+const {
+    RunDatabaseMigrationUseCase,
+    MigrationError,
+    ValidationError,
+} = require('../../database/use-cases/run-database-migration-use-case');
+const {
+    CheckDatabaseStateUseCase,
+} = require('../../database/use-cases/check-database-state-use-case');
+const {
+    MigrationStatusRepositoryS3,
+} = require('../../database/repositories/migration-status-repository-s3');
+
+// Inject prisma-runner as dependency
+const prismaRunner = require('../../database/utils/prisma-runner');
+const { getLogger } = require('../../logs');
+
+const log = getLogger('frigg.database.migration');
+
+// Use S3 repository for migration status tracking (no User table dependency)
+const bucketName = process.env.S3_BUCKET_NAME || process.env.MIGRATION_STATUS_BUCKET;
+const migrationStatusRepository = new MigrationStatusRepositoryS3(bucketName);
+
+/**
+ * Sanitizes error messages to prevent credential leaks
+ * @param {string} errorMessage - Error message that might contain credentials
+ * @returns {string} Sanitized error message
+ */
+function sanitizeError(errorMessage) {
+    if (!errorMessage) return 'Unknown error';
+
+    return String(errorMessage)
+        // Remove PostgreSQL connection strings
+        .replace(/postgresql:\/\/[^@\s]+@[^\s/]+/gi, 'postgresql://***:***@***')
+        // Remove MongoDB connection strings
+        .replace(/mongodb(\+srv)?:\/\/[^@\s]+@[^\s/]+/gi, 'mongodb$1://***:***@***')
+        // Remove password parameters
+        .replace(/password[=:]\s*[^\s,;)]+/gi, 'password=***')
+        // Remove API keys
+        .replace(/apikey[=:]\s*[^\s,;)]+/gi, 'apikey=***')
+        .replace(/api[_-]?key[=:]\s*[^\s,;)]+/gi, 'api_key=***')
+        // Remove tokens
+        .replace(/token[=:]\s*[^\s,;)]+/gi, 'token=***')
+        .replace(/bearer\s+[^\s,;)]+/gi, 'bearer ***');
+}
+
+/**
+ * Sanitizes DATABASE_URL for safe logging
+ * @param {string} url - Database URL
+ * @returns {string} Sanitized URL
+ */
+function sanitizeDatabaseUrl(url) {
+    if (!url) return '';
+
+    // Replace credentials in connection string
+    return url.replace(/(:\/\/)([^:]+):([^@]+)@/, '$1***:***@');
+}
+
+/**
+ * Extract migration parameters from SQS event or direct invocation
+ * @param {Object} event - Lambda event (SQS or direct)
+ * @returns {Object} Extracted parameters { migrationId, dbType, stage }
+ */
+function extractMigrationParams(event) {
+    let migrationId = null;
+    let stage = null;
+    let dbType = process.env.DB_TYPE || 'postgresql';
+
+    // Check if this is an SQS event
+    if (event.Records && event.Records.length > 0) {
+        // SQS event - extract from message body
+        const message = JSON.parse(event.Records[0].body);
+        migrationId = message.migrationId;
+        stage = message.stage || process.env.STAGE || 'production';
+        dbType = message.dbType || dbType;
+
+        console.log('SQS event detected');
+        console.log(`  Migration ID: ${migrationId}`);
+        console.log(`  DB Type: ${dbType}`);
+        console.log(`  Stage: ${stage}`);
+    } else {
+        // Direct invocation - use event properties or environment variables
+        migrationId = event.migrationId || null;
+        stage = event.stage || process.env.STAGE || 'production';
+        dbType = event.dbType || dbType;
+
+        console.log('Direct invocation detected');
+        if (migrationId) {
+            console.log(`  Migration ID: ${migrationId}`);
+        }
+        console.log(`  DB Type: ${dbType}`);
+        console.log(`  Stage: ${stage}`);
+    }
+
+    return { migrationId, dbType, stage };
+}
+
+/**
+ * Lambda handler entry point
+ * @param {Object} event - Lambda event (SQS message or direct invocation)
+ * @param {Object} context - Lambda context (contains AWS request ID, timeout info)
+ * @returns {Promise<Object>} Response with statusCode and body
+ */
+exports.handler = async (event, context) => {
+    console.log('========================================');
+    console.log('Database Migration Lambda Started');
+    console.log('========================================');
+    console.log('Context:', JSON.stringify({
+        requestId: context.requestId,
+        functionName: context.functionName,
+        remainingTimeInMillis: context.getRemainingTimeInMillis(),
+    }, null, 2));
+
+    // Extract migration parameters from event
+    const { migrationId, dbType, stage } = extractMigrationParams(event);
+
+    // Check for action parameter (direct invocation for status checks)
+    const action = event.action || 'migrate'; // Default to migration
+
+    // targetStage, not stage: the record's own stage field would win.
+    log.info('Database migration invoked', {
+        eventName: 'frigg.database.migration.invoked',
+        migrationId,
+        dbType,
+        targetStage: stage,
+        action,
+    });
+
+    // Handle checkStatus action
+    if (action === 'checkStatus') {
+        console.log(`\n========================================`);
+        console.log(`Action: checkStatus (dbType=${dbType}, stage=${stage})`);
+        console.log(`========================================`);
+
+        try {
+            const checkDbStateUseCase = new CheckDatabaseStateUseCase({ prismaRunner });
+            const status = await checkDbStateUseCase.execute(dbType, stage);
+
+            console.log('✓ Database state check completed');
+            console.log(`  Up to date: ${status.upToDate}`);
+            console.log(`  Pending migrations: ${status.pendingMigrations}`);
+
+            return {
+                statusCode: 200,
+                body: status,
+            };
+        } catch (error) {
+            console.error('❌ Database state check failed:', error.message);
+            return {
+                statusCode: 500,
+                body: {
+                    success: false,
+                    error: sanitizeError(error.message),
+                    upToDate: false,
+                },
+            };
+        }
+    }
+
+    if (action === 'resolve') {
+        const { migrationName, resolveAction = 'applied' } = event;
+        console.log(`\n========================================`);
+        console.log(
+            `Action: resolve (migration=${migrationName}, mode=${resolveAction})`
+        );
+        console.log(`========================================`);
+
+        if (!migrationName) {
+            return {
+                statusCode: 400,
+                body: { success: false, error: 'migrationName is required' },
+            };
+        }
+        if (!/^\d{14}_[a-z0-9_]+$/i.test(migrationName)) {
+            return {
+                statusCode: 400,
+                body: {
+                    success: false,
+                    error: 'migrationName is not a valid migration identifier',
+                },
+            };
+        }
+        if (!['applied', 'rolled-back'].includes(resolveAction)) {
+            return {
+                statusCode: 400,
+                body: {
+                    success: false,
+                    error: 'resolveAction must be "applied" or "rolled-back"',
+                },
+            };
+        }
+        if (dbType !== 'postgresql') {
+            return {
+                statusCode: 400,
+                body: {
+                    success: false,
+                    error: `Migration resolve is only supported for postgresql, not "${dbType}"`,
+                },
+            };
+        }
+
+        try {
+            const result = await prismaRunner.runPrismaMigrateResolve(
+                migrationName,
+                resolveAction,
+                true
+            );
+            if (!result.success) {
+                return {
+                    statusCode: 500,
+                    body: {
+                        success: false,
+                        error: sanitizeError(result.error),
+                    },
+                };
+            }
+            return {
+                statusCode: 200,
+                body: {
+                    success: true,
+                    message: `Migration ${migrationName} marked as ${resolveAction}`,
+                    migrationName,
+                    action: resolveAction,
+                },
+            };
+        } catch (error) {
+            console.error('❌ Migration resolve failed:', error.message);
+            return {
+                statusCode: 500,
+                body: { success: false, error: sanitizeError(error.message) },
+            };
+        }
+    }
+
+    // Otherwise, handle migration (existing code)
+    console.log(`\n========================================`);
+    console.log(`Action: migrate (migrationId=${migrationId || 'new'})`);
+    console.log(`========================================`);
+
+    // Get environment variables
+    const databaseUrl = process.env.DATABASE_URL;
+
+    try {
+        // Validate DATABASE_URL is set
+        if (!databaseUrl) {
+            const error = 'DATABASE_URL environment variable is not set';
+            console.error('❌ Validation failed:', error);
+            return {
+                statusCode: 500,
+                body: JSON.stringify({
+                    success: false,
+                    error,
+                }),
+            };
+        }
+
+        console.log('✓ Environment validated');
+        console.log(`  Database Type: ${dbType}`);
+        console.log(`  Stage: ${stage}`);
+        console.log(`  Database URL: ${sanitizeDatabaseUrl(databaseUrl)}`);
+
+        // Update migration status to RUNNING (if migrationId provided)
+        if (migrationId) {
+            console.log(`\n✓ Updating migration status to RUNNING: ${migrationId}`);
+            await migrationStatusRepository.update({
+                migrationId,
+                stage,
+                state: 'RUNNING',
+                progress: 10,
+                startedAt: new Date().toISOString(),
+            });
+        }
+
+        // Create use case with dependencies (Dependency Injection)
+        const runDatabaseMigrationUseCase = new RunDatabaseMigrationUseCase({
+            prismaRunner,
+        });
+
+        console.log('\n========================================');
+        console.log('Executing Database Migration');
+        console.log('========================================');
+
+        // Execute use case (business logic layer)
+        const result = await runDatabaseMigrationUseCase.execute({
+            dbType,
+            stage,
+            verbose: true, // Enable verbose output for Lambda CloudWatch logs
+        });
+
+        console.log('✓ Database migration completed successfully');
+        console.log('\n========================================');
+        console.log('Migration Summary');
+        console.log('========================================');
+        console.log(`  Status: Success`);
+        console.log(`  Database: ${result.dbType}`);
+        console.log(`  Stage: ${result.stage}`);
+        console.log(`  Command: ${result.command}`);
+        console.log('========================================');
+
+        // Update migration status to COMPLETED (if migrationId provided)
+        if (migrationId) {
+            console.log(`\n✓ Updating migration status to COMPLETED: ${migrationId}`);
+            await migrationStatusRepository.update({
+                migrationId,
+                stage,
+                state: 'COMPLETED',
+                progress: 100,
+                completedAt: new Date().toISOString(),
+                migrationCommand: result.command,
+            });
+        }
+
+        // Return success response (adapter layer - HTTP mapping)
+        const responseBody = {
+            success: true,
+            message: result.message,
+            dbType: result.dbType,
+            stage: result.stage,
+            migrationCommand: result.command,
+            timestamp: new Date().toISOString(),
+        };
+
+        if (migrationId) {
+            responseBody.migrationId = migrationId;
+        }
+
+        return {
+            statusCode: 200,
+            body: JSON.stringify(responseBody),
+        };
+
+    } catch (error) {
+        console.error('\n========================================');
+        console.error('Migration Failed');
+        console.error('========================================');
+        console.error('Error:', error.name, error.message);
+
+        // Log full stack trace to CloudWatch (only visible to developers)
+        if (error.stack) {
+            console.error('Stack:', error.stack);
+        }
+
+        // Log context if available (from MigrationError)
+        if (error.context) {
+            console.error('Context:', JSON.stringify(error.context, null, 2));
+        }
+
+        // Map domain errors to HTTP status codes (adapter layer)
+        let statusCode = 500;
+        let errorMessage = error.message || 'Unknown error occurred';
+
+        if (error instanceof ValidationError) {
+            statusCode = 400; // Bad Request for validation errors
+        } else if (error instanceof MigrationError) {
+            statusCode = 500; // Internal Server Error for migration failures
+        }
+
+        // Sanitize error message before returning
+        const sanitizedError = sanitizeError(errorMessage);
+
+        // Update migration status to FAILED (if migrationId provided)
+        if (migrationId) {
+            try {
+                console.log(`\n✓ Updating migration status to FAILED: ${migrationId}`);
+                await migrationStatusRepository.update({
+                    migrationId,
+                    stage,
+                    state: 'FAILED',
+                    progress: 0,
+                    error: sanitizedError,
+                    failedAt: new Date().toISOString(),
+                });
+            } catch (updateError) {
+                console.error('Failed to update migration status:', updateError.message);
+                // Continue - don't let status update failure block error response
+            }
+        }
+
+        const errorBody = {
+            success: false,
+            error: sanitizedError,
+            errorType: error.name || 'Error',
+            // Only include stack traces in development environments
+            ...(stage === 'dev' || stage === 'local' || stage === 'test' ? { stack: error.stack } : {}),
+        };
+
+        if (migrationId) {
+            errorBody.migrationId = migrationId;
+        }
+
+        return {
+            statusCode,
+            body: JSON.stringify(errorBody),
+        };
+    }
+};

package/handlers/workers/dlq-processor.js

@@ -0,0 +1,89 @@
+/**
+ * DLQ Processor — logs failed messages from the InternalErrorQueue
+ * with structured context for monitoring and debugging.
+ *
+ * This handler MUST NOT throw. If it throws, the message goes back to
+ * the DLQ and creates an infinite loop. All errors are caught and logged.
+ */
+const crypto = require('node:crypto');
+const { getLogger } = require('../../logs');
+const {
+    summarizeLambdaEvent,
+    toScopeInvocation,
+} = require('../../logs/summarize-event');
+const {
+    runInvocationScope,
+    runMessageScope,
+} = require('../../core/invocation-scope');
+
+const log = getLogger('frigg.queue.dlq');
+
+function extractQueueName(eventSourceARN) {
+    if (!eventSourceARN) return 'UNKNOWN';
+    const parts = eventSourceARN.split(':');
+    return parts[parts.length - 1] || 'UNKNOWN';
+}
+
+// The body can hold credentials, so only its size and digest are logged.
+function describeBody(body) {
+    const text = typeof body === 'string' ? body : String(body ?? '');
+    let parsed = true;
+    try {
+        JSON.parse(text);
+    } catch {
+        parsed = false;
+    }
+    return {
+        parsed,
+        bodyLength: Buffer.byteLength(text),
+        bodySha256: crypto.createHash('sha256').update(text).digest('hex'),
+    };
+}
+
+function logRecord(record) {
+    const { parsed, ...body } = describeBody(record.body);
+    if (!parsed) {
+        log.warn('DLQ message body is not JSON', {
+            eventName: 'frigg.queue.dlq.body_unparsed',
+            ...body,
+        });
+    }
+    // messageId, receiveCount and the body ids come from the message scope.
+    log.error('Message reached the DLQ', {
+        eventName: 'frigg.queue.dlq.message_failed',
+        sentTimestamp: record.attributes?.SentTimestamp,
+        sourceQueue: extractQueueName(record.eventSourceARN),
+        ...body,
+    });
+}
+
+async function dlqProcessor(event, context) {
+    if (!event?.Records?.length) return { batchItemFailures: [] };
+
+    await runInvocationScope(
+        {
+            requestId: context?.awsRequestId,
+            handlerName: 'dlqProcessor',
+            invocation: toScopeInvocation(summarizeLambdaEvent(event)),
+        },
+        async () => {
+            for (const record of event.Records) {
+                await runMessageScope(record, async () => {
+                    try {
+                        logRecord(record);
+                    } catch (error) {
+                        log.error('DLQ record failed', {
+                            eventName: 'frigg.queue.dlq.record_failed',
+                            error,
+                        });
+                    }
+                });
+            }
+        },
+        { shouldUseDatabase: false, context }
+    );
+
+    return { batchItemFailures: [] };
+}
+
+module.exports = { dlqProcessor };

package/handlers/workers/integration-defined-workers.js

@@ -1,8 +1,18 @@
 const { createHandler } = require('@friggframework/core');
-const { integrationFactory, createQueueWorker } = require('../backend-utils');
+const { loadAppDefinition } = require('../app-definition-loader');
+const { createQueueWorker } = require('../backend-utils');
+// TODO(Phase 2): mount extension-declared workers in addition to the per-integration
+// default queue worker. Today, getExtensionWorkers(IntegrationClass) returns the
+// declared workers but they are not yet bound to dedicated SQS sources. Extension-
+// contributed *events* still flow through the default queue worker below because
+// _mergeExtensions() registers them in instance.events, so end-to-end webhook
+// delivery for Tier 3 extensions works without this Phase 2 work.
+// const { getExtensionWorkers } = require('../../integrations/extension');
 
 const handlers = {};
-integrationFactory.integrationClasses.forEach((IntegrationClass) => {
+const { integrations: integrationClasses } = loadAppDefinition();
+
+integrationClasses.forEach((IntegrationClass) => {
     const defaultQueueWorker = createQueueWorker(IntegrationClass);
 
     handlers[`${IntegrationClass.Definition.name}`] = {
@@ -11,11 +21,7 @@ integrationFactory.integrationClasses.forEach((IntegrationClass) => {
             isUserFacingResponse: false,
             method: async (event, context) => {
                 const worker = new defaultQueueWorker();
-                await worker.run(event, context);
-                return {
-                    message: 'Successfully processed the Generic Queue Worker',
-                    input: event,
-                };
+                return await worker.run(event, context);
             },
         }),
     };