@friggframework/core 2.0.0--canary.461.e58db0a.0 → 2.0.0--canary.461.4f3c330.0

package/database/use-cases/trigger-database-migration-use-case.test.js

@@ -0,0 +1,265 @@
+/**
+ * Tests for TriggerDatabaseMigrationUseCase
+ */
+
+const {
+    TriggerDatabaseMigrationUseCase,
+    ValidationError,
+} = require('./trigger-database-migration-use-case');
+
+describe('TriggerDatabaseMigrationUseCase', () => {
+    let useCase;
+    let mockProcessRepository;
+    let mockQueuerUtil;
+    let originalEnv;
+
+    beforeEach(() => {
+        // Save original environment value
+        originalEnv = process.env.DB_MIGRATION_QUEUE_URL;
+
+        // Set test environment
+        process.env.DB_MIGRATION_QUEUE_URL = 'https://sqs.us-east-1.amazonaws.com/123456789/test-queue';
+
+        // Create mock repository
+        mockProcessRepository = {
+            create: jest.fn().mockResolvedValue({
+                id: 'process-123',
+                userId: 'user-456',
+                integrationId: null,
+                name: 'database-migration',
+                type: 'DATABASE_MIGRATION',
+                state: 'INITIALIZING',
+                context: {
+                    dbType: 'postgresql',
+                    stage: 'production',
+                },
+                results: {},
+                createdAt: new Date(),
+                updatedAt: new Date(),
+            }),
+            updateState: jest.fn().mockResolvedValue(true),
+        };
+
+        // Create mock queuer util
+        mockQueuerUtil = {
+            send: jest.fn().mockResolvedValue({ MessageId: 'msg-123' }),
+        };
+
+        // Create use case with mocks
+        useCase = new TriggerDatabaseMigrationUseCase({
+            processRepository: mockProcessRepository,
+            queuerUtil: mockQueuerUtil,
+        });
+    });
+
+    afterEach(() => {
+        // Restore original environment
+        if (originalEnv !== undefined) {
+            process.env.DB_MIGRATION_QUEUE_URL = originalEnv;
+        } else {
+            delete process.env.DB_MIGRATION_QUEUE_URL;
+        }
+        jest.clearAllMocks();
+    });
+
+    describe('constructor', () => {
+        it('should throw error if processRepository not provided', () => {
+            expect(() => {
+                new TriggerDatabaseMigrationUseCase({});
+            }).toThrow('processRepository dependency is required');
+        });
+
+        it('should accept custom queuerUtil', () => {
+            const customQueuer = { send: jest.fn() };
+            const instance = new TriggerDatabaseMigrationUseCase({
+                processRepository: mockProcessRepository,
+                queuerUtil: customQueuer,
+            });
+
+            expect(instance.queuerUtil).toBe(customQueuer);
+        });
+    });
+
+    describe('execute', () => {
+        it('should create process and queue migration job', async () => {
+            const result = await useCase.execute({
+                userId: 'user-456',
+                dbType: 'postgresql',
+                stage: 'production',
+            });
+
+            // Verify process creation
+            expect(mockProcessRepository.create).toHaveBeenCalledWith({
+                userId: 'user-456',
+                integrationId: null,
+                name: 'database-migration',
+                type: 'DATABASE_MIGRATION',
+                state: 'INITIALIZING',
+                context: expect.objectContaining({
+                    dbType: 'postgresql',
+                    stage: 'production',
+                }),
+                results: {},
+            });
+
+            // Verify SQS message sent
+            expect(mockQueuerUtil.send).toHaveBeenCalledWith(
+                {
+                    processId: 'process-123',
+                    dbType: 'postgresql',
+                    stage: 'production',
+                },
+                'https://sqs.us-east-1.amazonaws.com/123456789/test-queue'
+            );
+
+            // Verify response
+            expect(result).toEqual({
+                success: true,
+                processId: 'process-123',
+                state: 'INITIALIZING',
+                statusUrl: '/db-migrate/process-123',
+                message: 'Database migration queued successfully',
+            });
+        });
+
+        it('should handle MongoDB dbType', async () => {
+            await useCase.execute({
+                userId: 'user-456',
+                dbType: 'mongodb',
+                stage: 'dev',
+            });
+
+            expect(mockProcessRepository.create).toHaveBeenCalledWith(
+                expect.objectContaining({
+                    context: expect.objectContaining({
+                        dbType: 'mongodb',
+                        stage: 'dev',
+                    }),
+                })
+            );
+        });
+
+        it('should throw ValidationError if userId is missing', async () => {
+            await expect(
+                useCase.execute({
+                    dbType: 'postgresql',
+                    stage: 'production',
+                })
+            ).rejects.toThrow(ValidationError);
+
+            await expect(
+                useCase.execute({
+                    dbType: 'postgresql',
+                    stage: 'production',
+                })
+            ).rejects.toThrow('userId is required');
+        });
+
+        it('should throw ValidationError if userId is not a string', async () => {
+            await expect(
+                useCase.execute({
+                    userId: 123,
+                    dbType: 'postgresql',
+                    stage: 'production',
+                })
+            ).rejects.toThrow('userId must be a string');
+        });
+
+        it('should throw ValidationError if dbType is missing', async () => {
+            await expect(
+                useCase.execute({
+                    userId: 'user-456',
+                    stage: 'production',
+                })
+            ).rejects.toThrow('dbType is required');
+        });
+
+        it('should throw ValidationError if dbType is invalid', async () => {
+            await expect(
+                useCase.execute({
+                    userId: 'user-456',
+                    dbType: 'mysql',
+                    stage: 'production',
+                })
+            ).rejects.toThrow('Invalid dbType: "mysql"');
+        });
+
+        it('should throw ValidationError if stage is missing', async () => {
+            await expect(
+                useCase.execute({
+                    userId: 'user-456',
+                    dbType: 'postgresql',
+                })
+            ).rejects.toThrow('stage is required');
+        });
+
+        it('should throw ValidationError if stage is not a string', async () => {
+            await expect(
+                useCase.execute({
+                    userId: 'user-456',
+                    dbType: 'postgresql',
+                    stage: 123,
+                })
+            ).rejects.toThrow('stage must be a string');
+        });
+
+        it('should throw error if DB_MIGRATION_QUEUE_URL not set', async () => {
+            delete process.env.DB_MIGRATION_QUEUE_URL;
+
+            await expect(
+                useCase.execute({
+                    userId: 'user-456',
+                    dbType: 'postgresql',
+                    stage: 'production',
+                })
+            ).rejects.toThrow('DB_MIGRATION_QUEUE_URL environment variable is not set');
+        });
+
+        it('should update process to FAILED if queue send fails', async () => {
+            mockQueuerUtil.send.mockRejectedValue(new Error('SQS unavailable'));
+
+            await expect(
+                useCase.execute({
+                    userId: 'user-456',
+                    dbType: 'postgresql',
+                    stage: 'production',
+                })
+            ).rejects.toThrow('Failed to queue migration: SQS unavailable');
+
+            // Verify process was marked as failed
+            expect(mockProcessRepository.updateState).toHaveBeenCalledWith(
+                'process-123',
+                'FAILED',
+                {
+                    error: 'Failed to queue migration job',
+                    errorDetails: 'SQS unavailable',
+                }
+            );
+        });
+
+        it('should handle process creation failure', async () => {
+            mockProcessRepository.create.mockRejectedValue(new Error('Database error'));
+
+            await expect(
+                useCase.execute({
+                    userId: 'user-456',
+                    dbType: 'postgresql',
+                    stage: 'production',
+                })
+            ).rejects.toThrow('Database error');
+
+            // Should not attempt to send to queue if process creation fails
+            expect(mockQueuerUtil.send).not.toHaveBeenCalled();
+        });
+    });
+
+    describe('ValidationError', () => {
+        it('should have correct name', () => {
+            const error = new ValidationError('test message');
+            expect(error.name).toBe('ValidationError');
+            expect(error.message).toBe('test message');
+            expect(error instanceof Error).toBe(true);
+        });
+    });
+});
+

package/handlers/routers/db-migration.handler.js

@@ -0,0 +1,20 @@
+/**
+ * Database Migration Router Lambda Handler
+ *
+ * Wraps the Express router with Lambda infrastructure:
+ * - Express app with middleware (CORS, body-parser, error handling)
+ * - serverless-http for Lambda compatibility
+ * - createHandler for DB pooling + secrets management
+ *
+ * This matches the pattern used by health.handler.js and user.handler.js
+ */
+
+const { createAppHandler } = require('../app-handler-helpers');
+const dbMigrationRouter = require('./db-migration');
+
+module.exports.handler = createAppHandler(
+    'db-migration-router',
+    dbMigrationRouter,
+    true // shouldUseDatabase - need DB for Process repository
+);
+

package/handlers/routers/db-migration.js

@@ -0,0 +1,175 @@
+/**
+ * Database Migration Router
+ *
+ * HTTP API for triggering and monitoring database migrations.
+ *
+ * Endpoints:
+ * - POST /db-migrate - Trigger async migration (queues job)
+ * - GET /db-migrate/:processId - Check migration status
+ *
+ * Security:
+ * - Requires ADMIN_API_KEY header for all requests
+ *
+ * Architecture:
+ * - Router (Adapter Layer) → Use Cases (Domain) → Repositories (Infrastructure)
+ * - Follows DDD/Hexagonal architecture
+ */
+
+const { Router } = require('express');
+const catchAsyncError = require('express-async-handler');
+const { createProcessRepository } = require('../../integrations/repositories/process-repository-factory');
+const {
+    TriggerDatabaseMigrationUseCase,
+    ValidationError: TriggerValidationError,
+} = require('../../database/use-cases/trigger-database-migration-use-case');
+const {
+    GetMigrationStatusUseCase,
+    ValidationError: GetValidationError,
+    NotFoundError,
+} = require('../../database/use-cases/get-migration-status-use-case');
+
+const router = Router();
+
+// Dependency injection (like health.js:34-70)
+const processRepository = createProcessRepository();
+const triggerMigrationUseCase = new TriggerDatabaseMigrationUseCase({
+    processRepository,
+    // Note: QueuerUtil is used directly in the use case (static utility)
+});
+const getStatusUseCase = new GetMigrationStatusUseCase({ processRepository });
+
+/**
+ * Admin API key validation middleware
+ * Matches pattern from health.js:72-88
+ */
+const validateApiKey = (req, res, next) => {
+    const apiKey = req.headers['x-api-key'];
+
+    if (!apiKey || apiKey !== process.env.ADMIN_API_KEY) {
+        console.error('Unauthorized access attempt to db-migrate endpoint');
+        return res.status(401).json({
+            status: 'error',
+            message: 'Unauthorized',
+        });
+    }
+
+    next();
+};
+
+// Apply API key validation to all routes
+router.use(validateApiKey);
+
+/**
+ * POST /db-migrate
+ *
+ * Trigger database migration (async via SQS queue)
+ *
+ * Request body:
+ * {
+ *   userId: string (optional, defaults to 'admin'),
+ *   dbType: 'postgresql' | 'mongodb',
+ *   stage: string (e.g., 'production', 'dev')
+ * }
+ *
+ * Response (202 Accepted):
+ * {
+ *   success: true,
+ *   processId: string,
+ *   state: 'INITIALIZING',
+ *   statusUrl: string,
+ *   message: string
+ * }
+ */
+router.post(
+    '/db-migrate',
+    catchAsyncError(async (req, res) => {
+        const { dbType, stage } = req.body;
+        // TODO: Extract userId from JWT token when auth is implemented
+        const userId = req.body.userId || 'admin';
+
+        console.log(`Migration trigger request: dbType=${dbType}, stage=${stage}, userId=${userId}`);
+
+        try {
+            const result = await triggerMigrationUseCase.execute({
+                userId,
+                dbType,
+                stage,
+            });
+
+            // 202 Accepted - request accepted but not completed
+            res.status(202).json(result);
+        } catch (error) {
+            // Handle validation errors (400 Bad Request)
+            if (error instanceof TriggerValidationError) {
+                return res.status(400).json({
+                    success: false,
+                    error: error.message,
+                });
+            }
+
+            // Re-throw other errors for global error handler
+            throw error;
+        }
+    })
+);
+
+/**
+ * GET /db-migrate/:processId
+ *
+ * Get migration status by process ID
+ *
+ * Response (200 OK):
+ * {
+ *   processId: string,
+ *   type: 'DATABASE_MIGRATION',
+ *   state: 'INITIALIZING' | 'RUNNING' | 'COMPLETED' | 'FAILED',
+ *   context: {
+ *     dbType: string,
+ *     stage: string,
+ *     migrationCommand: string (if started)
+ *   },
+ *   results: {
+ *     success: boolean (if completed),
+ *     duration: string (if completed),
+ *     error: string (if failed)
+ *   },
+ *   createdAt: string,
+ *   updatedAt: string
+ * }
+ */
+router.get(
+    '/db-migrate/:processId',
+    catchAsyncError(async (req, res) => {
+        const { processId } = req.params;
+
+        console.log(`Migration status request: processId=${processId}`);
+
+        try {
+            const status = await getStatusUseCase.execute({ processId });
+
+            res.status(200).json(status);
+        } catch (error) {
+            // Handle not found errors (404 Not Found)
+            if (error instanceof NotFoundError) {
+                return res.status(404).json({
+                    success: false,
+                    error: error.message,
+                });
+            }
+
+            // Handle validation errors (400 Bad Request)
+            if (error instanceof GetValidationError) {
+                return res.status(400).json({
+                    success: false,
+                    error: error.message,
+                });
+            }
+
+            // Re-throw other errors for global error handler
+            throw error;
+        }
+    })
+);
+
+module.exports = router;
+

package/handlers/workers/db-migration.js

@@ -46,10 +46,20 @@ const {
     MigrationError,
     ValidationError,
 } = require('../../database/use-cases/run-database-migration-use-case');
+const {
+    UpdateProcessState,
+} = require('../../integrations/use-cases/update-process-state');
+const {
+    createProcessRepository,
+} = require('../../integrations/repositories/process-repository-factory');
 
 // Inject prisma-runner as dependency
 const prismaRunner = require('../../database/utils/prisma-runner');
 
+// Create process repository and use case for tracking migration progress
+const processRepository = createProcessRepository();
+const updateProcessState = new UpdateProcessState({ processRepository });
+
 /**
  * Sanitizes error messages to prevent credential leaks
  * @param {string} errorMessage - Error message that might contain credentials
@@ -85,9 +95,48 @@ function sanitizeDatabaseUrl(url) {
     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 { processId, dbType, stage }
+ */
+function extractMigrationParams(event) {
+    let processId = null;
+    let dbType = null;
+    let stage = null;
+
+    // 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);
+        processId = message.processId;
+        dbType = message.dbType;
+        stage = message.stage;
+
+        console.log('SQS event detected');
+        console.log(`  Process ID: ${processId}`);
+        console.log(`  DB Type: ${dbType}`);
+        console.log(`  Stage: ${stage}`);
+    } else {
+        // Direct invocation - use event properties or environment variables
+        processId = event.processId || null;
+        dbType = event.dbType || process.env.DB_TYPE || 'postgresql';
+        stage = event.stage || process.env.STAGE || 'production';
+
+        console.log('Direct invocation detected');
+        if (processId) {
+            console.log(`  Process ID: ${processId}`);
+        }
+        console.log(`  DB Type: ${dbType}`);
+        console.log(`  Stage: ${stage}`);
+    }
+
+    return { processId, dbType, stage };
+}
+
 /**
  * Lambda handler entry point
- * @param {Object} event - Lambda event (not used, migrations don't need input)
+ * @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
  */
@@ -102,10 +151,11 @@ exports.handler = async (event, context) => {
         remainingTimeInMillis: context.getRemainingTimeInMillis(),
     }, null, 2));
 
+    // Extract migration parameters from event
+    const { processId, dbType, stage } = extractMigrationParams(event);
+
     // Get environment variables
     const databaseUrl = process.env.DATABASE_URL;
-    const dbType = process.env.DB_TYPE || 'postgresql';
-    const stage = process.env.STAGE || 'production';
 
     try {
         // Validate DATABASE_URL is set
@@ -126,6 +176,14 @@ exports.handler = async (event, context) => {
         console.log(`  Stage: ${stage}`);
         console.log(`  Database URL: ${sanitizeDatabaseUrl(databaseUrl)}`);
 
+        // Update process state to RUNNING (if processId provided)
+        if (processId) {
+            console.log(`\n✓ Updating process state to RUNNING: ${processId}`);
+            await updateProcessState.execute(processId, 'RUNNING', {
+                startedAt: new Date().toISOString(),
+            });
+        }
+
         // Create use case with dependencies (Dependency Injection)
         const runDatabaseMigrationUseCase = new RunDatabaseMigrationUseCase({
             prismaRunner,
@@ -152,17 +210,32 @@ exports.handler = async (event, context) => {
         console.log(`  Command: ${result.command}`);
         console.log('========================================');
 
+        // Update process state to COMPLETED (if processId provided)
+        if (processId) {
+            console.log(`\n✓ Updating process state to COMPLETED: ${processId}`);
+            await updateProcessState.execute(processId, 'COMPLETED', {
+                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 (processId) {
+            responseBody.processId = processId;
+        }
+
         return {
             statusCode: 200,
-            body: JSON.stringify({
-                success: true,
-                message: result.message,
-                dbType: result.dbType,
-                stage: result.stage,
-                migrationCommand: result.command,
-                timestamp: new Date().toISOString(),
-            }),
+            body: JSON.stringify(responseBody),
         };
 
     } catch (error) {
@@ -194,15 +267,36 @@ exports.handler = async (event, context) => {
         // Sanitize error message before returning
         const sanitizedError = sanitizeError(errorMessage);
 
+        // Update process state to FAILED (if processId provided)
+        if (processId) {
+            try {
+                console.log(`\n✓ Updating process state to FAILED: ${processId}`);
+                await updateProcessState.execute(processId, 'FAILED', {
+                    failedAt: new Date().toISOString(),
+                    error: sanitizedError,
+                    errorType: error.name || 'Error',
+                });
+            } catch (updateError) {
+                console.error('Failed to update process state:', updateError);
+                // Don't fail the entire handler if state update fails
+            }
+        }
+
+        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 (processId) {
+            errorBody.processId = processId;
+        }
+
         return {
             statusCode,
-            body: JSON.stringify({
-                success: false,
-                error: sanitizedError,
-                errorType: error.name || 'Error',
-                // Only include stack traces in development environments
-                ...(stage === 'dev' || stage === 'local' || stage === 'test' ? { stack: error.stack } : {}),
-            }),
+            body: JSON.stringify(errorBody),
         };
     }
 };

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0--canary.461.e58db0a.0",
+    "version": "2.0.0--canary.461.4f3c330.0",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -37,9 +37,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0--canary.461.e58db0a.0",
-        "@friggframework/prettier-config": "2.0.0--canary.461.e58db0a.0",
-        "@friggframework/test": "2.0.0--canary.461.e58db0a.0",
+        "@friggframework/eslint-config": "2.0.0--canary.461.4f3c330.0",
+        "@friggframework/prettier-config": "2.0.0--canary.461.4f3c330.0",
+        "@friggframework/test": "2.0.0--canary.461.4f3c330.0",
         "@prisma/client": "^6.17.0",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -79,5 +79,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "e58db0af84dd0c8fe3abdbbc472e433815c0f96d"
+    "gitHead": "4f3c33010ab48c11f66a630ea72f75afc2e21762"
 }