@friggframework/core 2.0.0-next.88 → 2.0.0-next.89

package/core/create-handler.js

@@ -49,6 +49,7 @@ const createHandler = (optionByName = {}) => {
         eventName = 'Event',
         isUserFacingResponse = true,
         method,
+        shouldUseDatabase = true,
     } = optionByName;
 
     if (!method) {
@@ -79,6 +80,12 @@ const createHandler = (optionByName = {}) => {
             // If enabled (i.e. if SECRET_ARN is set in process.env) Fetch secrets from AWS Secrets Manager, and set them as environment variables.
             await secretsToEnv();
 
+            // Lazy-required so DB-free handlers never load the Prisma client.
+            if (shouldUseDatabase) {
+                const { connectPrisma } = require('../database/prisma');
+                await connectPrisma();
+            }
+
             // Helps reuse the database connection.  Lowers response times.
             context.callbackWaitsForEmptyEventLoop = false;
 

package/handlers/routers/health.js

@@ -511,6 +511,8 @@ router.get('/health/ready', async (_req, res) => {
     });
 });
 
-const handler = createAppHandler('HTTP Event: Health', router);
+// DB-free: /health/ready probes the DB itself and degrades to 503. Eager-connect
+// here would turn a DB outage into a 500, killing otherwise-healthy containers.
+const handler = createAppHandler('HTTP Event: Health', router, false);
 
 module.exports = { handler, router };

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

@@ -12,6 +12,9 @@ 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();
@@ -53,20 +56,29 @@ for (const IntegrationClass of integrationClasses) {
         }
     }
 
-    // Tier 3 Integration Extension routes — see EXTENSIONS.md
+    // 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,
-            extRoute.path,
+            namespacedPath,
             `extension "${extRoute.extensionName}" (binding "${extRoute.bindingName}")`
         );
-        router.use(
-            basePath,
+        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)
         );
-        const method = extRoute.method.toUpperCase();
         console.log(
-            `│ ${method} ${basePath}${extRoute.path}  (extension: ${extRoute.extensionName})`
+            `│ ${extRoute.method.toUpperCase()} ${basePath}/${extRoute.bindingName}${extRoute.path}  (extension: ${extRoute.extensionName}, useDatabase: ${extRoute.useDatabase})`
         );
     }
     console.log('│');
@@ -77,6 +89,29 @@ for (const IntegrationClass of integrationClasses) {
             router
         ),
     };
+
+    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 };

package/integrations/EXTENSIONS.md

@@ -24,6 +24,8 @@ class HubSpotIntegration extends IntegrationBase {
             hubspotWebhooks: {
                 extension: hubspot.extensions.webhooks,
                 handlers: { HUBSPOT_WEBHOOK: 'onHubSpotEvent' },
+                // optional: override the extension's declared useDatabase
+                // useDatabase: true,
             },
         },
     };
@@ -39,19 +41,42 @@ class HubSpotIntegration extends IntegrationBase {
 }
 ```
 
-The binding key (`hubspotWebhooks`) is your local name. The extension reference (`hubspot.extensions.webhooks`) is whatever the API module exports.
+The binding key (`hubspotWebhooks`) is your local name. It is also the **URL namespace** for the extension's routes (see below), so pick something readable — `hubspot` yields a cleaner URL than `hubspotWebhooks`. The extension reference (`hubspot.extensions.webhooks`) is whatever the API module exports.
 
 ## Step 2: Deploy
 
-The framework auto-mounts each extension's routes at the integration's base path. Boot logs show:
+Each extension binding is mounted under its **binding key**, on its own dedicated handler/Lambda function. This means two modules' extensions (e.g. a HubSpot and a Clockwork webhooks extension on the same integration) never collide — each lives at a distinct namespaced path. Boot logs show:
 
 ```
 │ Configuring routes for hubspot Integration:
-│ POST /api/hubspot-integration/webhooks  (extension: hubspot-webhooks)
+│ POST /api/hubspot-integration/hubspotWebhooks/webhooks  (extension: hubspot-webhooks, useDatabase: false)
 │
 ```
 
-Hit that URL and the bound method (`onHubSpotEvent`) fires on the resolved per-account integration instance.
+So the full URL is `/api/{integration-name}-integration/{bindingKey}{route.path}`. Register that URL with the upstream provider (e.g. paste it into your HubSpot app's webhook settings). Hit it and the bound method (`onHubSpotEvent`) fires on the resolved per-account integration instance.
+
+> **⚠️ Breaking:** extension routes used to mount un-namespaced (`/api/{x}-integration/webhooks`). They are now namespaced under the binding key. Any provider webhook already registered against the old path must be re-pointed at the new `/{bindingKey}` URL — and for signature schemes that sign the full URL (e.g. HubSpot v3), the old registration will also fail verification until updated.
+
+## `useDatabase` — does the receiver open a DB connection?
+
+Each extension declares whether its route handler should open a database connection:
+
+```javascript
+// in the extension bundle (api-module side)
+module.exports = {
+    name: 'hubspot-webhooks',
+    useDatabase: false,   // default — the receiver is DB-free
+    routes: [ /* ... */ ],
+    events: { /* ... */ },
+};
+```
+
+- **Default is `false`** — a webhook receiver that only verifies a signature and enqueues should not pay for a DB connection (faster cold start; at build time its Lambda doesn't get the Prisma layer).
+- Set `useDatabase: true` at the **extension level** if the receiver itself needs the DB. A binding may override it locally (`extensions: { x: { extension, useDatabase: true } }`), though that's rarely needed.
+- Resolution order: `binding.useDatabase ?? extension.useDatabase ?? false`.
+- Scope note: `false` is the default **for extension routes**. `createHandler` itself still defaults `shouldUseDatabase: true` for the integration's own catch-all handler and the legacy `Definition.webhooks: true` path — those connect as before. The `false` default applies only to the per-binding extension handler.
+
+If `useDatabase` is `false`, the receiver must not touch the database. Work that needs the DB (e.g. resolving `portalId → integrationId`) belongs in the queue worker that processes the dispatched event, not in the receiver.
 
 ## How handler binding works
 
@@ -84,7 +109,7 @@ This means **binding the same extension twice only works if the extension itself
 
 Subclass overrides via `this.events[eventName]` (set in the constructor) take precedence over extension-declared events. If a binding tried to wire a handler that's now shadowed, the framework logs a warning naming the integration, binding, and ignored method.
 
-Route path conflicts (two extensions declaring the same `method + path`, or an extension colliding with a `Definition.routes` entry) also throw at boot.
+**Routes do not collide across bindings** — each binding's routes are namespaced under its binding key (`/{bindingKey}{route.path}`), so two extensions can both declare `POST /webhooks` and live at distinct URLs. A route conflict only throws at boot if a *single* binding declares two routes with the same `method + path` (or a `Definition.routes` entry exactly matches an extension's namespaced path). Note this is independent of event-name conflicts above: namespacing disambiguates URLs, but two bindings still must use distinct **event** names since events are merged into one `this.events` map.
 
 ## Authoring an extension (for API module authors)
 

package/integrations/extension.js

@@ -70,6 +70,24 @@ function validateExtensionBinding(extension, bindingName, integrationName, bindi
         throw new Error(`${ctx}: extension is missing required "name" field`);
     }
 
+    if (
+        extension.useDatabase !== undefined &&
+        typeof extension.useDatabase !== 'boolean'
+    ) {
+        throw new Error(
+            `${ctx}: extension "${extension.name}" "useDatabase" must be a boolean`
+        );
+    }
+    if (
+        binding &&
+        binding.useDatabase !== undefined &&
+        typeof binding.useDatabase !== 'boolean'
+    ) {
+        throw new Error(
+            `${ctx}: binding "useDatabase" must be a boolean`
+        );
+    }
+
     const events = extension.events || {};
     if (typeof events !== 'object' || Array.isArray(events)) {
         throw new Error(
@@ -181,6 +199,8 @@ function getExtensionRoutes(IntegrationClass) {
             integrationName,
             binding
         );
+        const useDatabase =
+            binding.useDatabase ?? binding.extension.useDatabase ?? false;
         const routes = binding.extension.routes || [];
         for (const route of routes) {
             flat.push({
@@ -189,6 +209,7 @@ function getExtensionRoutes(IntegrationClass) {
                 path: route.path,
                 method: route.method,
                 event: route.event,
+                useDatabase,
             });
         }
     }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@friggframework/core",
     "prettier": "@friggframework/prettier-config",
-    "version": "2.0.0-next.88",
+    "version": "2.0.0-next.89",
     "dependencies": {
         "@aws-sdk/client-apigatewaymanagementapi": "^3.588.0",
         "@aws-sdk/client-kms": "^3.588.0",
@@ -38,9 +38,9 @@
         }
     },
     "devDependencies": {
-        "@friggframework/eslint-config": "2.0.0-next.88",
-        "@friggframework/prettier-config": "2.0.0-next.88",
-        "@friggframework/test": "2.0.0-next.88",
+        "@friggframework/eslint-config": "2.0.0-next.89",
+        "@friggframework/prettier-config": "2.0.0-next.89",
+        "@friggframework/test": "2.0.0-next.89",
         "@prisma/client": "^6.17.0",
         "@types/lodash": "4.17.15",
         "@typescript-eslint/eslint-plugin": "^8.0.0",
@@ -80,5 +80,5 @@
     "publishConfig": {
         "access": "public"
     },
-    "gitHead": "613b1c6f878086fadaf5a400c4227e4911a06d3e"
+    "gitHead": "19d4f89c10f2c0214fda28dbbd6c3bd83430da6b"
 }