@friggframework/core 2.0.0-next.5 → 2.0.0-next.51

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

@@ -0,0 +1,108 @@
+const { prisma } = require('../prisma');
+const { mongoose } = require('../mongoose');
+const {
+    HealthCheckRepositoryInterface,
+} = require('./health-check-repository-interface');
+
+/**
+ * Repository for Health Check database operations.
+ * Provides atomic database operations for health testing.
+ *
+ * Follows DDD/Hexagonal Architecture:
+ * - Infrastructure Layer (this repository)
+ * - Pure database operations only, no business logic
+ * - Used by Application Layer (Use Cases)
+ *
+ * Works identically for both MongoDB and PostgreSQL:
+ * - Uses Prisma for database operations
+ * - Encryption happens transparently via Prisma extension
+ * - Both MongoDB and PostgreSQL use same Prisma API
+ *
+ * Migration from Mongoose to Prisma:
+ * - Replaced Mongoose models with Prisma client
+ * - Uses Credential model for encryption testing
+ * - Maintains same method signatures for compatibility
+ */
+class HealthCheckRepository extends HealthCheckRepositoryInterface {
+    constructor() {
+        super();
+    }
+
+    /**
+     * Get database connection state
+     * @returns {Object} Object with readyState, stateName, and isConnected
+     */
+    getDatabaseConnectionState() {
+        const stateMap = {
+            0: 'disconnected',
+            1: 'connected',
+            2: 'connecting',
+            3: 'disconnecting',
+        };
+        const readyState = mongoose.connection.readyState;
+
+        return {
+            readyState,
+            stateName: stateMap[readyState],
+            isConnected: readyState === 1,
+        };
+    }
+
+    /**
+     * Ping the database to verify connectivity
+     * @param {number} maxTimeMS - Maximum time to wait for ping response
+     * @returns {Promise<number>} Response time in milliseconds
+     * @throws {Error} If database is not connected or ping fails
+     */
+    async pingDatabase(maxTimeMS = 2000) {
+        const pingStart = Date.now();
+        await mongoose.connection.db.admin().ping({ maxTimeMS });
+        return Date.now() - pingStart;
+    }
+
+    /**
+     * Create a test credential for encryption testing
+     * @param {Object} credentialData - Credential data to create
+     * @returns {Promise<Object>} Created credential
+     */
+    async createCredential(credentialData) {
+        return await prisma.credential.create({
+            data: credentialData,
+        });
+    }
+
+    /**
+     * Find a credential by ID
+     * @param {string} id - Credential ID
+     * @returns {Promise<Object|null>} Found credential or null
+     */
+    async findCredentialById(id) {
+        return await prisma.credential.findUnique({
+            where: { id },
+        });
+    }
+
+    /**
+     * Get raw credential from database bypassing Prisma encryption extension
+     * @param {string} id - Credential ID
+     * @returns {Promise<Object|null>} Raw credential from database
+     */
+    async getRawCredentialById(id) {
+        return await mongoose.connection.db
+            .collection('credentials')
+            .findOne({ _id: id });
+    }
+
+    /**
+     * Delete a credential by ID
+     * @param {string} id - Credential ID
+     * @returns {Promise<void>}
+     */
+    async deleteCredential(id) {
+        await prisma.credential.delete({
+            where: { id },
+        });
+    }
+}
+
+module.exports = { HealthCheckRepository };

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-health-use-case.js

@@ -0,0 +1,29 @@
+class CheckDatabaseHealthUseCase {
+    /**
+     * @param {Object} params
+     * @param {import('../repositories/health-check-repository-interface').HealthCheckRepositoryInterface} params.healthCheckRepository
+     */
+    constructor({ healthCheckRepository }) {
+        this.repository = healthCheckRepository;
+    }
+
+    /**
+     * @returns {Promise<{status: string, state: string, responseTime?: number}>}
+     */
+    async execute() {
+        const { stateName, isConnected } = await this.repository.getDatabaseConnectionState();
+
+        const result = {
+            status: isConnected ? 'healthy' : 'unhealthy',
+            state: stateName,
+        };
+
+        if (isConnected) {
+            result.responseTime = await this.repository.pingDatabase(2000);
+        }
+
+        return result;
+    }
+}
+
+module.exports = { CheckDatabaseHealthUseCase };

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

@@ -0,0 +1,83 @@
+class CheckEncryptionHealthUseCase {
+    constructor({ testEncryptionUseCase }) {
+        this.testEncryptionUseCase = testEncryptionUseCase;
+    }
+
+    async execute() {
+        const config = this._getEncryptionConfiguration();
+
+        if (config.isBypassed || config.mode === 'none') {
+            const testResult = config.isBypassed
+                ? 'Encryption bypassed for this stage'
+                : 'No encryption keys configured';
+
+            return {
+                status: 'disabled',
+                mode: config.mode,
+                bypassed: config.isBypassed,
+                stage: config.stage,
+                testResult,
+                encryptionWorks: false,
+                debug: {
+                    hasKMS: config.hasKMS,
+                    hasAES: config.hasAES,
+                },
+            };
+        }
+
+        try {
+            const testResults = await this.testEncryptionUseCase.execute();
+
+            return {
+                ...testResults,
+                mode: config.mode,
+                bypassed: config.isBypassed,
+                stage: config.stage,
+                debug: {
+                    hasKMS: config.hasKMS,
+                    hasAES: config.hasAES,
+                },
+            };
+        } catch (error) {
+            return {
+                status: 'unhealthy',
+                mode: config.mode,
+                bypassed: config.isBypassed,
+                stage: config.stage,
+                testResult: `Encryption test failed: ${error.message}`,
+                encryptionWorks: false,
+                debug: {
+                    hasKMS: config.hasKMS,
+                    hasAES: config.hasAES,
+                },
+            };
+        }
+    }
+
+    _getEncryptionConfiguration() {
+        const { STAGE, BYPASS_ENCRYPTION_STAGE, KMS_KEY_ARN, AES_KEY_ID } =
+            process.env;
+
+        const defaultBypassStages = ['dev', 'test', 'local'];
+        const useEnv = BYPASS_ENCRYPTION_STAGE !== undefined;
+        const bypassStages = useEnv
+            ? BYPASS_ENCRYPTION_STAGE.split(',').map((s) => s.trim())
+            : defaultBypassStages;
+
+        const isBypassed = bypassStages.includes(STAGE);
+        const hasAES = AES_KEY_ID && AES_KEY_ID.trim() !== '';
+        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,
+            isBypassed,
+            hasAES,
+            hasKMS,
+            mode,
+        };
+    }
+}
+
+module.exports = { CheckEncryptionHealthUseCase };

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,
+};
+