@friggframework/core 2.0.0--canary.704.79d9a63.0 → 2.0.0--canary.686.e94de4d.0

package/handlers/app-handler-helpers.js

@@ -6,6 +6,12 @@ const bodyParser = require('body-parser');
 const cors = require('cors');
 const Boom = require('@hapi/boom');
 const serverlessHttp = require('serverless-http');
+const {
+    API_VERSION_HEADER,
+    isVersionedManagementApiPath,
+    toBoom,
+    toV2ErrorBody,
+} = require('../management-api/error-response');
 
 const log = getLogger('frigg.http');
 
@@ -26,11 +32,15 @@ const createApp = (applyMiddleware) => {
     if (applyMiddleware) applyMiddleware(app);
 
     // The express boundary: send the error response and log it one time.
+    // A Boom error keeps its status; other errors keep theirs only when they
+    // mark a 4xx safe to expose (body-parser's 400/413 via http-errors), so a
+    // malformed body is a 400, not a 500.
     app.use((err, req, res, next) => {
-        const boomError = err.isBoom ? err : Boom.boomify(err);
+        const boomError = toBoom(err);
         const {
             output: { statusCode = 500 },
         } = boomError;
+        const versioned = isVersionedManagementApiPath(req.path);
 
         if (statusCode >= 500) {
             log.error('Request failed', {
@@ -39,7 +49,6 @@ const createApp = (applyMiddleware) => {
                 invocation: summarizeExpressRequest(req),
                 error: boomError,
             });
-            res.status(statusCode).json({ error: 'Internal Server Error' });
         } else {
             // A client error needs no stack; the logger scrubs the reason.
             log.warn('Request rejected', {
@@ -47,8 +56,21 @@ const createApp = (applyMiddleware) => {
                 statusCode,
                 reason: boomError.message,
             });
-            res.status(statusCode).json({ error: err.message });
         }
+
+        if (versioned) {
+            // Management API v2 / meta: { error: { code, message, details? } }.
+            if (req.path.startsWith('/api/v2')) {
+                res.set(API_VERSION_HEADER, '2');
+            }
+            return res.status(statusCode).json(toV2ErrorBody(boomError));
+        }
+
+        // v1 and other routes keep their historical body.
+        if (statusCode >= 500) {
+            return res.status(statusCode).json({ error: 'Internal Server Error' });
+        }
+        return res.status(statusCode).json({ error: err.message });
     });
 
     return app;

package/handlers/backend-utils.js

@@ -18,8 +18,9 @@ const {
     createModuleRepository,
 } = require('../modules/repositories/module-repository-factory');
 const {
-    getModulesDefinitionFromIntegrationClasses,
-} = require('../integrations/utils/map-integration-dto');
+    getEntityTypeRegistry,
+    getEntityTypeDefinitions,
+} = require('../modules/entity-type-registry');
 const { processNotFound } = require('../integrations/use-cases/process-errors');
 
 const loadRouterFromObject = (IntegrationClass, routerObject) => {
@@ -61,30 +62,18 @@ const initializeRepositories = () => {
     return { processRepository, integrationRepository, moduleRepository };
 };
 
-const createModuleFactoryWithDefinitions = (
-    moduleRepository,
-    integrationClasses
-) => {
-    const moduleDefinitions =
-        getModulesDefinitionFromIntegrationClasses(integrationClasses);
-
-    return new ModuleFactory({
-        moduleRepository,
-        moduleDefinitions,
-    });
-};
-
 const loadIntegrationForWebhook = async (integrationId) => {
     const { loadAppDefinition } = require('./app-definition-loader');
-    const { integrations: integrationClasses } = loadAppDefinition();
+    const { integrations: integrationClasses, moduleDefinitions } =
+        loadAppDefinition();
 
     const { integrationRepository, moduleRepository } =
         initializeRepositories();
 
-    const moduleFactory = createModuleFactoryWithDefinitions(
+    const moduleFactory = new ModuleFactory({
         moduleRepository,
-        integrationClasses
-    );
+        moduleDefinitions,
+    });
 
     const getIntegrationInstance = new GetIntegrationInstance({
         integrationRepository,
@@ -129,13 +118,23 @@ const integrationExists = async (integrationId) => {
     }
 };
 
-const loadIntegrationForProcess = async (processId, integrationClass) => {
+const loadIntegrationForProcess = async (
+    processId,
+    integrationClass,
+    moduleDefinitions
+) => {
     const { processRepository, integrationRepository, moduleRepository } =
         initializeRepositories();
 
-    const moduleFactory = createModuleFactoryWithDefinitions(moduleRepository, [
-        integrationClass,
-    ]);
+    const moduleFactory = new ModuleFactory({
+        moduleRepository,
+        moduleDefinitions:
+            moduleDefinitions ??
+            // No app definition handed in: this integration's own modules only.
+            getEntityTypeDefinitions(
+                getEntityTypeRegistry({ integrations: [integrationClass] })
+            ),
+    });
 
     const getIntegrationInstance = new GetIntegrationInstance({
         integrationRepository,
@@ -161,7 +160,13 @@ const loadIntegrationForProcess = async (processId, integrationClass) => {
     return instance;
 };
 
-const createQueueWorker = (integrationClass) => {
+/**
+ * @param {Function} integrationClass
+ * @param {{moduleDefinitions?: Array<object>}} [options] - the app's offered
+ *   module definitions (`loadAppDefinition().moduleDefinitions`). When omitted
+ *   the worker hydrates with this integration's own modules only.
+ */
+const createQueueWorker = (integrationClass, { moduleDefinitions } = {}) => {
     const integrationName = integrationClass.Definition.name;
 
     class QueueWorker extends Worker {
@@ -183,7 +188,8 @@ const createQueueWorker = (integrationClass) => {
                     console.log(`[QueueWorker] hydrating by processId`, logCtx);
                     integrationInstance = await loadIntegrationForProcess(
                         params.data.processId,
-                        integrationClass
+                        integrationClass,
+                        moduleDefinitions
                     );
                     console.log(`[QueueWorker] hydrated`, {
                         ...logCtx,

package/handlers/middleware/admin-auth.js

@@ -29,6 +29,19 @@ function secretsMatch(provided, expected) {
     return crypto.timingSafeEqual(providedHash, expectedHash);
 }
 
+/**
+ * True when `provided` matches the configured ADMIN_API_KEY. False when no
+ * key is configured or none was provided. For callers that change a response
+ * for admins rather than reject everyone else (GET /api/meta).
+ * @param {string|undefined} provided
+ * @returns {boolean}
+ */
+function isValidAdminApiKey(provided) {
+    const expectedKey = process.env.ADMIN_API_KEY;
+    if (!expectedKey || !provided) return false;
+    return secretsMatch(provided, expectedKey);
+}
+
 /**
  * Validate admin API key from request header
  * @param {import('express').Request} req
@@ -70,4 +83,4 @@ function validateAdminApiKey(req, res, next) {
     next();
 }
 
-module.exports = { validateAdminApiKey };
+module.exports = { validateAdminApiKey, isValidAdminApiKey };

package/handlers/routers/auth.js

@@ -1,15 +1,51 @@
-const { createIntegrationRouter } = require('@friggframework/core');
+const express = require('express');
+const {
+    createManagementApiRouter,
+} = require('../../management-api/create-management-api-router');
+const {
+    createExtensionRoutesRouter,
+} = require('../../extensions/route-mounter');
 const { createAppHandler } = require('./../app-handler-helpers');
 
-const router = createIntegrationRouter();
+// The Management API (ADR-053): v2 under /api/v2, the deprecated v1 at the
+// unprefixed paths (or 410 when managementApi.v1 is false).
+//
+// Built on first access, not at require time (friggframework/frigg#545,
+// c40eca49): a host that presets the app definition (setAppDefinition, as
+// provider-netlify's function entry points do) can require this module
+// before or after doing so.
+let router;
+let handler;
 
-router.route('/api/integrations/redirect/:appId').get((req, res) => {
-    res.redirect(
-        `${process.env.FRONTEND_URI}/redirect/${req.params.appId
-        }?${new URLSearchParams(req.query)}`
-    );
-});
+function buildRouter() {
+    const built = express.Router();
+    built.use(createManagementApiRouter());
 
-const handler = createAppHandler('HTTP Event: Auth', router);
+    // The OAuth provider's redirect target. Unversioned: it is neither part
+    // of v1 nor v2, so it is never deprecated or disabled.
+    built.route('/api/integrations/redirect/:appId').get((req, res) => {
+        res.redirect(
+            `${process.env.FRONTEND_URI}/redirect/${req.params.appId
+            }?${new URLSearchParams(req.query)}`
+        );
+    });
 
-module.exports = { handler };
+    // Core extension routes (appDefinition.coreExtensions[].routes), each
+    // behind the admin API key.
+    built.use(createExtensionRoutesRouter());
+
+    return built;
+}
+
+module.exports = {
+    get router() {
+        if (!router) router = buildRouter();
+        return router;
+    },
+    get handler() {
+        if (!handler) {
+            handler = createAppHandler('HTTP Event: Auth', module.exports.router);
+        }
+        return handler;
+    },
+};

package/handlers/routers/health.js

@@ -2,9 +2,6 @@ const { Router } = require('express');
 const { createAppHandler } = require('./../app-handler-helpers');
 const { loadAppDefinition } = require('./../app-definition-loader');
 const { ModuleFactory } = require('../../modules/module-factory');
-const {
-    getModulesDefinitionFromIntegrationClasses,
-} = require('../../integrations/utils/map-integration-dto');
 const {
     createModuleRepository,
 } = require('../../modules/repositories/module-repository-factory');
@@ -28,18 +25,25 @@ const {
     CheckIntegrationsHealthUseCase,
 } = require('../use-cases/check-integrations-health-use-case');
 
+const {
+    createManagementApiMetaRouter,
+    createDocsRedirectRouter,
+} = require('../../management-api/meta-router');
+
 const router = Router();
 const healthCheckRepository = createHealthCheckRepository({ prismaClient: prisma });
 
 // Load integrations and create factories just like auth router does
 // This verifies the system can properly load integrations
 let moduleFactory, integrationClasses;
+let appDefinition = {};
 try {
     const appDef = loadAppDefinition();
+    appDefinition = appDef;
     integrationClasses = appDef.integrations || [];
 
     const moduleRepository = createModuleRepository();
-    const moduleDefinitions = getModulesDefinitionFromIntegrationClasses(integrationClasses);
+    const { moduleDefinitions } = appDef;
 
     moduleFactory = new ModuleFactory({
         moduleRepository,
@@ -85,6 +89,11 @@ const validateApiKey = (req, res, next) => {
     next();
 };
 
+// Management API discovery (ADR-053 §4) and the /api/docs redirect to it are
+// public and DB-free, so they are mounted ahead of the health API key check.
+router.use(createManagementApiMetaRouter({ appDefinition }));
+router.use(createDocsRedirectRouter());
+
 router.use(validateApiKey);
 
 // Helper to detect VPC configuration

package/handlers/routers/integration-defined-routers.js

@@ -1,117 +1,169 @@
 const { createAppHandler } = require('./../app-handler-helpers');
-const {
-    loadAppDefinition,
-} = require('../app-definition-loader');
+const { loadAppDefinition } = require('../app-definition-loader');
 const express = require('express');
 const { Router } = express;
 const { loadRouterFromObject } = require('../backend-utils');
 const { getExtensionRoutes } = require('../../integrations/extension');
 
-const handlers = {};
-const { integrations: integrationClasses } = loadAppDefinition();
-
 const routeKey = (method, path) => `${(method || 'ANY').toUpperCase()} ${path}`;
 
 // Serverless function keys must be alphanumeric; binding keys are developer-chosen.
 const sanitizeBindingKey = (name) => String(name).replace(/[^A-Za-z0-9]/g, '');
 
-//todo: this should be in a use case class
-for (const IntegrationClass of integrationClasses) {
-    const router = Router();
-    const basePath = `/api/${IntegrationClass.Definition.name}-integration`;
-    // Track (method, path) tuples to fail fast on conflicts between Definition.routes,
-    // extension routes, or two extensions claiming the same path.
-    const claimedRoutes = new Map();
-    const claim = (method, path, source) => {
-        const key = routeKey(method, path);
-        if (claimedRoutes.has(key)) {
-            const prev = claimedRoutes.get(key);
-            throw new Error(
-                `Integration "${IntegrationClass.Definition.name}" route conflict: ` +
-                    `${key} declared by ${prev} and ${source}`
-            );
-        }
-        claimedRoutes.set(key, source);
-    };
+/**
+ * Builds the Express routers for every integration's Definition.routes and
+ * extension bindings. Pure: no handler wrapping, so the AWS handlers below
+ * and other hosts (provider-netlify's integration-routes function) mount the
+ * very same routers.
+ *
+ * @param {Array<Function>} integrationClasses
+ * @returns {Array<{ key: string, eventName: string, router: import('express').Router, useDatabase: boolean }>}
+ *   One entry per integration, then one per extension binding (key
+ *   `${name}__${binding}`), in declaration order.
+ */
+function buildIntegrationRouters(integrationClasses) {
+    const entries = [];
+    const keys = new Set();
+    //todo: this should be in a use case class
+    for (const IntegrationClass of integrationClasses) {
+        const router = Router();
+        const basePath = `/api/${IntegrationClass.Definition.name}-integration`;
+        // Track (method, path) tuples to fail fast on conflicts between Definition.routes,
+        // extension routes, or two extensions claiming the same path.
+        const claimedRoutes = new Map();
+        const claim = (method, path, source) => {
+            const key = routeKey(method, path);
+            if (claimedRoutes.has(key)) {
+                const prev = claimedRoutes.get(key);
+                throw new Error(
+                    `Integration "${IntegrationClass.Definition.name}" route conflict: ` +
+                        `${key} declared by ${prev} and ${source}`
+                );
+            }
+            claimedRoutes.set(key, source);
+        };
+
+        console.log(
+            `\n│ Configuring routes for ${IntegrationClass.Definition.name} Integration:`
+        );
 
-    console.log(`\n│ Configuring routes for ${IntegrationClass.Definition.name} Integration:`);
+        const routes = IntegrationClass.Definition.routes || [];
+        for (const routeDef of routes) {
+            if (typeof routeDef === 'function') {
+                router.use(basePath, routeDef(IntegrationClass));
+                console.log(`│ ANY ${basePath}/* (function handler)`);
+            } else if (routeDef instanceof express.Router) {
+                router.use(basePath, routeDef);
+                console.log(`│ ANY ${basePath}/* (express router)`);
+            } else if (typeof routeDef === 'object') {
+                claim(routeDef.method, routeDef.path, 'Definition.routes');
+                router.use(
+                    basePath,
+                    loadRouterFromObject(IntegrationClass, routeDef)
+                );
+                const method = (routeDef.method || 'ANY').toUpperCase();
+                const fullPath = `${basePath}${routeDef.path}`;
+                console.log(`│ ${method} ${fullPath}`);
+            }
+        }
 
-    const routes = IntegrationClass.Definition.routes || [];
-    for (const routeDef of routes) {
-        if (typeof routeDef === 'function') {
-            router.use(basePath, routeDef(IntegrationClass));
-            console.log(`│ ANY ${basePath}/* (function handler)`);
-        } else if (routeDef instanceof express.Router) {
-            router.use(basePath, routeDef);
-            console.log(`│ ANY ${basePath}/* (express router)`);
-        } else if (typeof routeDef === 'object') {
-            claim(routeDef.method, routeDef.path, 'Definition.routes');
-            router.use(
-                basePath,
-                loadRouterFromObject(IntegrationClass, routeDef)
+        // Each extension binding gets its own namespaced handler (/{bindingName}),
+        // so two modules' extensions can share a path like /webhooks without colliding.
+        const bindingGroups = new Map();
+        for (const extRoute of getExtensionRoutes(IntegrationClass)) {
+            const namespacedPath = `/${extRoute.bindingName}${extRoute.path}`;
+            claim(
+                extRoute.method,
+                namespacedPath,
+                `extension "${extRoute.extensionName}" (binding "${extRoute.bindingName}")`
+            );
+            if (!bindingGroups.has(extRoute.bindingName)) {
+                bindingGroups.set(extRoute.bindingName, {
+                    router: Router(),
+                    useDatabase: extRoute.useDatabase,
+                });
+            }
+            const group = bindingGroups.get(extRoute.bindingName);
+            group.router.use(
+                `${basePath}/${extRoute.bindingName}`,
+                loadRouterFromObject(IntegrationClass, extRoute)
+            );
+            console.log(
+                `│ ${extRoute.method.toUpperCase()} ${basePath}/${
+                    extRoute.bindingName
+                }${extRoute.path}  (extension: ${
+                    extRoute.extensionName
+                }, useDatabase: ${extRoute.useDatabase})`
             );
-            const method = (routeDef.method || 'ANY').toUpperCase();
-            const fullPath = `${basePath}${routeDef.path}`;
-            console.log(`│ ${method} ${fullPath}`);
         }
-    }
+        console.log('│');
 
-    // Each extension binding gets its own namespaced handler (/{bindingName}),
-    // so two modules' extensions can share a path like /webhooks without colliding.
-    const bindingGroups = new Map();
-    for (const extRoute of getExtensionRoutes(IntegrationClass)) {
-        const namespacedPath = `/${extRoute.bindingName}${extRoute.path}`;
-        claim(
-            extRoute.method,
-            namespacedPath,
-            `extension "${extRoute.extensionName}" (binding "${extRoute.bindingName}")`
-        );
-        if (!bindingGroups.has(extRoute.bindingName)) {
-            bindingGroups.set(extRoute.bindingName, {
-                router: Router(),
-                useDatabase: extRoute.useDatabase,
+        entries.push({
+            key: `${IntegrationClass.Definition.name}`,
+            eventName: `HTTP Event: ${IntegrationClass.Definition.name}`,
+            router,
+            useDatabase: true,
+        });
+        keys.add(`${IntegrationClass.Definition.name}`);
+
+        for (const [bindingName, group] of bindingGroups) {
+            // Wire contract: integration-builder.js (devtools) derives the identical
+            // function key for the serverless config. Keep both in sync.
+            const fnKey = `${
+                IntegrationClass.Definition.name
+            }__${sanitizeBindingKey(bindingName)}`;
+            // Distinct binding keys can sanitize to the same fnKey — fail loud rather than overwrite.
+            if (keys.has(fnKey)) {
+                throw new Error(
+                    `Integration "${IntegrationClass.Definition.name}" extension handler conflict: ` +
+                        `binding "${bindingName}" sanitizes to "${fnKey}", which is already taken. ` +
+                        `Use binding keys that are distinct after stripping non-alphanumeric characters.`
+                );
+            }
+            entries.push({
+                key: fnKey,
+                eventName: `HTTP Event: ${IntegrationClass.Definition.name} extension ${bindingName}`,
+                router: group.router,
+                useDatabase: group.useDatabase,
             });
+            keys.add(fnKey);
         }
-        const group = bindingGroups.get(extRoute.bindingName);
-        group.router.use(
-            `${basePath}/${extRoute.bindingName}`,
-            loadRouterFromObject(IntegrationClass, extRoute)
-        );
-        console.log(
-            `│ ${extRoute.method.toUpperCase()} ${basePath}/${extRoute.bindingName}${extRoute.path}  (extension: ${extRoute.extensionName}, useDatabase: ${extRoute.useDatabase})`
-        );
     }
-    console.log('│');
+    return entries;
+}
+
+/**
+ * One router serving every integration-defined route and extension binding,
+ * for hosts that run them all in one function (provider-netlify).
+ *
+ * @param {Array<Function>} [integrationClasses] - defaults to the app's.
+ * @returns {import('express').Router}
+ */
+function createIntegrationDefinedRouter(integrationClasses) {
+    const classes = integrationClasses || loadAppDefinition().integrations;
+    const combined = Router();
+    for (const entry of buildIntegrationRouters(classes)) {
+        combined.use(entry.router);
+    }
+    return combined;
+}
 
-    handlers[`${IntegrationClass.Definition.name}`] = {
+// The AWS handlers (one Lambda per integration and per extension binding,
+// see devtools integration-builder). Built at require time on purpose: a
+// route conflict fails the cold start, not the first request.
+const handlers = {};
+for (const entry of buildIntegrationRouters(loadAppDefinition().integrations)) {
+    handlers[entry.key] = {
         handler: createAppHandler(
-            `HTTP Event: ${IntegrationClass.Definition.name}`,
-            router
+            entry.eventName,
+            entry.router,
+            entry.useDatabase
         ),
     };
-
-    for (const [bindingName, group] of bindingGroups) {
-        // Wire contract: integration-builder.js (devtools) derives the identical
-        // function key for the serverless config. Keep both in sync.
-        const fnKey = `${IntegrationClass.Definition.name}__${sanitizeBindingKey(
-            bindingName
-        )}`;
-        // Distinct binding keys can sanitize to the same fnKey — fail loud rather than overwrite.
-        if (Object.prototype.hasOwnProperty.call(handlers, fnKey)) {
-            throw new Error(
-                `Integration "${IntegrationClass.Definition.name}" extension handler conflict: ` +
-                    `binding "${bindingName}" sanitizes to "${fnKey}", which is already taken. ` +
-                    `Use binding keys that are distinct after stripping non-alphanumeric characters.`
-            );
-        }
-        handlers[fnKey] = {
-            handler: createAppHandler(
-                `HTTP Event: ${IntegrationClass.Definition.name} extension ${bindingName}`,
-                group.router,
-                group.useDatabase
-            ),
-        };
-    }
 }
 
-module.exports = { handlers };
+module.exports = {
+    handlers,
+    buildIntegrationRouters,
+    createIntegrationDefinedRouter,
+};