@yarkivaev/scada 2.3.85 → 2.3.87

package/src/application/mcp/mcpResources.js

@@ -0,0 +1,106 @@
+/**
+ * Parent path of a node, or an empty string at the root.
+ *
+ * @param {string} path - namespace path
+ * @returns {string} parent path
+ *
+ * @example
+ *   parentOf('site/shop');
+ */
+function parentOf(path) {
+    const cut = path.lastIndexOf('/');
+    if (cut < 0) {
+        return '';
+    }
+    return path.slice(0, cut);
+}
+
+/**
+ * Topology resource body without source topics.
+ *
+ * @param {object} tree - namespaceTree
+ * @returns {Array<object>} nodes
+ *
+ * @example
+ *   topology(tree);
+ */
+function topology(tree) {
+    return tree.list().map((node) => {
+        return {
+            kind: node.kind,
+            liveness: node.silenceSeconds,
+            parent: parentOf(node.path),
+            path: node.path,
+            title: node.title
+        };
+    });
+}
+
+/**
+ * Binding resource body: path, source topic, and unit.
+ *
+ * @param {object} tree - namespaceTree
+ * @returns {Array<object>} bindings
+ *
+ * @example
+ *   bindings(tree);
+ */
+function bindings(tree) {
+    return tree.list().filter((node) => {
+        return typeof node.source === 'string';
+    }).map((node) => {
+        return {
+            path: node.path,
+            topic: node.source,
+            unit: typeof node.unit === 'string' ? node.unit : ''
+        };
+    });
+}
+
+/**
+ * JSON resource contents for one URI.
+ *
+ * @param {string} uri - resource URI
+ * @param {object} payload - JSON body
+ * @returns {object} read result
+ *
+ * @example
+ *   body('plant://topology', []);
+ */
+function body(uri, payload) {
+    return {
+        contents: [{
+            mimeType: 'application/json',
+            text: JSON.stringify(payload),
+            uri
+        }]
+    };
+}
+
+/**
+ * Registers plant topology and source bindings.
+ *
+ * Topology has paths, kinds, titles, and liveness. Bindings map a path to a
+ * topic and a unit. Gateway topics are not part of topology.
+ *
+ * @param {object} server - McpServer
+ * @param {object} tree - namespaceTree
+ * @returns {void}
+ *
+ * @example
+ *   registerResources(server, tree);
+ */
+export default function registerResources(server, tree) {
+    server.registerResource('topology', 'plant://topology', {
+        description: 'Paths, kinds, titles, and liveness',
+        mimeType: 'application/json'
+    }, () => {
+        return body('plant://topology', topology(tree));
+    });
+    server.registerResource('bindings', 'plant://bindings', {
+        description: 'Source topic and unit for each bound path',
+        mimeType: 'application/json'
+    }, () => {
+        return body('plant://bindings', bindings(tree));
+    });
+}

package/src/application/mcp/mcpText.js

@@ -0,0 +1,106 @@
+/**
+ * Caps a row list at the analytics response limit.
+ *
+ * @param {Array} rows - port rows
+ * @returns {{rows: Array, truncated: boolean}} capped rows
+ *
+ * @example
+ *   capRows([{ id: 1 }]);
+ */
+export function capRows(rows) {
+    const list = Array.isArray(rows) ? rows : [];
+    return {
+        rows: list.slice(0, 200),
+        truncated: list.length > 200
+    };
+}
+
+/**
+ * Wraps a payload as MCP text content.
+ *
+ * @param {object} payload - JSON payload
+ * @returns {object} tool result
+ *
+ * @example
+ *   toolText({ rows: [] });
+ */
+export function toolText(payload) {
+    return {
+        content: [{
+            text: JSON.stringify(payload),
+            type: 'text'
+        }]
+    };
+}
+
+/**
+ * Reads a point list from an array or a points field.
+ *
+ * @param {Array|object} raw - port payload
+ * @returns {Array} points
+ *
+ * @example
+ *   readPoints({ points: [1] });
+ */
+function readPoints(raw) {
+    if (Array.isArray(raw)) {
+        return raw;
+    }
+    if (raw && Array.isArray(raw.points)) {
+        return raw.points;
+    }
+    return [];
+}
+
+/**
+ * Reads the step the port actually used.
+ *
+ * @param {Array|object} raw - port payload
+ * @param {number} step - requested step seconds
+ * @returns {number} step seconds
+ *
+ * @example
+ *   readStep({ points: [], step: 30 }, 15);
+ */
+function readStep(raw, step) {
+    if (raw && typeof raw.step === 'number') {
+        return raw.step;
+    }
+    return step;
+}
+
+/**
+ * Keeps a truncated flag supplied by the port.
+ *
+ * @param {Array|object} raw - port payload
+ * @returns {boolean} whether the port already truncated
+ *
+ * @example
+ *   flagged({ truncated: true });
+ */
+function flagged(raw) {
+    if (raw && raw.truncated === true) {
+        return true;
+    }
+    return false;
+}
+
+/**
+ * Caps measurement points at 200 and reports the step.
+ *
+ * @param {Array|object} raw - port payload
+ * @param {number} step - requested step seconds
+ * @returns {object} points, step, truncated
+ *
+ * @example
+ *   capMeasurements([{ v: 1 }], 15);
+ */
+export function capMeasurements(raw, step) {
+    const points = readPoints(raw);
+    const truncated = points.length > 200 || flagged(raw);
+    return {
+        points: points.slice(0, 200),
+        step: readStep(raw, step),
+        truncated
+    };
+}

package/src/application/metricsPlant.js

@@ -1,7 +1,25 @@
 import plant from '../domain/plant/plant.js';
 import initialized from '../domain/shared/initialized.js';
+import pgAlerts from '../infrastructure/persistence/pg/alerts.js';
 import postgresPool from '../infrastructure/persistence/postgresPool.js';
 
+/**
+ * Plant extras: injected ports, or pgAlerts when a pool exists.
+ *
+ * @param {object} options - optional operations and alerts
+ * @param {object|undefined} pool - pg pool
+ * @returns {object} plant options
+ *
+ * @example
+ *   extras({ operations }, pool);
+ */
+function extras(options, pool) {
+    return {
+        operations: options.operations,
+        alerts: options.alerts || (pool ? pgAlerts(pool) : undefined)
+    };
+}
+
 /**
  * Generic plant factory wiring sensors and a shop factory over a connection.
  *
@@ -32,5 +50,5 @@ export default async function metricsPlant(machines, options) {
         segments: options.segments,
         shopName: options.shopName
     });
-    return plant(initialized({ [shop.name()]: shop }, Object.values));
+    return plant(initialized({ [shop.name()]: shop }, Object.values), extras(options, pool));
 }

package/src/application/shopWithTimeline.js

@@ -73,6 +73,13 @@ function writePort(name, decisions, owners) {
     }, owners)(name);
 }
 
+function demandWrite(name, decisions, owners) {
+    if (!decisions) {
+        throw new Error(`Timeline write requires userDecisions for ${name}`);
+    }
+    return writePort(name, decisions, owners);
+}
+
 function ownsLocal(owners, name) {
     if (!owners) {
         return true;
@@ -153,23 +160,23 @@ async function answer(scope, requestId, body, audit) {
 }
 
 /**
- * Builds a machine timeline from PostgreSQL persistence and STOMP user decisions.
+ * Builds a machine timeline from PostgreSQL when a pool exists.
  *
- * Optional owners registry routes retag/respond to an edge HTTP plant API.
+ * Reads do not need userDecisions. retag and respond throw without it.
+ * Optional owners registry routes those writes to an edge HTTP plant API.
  *
  * @param {string} name - machine id
- * @param {object} options - pool, userDecisions, optional owners
+ * @param {object} options - pool, optional userDecisions and owners
  * @returns {object} timeline port with list, rowAt, pending, stream, retag, respond, bus
  *
  * @example
- *   const tl = shopWithTimeline('machine1', { pool, userDecisions, owners });
+ *   const tl = shopWithTimeline('machine1', { pool });
  */
 export default function shopWithTimeline(name, options) {
     const { pool, userDecisions: decisions, owners, segments } = options;
-    if (pool && decisions) {
+    if (pool) {
         const bus = pubsub();
         const read = pgTimeline(pool, name);
-        const write = writePort(name, decisions, owners);
         const port = timeline(read, bus);
         return {
             list: port.list,
@@ -179,6 +186,7 @@ export default function shopWithTimeline(name, options) {
             stream: port.stream,
             bus,
             async retag(start, tags, properties, audit) {
+                const write = demandWrite(name, decisions, owners);
                 if (ownsLocal(owners, name)) {
                     await confirm(pool, {
                         machine: name,
@@ -192,6 +200,7 @@ export default function shopWithTimeline(name, options) {
                 bus.emit({ type: 'resolved', segment: resolvedStub(start, tags, properties), audit });
             },
             respond(requestId, body, audit) {
+                const write = demandWrite(name, decisions, owners);
                 return answer({ pool, owners, name, segments, write, bus }, requestId, body, audit);
             }
         };

package/src/domain/namespace/namespaceTree.js

@@ -0,0 +1,182 @@
+/**
+ * Reads a non-empty path.
+ *
+ * @param {object} node - candidate node
+ * @returns {string} path
+ *
+ * @example
+ *   pathOf({ path: 'site/unit' });
+ */
+function pathOf(node) {
+    if (typeof node.path === 'string' && node.path.length > 0) {
+        return node.path;
+    }
+    throw new Error('Namespace path is empty');
+}
+
+/**
+ * Requires a non-empty opaque kind.
+ *
+ * @param {object} node - candidate node
+ * @returns {string} kind
+ *
+ * @example
+ *   kindOf({ kind: 'metric', path: 'site/metric' });
+ */
+function kindOf(node) {
+    if (typeof node.kind === 'string' && node.kind.length > 0) {
+        return node.kind;
+    }
+    throw new Error(`Namespace kind is missing for ${pathOf(node)}`);
+}
+
+/**
+ * Requires a non-negative silence threshold in seconds.
+ *
+ * @param {object} node - candidate node
+ * @returns {number} silence seconds
+ *
+ * @example
+ *   silenceOf({ path: 'site', silenceSeconds: 60 });
+ */
+function silenceOf(node) {
+    const value = node.silenceSeconds;
+    if (typeof value === 'number' && value >= 0) {
+        return value;
+    }
+    throw new Error(`Namespace silence is missing for ${pathOf(node)}`);
+}
+
+/**
+ * Uses an explicit title or the last path segment.
+ *
+ * @param {object} node - candidate node
+ * @param {string} path - unique path
+ * @returns {string} display title
+ *
+ * @example
+ *   titled({ title: 'Unit' }, 'site/unit');
+ */
+function titled(node, path) {
+    if (typeof node.title === 'string' && node.title.length > 0) {
+        return node.title;
+    }
+    const parts = path.split('/');
+    return parts[parts.length - 1];
+}
+
+/**
+ * Copies one node into a frozen record.
+ *
+ * @param {object} node - candidate node
+ * @param {string} path - unique path
+ * @returns {object} frozen node
+ *
+ * @example
+ *   freezeNode({ kind: 'site', path: 'site', silenceSeconds: 30 }, 'site');
+ */
+function freezeNode(node, path) {
+    const frozen = {
+        kind: kindOf(node),
+        path,
+        silenceSeconds: silenceOf(node),
+        title: titled(node, path)
+    };
+    if (typeof node.source === 'string') {
+        frozen.source = node.source;
+    }
+    if (typeof node.unit === 'string') {
+        frozen.unit = node.unit;
+    }
+    return Object.freeze(frozen);
+}
+
+/**
+ * Builds a path map and rejects duplicates.
+ *
+ * @param {Array<object>} nodes - candidate nodes
+ * @returns {{ list: Array<object>, map: Map<string, object> }} index
+ *
+ * @example
+ *   indexNodes([{ kind: 'site', path: 'site', silenceSeconds: 30 }]);
+ */
+function indexNodes(nodes) {
+    const map = new Map();
+    for (const node of nodes) {
+        const path = pathOf(node);
+        if (map.has(path)) {
+            throw new Error(`Namespace path is duplicated: ${path}`);
+        }
+        map.set(path, freezeNode(node, path));
+    }
+    return { list: [...map.values()], map };
+}
+
+/**
+ * Returns the node for a path or throws when it is absent.
+ *
+ * @param {Map<string, object>} map - path index
+ * @param {string} path - requested path
+ * @returns {object} frozen node
+ *
+ * @example
+ *   lookup(new Map([['site', { path: 'site' }]]), 'site');
+ */
+function lookup(map, path) {
+    const node = map.get(path);
+    if (node) {
+        return node;
+    }
+    throw new Error(`Namespace path is missing: ${path}`);
+}
+
+/**
+ * Requires an array of nodes.
+ *
+ * @param {Array<object>} nodes - candidate nodes
+ * @returns {Array<object>} the same array when it is an array
+ *
+ * @example
+ *   nodesOf([{ kind: 'site', path: 'site', silenceSeconds: 30 }]);
+ */
+function nodesOf(nodes) {
+    if (Array.isArray(nodes)) {
+        return nodes;
+    }
+    throw new Error('Namespace nodes are missing');
+}
+
+/**
+ * Indexes plant nodes by a unique path for analytics reads.
+ *
+ * A node is an opaque kind, a silence threshold in seconds, and an optional
+ * source topic. Paths are the address. Gateway topics stay on the node and
+ * are not required.
+ *
+ * @param {Array<object>} nodes - path, kind, silenceSeconds, optional source, title, unit
+ * @returns {object} list, resolve, and below
+ *
+ * @example
+ *   const tree = namespaceTree([
+ *     { path: 'site/shop/unit', kind: 'unit', silenceSeconds: 60 }
+ *   ]);
+ *   tree.resolve('site/shop/unit').kind;
+ */
+export default function namespaceTree(nodes) {
+    const index = indexNodes(nodesOf(nodes));
+    return Object.freeze({
+        below(path) {
+            const node = lookup(index.map, path);
+            const prefix = `${node.path}/`;
+            return index.list.filter((item) => {
+                return item.path.startsWith(prefix);
+            });
+        },
+        list() {
+            return index.list.slice();
+        },
+        resolve(path) {
+            return lookup(index.map, path);
+        }
+    });
+}

package/src/domain/plant/plant.js

@@ -3,7 +3,7 @@
  * Provides initialization for all contained shops.
  *
  * @param {object} shops - initialized list of shops
- * @param {object} [options] - operations, topology
+ * @param {object} [options] - operations, alerts, topology
  * @returns {object} plant with shops property and init method
  *
  * @example
@@ -14,6 +14,7 @@ export default function plant(shops, options = {}) {
     return {
         shops,
         operations: options.operations,
+        alerts: options.alerts,
         topology: options.topology,
         init() {
             shops.init();