@lowdefy/api 5.6.0 → 6.0.0

package/dist/routes/websocket/authorizeWebsocket.js

@@ -0,0 +1,27 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { ConfigError } from '@lowdefy/errors';
+function authorizeWebsocket({ authorize, logger }, { websocketConfig }) {
+    if (!authorize(websocketConfig)) {
+        logger.debug({
+            event: 'debug_websocket_authorize',
+            authorized: false,
+            auth_config: websocketConfig.auth
+        });
+        // Same message as a missing websocket so channel existence does not leak.
+        throw new ConfigError(`Websocket "${websocketConfig.websocketId}" does not exist.`);
+    }
+}
+export default authorizeWebsocket;

package/dist/routes/websocket/createChannelRegistry.js

@@ -0,0 +1,269 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import crypto from 'crypto';
+import { serializer } from '@lowdefy/helpers';
+import { ConfigError, PluginError, ServiceError } from '@lowdefy/errors';
+import prepareChannel from './prepareChannel.js';
+const MAX_RETRIES = 5;
+const RETRY_BASE_MS = 1000;
+const HEALTHY_RESET_MS = 60 * 1000;
+// One registry per server process. The unit of sharing is the evaluated
+// subscription: subscribers whose evaluated connection and websocket
+// properties are identical join the same channel entry and share one running
+// source resolver. Sources start on the first subscriber and stop when the
+// last one leaves.
+function createChannelRegistry() {
+    const channels = new Map();
+    function getChannelKey({ connectionProperties, properties, websocketId }) {
+        const hash = crypto.createHash('sha1').update(serializer.serializeToString({
+            connectionProperties,
+            properties
+        })).digest('base64');
+        return `${websocketId}:${hash}`;
+    }
+    function broadcast(channel, frame) {
+        const message = JSON.stringify(frame);
+        channel.subscribers.forEach((subscriber)=>{
+            subscriber.send(message);
+        });
+    }
+    function wrapResolverError({ channel, error }) {
+        if (!error.configKey) {
+            error.configKey = channel.websocketConfig['~k'];
+        }
+        if (error.isLowdefyError) {
+            return error;
+        }
+        if (ServiceError.isServiceError(error)) {
+            return new ServiceError(undefined, {
+                cause: error,
+                service: channel.websocketConfig.connectionId ?? channel.websocketConfig.type,
+                configKey: channel.websocketConfig['~k']
+            });
+        }
+        return new PluginError(error.message, {
+            cause: error,
+            typeName: channel.websocketConfig.type,
+            received: channel.properties,
+            location: channel.websocketConfig.websocketId,
+            configKey: channel.websocketConfig['~k']
+        });
+    }
+    function removeChannel(channel) {
+        if (channel.restartTimer) {
+            clearTimeout(channel.restartTimer);
+            channel.restartTimer = null;
+        }
+        channel.abortController?.abort();
+        channels.delete(channel.key);
+    }
+    function handleResolverError({ channel, error, startedAt }) {
+        if (channel.abortController?.signal.aborted) {
+            // Errors thrown while winding down are expected (closed cursors, etc).
+            channel.logger.debug({
+                event: 'ws_source_stopped_error_ignored',
+                websocketId: channel.websocketId
+            }, error.message);
+            return;
+        }
+        const wrapped = wrapResolverError({
+            channel,
+            error
+        });
+        channel.logger.debug({
+            err: wrapped
+        }, wrapped.message);
+        channel.context.handleError(wrapped);
+        broadcast(channel, {
+            type: 'error',
+            websocketId: channel.websocketId,
+            message: wrapped.message
+        });
+        // A run that stayed healthy resets the backoff window.
+        if (Date.now() - startedAt > HEALTHY_RESET_MS) {
+            channel.retryCount = 0;
+        }
+        if (channel.retryCount >= MAX_RETRIES) {
+            channel.logger.error({
+                event: 'ws_source_max_retries',
+                websocketId: channel.websocketId
+            });
+            removeChannel(channel);
+            return;
+        }
+        const delay = RETRY_BASE_MS * 2 ** channel.retryCount;
+        channel.retryCount += 1;
+        channel.restartTimer = setTimeout(()=>{
+            channel.restartTimer = null;
+            // Subscribers may all have left while the restart was pending.
+            if (channel.subscribers.size === 0) {
+                removeChannel(channel);
+                return;
+            }
+            channel.logger.info({
+                event: 'ws_source_restart',
+                websocketId: channel.websocketId,
+                retryCount: channel.retryCount
+            });
+            startResolver(channel);
+        }, delay);
+    }
+    function startResolver(channel) {
+        const abortController = new AbortController();
+        channel.abortController = abortController;
+        const startedAt = Date.now();
+        function publish({ data }) {
+            if (abortController.signal.aborted) {
+                return;
+            }
+            broadcast(channel, {
+                type: 'message',
+                websocketId: channel.websocketId,
+                payload: serializer.serialize({
+                    data
+                })
+            });
+        }
+        channel.publish = publish;
+        Promise.resolve().then(()=>channel.resolver({
+                connection: channel.connectionProperties,
+                properties: channel.properties,
+                publish,
+                signal: abortController.signal,
+                logger: channel.logger
+            })).catch((error)=>handleResolverError({
+                channel,
+                error,
+                startedAt
+            }));
+    }
+    async function subscribe(context, { websocketId, payload, subscriber }) {
+        const { connectionProperties, properties, websocketConfig, websocketResolver } = await prepareChannel(context, {
+            websocketId,
+            payload
+        });
+        // One subscription per websocketId per connection — a re-subscribe (e.g.
+        // with a new payload) replaces the previous one.
+        if (subscriber.subscriptions.has(websocketId)) {
+            unsubscribe({
+                websocketId,
+                subscriber
+            });
+        }
+        const key = getChannelKey({
+            connectionProperties,
+            properties,
+            websocketId
+        });
+        let channel = channels.get(key);
+        if (!channel) {
+            channel = {
+                key,
+                websocketId,
+                websocketConfig,
+                resolver: websocketResolver,
+                connectionProperties,
+                properties,
+                subscribers: new Set(),
+                abortController: null,
+                restartTimer: null,
+                retryCount: 0,
+                publish: null,
+                context,
+                logger: context.logger
+            };
+            channels.set(key, channel);
+            startResolver(channel);
+        }
+        channel.subscribers.add(subscriber);
+        subscriber.subscriptions.set(websocketId, key);
+        context.logger.debug({
+            event: 'ws_subscribe',
+            websocketId,
+            subscribers: channel.subscribers.size
+        });
+    }
+    function unsubscribe({ websocketId, subscriber }) {
+        const key = subscriber.subscriptions.get(websocketId);
+        subscriber.subscriptions.delete(websocketId);
+        if (!key) {
+            return;
+        }
+        const channel = channels.get(key);
+        if (!channel) {
+            return;
+        }
+        channel.subscribers.delete(subscriber);
+        if (channel.subscribers.size === 0) {
+            removeChannel(channel);
+        }
+    }
+    function unsubscribeAll({ subscriber }) {
+        [
+            ...subscriber.subscriptions.keys()
+        ].forEach((websocketId)=>{
+            unsubscribe({
+                websocketId,
+                subscriber
+            });
+        });
+    }
+    async function publish(context, { websocketId, payload }) {
+        // Publish identity is evaluated without a subscription payload — channels
+        // that fragment on _payload/_user in properties are not publish targets.
+        const { connectionProperties, properties, websocketConfig, websocketResolver } = await prepareChannel(context, {
+            websocketId,
+            payload: {}
+        });
+        if (websocketResolver.meta?.publish !== true || properties.publish !== true) {
+            throw new ConfigError(`Websocket "${websocketId}" does not allow publishing.`, {
+                configKey: websocketConfig['~k']
+            });
+        }
+        const key = getChannelKey({
+            connectionProperties,
+            properties,
+            websocketId
+        });
+        const channel = channels.get(key);
+        // No channel means no subscribers on this instance — the publish is
+        // accepted and simply reaches nobody here.
+        if (!channel?.publish) {
+            return;
+        }
+        const data = serializer.deserialize(payload);
+        if (typeof websocketResolver.onPublish === 'function') {
+            await websocketResolver.onPublish({
+                data,
+                properties,
+                publish: channel.publish,
+                user: context.user
+            });
+            return;
+        }
+        channel.publish({
+            data
+        });
+    }
+    return {
+        publish,
+        subscribe,
+        unsubscribe,
+        unsubscribeAll,
+        // Exposed for tests and shutdown.
+        channels
+    };
+}
+export default createChannelRegistry;

package/dist/routes/websocket/createWebSocketConnection.js

@@ -0,0 +1,131 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { type } from '@lowdefy/helpers';
+// Wraps one client websocket connection: parses frames, dispatches
+// subscribe/unsubscribe/publish to the channel registry, and answers every
+// frame with an ack or an error so client actions never hang.
+function createWebSocketConnection(context, { registry, send }) {
+    const { logger } = context;
+    const subscriber = {
+        id: context.rid,
+        subscriptions: new Map(),
+        send
+    };
+    function sendError({ message, requestId, websocketId }) {
+        send(JSON.stringify({
+            type: 'error',
+            websocketId,
+            requestId,
+            message
+        }));
+    }
+    async function handleFrame(frame) {
+        const { payload, requestId, websocketId } = frame;
+        if (!type.isString(websocketId)) {
+            sendError({
+                message: 'Frame "websocketId" should be a string.',
+                requestId
+            });
+            return;
+        }
+        switch(frame.type){
+            case 'subscribe':
+                await registry.subscribe(context, {
+                    websocketId,
+                    payload,
+                    subscriber
+                });
+                send(JSON.stringify({
+                    type: 'subscribed',
+                    websocketId
+                }));
+                return;
+            case 'unsubscribe':
+                registry.unsubscribe({
+                    websocketId,
+                    subscriber
+                });
+                send(JSON.stringify({
+                    type: 'unsubscribed',
+                    websocketId
+                }));
+                return;
+            case 'publish':
+                await registry.publish(context, {
+                    websocketId,
+                    payload
+                });
+                send(JSON.stringify({
+                    type: 'published',
+                    websocketId,
+                    requestId
+                }));
+                return;
+            default:
+                // Unknown frame types are ignored for forward compatibility.
+                logger.debug({
+                    event: 'ws_unknown_frame',
+                    frameType: frame.type
+                });
+        }
+    }
+    async function handleMessage(raw) {
+        let frame;
+        try {
+            frame = JSON.parse(raw);
+        } catch (error) {
+            sendError({
+                message: 'Invalid frame — expected JSON.'
+            });
+            return;
+        }
+        if (!type.isObject(frame)) {
+            sendError({
+                message: 'Invalid frame — expected an object.'
+            });
+            return;
+        }
+        try {
+            await handleFrame(frame);
+        } catch (error) {
+            logger.debug({
+                err: error
+            }, error.message);
+            context.handleError(error);
+            sendError({
+                message: error.message,
+                requestId: frame.requestId,
+                websocketId: frame.websocketId
+            });
+        }
+    }
+    function close() {
+        registry.unsubscribeAll({
+            subscriber
+        });
+        logger.debug({
+            event: 'ws_disconnect'
+        });
+    }
+    logger.debug({
+        event: 'ws_connect'
+    });
+    return {
+        close,
+        handleMessage,
+        subscriber
+    };
+}
+export default createWebSocketConnection;

package/dist/routes/websocket/getWebsocketConfig.js

@@ -0,0 +1,30 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { ConfigError } from '@lowdefy/errors';
+async function getWebsocketConfig({ logger, readConfigFile }, { websocketId }) {
+    const websocketConfig = await readConfigFile(`websockets/${websocketId}.json`);
+    if (!websocketConfig) {
+        const err = new ConfigError(`Websocket "${websocketId}" does not exist.`);
+        logger.debug({
+            params: {
+                websocketId
+            },
+            err
+        }, err.message);
+        throw err;
+    }
+    return websocketConfig;
+}
+export default getWebsocketConfig;

package/dist/routes/websocket/getWebsocketResolver.js

@@ -0,0 +1,33 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { ConfigError } from '@lowdefy/errors';
+function getWebsocketResolver({ logger, websockets }, { websocketConfig }) {
+    const websocketResolver = (websockets ?? {})[websocketConfig.type];
+    if (!websocketResolver) {
+        const err = new ConfigError(`Websocket type "${websocketConfig.type}" can not be found.`, {
+            configKey: websocketConfig['~k']
+        });
+        logger.debug({
+            params: {
+                id: websocketConfig.websocketId,
+                type: websocketConfig.type
+            },
+            err
+        }, err.message);
+        throw err;
+    }
+    return websocketResolver;
+}
+export default getWebsocketResolver;

package/dist/routes/websocket/prepareChannel.js

@@ -0,0 +1,72 @@
+/*
+  Copyright 2020-2026 Lowdefy, Inc
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/ import { type } from '@lowdefy/helpers';
+import authorizeWebsocket from './authorizeWebsocket.js';
+import getConnection from '../connections/getConnection.js';
+import getConnectionConfig from '../connections/getConnectionConfig.js';
+import getWebsocketConfig from './getWebsocketConfig.js';
+import getWebsocketResolver from './getWebsocketResolver.js';
+import createEvaluateOperators from '../../context/createEvaluateOperators.js';
+// Shared preparation for subscribe and publish frames: load config, authorize,
+// resolve the websocket type, and evaluate server operators per subscription.
+// Properties are evaluated with the subscriber's payload and user, so the same
+// websocket definition can produce user- or filter-specific channels. The
+// evaluated result is the channel identity — subscribers whose evaluation is
+// identical share one running source.
+async function prepareChannel(context, { websocketId, payload }) {
+    context.evaluateOperators = createEvaluateOperators(context);
+    const websocketConfig = await getWebsocketConfig(context, {
+        websocketId
+    });
+    authorizeWebsocket(context, {
+        websocketConfig
+    });
+    const websocketResolver = getWebsocketResolver(context, {
+        websocketConfig
+    });
+    let connectionProperties = null;
+    if (!type.isNone(websocketConfig.connectionId)) {
+        const connectionConfig = await getConnectionConfig(context, {
+            connectionId: websocketConfig.connectionId,
+            configKey: websocketConfig['~k']
+        });
+        // Validates the connection type exists — resolver lookup is on the
+        // websocket type itself, not nested on the connection.
+        getConnection(context, {
+            connectionConfig
+        });
+        connectionProperties = context.evaluateOperators({
+            input: connectionConfig.properties ?? {},
+            location: connectionConfig.connectionId,
+            payload,
+            state: {},
+            steps: {}
+        });
+    }
+    const properties = context.evaluateOperators({
+        input: websocketConfig.properties ?? {},
+        location: websocketConfig.websocketId,
+        payload,
+        state: {},
+        steps: {}
+    });
+    return {
+        connectionProperties,
+        properties,
+        websocketConfig,
+        websocketResolver
+    };
+}
+export default prepareChannel;

package/dist/test/testContext.js

@@ -20,11 +20,12 @@ function testContext({ appMeta = {}, config = {}, configDirectory, connections =
     warn: ()=>{}
 }, operators = {
     _test: ()=>'test'
-}, readConfigFile, secrets = {}, session } = {}) {
+}, readConfigFile, secrets = {}, session, system } = {}) {
     return {
         appMeta,
         authorize: createAuthorize({
-            session
+            session,
+            system
         }),
         config,
         configDirectory,
@@ -43,6 +44,7 @@ function testContext({ appMeta = {}, config = {}, configDirectory, connections =
         secrets,
         session,
         steps: {},
+        system,
         user: session?.user
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lowdefy/api",
-  "version": "5.6.0",
+  "version": "6.0.0",
   "license": "Apache-2.0",
   "description": "",
   "homepage": "https://lowdefy.com",
@@ -34,18 +34,20 @@
     "dist/*"
   ],
   "dependencies": {
-    "@lowdefy/ajv": "5.6.0",
-    "@lowdefy/errors": "5.6.0",
-    "@lowdefy/helpers": "5.6.0",
-    "@lowdefy/node-utils": "5.6.0",
-    "@lowdefy/nunjucks": "5.6.0",
-    "@lowdefy/operators": "5.6.0",
-    "@lowdefy/operators-js": "5.6.0"
+    "@lowdefy/ajv": "6.0.0",
+    "@lowdefy/build": "6.0.0",
+    "@lowdefy/errors": "6.0.0",
+    "@lowdefy/helpers": "6.0.0",
+    "@lowdefy/node-utils": "6.0.0",
+    "@lowdefy/nunjucks": "6.0.0",
+    "@lowdefy/operators": "6.0.0",
+    "@lowdefy/operators-js": "6.0.0",
+    "@modelcontextprotocol/sdk": "1.29.0"
   },
   "devDependencies": {
     "@jest/globals": "28.1.3",
-    "@swc/cli": "0.8.0",
-    "@swc/core": "1.15.18",
+    "@swc/cli": "0.8.1",
+    "@swc/core": "1.15.32",
     "@swc/jest": "0.2.39",
     "jest": "28.1.3"
   },