@lowdefy/api 5.5.1 → 6.0.0

package/dist/routes/page/dynamic/resolveDynamicContent.js

@@ -0,0 +1,172 @@
+/*
+  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 { ConfigError } from '@lowdefy/errors';
+import createEvaluateOperators from '../../../context/createEvaluateOperators.js';
+import invokeEndpoint from '../../endpoints/invokeEndpoint.js';
+import unescapeOperators from './unescapeOperators.js';
+import validateFragment from './validateFragment.js';
+const MAX_DYNAMIC_DEPTH = 5;
+function collectDynamicBlocks(block, found) {
+    if (block.type === 'Dynamic') {
+        // A Dynamic block's content comes from resolution; its fallback slot is
+        // resolved separately when a failure activates it.
+        found.push(block);
+        return;
+    }
+    Object.values(block.slots ?? {}).forEach((slot)=>{
+        (slot.blocks ?? []).forEach((child)=>collectDynamicBlocks(child, found));
+    });
+}
+function setResolvedContent(block, blocks) {
+    if (!block.slots) {
+        block.slots = {};
+    }
+    block.slots.content = {
+        ...block.slots.content ?? {},
+        blocks
+    };
+    delete block.slots.fallback;
+    delete block.properties.endpointId;
+    delete block.properties.params;
+    delete block.properties.required;
+    delete block.properties.types;
+}
+async function resolveBlocks(context, { blocks, depth, shared }) {
+    const found = [];
+    blocks.forEach((block)=>collectDynamicBlocks(block, found));
+    await Promise.all(found.map((block)=>resolveDynamicBlock(context, {
+            block,
+            depth,
+            shared
+        })));
+}
+async function resolveDynamicBlock(context, { block, depth, shared }) {
+    const { logger } = context;
+    const { endpointId, params, required } = block.properties;
+    try {
+        if (depth >= MAX_DYNAMIC_DEPTH) {
+            throw new ConfigError(`Dynamic block "${block.blockId}" on page "${shared.pageId}" exceeded the maximum dynamic nesting depth of ${MAX_DYNAMIC_DEPTH}.`, {
+                configKey: block['~k']
+            });
+        }
+        const { error, response, status } = await invokeEndpoint(context, {
+            endpointId,
+            payload: {
+                blockId: block.blockId,
+                pageId: shared.pageId,
+                params: params ?? {},
+                urlQuery: shared.urlQuery ?? {}
+            },
+            endpointDepth: 0
+        });
+        if ([
+            'error',
+            'reject'
+        ].includes(status)) {
+            throw error ?? new ConfigError(`Dynamic block "${block.blockId}" on page "${shared.pageId}" endpoint "${endpointId}" failed with status "${status}".`, {
+                configKey: block['~k']
+            });
+        }
+        if (!type.isObject(response) || !type.isArray(response.blocks)) {
+            throw new ConfigError(`Dynamic block "${block.blockId}" on page "${shared.pageId}" endpoint "${endpointId}" must return an object with a "blocks" array.`, {
+                received: response,
+                configKey: block['~k']
+            });
+        }
+        // Unescape before building so operator counting validates the real
+        // (client-evaluated) operators against the bundle.
+        const { blocks, callApiActionRefs, requestActionRefs, warnings } = shared.buildDynamicBlocks({
+            blocks: unescapeOperators(response.blocks),
+            pageId: shared.pageId,
+            dynamicBlockId: block.blockId,
+            idPrefix: block.id,
+            types: shared.types,
+            blockMetas: shared.blockMetas
+        });
+        warnings.forEach((warning)=>{
+            logger.warn({
+                event: 'dynamic_block_warning',
+                blockId: block.blockId,
+                pageId: shared.pageId
+            }, warning.message);
+        });
+        await validateFragment(context, {
+            blocks,
+            blockSchemas: shared.blockSchemas,
+            callApiActionRefs,
+            dynamicBlockId: block.blockId,
+            pageId: shared.pageId,
+            pageRequests: shared.pageRequests,
+            requestActionRefs
+        });
+        await resolveBlocks(context, {
+            blocks,
+            depth: depth + 1,
+            shared
+        });
+        setResolvedContent(block, blocks);
+    } catch (error) {
+        if (required === true) {
+            throw new ConfigError(`Dynamic block "${block.blockId}" on page "${shared.pageId}" failed to resolve: ${error.message}`, {
+                configKey: block['~k'],
+                cause: error
+            });
+        }
+        logger.error({
+            event: 'dynamic_block_error',
+            blockId: block.blockId,
+            endpointId,
+            pageId: shared.pageId,
+            err: error
+        }, `Dynamic block "${block.blockId}" on page "${shared.pageId}" failed to resolve: ${error.message}`);
+        const fallbackBlocks = block.slots?.fallback?.blocks ?? [];
+        setResolvedContent(block, fallbackBlocks);
+        await resolveBlocks(context, {
+            blocks: fallbackBlocks,
+            depth: depth + 1,
+            shared
+        });
+    }
+}
+async function resolveDynamicContent(context, { pageConfig, urlQuery }) {
+    // Loaded lazily so apps without dynamic pages never load the build package.
+    const { default: buildDynamicBlocks } = await import('@lowdefy/build/dynamic');
+    const [types, blockMetas, blockSchemas] = await Promise.all([
+        context.readConfigFile('types.json'),
+        context.readConfigFile('plugins/blockMetas.json'),
+        context.readConfigFile('plugins/blockSchemas.json')
+    ]);
+    context.evaluateOperators = createEvaluateOperators(context);
+    const shared = {
+        blockMetas: blockMetas ?? {},
+        blockSchemas: blockSchemas ?? {},
+        buildDynamicBlocks,
+        pageId: pageConfig.pageId,
+        pageRequests: pageConfig.requests ?? [],
+        types: types ?? {},
+        urlQuery
+    };
+    // The page root block itself can be a Dynamic block.
+    await resolveBlocks(context, {
+        blocks: [
+            pageConfig
+        ],
+        depth: 0,
+        shared
+    });
+    return pageConfig;
+}
+export default resolveDynamicContent;

package/dist/routes/page/dynamic/unescapeOperators.js

@@ -0,0 +1,36 @@
+/*
+  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';
+// One extra leading underscore defers operator evaluation by one level — the
+// same convention _function bodies use for __args. Shared operators like
+// _state are registered on the server, so a plain `_state` in a routine's
+// :return evaluates there (against empty routine state). Authors write
+// `__state` instead: it survives the server evaluation untouched, and this
+// unescape strips one underscore so the client evaluates the real operator.
+function unescapeOperators(value) {
+    if (type.isArray(value)) {
+        return value.map(unescapeOperators);
+    }
+    if (!type.isObject(value)) {
+        return value;
+    }
+    const result = {};
+    Object.keys(value).forEach((key)=>{
+        const unescapedKey = key.startsWith('__') ? key.slice(1) : key;
+        result[unescapedKey] = unescapeOperators(value[key]);
+    });
+    return result;
+}
+export default unescapeOperators;

package/dist/routes/page/dynamic/validateFragment.js

@@ -0,0 +1,104 @@
+/*
+  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 { validate } from '@lowdefy/ajv';
+import { getOperatorType, type } from '@lowdefy/helpers';
+import { ConfigError } from '@lowdefy/errors';
+function isOperatorObject(value) {
+    return getOperatorType(value) !== null;
+}
+function escapePointerSegment(segment) {
+    return segment.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+function collectOperatorPaths(value, path, paths) {
+    if (type.isArray(value)) {
+        value.forEach((item, index)=>collectOperatorPaths(item, `${path}/${index}`, paths));
+        return;
+    }
+    if (!type.isObject(value)) {
+        return;
+    }
+    if (isOperatorObject(value)) {
+        paths.push(path);
+        return;
+    }
+    Object.keys(value).forEach((key)=>{
+        if (key.startsWith('~')) return;
+        collectOperatorPaths(value[key], `${path}/${escapePointerSegment(key)}`, paths);
+    });
+}
+// A schema violation at or under an operator node cannot be judged before the
+// operator evaluates on the client — { _state: columns } may legitimately sit
+// where the schema wants an array. Violations on operator-free paths stand.
+function validateBlockProperties(block, { blockSchemas, dynamicBlockId, pageId }) {
+    const properties = block.properties;
+    if (!type.isObject(properties) || isOperatorObject(properties)) {
+        return;
+    }
+    // Block schemas validate the whole pre-build block shape; the plugin's
+    // properties schema sits at schema.properties.properties.
+    const propertiesSchema = blockSchemas[block.type]?.properties?.properties;
+    if (type.isNone(propertiesSchema)) {
+        return;
+    }
+    const result = validate({
+        schema: propertiesSchema,
+        data: properties,
+        returnErrors: true
+    });
+    if (result.valid) {
+        return;
+    }
+    const operatorPaths = [];
+    collectOperatorPaths(properties, '', operatorPaths);
+    const errors = result.errors.filter((error)=>!operatorPaths.some((path)=>error.instancePath === path || error.instancePath.startsWith(`${path}/`)));
+    if (errors.length > 0) {
+        const messages = errors.map((error)=>`properties${error.instancePath || ''} ${error.message}`);
+        throw new ConfigError(`Dynamic block "${dynamicBlockId}" on page "${pageId}" resolved block "${block.blockId}" (${block.type}) has invalid properties:\n${messages.map((message)=>`  - ${message}`).join('\n')}`);
+    }
+}
+function walkBlocks(blocks, callback) {
+    blocks.forEach((block)=>{
+        callback(block);
+        Object.values(block.slots ?? {}).forEach((slot)=>{
+            walkBlocks(slot.blocks ?? [], callback);
+        });
+    });
+}
+async function validateFragment(context, { blocks, blockSchemas, callApiActionRefs, dynamicBlockId, pageId, pageRequests, requestActionRefs }) {
+    walkBlocks(blocks, (block)=>{
+        validateBlockProperties(block, {
+            blockSchemas,
+            dynamicBlockId,
+            pageId
+        });
+    });
+    // Request actions can only reference requests defined statically on the page —
+    // request artifacts are written at build time.
+    const pageRequestIds = new Set(pageRequests.map((request)=>request.requestId));
+    requestActionRefs.forEach(({ requestId, blockId, eventId })=>{
+        if (!pageRequestIds.has(requestId)) {
+            throw new ConfigError(`Dynamic block "${dynamicBlockId}" on page "${pageId}" resolved content references request "${requestId}" on event "${eventId}" on block "${blockId}" which is not defined on the page.`);
+        }
+    });
+    // CallAPI refs fail resolution instead of the user's click — same checks the
+    // HTTP endpoint route applies.
+    await Promise.all(callApiActionRefs.map(async ({ endpointId, blockId, eventId })=>{
+        const endpointConfig = await context.readConfigFile(`api/${endpointId}.json`);
+        if (!endpointConfig || endpointConfig.type === 'InternalApi') {
+            throw new ConfigError(`Dynamic block "${dynamicBlockId}" on page "${pageId}" resolved content has a CallAPI action on event "${eventId}" on block "${blockId}" targeting endpoint "${endpointId}" which does not exist or is not accessible from client pages.`);
+        }
+    }));
+}
+export default validateFragment;

package/dist/routes/page/getPageConfig.js

@@ -13,14 +13,24 @@
   See the License for the specific language governing permissions and
   limitations under the License.
 */ import { serializer } from '@lowdefy/helpers';
-async function getPageConfig({ authorize, readConfigFile }, { pageId }) {
-    const pageConfig = await readConfigFile(`pages/${pageId}.json`);
-    if (pageConfig && authorize(pageConfig)) {
+import resolveDynamicContent from './dynamic/resolveDynamicContent.js';
+async function getPageConfig(context, { pageId, urlQuery }) {
+    const pageConfig = await context.readConfigFile(`pages/${pageId}.json`);
+    if (pageConfig && context.authorize(pageConfig)) {
         // eslint-disable-next-line no-unused-vars
         const { auth, ...rest } = pageConfig;
-        // Use serializer.serialize to ensure ~k keys (non-enumerable after deserialize)
-        // are made enumerable again for JSON transfer to client
-        return serializer.serialize(rest);
+        if (rest.dynamic !== true) {
+            // Use serializer.serialize to ensure ~k keys (non-enumerable after deserialize)
+            // are made enumerable again for JSON transfer to client
+            return serializer.serialize(rest);
+        }
+        // readConfigFile caches parsed artifacts — deep copy before resolution so
+        // one request's resolved content never reaches another via the cache.
+        const resolved = await resolveDynamicContent(context, {
+            pageConfig: serializer.copy(rest),
+            urlQuery
+        });
+        return serializer.serialize(resolved);
     }
     return null;
 }

package/dist/routes/request/callRequest.js

@@ -24,6 +24,7 @@ import getRequestConfig from './getRequestConfig.js';
 import getRequestResolver from './getRequestResolver.js';
 import validateSchemas from './validateSchemas.js';
 import createEvaluateOperators from '../../context/createEvaluateOperators.js';
+import redactResponse from '../../response/redactResponse.js';
 async function callRequest(context, { blockId, pageId, payload, requestId }) {
     const { logger } = context;
     context.blockId = blockId;
@@ -93,7 +94,7 @@ async function callRequest(context, { blockId, pageId, payload, requestId }) {
         id: requestConfig.id,
         success: true,
         type: requestConfig.type,
-        response: serializer.serialize(response)
+        response: redactResponse(context, response)
     };
 }
 export default callRequest;

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;