@yarkivaev/scada 2.3.89 → 2.3.112

package/index.js

@@ -70,6 +70,7 @@ export { default as stompAlerts } from './src/infrastructure/messaging/stomp/ale
 export { default as stompAlertsInit } from './src/infrastructure/messaging/stomp/alerts/stompAlertsInit.js';
 export { default as mqttMetrics } from './src/infrastructure/ingest/mqtt/mqttMetrics.js';
 export { default as modbusMqtt } from './src/infrastructure/ingest/mqtt/modbusMqtt.js';
+export { default as modbusPublish } from './src/infrastructure/ingest/mqtt/modbusPublish.js';
 export { default as mx210Tcp } from './src/infrastructure/ingest/modbus/mx210Tcp.js';
 export { default as silentStreams } from './src/infrastructure/ingest/modbus/silentStreams.js';
 export { default as activityTracking } from './src/infrastructure/ingest/activity/activityTracking.js';
@@ -92,3 +93,12 @@ export { default as coverageSpans } from './src/domain/span/coverageSpans.js';
 export { default as coverageCursor } from './src/application/mcp/coverageCursor.js';
 export { default as sqlGuard } from './src/domain/sql/sqlGuard.js';
 export { default as analyticsMcp } from './src/application/mcp/analyticsMcp.js';
+export { default as expand } from './src/application/deploy/expand.js';
+export { default as readDocument } from './src/application/deploy/readDocument.js';
+export { default as mergeDocuments } from './src/application/deploy/mergeDocuments.js';
+export { default as releases } from './src/application/deploy/releases.js';
+export { default as paths } from './src/application/deploy/paths.js';
+export { default as appReleases } from './src/application/deploy/appReleases.js';
+export { default as withCollectors } from './src/application/deploy/withCollectors.js';
+export { default as pointPaths } from './src/application/deploy/pointPaths.js';
+export { clusterOf, serverFor } from './src/application/deploy/releaseNodes.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yarkivaev/scada",
-  "version": "2.3.89",
+  "version": "2.3.112",
   "description": "SCADA domain objects, state persistence, and plant monitoring",
   "repository": {
     "type": "git",
@@ -16,6 +16,7 @@
     "./package.json": "./package.json"
   },
   "bin": {
+    "modbus-to-mqtt": "./src/bin/modbus-to-mqtt.js",
     "supervisor-sink": "./src/bin/supervisor-sink.js"
   },
   "scripts": {
@@ -30,7 +31,7 @@
     "@clickhouse/client": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.24.3",
     "@yarkivaev/simple-server": "1.0.2",
-    "@yarkivaev/source-to-sink": "1.3.7",
+    "@yarkivaev/source-to-sink": "1.3.8",
     "amqplib": "^0.10.9",
     "pg": "^8.0.0",
     "stompit": "^1.0.0",
@@ -48,6 +49,7 @@
   },
   "files": [
     "index.js",
+    "charts/",
     "db/",
     "src/"
   ]

package/src/application/deploy/appReleases.js

@@ -0,0 +1,50 @@
+/**
+ * Values a profile app passes to its own chart.
+ *
+ * An app that already carries chart values keeps them. Otherwise the
+ * image, node port, and url are the values.
+ *
+ * @param {object} app - profile app
+ * @returns {object} chart values
+ * @example
+ *   valuesOf({ image: 'example.invalid/hmi:1', name: 'frontend', nodePort: 30080 });
+ */
+function valuesOf(app) {
+    if (app.values) {
+        return { ...app.values };
+    }
+    const values = {};
+    if (app.image) {
+        values.image = app.image;
+    }
+    if (app.nodePort) {
+        values.nodePort = app.nodePort;
+    }
+    if (app.url) {
+        values.url = app.url;
+    }
+    return values;
+}
+
+/**
+ * Helm releases for profile apps beside scada.
+ *
+ * The scada chart does not draw these. Each app is installed by its own
+ * chart into the same cluster.
+ *
+ * @example
+ *   appReleases([{ image: 'example.invalid/hmi:1', name: 'frontend' }], 'cell-a');
+ *
+ * @param {object[]} apps - releases().apps
+ * @param {string} cluster - release cluster
+ * @returns {object[]} chart releases
+ */
+export default function appReleases(apps, cluster) {
+    return (apps || []).map((app) => {
+        return {
+            chart: app.chart || app.name,
+            name: `${cluster}-${app.name}`,
+            values: valuesOf(app)
+        };
+    });
+}

package/src/application/deploy/applyIncludes.js

@@ -0,0 +1,31 @@
+import mergeDocuments from './mergeDocuments.js';
+
+/**
+ * Loads `include` entries, then overlays the rest of the document.
+ *
+ * @param {object} parsed - one parsed file
+ * @param {Function|undefined} load - file reader
+ * @param {string[]} stack - includes already being read
+ * @param {Function} read - document reader
+ * @returns {object} combined document
+ * @example
+ *   applyIncludes({ include: ['maps.yaml'] }, () => { return 'mappings: {}\n'; }, [], readDocument);
+ */
+export default function applyIncludes(parsed, load, stack, read) {
+    if (!Object.hasOwn(parsed, 'include')) {
+        return parsed;
+    }
+    if (typeof load !== 'function') {
+        throw new Error('system document include needs a reader');
+    }
+    const listed = Array.isArray(parsed.include) ? parsed.include : [parsed.include];
+    const rest = { ...parsed };
+    delete rest.include;
+    const catalog = listed.reduce((acc, name) => {
+        if (stack.includes(name)) {
+            throw new Error(`system document include cycles ${name}`);
+        }
+        return mergeDocuments(acc, read(load(name), load, stack.concat(name)));
+    }, {});
+    return mergeDocuments(catalog, rest);
+}

package/src/application/deploy/expand.js

@@ -0,0 +1,49 @@
+import { expandTree, treePaths } from './expandNamespace.js';
+import { expandProfiles } from './expandProfiles.js';
+import { expandServers } from './expandFlows.js';
+import frozen from './frozen.js';
+
+/**
+ * Rejects a server whose profile is missing.
+ *
+ * @param {object[]} servers - declared servers
+ * @param {object} profiles - resolved profiles
+ * @returns {void}
+ * @example
+ *   assertProfiles([], {});
+ */
+function assertProfiles(servers, profiles) {
+    servers.forEach((server) => {
+        const label = server.profile && server.profile.id;
+        if (!label || !profiles[label]) {
+            throw new Error(`system document has no profile ${label}`);
+        }
+    });
+}
+
+/**
+ * Expands templates, mappings, patterns, and profile `extends`.
+ *
+ * The result is a concrete document. It does not install a cluster.
+ *
+ * @param {object} document - system document
+ * @returns {object} expanded document
+ * @example
+ *   expand({ namespace: [{ id: 'mill' }], profiles: {}, servers: [] });
+ */
+export default function expand(document) {
+    if (!document || typeof document !== 'object' || Array.isArray(document)) {
+        throw new Error('system document is empty');
+    }
+    const namespace = expandTree(document.namespace, document.templates || {});
+    const paths = treePaths(namespace);
+    const profiles = expandProfiles(document.profiles || {});
+    assertProfiles(document.servers || [], profiles);
+    const servers = expandServers(document.servers || [], paths, document.mappings || {});
+    return frozen({
+        mappings: document.mappings || {},
+        namespace,
+        profiles,
+        servers
+    });
+}

package/src/application/deploy/expandDevices.js

@@ -0,0 +1,135 @@
+import { picked, zipped } from './expandPattern.js';
+
+/**
+ * Reads an object entry as a path.
+ *
+ * @param {string|object} entry - object path or record
+ * @returns {string} path
+ * @example
+ *   asPath('mill/unit');
+ */
+function asPath(entry) {
+    if (typeof entry === 'string' && entry.length > 0) {
+        return entry;
+    }
+    if (entry && typeof entry.id === 'string' && entry.id.length > 0) {
+        return entry.id;
+    }
+    throw new Error('system document object path is empty');
+}
+
+/**
+ * Rejects a flow name that is only an object path.
+ *
+ * @param {Array<string|object>} objects - server objects
+ * @param {string} path - flow name
+ * @returns {void}
+ * @example
+ *   assertLeaf(['mill/unit'], 'mill/unit/electrical');
+ */
+export function assertLeaf(objects, path) {
+    const listed = (objects || []).map((entry) => {
+        return asPath(entry);
+    });
+    if (listed.includes(path)) {
+        throw new Error(`system document flow name ${path} is an object path`);
+    }
+}
+
+/**
+ * Expands object patterns to namespace paths.
+ *
+ * @param {Array<string|object>|undefined} entries - declared objects
+ * @param {string[]} paths - namespace paths
+ * @returns {Array<string|object>} concrete objects
+ * @example
+ *   expandObjects(['mill/*'], ['mill/unit']);
+ */
+export function expandObjects(entries, paths) {
+    return (entries || []).flatMap((entry) => {
+        return picked(asPath(entry), paths, 'path', true).map((path) => {
+            if (typeof entry === 'string') {
+                return path;
+            }
+            return { ...entry, id: path };
+        });
+    });
+}
+
+/**
+ * Copies a mapping id or an inline map onto one flow.
+ *
+ * @param {object} flow - one flow
+ * @param {string[]} paths - namespace paths
+ * @param {object} mappings - shared point maps
+ * @returns {object} flow with a concrete map
+ * @example
+ *   withMapping({ mapping: 'drive', name: 'mill/electrical' }, [], {});
+ */
+function withMapping(flow, paths, mappings) {
+    if (!Object.hasOwn(flow, 'mapping')) {
+        return flow;
+    }
+    const token = flow.mapping;
+    const resolved = typeof token === 'string' ? mappings[token] : token;
+    if (!resolved || typeof resolved !== 'object' || Array.isArray(resolved)) {
+        const label = typeof token === 'string' ? token : 'inline';
+        throw new Error(`system document has no mapping ${label}`);
+    }
+    Object.keys(resolved).forEach((key) => {
+        if (!paths.includes(`${flow.name}/${key}`)) {
+            throw new Error(`system document mapping key ${key} is not under ${flow.name}`);
+        }
+    });
+    return { ...flow, mapping: { ...resolved } };
+}
+
+/**
+ * Pairs device addresses with expanded names.
+ *
+ * A fixed address is repeated. Brace groups of equal length zip together.
+ *
+ * @param {string[]} origins - expanded addresses
+ * @param {string[]} names - expanded names
+ * @returns {{from: string, name: string}[]} pairs
+ * @example
+ *   paired(['modbus://192.0.2.10:502'], ['mill/a', 'mill/b']);
+ */
+function paired(origins, names) {
+    if (origins.length === 1) {
+        return names.map((name) => {
+            return { from: origins[0], name };
+        });
+    }
+    if (names.length === 1) {
+        return origins.map((from) => {
+            return { from, name: names[0] };
+        });
+    }
+    if (origins.length !== names.length) {
+        throw new Error('system document braces differ in length');
+    }
+    return origins.map((from, index) => {
+        return { from, name: names[index] };
+    });
+}
+
+/**
+ * Expands one device fan-in against the namespace.
+ *
+ * @param {object} flow - device flow
+ * @param {string[]} paths - namespace paths
+ * @param {object} mappings - shared point maps
+ * @param {Array<string|object>} objects - server objects
+ * @returns {object[]} concrete flows
+ * @example
+ *   deviceFlows({ from: 'modbus://192.0.2.10:502', name: 'mill/*' }, ['mill/a'], {}, []);
+ */
+export function deviceFlows(flow, paths, mappings, objects) {
+    const names = picked(flow.name, paths, 'path', true);
+    const origins = zipped(flow.from);
+    return paired(origins, names).map((pair) => {
+        assertLeaf(objects, pair.name);
+        return withMapping({ ...flow, from: pair.from, name: pair.name }, paths, mappings);
+    });
+}

package/src/application/deploy/expandFlows.js

@@ -0,0 +1,281 @@
+import { assertLeaf, deviceFlows, expandObjects } from './expandDevices.js';
+import { isAddress, picked } from './expandPattern.js';
+
+/**
+ * Selects pattern matches, keeping a concrete name even when the pool lacks it.
+ *
+ * @param {string} pattern - flow name pattern
+ * @param {string[]} pool - candidate names
+ * @param {boolean} strict - whether a star that misses is an error
+ * @returns {string[]} names
+ * @example
+ *   chosen('mill/unit', ['mill/unit'], true);
+ */
+function chosen(pattern, pool, strict) {
+    if (!pattern.includes('*') && !pattern.includes('{')) {
+        if (pattern.split('/').some((part) => {
+            return part.length === 0;
+        })) {
+            throw new Error(`system document path ${pattern} has an empty segment`);
+        }
+        return [pattern];
+    }
+    return picked(pattern, pool, 'path', strict);
+}
+
+/**
+ * Names a source already sends to one receiver, or the streams it holds.
+ *
+ * @param {object} source - source draft
+ * @param {string} receiverId - receiver id
+ * @returns {string[]} candidate names
+ * @example
+ *   poolOf({ fanIn: [], fanOut: [] }, 'archive');
+ */
+function poolOf(source, receiverId) {
+    const aimed = source.fanOut.filter((flow) => {
+        return flow.to === receiverId;
+    }).map((flow) => {
+        return flow.name;
+    });
+    if (aimed.length > 0) {
+        return aimed;
+    }
+    return source.fanIn.map((flow) => {
+        return flow.name;
+    });
+}
+
+/**
+ * Expands fan-out to streams this server already has.
+ *
+ * A star does not add names from the rest of the namespace.
+ *
+ * @param {object} server - server draft
+ * @param {string[]} ids - server ids
+ * @param {boolean} strict - whether a miss is an error
+ * @returns {object[]} concrete fan-out
+ * @example
+ *   expandOut({ fanIn: [], objects: [], patternsOut: [] }, [], true);
+ */
+function expandOut(server, ids, strict) {
+    const rows = [];
+    const streams = server.fanIn.map((flow) => {
+        return flow.name;
+    });
+    server.patternsOut.forEach((flow) => {
+        const destinations = picked(flow.to, ids, 'server', true);
+        const names = picked(flow.name, streams, 'path', strict);
+        destinations.forEach((dest) => {
+            names.forEach((path) => {
+                assertLeaf(server.objects, path);
+                rows.push({ name: path, to: dest });
+            });
+        });
+    });
+    return rows;
+}
+
+/**
+ * Expands fan-in whose source is a server.
+ *
+ * Each matching server contributes its own outgoing names.
+ *
+ * @param {object} server - receiver draft
+ * @param {object[]} drafts - drafts with fan-out already expanded
+ * @param {boolean} strict - whether a star that misses is an error
+ * @returns {object[]} concrete fan-in
+ * @example
+ *   expandIn({ id: 'archive', objects: [], patternsIn: [] }, [], true);
+ */
+function expandIn(server, drafts, strict) {
+    const rows = [];
+    server.patternsIn.forEach((flow) => {
+        if (Object.hasOwn(flow, 'mapping')) {
+            throw new Error(`system document flow from ${flow.from} names a mapping`);
+        }
+        const sources = picked(flow.from, drafts.map((item) => {
+            return item.id;
+        }), 'server', true);
+        sources.forEach((sourceId) => {
+            const source = drafts.find((item) => {
+                return item.id === sourceId;
+            });
+            chosen(flow.name, poolOf(source, server.id), strict).forEach((path) => {
+                assertLeaf(server.objects, path);
+                const copy = { from: sourceId, name: path };
+                if (flow.api) {
+                    copy.api = flow.api;
+                }
+                rows.push(copy);
+            });
+        });
+    });
+    return rows;
+}
+
+/**
+ * Splits device fan-in from server fan-in.
+ *
+ * @param {object} server - declared server
+ * @param {string[]} paths - namespace paths
+ * @param {object} mappings - shared point maps
+ * @returns {object} server draft
+ * @example
+ *   draftOne({ fan_in: [], id: 'cell', profile: { id: 'cell' } }, [], {});
+ */
+function draftOne(server, paths, mappings) {
+    if (!server.profile || typeof server.profile.id !== 'string') {
+        throw new Error(`system document server ${server.id} has no profile`);
+    }
+    const local = [];
+    const objects = expandObjects(server.objects, paths);
+    const remote = [];
+    (server.fan_in || []).forEach((flow) => {
+        if (!flow.from) {
+            throw new Error(`system document server ${server.id} fan-in has no from`);
+        }
+        if (isAddress(flow.from)) {
+            deviceFlows(flow, paths, mappings, objects).forEach((item) => {
+                local.push(item);
+            });
+            return;
+        }
+        remote.push(flow);
+    });
+    return {
+        api: server.api,
+        fanIn: local,
+        id: server.id,
+        objects,
+        ownership: server.ownership,
+        patternsIn: remote,
+        patternsOut: server.fan_out || [],
+        profile: server.profile,
+        service: server.service
+    };
+}
+
+/**
+ * Recomputes fan-out and server fan-in from the streams held so far.
+ *
+ * @param {object[]} drafts - server drafts
+ * @param {boolean} strict - whether a miss is an error
+ * @returns {object[]} next drafts
+ * @example
+ *   wave([], false);
+ */
+function wave(drafts, strict) {
+    const ids = drafts.map((server) => {
+        return server.id;
+    });
+    const withOut = drafts.map((server) => {
+        return { ...server, fanOut: expandOut(server, ids, strict) };
+    });
+    return withOut.map((server) => {
+        const incoming = expandIn(server, withOut, strict);
+        const local = server.fanIn.filter((flow) => {
+            return isAddress(flow.from);
+        });
+        return { ...server, fanIn: local.concat(incoming) };
+    });
+}
+
+/**
+ * Fingerprints expanded flow names.
+ *
+ * @param {object[]} drafts - server drafts
+ * @returns {string} stable signature
+ * @example
+ *   signature([]);
+ */
+function signature(drafts) {
+    return JSON.stringify(drafts.map((server) => {
+        return {
+            fanIn: server.fanIn.map((flow) => {
+                return `${flow.from}|${flow.name}`;
+            }),
+            fanOut: (server.fanOut || []).map((flow) => {
+                return `${flow.to}|${flow.name}`;
+            })
+        };
+    }));
+}
+
+/**
+ * Copies a draft into a server record.
+ *
+ * @param {object} server - settled draft
+ * @returns {object} server
+ * @example
+ *   materialize({ fanIn: [], fanOut: [], id: 'cell', objects: [], profile: { id: 'cell' } });
+ */
+function materialize(server) {
+    const row = {
+        fan_in: server.fanIn,
+        fan_out: server.fanOut,
+        id: server.id,
+        objects: server.objects,
+        profile: server.profile
+    };
+    if (server.api) {
+        row.api = server.api;
+    }
+    if (server.ownership) {
+        row.ownership = server.ownership;
+    }
+    if (server.service) {
+        row.service = server.service;
+    }
+    return row;
+}
+
+/**
+ * Expands flows until forwarded names stop appearing.
+ *
+ * @param {object[]} drafts - initial drafts
+ * @returns {object[]} settled drafts
+ * @example
+ *   settle([]);
+ */
+function settle(drafts) {
+    let current = drafts;
+    const limit = drafts.length + 3;
+    let prior = '';
+    for (let turn = 0; turn < limit; turn += 1) {
+        const next = wave(current, false);
+        const sign = signature(next);
+        if (sign === prior) {
+            return wave(current, true);
+        }
+        prior = sign;
+        current = next;
+    }
+    throw new Error('system document flows did not settle');
+}
+
+/**
+ * Expands every server's objects, fan-in, and fan-out.
+ *
+ * @param {object[]} servers - declared servers
+ * @param {string[]} paths - namespace paths
+ * @param {object} mappings - shared point maps
+ * @returns {object[]} expanded servers
+ * @example
+ *   expandServers([], [], {});
+ */
+export function expandServers(servers, paths, mappings) {
+    const ids = servers.map((server) => {
+        return server.id;
+    });
+    ids.forEach((id, index) => {
+        if (ids.indexOf(id) !== index) {
+            throw new Error(`system document server ${id} is duplicated`);
+        }
+    });
+    return settle(servers.map((server) => {
+        return draftOne(server, paths, mappings);
+    })).map((server) => {
+        return materialize(server);
+    });
+}