@friggframework/core 2.0.0-next.45 → 2.0.0-next.47

package/database/models/WebsocketConnection.js

@@ -1,5 +1,8 @@
 const { mongoose } = require('../mongoose');
-const AWS = require('aws-sdk');
+const {
+    ApiGatewayManagementApiClient,
+    PostToConnectionCommand,
+} = require('@aws-sdk/client-apigatewaymanagementapi');
 
 const schema = new mongoose.Schema({
     connectionId: { type: mongoose.Schema.Types.String },
@@ -17,20 +20,18 @@ schema.statics.getActiveConnections = async function () {
         return connections.map((conn) => ({
             connectionId: conn.connectionId,
             send: async (data) => {
-                const apigwManagementApi = new AWS.ApiGatewayManagementApi({
-                    apiVersion: '2018-11-29',
+                const apigwManagementApi = new ApiGatewayManagementApiClient({
                     endpoint: process.env.WEBSOCKET_API_ENDPOINT,
                 });
 
                 try {
-                    await apigwManagementApi
-                        .postToConnection({
-                            ConnectionId: conn.connectionId,
-                            Data: JSON.stringify(data),
-                        })
-                        .promise();
+                    const command = new PostToConnectionCommand({
+                        ConnectionId: conn.connectionId,
+                        Data: JSON.stringify(data),
+                    });
+                    await apigwManagementApi.send(command);
                 } catch (error) {
-                    if (error.statusCode === 410) {
+                    if (error.statusCode === 410 || error.$metadata?.httpStatusCode === 410) {
                         console.log(`Stale connection ${conn.connectionId}`);
                         await this.deleteOne({
                             connectionId: conn.connectionId,

package/database/prisma.js

@@ -6,6 +6,32 @@ const { logger } = require('./encryption/logger');
 const { Cryptor } = require('../encrypt/Cryptor');
 const config = require('./config');
 
+/**
+ * Ensures DATABASE_URL is set for MongoDB connections
+ * Falls back to MONGO_URI if DATABASE_URL is not set
+ * Infrastructure layer concern - maps legacy MONGO_URI to Prisma's expected DATABASE_URL
+ * 
+ * Note: This should only be called when DB_TYPE is 'mongodb'
+ */
+function ensureMongoDbUrl() {
+    // If DATABASE_URL is already set, use it
+    if (process.env.DATABASE_URL && process.env.DATABASE_URL.trim()) {
+        return;
+    }
+
+    // Fallback to MONGO_URI for backwards compatibility with DocumentDB deployments
+    if (process.env.MONGO_URI && process.env.MONGO_URI.trim()) {
+        process.env.DATABASE_URL = process.env.MONGO_URI;
+        logger.debug('Using MONGO_URI as DATABASE_URL for MongoDB connection');
+        return;
+    }
+
+    // Neither is set - error
+    throw new Error(
+        'DATABASE_URL or MONGO_URI environment variable must be set for MongoDB'
+    );
+}
+
 function getEncryptionConfig() {
     const STAGE = process.env.STAGE || process.env.NODE_ENV || 'development';
     const shouldBypassEncryption = ['dev', 'test', 'local'].includes(STAGE);
@@ -22,7 +48,7 @@ function getEncryptionConfig() {
     if (!hasKMS && !hasAES) {
         logger.warn(
             'No encryption keys configured (KMS_KEY_ARN or AES_KEY_ID). ' +
-                'Field-level encryption disabled. Set STAGE=production and configure keys to enable.'
+            'Field-level encryption disabled. Set STAGE=production and configure keys to enable.'
         );
         return { enabled: false };
     }
@@ -76,10 +102,34 @@ function loadCustomEncryptionSchema() {
 const prismaClientSingleton = () => {
     let PrismaClient;
 
+    // Helper to try loading Prisma client from multiple locations
+    const loadPrismaClient = (dbType) => {
+        const paths = [
+            // Lambda layer location (when using Prisma Lambda layer)
+            `/opt/nodejs/node_modules/generated/prisma-${dbType}`,
+            // Local development location (relative to core package)
+            `../generated/prisma-${dbType}`,
+        ];
+
+        for (const path of paths) {
+            try {
+                return require(path).PrismaClient;
+            } catch (err) {
+                // Continue to next path
+            }
+        }
+
+        throw new Error(
+            `Cannot find Prisma client for ${dbType}. Tried paths: ${paths.join(', ')}`
+        );
+    };
+
     if (config.DB_TYPE === 'mongodb') {
-        PrismaClient = require('@prisma-mongodb/client').PrismaClient;
+        // Ensure DATABASE_URL is set (fallback to MONGO_URI if needed)
+        ensureMongoDbUrl();
+        PrismaClient = loadPrismaClient('mongodb');
     } else if (config.DB_TYPE === 'postgresql') {
-        PrismaClient = require('@prisma-postgresql/client').PrismaClient;
+        PrismaClient = loadPrismaClient('postgresql');
     } else {
         throw new Error(
             `Unsupported database type: ${config.DB_TYPE}. Supported values: 'mongodb', 'postgresql'`
@@ -151,6 +201,15 @@ async function disconnectPrisma() {
 
 async function connectPrisma() {
     await getPrismaClient().$connect();
+
+    // Initialize MongoDB schema - ensure all collections exist
+    // Only run for MongoDB/DocumentDB (not PostgreSQL)
+    // This prevents "Cannot create namespace in multi-document transaction" errors
+    if (config.DB_TYPE === 'mongodb') {
+        const { initializeMongoDBSchema } = require('./utils/mongodb-schema-init');
+        await initializeMongoDBSchema();
+    }
+
     return getPrismaClient();
 }
 
@@ -159,4 +218,5 @@ module.exports = {
     connectPrisma,
     disconnectPrisma,
     getEncryptionConfig,
+    ensureMongoDbUrl, // Exported for testing
 };

package/database/repositories/health-check-repository-mongodb.js

@@ -38,6 +38,9 @@ class HealthCheckRepositoryMongoDB extends HealthCheckRepositoryInterface {
     }
 
     async createCredential(credentialData) {
+        // Note: Collection existence is ensured at application startup via
+        // initializeMongoDBSchema() in database/utils/mongodb-schema-init.js
+        // This prevents "Cannot create namespace in multi-document transaction" errors
         return await prisma.credential.create({
             data: credentialData,
         });

package/database/repositories/migration-status-repository-s3.js

@@ -0,0 +1,137 @@
+/**
+ * Migration Status Repository - S3 Storage
+ * 
+ * Infrastructure Layer - Hexagonal Architecture
+ * 
+ * Stores migration status in S3 to avoid chicken-and-egg dependency on User/Process tables.
+ * Initial database migrations can't use Process table (requires User FK which doesn't exist yet).
+ */
+
+const { S3Client, PutObjectCommand, GetObjectCommand } = require('@aws-sdk/client-s3');
+const { randomUUID } = require('crypto');
+
+class MigrationStatusRepositoryS3 {
+    /**
+     * @param {string} bucketName - S3 bucket name for migration status storage
+     * @param {S3Client} s3Client - Optional S3 client (for testing)
+     */
+    constructor(bucketName, s3Client = null) {
+        this.bucketName = bucketName;
+        this.s3Client = s3Client || new S3Client({ region: process.env.AWS_REGION || 'us-east-1' });
+    }
+
+    /**
+     * Build S3 key for migration status
+     * @param {string} migrationId - Migration identifier
+     * @param {string} stage - Deployment stage
+     * @returns {string} S3 key
+     */
+    _buildS3Key(migrationId, stage) {
+        return `migrations/${stage}/${migrationId}.json`;
+    }
+
+    /**
+     * Create new migration status record
+     * @param {Object} data - Migration data
+     * @param {string} [data.migrationId] - Migration ID (generates UUID if not provided)
+     * @param {string} data.stage - Deployment stage
+     * @param {string} [data.triggeredBy] - User or system that triggered migration
+     * @param {string} [data.triggeredAt] - ISO timestamp
+     * @returns {Promise<Object>} Created migration status
+     */
+    async create(data) {
+        const migrationId = data.migrationId || randomUUID();
+        const timestamp = data.triggeredAt || new Date().toISOString();
+
+        const status = {
+            migrationId,
+            stage: data.stage,
+            state: 'INITIALIZING',
+            progress: 0,
+            triggeredBy: data.triggeredBy || 'system',
+            triggeredAt: timestamp,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+        };
+
+        const key = this._buildS3Key(migrationId, data.stage);
+
+        await this.s3Client.send(
+            new PutObjectCommand({
+                Bucket: this.bucketName,
+                Key: key,
+                Body: JSON.stringify(status, null, 2),
+                ContentType: 'application/json',
+            })
+        );
+
+        return status;
+    }
+
+    /**
+     * Update existing migration status
+     * @param {Object} data - Update data
+     * @param {string} data.migrationId - Migration ID
+     * @param {string} data.stage - Deployment stage
+     * @param {string} [data.state] - New state
+     * @param {number} [data.progress] - Progress percentage (0-100)
+     * @param {string} [data.error] - Error message if failed
+     * @param {string} [data.completedAt] - Completion timestamp
+     * @returns {Promise<Object>} Updated migration status
+     */
+    async update(data) {
+        const key = this._buildS3Key(data.migrationId, data.stage);
+
+        // Get existing status
+        const existing = await this.get(data.migrationId, data.stage);
+
+        // Merge updates
+        const updated = {
+            ...existing,
+            ...data,
+            updatedAt: new Date().toISOString(),
+        };
+
+        await this.s3Client.send(
+            new PutObjectCommand({
+                Bucket: this.bucketName,
+                Key: key,
+                Body: JSON.stringify(updated, null, 2),
+                ContentType: 'application/json',
+            })
+        );
+
+        return updated;
+    }
+
+    /**
+     * Get migration status by ID
+     * @param {string} migrationId - Migration ID
+     * @param {string} stage - Deployment stage
+     * @returns {Promise<Object>} Migration status
+     * @throws {Error} If migration not found
+     */
+    async get(migrationId, stage) {
+        const key = this._buildS3Key(migrationId, stage);
+
+        try {
+            const response = await this.s3Client.send(
+                new GetObjectCommand({
+                    Bucket: this.bucketName,
+                    Key: key,
+                })
+            );
+
+            const body = await response.Body.transformToString();
+            return JSON.parse(body);
+        } catch (error) {
+            if (error.name === 'NoSuchKey') {
+                throw new Error(`Migration not found: ${migrationId}`);
+            }
+            throw error;
+        }
+    }
+}
+
+module.exports = { MigrationStatusRepositoryS3 };
+

package/database/use-cases/check-database-state-use-case.js

@@ -0,0 +1,81 @@
+/**
+ * Check Database State Use Case
+ * 
+ * Domain logic for checking database state (pending migrations, errors, etc).
+ * Does NOT trigger migrations, just reports current state.
+ * 
+ * Architecture: Hexagonal/Clean
+ * - Use Case (Domain Layer)
+ * - Depends on prismaRunner (Infrastructure abstraction)
+ * - Called by Router or other Use Cases (Adapter Layer)
+ */
+
+class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+
+class CheckDatabaseStateUseCase {
+    /**
+     * @param {Object} dependencies
+     * @param {Object} dependencies.prismaRunner - Prisma runner utility
+     */
+    constructor({ prismaRunner }) {
+        if (!prismaRunner) {
+            throw new Error('prismaRunner dependency is required');
+        }
+        this.prismaRunner = prismaRunner;
+    }
+
+    /**
+     * Execute check migration status
+     * 
+     * @param {string} dbType - Database type (postgresql or mongodb)
+     * @param {string} stage - Deployment stage (default: 'production')
+     * @returns {Promise<Object>} Migration status
+     */
+    async execute(dbType, stage = 'production') {
+        // Validate inputs
+        if (!dbType) {
+            throw new ValidationError('dbType is required');
+        }
+
+        if (!['postgresql', 'mongodb'].includes(dbType)) {
+            throw new ValidationError('dbType must be postgresql or mongodb');
+        }
+
+        console.log(`Checking migration status for ${dbType} in ${stage}`);
+
+        // Check database state using Prisma
+        const state = await this.prismaRunner.checkDatabaseState(dbType);
+
+        // Build response
+        const response = {
+            upToDate: state.upToDate,
+            pendingMigrations: state.pendingMigrations || 0,
+            dbType,
+            stage,
+        };
+
+        // Add error if present
+        if (state.error) {
+            response.error = state.error;
+            response.recommendation = 'Run POST /db-migrate to initialize database';
+        }
+
+        // Add recommendation if migrations pending
+        if (!state.upToDate && state.pendingMigrations > 0) {
+            response.recommendation = `Run POST /db-migrate to apply ${state.pendingMigrations} pending migration(s)`;
+        }
+
+        return response;
+    }
+}
+
+module.exports = {
+    CheckDatabaseStateUseCase,
+    ValidationError,
+};
+

package/database/use-cases/check-encryption-health-use-case.js

@@ -66,8 +66,9 @@ class CheckEncryptionHealthUseCase {
 
         const isBypassed = bypassStages.includes(STAGE);
         const hasAES = AES_KEY_ID && AES_KEY_ID.trim() !== '';
-        const hasKMS = KMS_KEY_ARN && KMS_KEY_ARN.trim() !== '' && !hasAES;
-        const mode = hasAES ? 'aes' : hasKMS ? 'kms' : 'none';
+        const hasKMS = KMS_KEY_ARN && KMS_KEY_ARN.trim() !== '';
+        // Prefer KMS over AES when both are configured (KMS is more secure)
+        const mode = hasKMS ? 'kms' : hasAES ? 'aes' : 'none';
 
         return {
             stage: STAGE || null,

package/database/use-cases/get-database-state-via-worker-use-case.js

@@ -0,0 +1,61 @@
+/**
+ * Get Database State Via Worker Use Case
+ * 
+ * Domain logic for getting database state by invoking the worker Lambda.
+ * This use case delegates to the worker Lambda which has Prisma CLI installed,
+ * keeping the router Lambda lightweight.
+ * 
+ * Architecture: Hexagonal/Clean
+ * - Use Case (Domain Layer)
+ * - Depends on LambdaInvoker (Infrastructure abstraction)
+ * - Called by Router (Adapter Layer)
+ */
+
+/**
+ * Domain Use Case: Get database state by invoking worker Lambda
+ * 
+ * This use case delegates database state checking to the worker Lambda,
+ * which has Prisma CLI installed. Keeps the router Lambda lightweight.
+ */
+class GetDatabaseStateViaWorkerUseCase {
+    /**
+     * @param {Object} dependencies
+     * @param {LambdaInvoker} dependencies.lambdaInvoker - Lambda invocation adapter
+     * @param {string} dependencies.workerFunctionName - Worker Lambda function name
+     */
+    constructor({ lambdaInvoker, workerFunctionName }) {
+        if (!lambdaInvoker) {
+            throw new Error('lambdaInvoker dependency is required');
+        }
+        if (!workerFunctionName) {
+            throw new Error('workerFunctionName is required');
+        }
+        this.lambdaInvoker = lambdaInvoker;
+        this.workerFunctionName = workerFunctionName;
+    }
+
+    /**
+     * Execute database state check via worker Lambda
+     * 
+     * @param {string} stage - Deployment stage (prod, dev, etc)
+     * @returns {Promise<Object>} Database state result
+     */
+    async execute(stage = 'production') {
+        const dbType = process.env.DB_TYPE || 'postgresql';
+
+        console.log(`Invoking worker Lambda to check database state: ${this.workerFunctionName}`);
+
+        // Invoke worker Lambda with checkStatus action
+        const result = await this.lambdaInvoker.invoke(this.workerFunctionName, {
+            action: 'checkStatus',
+            dbType,
+            stage,
+        });
+
+        return result;
+    }
+}
+
+module.exports = { GetDatabaseStateViaWorkerUseCase };
+
+

package/database/use-cases/get-migration-status-use-case.js

@@ -0,0 +1,93 @@
+/**
+ * Get Migration Status Use Case
+ *
+ * Retrieves the status of a database migration by process ID.
+ * Formats the Process record for migration-specific response.
+ *
+ * This use case follows the Frigg hexagonal architecture pattern where:
+ * - Routers (adapters) call use cases
+ * - Use cases contain business logic and formatting
+ * - Use cases call repositories for data access
+ */
+
+class GetMigrationStatusUseCase {
+    /**
+     * @param {Object} dependencies
+     * @param {Object} dependencies.migrationStatusRepository - Repository for migration status (S3)
+     */
+    constructor({ migrationStatusRepository }) {
+        if (!migrationStatusRepository) {
+            throw new Error('migrationStatusRepository dependency is required');
+        }
+        this.migrationStatusRepository = migrationStatusRepository;
+    }
+
+    /**
+     * Execute get migration status
+     *
+     * @param {string} migrationId - Migration ID to retrieve
+     * @param {string} [stage] - Deployment stage (defaults to env.STAGE)
+     * @returns {Promise<Object>} Migration status from S3
+     * @throws {NotFoundError} If migration not found
+     * @throws {ValidationError} If migrationId is invalid
+     */
+    async execute(migrationId, stage = null) {
+        // Validation
+        this._validateParams(migrationId);
+
+        const effectiveStage = stage || process.env.STAGE || 'production';
+
+        // Get migration status from S3
+        try {
+            const migrationStatus = await this.migrationStatusRepository.get(migrationId, effectiveStage);
+            return migrationStatus;
+        } catch (error) {
+            if (error.message.includes('not found')) {
+                throw new NotFoundError(`Migration not found: ${migrationId}`);
+            }
+            throw error;
+        }
+    }
+
+    /**
+     * Validate parameters
+     * @private
+     */
+    _validateParams(migrationId) {
+        if (!migrationId) {
+            throw new ValidationError('migrationId is required');
+        }
+
+        if (typeof migrationId !== 'string') {
+            throw new ValidationError('migrationId must be a string');
+        }
+    }
+}
+
+/**
+ * Custom error for validation failures
+ */
+class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+
+/**
+ * Custom error for not found resources
+ */
+class NotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'NotFoundError';
+        this.statusCode = 404;
+    }
+}
+
+module.exports = {
+    GetMigrationStatusUseCase,
+    ValidationError,
+    NotFoundError,
+};
+

package/database/use-cases/run-database-migration-use-case.js

@@ -0,0 +1,137 @@
+/**
+ * Run Database Migration Use Case
+ *
+ * Business logic for running Prisma database migrations.
+ * Orchestrates Prisma client generation and migration execution.
+ *
+ * This use case follows the Frigg hexagonal architecture pattern where:
+ * - Handlers (adapters) call use cases
+ * - Use cases contain business logic and orchestration
+ * - Use cases call repositories/utilities for data access
+ */
+
+class RunDatabaseMigrationUseCase {
+    /**
+     * @param {Object} dependencies
+     * @param {Object} dependencies.prismaRunner - Prisma runner utilities
+     */
+    constructor({ prismaRunner }) {
+        if (!prismaRunner) {
+            throw new Error('prismaRunner dependency is required');
+        }
+        this.prismaRunner = prismaRunner;
+    }
+
+    /**
+     * Execute database migration
+     *
+     * @param {Object} params
+     * @param {string} params.dbType - Database type ('postgresql' or 'mongodb')
+     * @param {string} params.stage - Deployment stage (determines migration command)
+     * @param {boolean} [params.verbose=false] - Enable verbose output
+     * @returns {Promise<Object>} Migration result { success, dbType, stage, command, message }
+     * @throws {MigrationError} If migration fails
+     * @throws {ValidationError} If parameters are invalid
+     */
+    async execute({ dbType, stage, verbose = false }) {
+        // Validation
+        this._validateParams({ dbType, stage });
+
+        // Step 1: Generate Prisma client
+        const generateResult = await this.prismaRunner.runPrismaGenerate(dbType, verbose);
+
+        if (!generateResult.success) {
+            throw new MigrationError(
+                `Failed to generate Prisma client: ${generateResult.error || 'Unknown error'}`,
+                { dbType, stage, step: 'generate', output: generateResult.output }
+            );
+        }
+
+        // Step 2: Run migrations based on database type
+        let migrationResult;
+        let migrationCommand;
+
+        if (dbType === 'postgresql') {
+            migrationCommand = this.prismaRunner.getMigrationCommand(stage);
+            migrationResult = await this.prismaRunner.runPrismaMigrate(migrationCommand, verbose);
+
+            if (!migrationResult.success) {
+                throw new MigrationError(
+                    `PostgreSQL migration failed: ${migrationResult.error || 'Unknown error'}`,
+                    { dbType, stage, command: migrationCommand, step: 'migrate', output: migrationResult.output }
+                );
+            }
+        } else if (dbType === 'mongodb') {
+            migrationCommand = 'db push';
+            // Use non-interactive mode for automated/Lambda environments
+            migrationResult = await this.prismaRunner.runPrismaDbPush(verbose, true);
+
+            if (!migrationResult.success) {
+                throw new MigrationError(
+                    `MongoDB push failed: ${migrationResult.error || 'Unknown error'}`,
+                    { dbType, stage, command: migrationCommand, step: 'push', output: migrationResult.output }
+                );
+            }
+        } else {
+            throw new ValidationError(`Unsupported database type: ${dbType}. Must be 'postgresql' or 'mongodb'.`);
+        }
+
+        // Return success result
+        return {
+            success: true,
+            dbType,
+            stage,
+            command: migrationCommand,
+            message: 'Database migration completed successfully',
+        };
+    }
+
+    /**
+     * Validate execution parameters
+     * @private
+     */
+    _validateParams({ dbType, stage }) {
+        if (!dbType) {
+            throw new ValidationError('dbType is required');
+        }
+
+        if (typeof dbType !== 'string') {
+            throw new ValidationError('dbType must be a string');
+        }
+
+        if (!stage) {
+            throw new ValidationError('stage is required');
+        }
+
+        if (typeof stage !== 'string') {
+            throw new ValidationError('stage must be a string');
+        }
+    }
+}
+
+/**
+ * Custom error for migration failures
+ */
+class MigrationError extends Error {
+    constructor(message, context = {}) {
+        super(message);
+        this.name = 'MigrationError';
+        this.context = context;
+    }
+}
+
+/**
+ * Custom error for validation failures
+ */
+class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+
+module.exports = {
+    RunDatabaseMigrationUseCase,
+    MigrationError,
+    ValidationError,
+};