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

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

@@ -0,0 +1,157 @@
+/**
+ * Trigger Database Migration Use Case
+ *
+ * Business logic for triggering async database migrations via SQS queue.
+ * Creates a Process record for tracking and sends migration job to queue.
+ *
+ * This use case follows the Frigg hexagonal architecture pattern where:
+ * - Routers (adapters) call use cases
+ * - Use cases contain business logic and orchestration
+ * - Use cases call repositories for data access
+ * - Use cases delegate infrastructure concerns (SQS) to utilities
+ *
+ * Flow:
+ * 1. Validate migration parameters
+ * 2. Create Process record (state: INITIALIZING)
+ * 3. Send message to SQS queue (fire-and-forget)
+ * 4. Return process info immediately (async pattern)
+ */
+
+const { QueuerUtil } = require('../../queues/queuer-util');
+
+class TriggerDatabaseMigrationUseCase {
+    /**
+     * @param {Object} dependencies
+     * @param {Object} dependencies.migrationStatusRepository - Repository for migration status (S3)
+     * @param {Object} [dependencies.queuerUtil] - SQS utility (injectable for testing)
+     */
+    constructor({ migrationStatusRepository, queuerUtil = QueuerUtil }) {
+        if (!migrationStatusRepository) {
+            throw new Error('migrationStatusRepository dependency is required');
+        }
+        this.migrationStatusRepository = migrationStatusRepository;
+        this.queuerUtil = queuerUtil;
+    }
+
+    /**
+     * Execute database migration trigger
+     *
+     * @param {Object} params
+     * @param {string} params.userId - User ID triggering the migration
+     * @param {string} params.dbType - Database type ('postgresql' or 'mongodb')
+     * @param {string} params.stage - Deployment stage (determines migration command)
+     * @returns {Promise<Object>} Process info { success, processId, state, statusUrl, message }
+     * @throws {ValidationError} If parameters are invalid
+     * @throws {Error} If process creation or queue send fails
+     */
+    async execute({ userId, dbType, stage }) {
+        // Validation
+        this._validateParams({ userId, dbType, stage });
+
+        // Create migration status in S3 (no User table dependency)
+        const migrationStatus = await this.migrationStatusRepository.create({
+            stage: stage || process.env.STAGE || 'production',
+            triggeredBy: userId || 'system',
+            triggeredAt: new Date().toISOString(),
+        });
+
+        console.log(`Created migration status: ${migrationStatus.migrationId}`);
+
+        // Get queue URL from environment
+        const queueUrl = process.env.DB_MIGRATION_QUEUE_URL;
+        if (!queueUrl) {
+            throw new Error(
+                'DB_MIGRATION_QUEUE_URL environment variable is not set. ' +
+                'Cannot send migration to queue.'
+            );
+        }
+
+        // Send message to SQS queue (async fire-and-forget)
+        try {
+            await this.queuerUtil.send(
+                {
+                    migrationId: migrationStatus.migrationId,
+                    dbType,
+                    stage,
+                },
+                queueUrl
+            );
+
+            console.log(`Sent migration job to queue: ${migrationStatus.migrationId}`);
+        } catch (error) {
+            console.error(`Failed to send migration to queue:`, error);
+
+            // Update migration status to FAILED
+            await this.migrationStatusRepository.update({
+                migrationId: migrationStatus.migrationId,
+                stage: migrationStatus.stage,
+                state: 'FAILED',
+                error: `Failed to queue migration: ${error.message}`,
+            });
+
+            throw new Error(
+                `Failed to queue migration: ${error.message}`
+            );
+        }
+
+        // Return migration info immediately (don't wait for migration completion)
+        return {
+            success: true,
+            migrationId: migrationStatus.migrationId,
+            state: migrationStatus.state,
+            statusUrl: `/db-migrate/${migrationStatus.migrationId}`,
+            s3Key: `migrations/${migrationStatus.stage}/${migrationStatus.migrationId}.json`,
+            message: 'Database migration queued successfully',
+        };
+    }
+
+    /**
+     * Validate execution parameters
+     * @private
+     */
+    _validateParams({ userId, dbType, stage }) {
+        // userId is optional for system migrations
+        if (userId && typeof userId !== 'string') {
+            throw new ValidationError('userId must be a string');
+        }
+
+        if (!dbType) {
+            throw new ValidationError('dbType is required');
+        }
+
+        if (typeof dbType !== 'string') {
+            throw new ValidationError('dbType must be a string');
+        }
+
+        const validDbTypes = ['postgresql', 'mongodb'];
+        if (!validDbTypes.includes(dbType)) {
+            throw new ValidationError(
+                `Invalid dbType: "${dbType}". Must be one of: ${validDbTypes.join(', ')}`
+            );
+        }
+
+        if (!stage) {
+            throw new ValidationError('stage is required');
+        }
+
+        if (typeof stage !== 'string') {
+            throw new ValidationError('stage must be a string');
+        }
+    }
+}
+
+/**
+ * Custom error for validation failures
+ */
+class ValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ValidationError';
+    }
+}
+
+module.exports = {
+    TriggerDatabaseMigrationUseCase,
+    ValidationError,
+};
+

package/database/utils/mongodb-collection-utils.js

@@ -0,0 +1,91 @@
+/**
+ * MongoDB Collection Utilities
+ *
+ * Provides utilities for managing MongoDB collections, particularly for
+ * handling the constraint that collections cannot be created inside
+ * multi-document transactions.
+ *
+ * @see https://github.com/prisma/prisma/issues/8305
+ * @see https://www.mongodb.com/docs/manual/core/transactions/#transactions-and-operations
+ */
+
+const { mongoose } = require('../mongoose');
+
+/**
+ * Ensures a MongoDB collection exists
+ *
+ * MongoDB doesn't allow creating collections (namespaces) inside multi-document
+ * transactions. This function checks if a collection exists and creates it if needed,
+ * preventing "Cannot create namespace in multi-document transaction" errors.
+ *
+ * @param {string} collectionName - Name of the collection to ensure exists
+ * @returns {Promise<void>}
+ *
+ * @example
+ * ```js
+ * await ensureCollectionExists('Credential');
+ * // Now safe to create documents in Credential collection
+ * await prisma.credential.create({ data: {...} });
+ * ```
+ */
+async function ensureCollectionExists(collectionName) {
+    try {
+        const collections = await mongoose.connection.db
+            .listCollections({ name: collectionName })
+            .toArray();
+
+        if (collections.length === 0) {
+            // Collection doesn't exist, create it outside of any transaction
+            await mongoose.connection.db.createCollection(collectionName);
+            console.log(`Created MongoDB collection: ${collectionName}`);
+        }
+    } catch (error) {
+        // Collection might already exist due to race condition, or other error
+        // Log warning but don't fail - let subsequent operations handle errors
+        if (error.codeName === 'NamespaceExists') {
+            // This is expected in race conditions, silently continue
+            return;
+        }
+        console.warn(`Error ensuring collection ${collectionName} exists:`, error.message);
+    }
+}
+
+/**
+ * Ensures multiple MongoDB collections exist
+ *
+ * @param {string[]} collectionNames - Array of collection names to ensure exist
+ * @returns {Promise<void>}
+ *
+ * @example
+ * ```js
+ * await ensureCollectionsExist(['Credential', 'User', 'Token']);
+ * ```
+ */
+async function ensureCollectionsExist(collectionNames) {
+    await Promise.all(collectionNames.map(name => ensureCollectionExists(name)));
+}
+
+/**
+ * Checks if a collection exists in MongoDB
+ *
+ * @param {string} collectionName - Name of the collection to check
+ * @returns {Promise<boolean>} True if collection exists, false otherwise
+ */
+async function collectionExists(collectionName) {
+    try {
+        const collections = await mongoose.connection.db
+            .listCollections({ name: collectionName })
+            .toArray();
+
+        return collections.length > 0;
+    } catch (error) {
+        console.error(`Error checking if collection ${collectionName} exists:`, error.message);
+        return false;
+    }
+}
+
+module.exports = {
+    ensureCollectionExists,
+    ensureCollectionsExist,
+    collectionExists,
+};

package/database/utils/mongodb-schema-init.js

@@ -0,0 +1,106 @@
+/**
+ * MongoDB Schema Initialization for Prisma
+ *
+ * Dynamically parses the Prisma schema and ensures all collections exist before
+ * the application starts handling requests. This prevents
+ * "Cannot create namespace in multi-document transaction" errors.
+ *
+ * MongoDB does not allow creating collections inside transactions.
+ * By pre-creating all collections at startup, we ensure all Prisma
+ * operations can safely use transactions without namespace creation errors.
+ *
+ * Collection names are extracted dynamically from the Prisma schema file,
+ * ensuring they stay in sync with schema changes without manual updates.
+ *
+ * @see https://github.com/prisma/prisma/issues/8305
+ * @see https://www.mongodb.com/docs/manual/core/transactions/#transactions-and-operations
+ */
+
+const { mongoose } = require('../mongoose');
+const { ensureCollectionsExist } = require('./mongodb-collection-utils');
+const { getCollectionsFromSchemaSync } = require('./prisma-schema-parser');
+const config = require('../config');
+
+/**
+ * Initialize MongoDB schema by ensuring all collections exist
+ *
+ * This should be called once at application startup, after the database
+ * connection is established but before handling any requests.
+ *
+ * Dynamically parses the Prisma schema to extract collection names,
+ * ensuring automatic sync with schema changes.
+ *
+ * Benefits:
+ * - Prevents transaction namespace creation errors
+ * - Fails fast if there are database connection issues
+ * - Ensures consistent state across all instances
+ * - Idempotent - safe to run multiple times
+ * - Automatically syncs with Prisma schema changes
+ *
+ * @returns {Promise<void>}
+ *
+ * @example
+ * ```js
+ * await connectPrisma();
+ * await initializeMongoDBSchema(); // Run after connection
+ * // Now safe to handle requests
+ * ```
+ */
+async function initializeMongoDBSchema() {
+    // Only run for MongoDB
+    if (config.DB_TYPE !== 'mongodb') {
+        console.log('Schema initialization skipped - not using MongoDB');
+        return;
+    }
+
+    // Check if database is connected
+    if (mongoose.connection.readyState !== 1) {
+        throw new Error(
+            'Cannot initialize MongoDB schema - database not connected. ' +
+            'Call connectPrisma() before initializeMongoDBSchema()'
+        );
+    }
+
+    console.log('Initializing MongoDB schema - ensuring all collections exist...');
+    const startTime = Date.now();
+
+    try {
+        // Dynamically parse Prisma schema to get collection names
+        const collections = getCollectionsFromSchemaSync();
+
+        if (collections.length === 0) {
+            console.warn('No collections found in Prisma schema - skipping initialization');
+            return;
+        }
+
+        await ensureCollectionsExist(collections);
+
+        const duration = Date.now() - startTime;
+        console.log(
+            `MongoDB schema initialization complete - ${collections.length} collections verified (${duration}ms)`
+        );
+    } catch (error) {
+        console.error('Failed to initialize MongoDB schema:', error.message);
+        throw error;
+    }
+}
+
+/**
+ * Get list of Prisma collection names by parsing the schema
+ * Useful for testing and introspection
+ *
+ * @returns {string[]} Array of collection names from Prisma schema
+ */
+function getPrismaCollections() {
+    try {
+        return getCollectionsFromSchemaSync();
+    } catch (error) {
+        console.warn('Could not parse Prisma collections:', error.message);
+        return [];
+    }
+}
+
+module.exports = {
+    initializeMongoDBSchema,
+    getPrismaCollections,
+};