@friggframework/core 2.0.0-next.41 → 2.0.0-next.42

package/handlers/backend-utils.js

@@ -1,36 +1,29 @@
-const { createFriggBackend, Worker } = require('@friggframework/core');
-const { findNearestBackendPackageJson } = require('@friggframework/core/utils');
-const path = require('node:path');
-const fs = require('fs-extra');
-
-const backendPath = findNearestBackendPackageJson();
-if (!backendPath) {
-    throw new Error('Could not find backend package.json');
-}
-
-const backendDir = path.dirname(backendPath);
-const backendFilePath = path.join(backendDir, 'index.js');
-if (!fs.existsSync(backendFilePath)) {
-    throw new Error('Could not find index.js');
-}
-
-const backendJsFile = require(backendFilePath);
 const { Router } = require('express');
-const appDefinition = backendJsFile.Definition;
+const { Worker } = require('@friggframework/core');
+const {
+    IntegrationEventDispatcher,
+} = require('./integration-event-dispatcher');
 
-const backend = createFriggBackend(appDefinition);
 const loadRouterFromObject = (IntegrationClass, routerObject) => {
     const router = Router();
     const { path, method, event } = routerObject;
+
     console.log(
         `Registering ${method} ${path} for ${IntegrationClass.Definition.name}`
     );
+
     router[method.toLowerCase()](path, async (req, res, next) => {
         try {
-            const integration = new IntegrationClass({});
-            await integration.loadModules();
-            await integration.registerEventHandlers();
-            const result = await integration.send(event, {req, res, next});
+            const integrationInstance = new IntegrationClass();
+            const dispatcher = new IntegrationEventDispatcher(
+                integrationInstance
+            );
+            const result = await dispatcher.dispatchHttp({
+                event,
+                req,
+                res,
+                next,
+            });
             res.json(result);
         } catch (error) {
             next(error);
@@ -39,31 +32,19 @@ const loadRouterFromObject = (IntegrationClass, routerObject) => {
 
     return router;
 };
-const createQueueWorker = (integrationClass, integrationFactory) => {
+
+const createQueueWorker = (integrationClass) => {
     class QueueWorker extends Worker {
         async _run(params, context) {
             try {
-                let instance;
-                if (!params.integrationId) {
-                    instance = new integrationClass({});
-                    await instance.loadModules();
-                    // await instance.loadUserActions();
-                    await instance.registerEventHandlers();
-                    console.log(
-                        `${params.event} for ${integrationClass.Definition.name} integration with no integrationId`
-                    );
-                } else {
-                    instance =
-                        await integrationFactory.getInstanceFromIntegrationId({
-                            integrationId: params.integrationId,
-                        });
-                    console.log(
-                        `${params.event} for ${instance.record.config.type} of integrationId: ${params.integrationId}`
-                    );
-                }
-                const res = await instance.send(params.event, {
+                const integrationInstance = new integrationClass();
+                const dispatcher = new IntegrationEventDispatcher(
+                    integrationInstance
+                );
+                const res = await dispatcher.dispatchJob({
+                    event: params.event,
                     data: params.data,
-                    context,
+                    context: context,
                 });
                 return res;
             } catch (error) {
@@ -79,7 +60,6 @@ const createQueueWorker = (integrationClass, integrationFactory) => {
 };
 
 module.exports = {
-    ...backend,
     loadRouterFromObject,
     createQueueWorker,
 };

package/handlers/integration-event-dispatcher.js

@@ -0,0 +1,54 @@
+/**
+ * Lightweight dispatcher that executes integration event handlers.
+ * @param {import('../integrations/integration-base')} integrationInstance Pre-instantiated integration.
+ */
+class IntegrationEventDispatcher {
+    constructor(integrationInstance) {
+        if (!integrationInstance) {
+            throw new Error('Integration instance is required');
+        }
+        this.integrationInstance = integrationInstance;
+    }
+
+    async dispatchHttp({ event, req, res, next }) {
+        const instance = this.integrationInstance;
+
+        const handler = this.findEventHandler(instance, event);
+
+        if (!handler) {
+            const name =
+                instance.constructor?.Definition?.name || 'integration';
+            throw new Error(`Event ${event} not registered for ${name}`);
+        }
+
+        return await handler.call(instance, { req, res, next });
+    }
+
+    async dispatchJob({ event, data, context }) {
+        const instance = this.integrationInstance;
+
+        const handler = this.findEventHandler(instance, event);
+
+        if (!handler) {
+            const name =
+                instance.constructor?.Definition?.name || 'integration';
+            throw new Error(`Event ${event} not registered for ${name}`);
+        }
+
+        return await handler.call(instance, { data, context });
+    }
+
+    findEventHandler(integration, event) {
+        if (integration.events && integration.events[event]) {
+            return integration.events[event].handler;
+        }
+
+        if (integration.defaultEvents && integration.defaultEvents[event]) {
+            return integration.defaultEvents[event].handler;
+        }
+
+        return null;
+    }
+}
+
+module.exports = { IntegrationEventDispatcher };

package/handlers/integration-event-dispatcher.test.js

@@ -0,0 +1,141 @@
+jest.mock('../database/config', () => ({
+    DB_TYPE: 'mongodb',
+    getDatabaseType: jest.fn(() => 'mongodb'),
+    PRISMA_LOG_LEVEL: 'error,warn',
+    PRISMA_QUERY_LOGGING: false,
+}));
+
+const { IntegrationEventDispatcher } = require('./integration-event-dispatcher');
+const { IntegrationBase } = require('../integrations/integration-base');
+
+class TestIntegration extends IntegrationBase {
+    static Definition = {
+        name: 'test-integration',
+        version: '1.0.0',
+        modules: {},
+        routes: [
+            { path: '/auth', method: 'GET', event: 'AUTH_REQUEST' },
+            { path: '/data', method: 'GET', event: 'LOAD_DATA' },
+            { path: '/job', method: 'POST', event: 'TEST_EVENT' },
+            { path: '/dynamic', method: 'GET', event: 'DYNAMIC_EVENT' },
+        ],
+    };
+
+    constructor(params) {
+        super(params);
+        this.events = {
+            AUTH_REQUEST: { handler: this.authRequest.bind(this) },
+            LOAD_DATA: { handler: this.loadData.bind(this) },
+            TEST_EVENT: { handler: this.testHandler.bind(this) },
+        };
+    }
+
+    async authRequest() {
+        TestIntegration.latestInstance = this;
+        return {
+            success: true,
+            hydrated: this.isHydrated,
+        };
+    }
+
+    async loadData() {
+        this.assertHydrated('loadData requires hydration');
+        return { success: true };
+    }
+
+    async testHandler({ data }) {
+        TestIntegration.latestInstance = this;
+        return { received: data };
+    }
+
+    async initialize() {
+        this.events = {
+            ...this.events,
+            DYNAMIC_EVENT: { handler: this.dynamicHandler.bind(this) },
+        };
+    }
+
+    async dynamicHandler() {
+        TestIntegration.latestInstance = this;
+        return { dynamic: true };
+    }
+}
+
+describe('IntegrationEventDispatcher', () => {
+    const createDispatcher = () =>
+        new IntegrationEventDispatcher(new TestIntegration());
+
+    beforeEach(() => {
+        TestIntegration.latestInstance = null;
+    });
+
+    describe('dispatchHttp', () => {
+        it('creates a stateless integration instance for HTTP events', async () => {
+            const dispatcher = createDispatcher();
+            const result = await dispatcher.dispatchHttp({
+                event: 'AUTH_REQUEST',
+                req: {},
+                res: {},
+                next: jest.fn(),
+            });
+
+            expect(result).toEqual({ success: true, hydrated: false });
+            expect(TestIntegration.latestInstance).toBeInstanceOf(TestIntegration);
+            expect(TestIntegration.latestInstance.isHydrated).toBe(false);
+        });
+
+        it('calls initialize to register dynamic events', async () => {
+            const dispatcher = createDispatcher();
+            await dispatcher.integrationInstance.initialize();
+            const result = await dispatcher.dispatchHttp({
+                event: 'DYNAMIC_EVENT',
+                req: {},
+                res: {},
+                next: jest.fn(),
+            });
+
+            expect(result).toEqual({ dynamic: true });
+            expect(TestIntegration.latestInstance).toBeInstanceOf(TestIntegration);
+        });
+
+        it('throws when requesting an unknown event', async () => {
+            const dispatcher = createDispatcher();
+            await expect(
+                dispatcher.dispatchHttp({
+                    event: 'UNKNOWN',
+                    req: {},
+                    res: {},
+                    next: jest.fn(),
+                })
+            ).rejects.toThrow('Event UNKNOWN not registered for test-integration');
+        });
+
+        it('does not hydrate automatically for handlers that require data', async () => {
+            const dispatcher = createDispatcher();
+            await expect(
+                dispatcher.dispatchHttp({
+                    event: 'LOAD_DATA',
+                    req: {},
+                    res: {},
+                    next: jest.fn(),
+                })
+            ).rejects.toThrow('loadData requires hydration');
+        });
+    });
+
+    describe('dispatchJob', () => {
+        it('creates a stateless integration instance for job events', async () => {
+            const payload = { foo: 'bar' };
+            const dispatcher = createDispatcher();
+            const result = await dispatcher.dispatchJob({
+                event: 'TEST_EVENT',
+                data: payload,
+                context: {},
+            });
+
+            expect(result).toEqual({ received: payload });
+            expect(TestIntegration.latestInstance).toBeInstanceOf(TestIntegration);
+            expect(TestIntegration.latestInstance.isHydrated).toBe(false);
+        });
+    });
+});

package/handlers/routers/HEALTHCHECK.md

@@ -237,4 +237,106 @@ await mongoose.connection.db.admin().ping({ maxTimeMS: 2000 });
 
 ## Environment Variables
 
-- `HEALTH_API_KEY`: Required API key for accessing detailed health endpoints
+- `HEALTH_API_KEY`: Required API key for accessing detailed health endpoints
+
+## TODO: DDD/Hexagonal Architecture Refactoring
+
+### Current Architecture Issues
+
+The health router (health.js, 677 lines) currently violates DDD/Hexagonal Architecture principles:
+
+**✅ What's Good:**
+- Database access properly abstracted through `HealthCheckRepository`
+- `CheckDatabaseHealthUseCase` and `TestEncryptionUseCase` correctly implement use case pattern
+- All tests passing, no breaking changes
+
+**❌ Architecture Violations:**
+1. **Handler contains significant business logic** - Functions like `getEncryptionConfiguration()`, `checkEncryptionHealth()`, `checkKmsDecryptCapability()`, `detectVpcConfiguration()`, `checkExternalAPIs()`, and `checkIntegrations()` contain business logic that should be in use cases
+2. **Direct infrastructure dependencies** - Handler directly uses `https`, `http`, Node.js `dns`, and factory modules instead of accessing through repositories
+3. **Mixed concerns** - Single file handles HTTP routing, business logic, infrastructure detection, and response formatting
+4. **Violates dependency rule** - Handler should only call use cases, never repositories or contain business logic
+
+### Proposed Refactoring Plan
+
+#### Priority 1: Extract Core Health Check Use Cases (Immediate)
+
+**New Use Cases:**
+1. `CheckEncryptionHealthUseCase` - Orchestrate encryption testing with configuration checks (from health.js:122-181)
+2. `CheckKmsConnectivityUseCase` - Test KMS decrypt capability (from health.js:339-490)
+3. `DetectNetworkConfigurationUseCase` - VPC and network detection (from health.js:244-336)
+
+**New Repositories:**
+1. `EncryptionConfigRepository` - Get encryption mode, bypass rules (from health.js:98-120)
+2. `KmsRepository` - KMS connectivity testing, decrypt capability checks
+3. `NetworkRepository` - DNS resolution, VPC detection, TCP connectivity tests
+
+#### Priority 2: Extract External Service Checks
+
+**New Use Cases:**
+4. `CheckExternalServicesUseCase` - Check external API availability (from health.js:183-209)
+
+**New Repositories:**
+4. `ExternalServiceRepository` - HTTP-based service health checking with timeout handling
+
+#### Priority 3: Extract Integration Checks
+
+**New Use Cases:**
+5. `CheckIntegrationAvailabilityUseCase` - Verify integrations and modules loaded (from health.js:211-231)
+
+**Extend Existing:**
+- Add `getAvailableIntegrations()` and `getAvailableModules()` methods to existing `IntegrationRepository`
+
+### Architectural Principles to Follow
+
+**The Handler Should Only:**
+- Define routes
+- Call use cases
+- Map use case results to HTTP responses
+- Handle HTTP-specific concerns (status codes, headers)
+
+**The Rule:**
+> "Handlers (adapters) should only call use cases, never repositories or business logic directly"
+
+**Dependency Direction:**
+```
+Handler (Adapter Layer)
+  ↓ calls
+Use Cases (Application Layer)
+  ↓ calls
+Repositories (Infrastructure Layer)
+  ↓ calls
+External Systems (Database, APIs, AWS Services)
+```
+
+### Expected Outcome
+
+- Reduce health.js from **677 lines to ~100-150 lines**
+- All business logic moved to use cases
+- All infrastructure access moved to repositories
+- Handler becomes thin HTTP adapter
+- Improved testability (use cases testable without HTTP context)
+- Better reusability (use cases usable in CLI tools, background jobs, etc.)
+
+### Implementation Status
+
+- [ ] P1: Extract `CheckEncryptionHealthUseCase`
+- [ ] P1: Create `EncryptionConfigRepository`
+- [ ] P1: Extract `CheckKmsConnectivityUseCase`
+- [ ] P1: Create `KmsRepository`
+- [ ] P1: Extract `DetectNetworkConfigurationUseCase`
+- [ ] P1: Create `NetworkRepository`
+- [ ] P2: Extract `CheckExternalServicesUseCase`
+- [ ] P2: Create `ExternalServiceRepository`
+- [ ] P3: Extract `CheckIntegrationAvailabilityUseCase`
+- [ ] P3: Extend existing `IntegrationRepository`
+
+### Future Considerations (Optional)
+
+**Domain Models (Value Objects):**
+- `HealthCheckResult` - Overall health check result with status, checks, timestamp
+- `DatabaseHealth` - Database-specific health information
+- `EncryptionHealth` - Encryption-specific health information
+- `ServiceHealth` - Generic external service health
+- `NetworkConfiguration` - VPC and network detection results
+
+These would replace plain objects and provide type safety and business logic encapsulation.

package/handlers/routers/auth.js

@@ -1,26 +1,15 @@
 const { createIntegrationRouter } = require('@friggframework/core');
 const { createAppHandler } = require('./../app-handler-helpers');
-const { requireLoggedInUser } = require('./middleware/requireLoggedInUser');
-const {
-    moduleFactory,
-    integrationFactory,
-    IntegrationHelper,
-} = require('./../backend-utils');
 
-const router = createIntegrationRouter({
-    factory: { moduleFactory, integrationFactory, IntegrationHelper },
-    requireLoggedInUser,
-    getUserId: (req) => req.user.getUserId(),
-});
+const router = createIntegrationRouter();
 
 router.route('/redirect/:appId').get((req, res) => {
     res.redirect(
-        `${process.env.FRONTEND_URI}/redirect/${
-            req.params.appId
+        `${process.env.FRONTEND_URI}/redirect/${req.params.appId
         }?${new URLSearchParams(req.query)}`
     );
 });
 
 const handler = createAppHandler('HTTP Event: Auth', router);
 
-module.exports = { handler, router };
+module.exports = { handler };