@yarkivaev/scada 2.3.114 → 2.3.116

package/charts/scada/templates/site-server.yaml

@@ -1,7 +1,8 @@
+{{- if .Values.site.enabled }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
-  name: {{ .Release.Name }}-site-server
+  name: {{ include "scada.prefix" . }}-site-server
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
@@ -70,7 +71,7 @@ spec:
 apiVersion: v1
 kind: Service
 metadata:
-  name: {{ .Release.Name }}-site-server
+  name: {{ include "scada.prefix" . }}-site-server
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
@@ -90,7 +91,7 @@ spec:
 apiVersion: v1
 kind: Service
 metadata:
-  name: {{ .Release.Name }}-site-server-plant-lan
+  name: {{ include "scada.prefix" . }}-site-server-plant-lan
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
@@ -105,3 +106,4 @@ spec:
   selector:
     {{- include "scada.match" (dict "app" "site-server" "ctx" .) | nindent 4 }}
 {{- end }}
+{{- end }}

package/charts/scada/templates/supervisor-sink.yaml

@@ -1,7 +1,8 @@
+{{- if .Values.sink.enabled }}
 apiVersion: apps/v1
 kind: Deployment
 metadata:
-  name: {{ .Release.Name }}-supervisor-sink
+  name: {{ include "scada.prefix" . }}-supervisor-sink
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
@@ -52,7 +53,7 @@ spec:
 apiVersion: v1
 kind: Service
 metadata:
-  name: {{ .Release.Name }}-supervisor-sink
+  name: {{ include "scada.prefix" . }}-supervisor-sink
   namespace: {{ .Release.Namespace }}
   labels:
     {{- include "scada.labels" . | nindent 4 }}
@@ -64,3 +65,4 @@ spec:
       targetPort: state
   selector:
     {{- include "scada.match" (dict "app" "supervisor-sink" "ctx" .) | nindent 4 }}
+{{- end }}

package/charts/scada/values.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "processes": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["name", "command"],
+        "properties": {
+          "name": { "type": "string", "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$" },
+          "command": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+          "env": { "type": "object", "additionalProperties": { "type": ["string", "number", "boolean"] } },
+          "hostDevices": {
+            "type": "array", "uniqueItems": true,
+            "items": { "type": "string", "pattern": "^/dev/([a-zA-Z0-9_-][a-zA-Z0-9_.-]*/)*[a-zA-Z0-9_-][a-zA-Z0-9_.-]*$" }
+          }
+        }
+      }
+    }
+  }
+}

package/charts/scada/values.yaml

@@ -1,4 +1,15 @@
 role: edge
+# Override the resource name prefix when adopting an existing installation.
+prefix: ""
+createNamespace: false
+site:
+  enabled: true
+sink:
+  enabled: true
+# Labels for workloads that must stay outside immutable selectors.
+workloadLabels: {}
+# Named deployments with command, env, optional resources and hostDevices.
+processes: []
 image: ""
 command: []
 pullSecret: ""
@@ -22,6 +33,16 @@ postgres:
 rabbitmq:
   enabled: true
   deadLetter: null
+  # A named standalone PVC replaces the default volumeClaimTemplates when set.
+  claimName: ""
+  configName: ""
+  rolloutOnConfigChange: false
+  definitions: null
+  plugins: [rabbitmq_stomp, rabbitmq_mqtt, rabbitmq_management]
+  extraConfig: {}
+  resources: {}
+  readinessProbe: {}
+  livenessProbe: {}
   image: rabbitmq:3.13-management
   storage: 5Gi
   storageClass: ""

package/index.js

@@ -96,9 +96,12 @@ 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 subscriptions } from './src/application/deploy/subscriptions.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';
+export { default as executeRelease } from './src/infrastructure/deploy/executeRelease.js';
+export { default as collectorProcesses } from './src/application/deploy/collectorProcesses.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yarkivaev/scada",
-  "version": "2.3.114",
+  "version": "2.3.116",
   "description": "SCADA domain objects, state persistence, and plant monitoring",
   "repository": {
     "type": "git",
@@ -13,7 +13,11 @@
     "./client": "./src/infrastructure/client/index.js",
     "./stateDataFake": "./src/infrastructure/persistence/stateDataFromMemory.js",
     "./startTestEdgeApi": "./src/infrastructure/http/edge/startTestEdgeApi.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./rabbitmq/definitions": "./src/infrastructure/messaging/rabbitmq/definitions.js",
+    "./rabbitmq/reconcile": "./src/infrastructure/messaging/rabbitmq/reconcile.js",
+    "./opcua": "./src/infrastructure/opcua/index.js",
+    "./opcua/config": "./src/infrastructure/opcua/config.js"
   },
   "bin": {
     "modbus-to-mqtt": "./src/bin/modbus-to-mqtt.js",
@@ -31,8 +35,9 @@
     "@clickhouse/client": "^1.0.0",
     "@modelcontextprotocol/sdk": "^1.24.3",
     "@yarkivaev/simple-server": "1.0.2",
-    "@yarkivaev/source-to-sink": "1.3.10",
+    "@yarkivaev/source-to-sink": "1.3.11",
     "amqplib": "^0.10.9",
+    "node-opcua": "2.179.0",
     "pg": "^8.0.0",
     "stompit": "^1.0.0",
     "zod": "^4.6.7"

package/src/application/deploy/collectorProcesses.js

@@ -0,0 +1,43 @@
+import { isDeepStrictEqual } from 'node:util';
+
+/** Group rows in first-seen order, keeping source order within each process. */
+function grouped(machines, describe) {
+    const groups = new Map();
+    const claimed = new Set();
+    for (const row of machines) {
+        if (claimed.has(row.name)) { throw new Error(`duplicate source ${row.name}`); }
+        claimed.add(row.name);
+        const descriptor = describe(row);
+        if (typeof descriptor?.name !== 'string' || !descriptor.name.trim()) {
+            throw new Error(`unassigned source ${row.name}`);
+        }
+        const group = groups.get(descriptor.name) || { descriptor, rows: [] };
+        if (!isDeepStrictEqual(group.descriptor, descriptor)) {
+            throw new Error(`conflicting descriptions for process ${descriptor.name}`);
+        }
+        group.rows.push(row);
+        groups.set(descriptor.name, group);
+    }
+    return [...groups.values()];
+}
+
+/**
+ * describe(row) returns a process descriptor with a name, command and optional
+ * env, resources and image. All sources describing the same process must agree.
+ * project(descriptor, rows) supplies adapter-specific env and optional hostDevices.
+ * A physical device may appear in many source rows but belongs to only one process.
+ */
+export default function collectorProcesses(machines, describe, project) {
+    const devices = new Set();
+    return grouped(machines, describe).map(({ descriptor, rows }) => {
+        const settings = project(descriptor, rows);
+        const hostDevices = [...new Set(settings.hostDevices || [])].sort();
+        hostDevices.forEach((device) => {
+            if (devices.has(device)) { throw new Error(`serial port or device ${device} is shared between processes`); }
+            devices.add(device);
+        });
+        return { name: descriptor.name, command: descriptor.command, env: { ...descriptor.env, ...settings.env },
+            hostDevices, resources: descriptor.resources,
+            ...(descriptor.image === undefined ? {} : { image: descriptor.image }) };
+    });
+}

package/src/application/deploy/expandFlows.js

@@ -1,4 +1,6 @@
 import { assertLeaf, deviceFlows, expandObjects } from './expandDevices.js';
+import { availableNames, expandApis, publishedNames } from './publishedStreams.js';
+import { serviceOf } from './releaseNodes.js';
 import { isAddress, picked } from './expandPattern.js';
 
 /**
@@ -32,18 +34,17 @@ function chosen(pattern, pool, strict) {
  * @example
  *   poolOf({ fanIn: [], fanOut: [] }, 'archive');
  */
-function poolOf(source, receiverId) {
+function poolOf(source, receiverId, api) {
+    const available = availableNames(source, api);
     const aimed = source.fanOut.filter((flow) => {
         return flow.to === receiverId;
     }).map((flow) => {
         return flow.name;
     });
     if (aimed.length > 0) {
-        return aimed;
+        return aimed.filter((name) => { return available.includes(name); });
     }
-    return source.fanIn.map((flow) => {
-        return flow.name;
-    });
+    return available;
 }
 
 /**
@@ -60,9 +61,7 @@ function poolOf(source, receiverId) {
  */
 function expandOut(server, ids, strict) {
     const rows = [];
-    const streams = server.fanIn.map((flow) => {
-        return flow.name;
-    });
+    const streams = availableNames(server);
     server.patternsOut.forEach((flow) => {
         const destinations = picked(flow.to, ids, 'server', true);
         const names = picked(flow.name, streams, 'path', strict);
@@ -76,6 +75,18 @@ function expandOut(server, ids, strict) {
     return rows;
 }
 
+/* A fixed object path can be held implicitly, but an API-only stream requires its service. */
+function incomingNames(source, receiver, flow, strict) {
+    const api = serviceOf(source, flow.api)?.id;
+    const pool = poolOf(source, receiver, api);
+    const names = chosen(flow.name, pool, strict);
+    if (strict && api && publishedNames(source).includes(flow.name)
+        && !availableNames(source, api).includes(flow.name)) {
+        throw new Error(`system document stream ${flow.name} is unavailable on api ${flow.api}`);
+    }
+    return names;
+}
+
 /**
  * Expands fan-in whose source is a server.
  *
@@ -101,7 +112,7 @@ function expandIn(server, drafts, strict) {
             const source = drafts.find((item) => {
                 return item.id === sourceId;
             });
-            chosen(flow.name, poolOf(source, server.id), strict).forEach((path) => {
+            incomingNames(source, server.id, flow, strict).forEach((path) => {
                 assertLeaf(server.objects, path);
                 const copy = { from: sourceId, name: path };
                 if (flow.api) {
@@ -144,7 +155,7 @@ function draftOne(server, paths, mappings) {
         remote.push(flow);
     });
     return {
-        api: server.api,
+        api: expandApis(server.api, paths, objects),
         fanIn: local,
         id: server.id,
         objects,

package/src/application/deploy/publishedStreams.js

@@ -0,0 +1,30 @@
+import { assertLeaf } from './expandDevices.js';
+import { picked } from './expandPattern.js';
+
+/** Resolve each API's published stream names, preserving its opaque contract metadata. */
+export function expandApis(apis, paths, objects) {
+    return apis?.map((api) => {
+        if (!api.publishes) { return api; }
+        const publishes = api.publishes.flatMap((entry) => {
+            return picked(entry.name, paths, 'path', true).map((name) => {
+                assertLeaf(objects, name);
+                return { ...entry, name };
+            });
+        });
+        return { ...api, publishes };
+    });
+}
+
+/** Streams made available by publishers on the selected service. */
+export function publishedNames(server, api) {
+    return (server.api || []).filter((item) => {
+        return !api || item.id === api;
+    }).flatMap((item) => {
+        return (item.publishes || []).map(({ name }) => { return name; });
+    });
+}
+
+/** Locally collected and forwarded streams stay available through the server's services. */
+export function availableNames(source, api) {
+    return [...new Set([...source.fanIn.map(({ name }) => { return name; }), ...publishedNames(source, api)])];
+}

package/src/application/deploy/releaseEdges.js

@@ -1,3 +1,4 @@
+import { publishedNames } from './publishedStreams.js';
 import { isAddress } from './expandPattern.js';
 import { asPath, objectPath, serverById } from './releaseNodes.js';
 
@@ -28,28 +29,22 @@ function sameObjects(left, right) {
  *   remember([], { from: 'cell', object: 'unit', side: 'out', to: 'archive' });
  */
 function remember(edges, edge) {
-    const found = edges.find((item) => {
+    let found = edges.find((item) => {
         return item.from === edge.from && item.to === edge.to;
     });
     if (!found) {
-        edges.push({
-            api: edge.api,
-            from: edge.from,
-            objects: [edge.object],
-            sides: { [edge.side]: [edge.object] },
-            to: edge.to
-        });
-        return;
-    }
-    const prior = found.sides[edge.side] ? found.sides[edge.side].slice() : [];
-    if (!prior.includes(edge.object)) {
-        prior.push(edge.object);
+        found = { from: edge.from, to: edge.to, sides: {}, streams: new Map() };
+        edges.push(found);
     }
-    found.sides[edge.side] = prior;
-    found.objects = (found.sides.out || found.sides.in).slice();
+    found.sides[edge.side] ||= [];
+    const objects = found.sides[edge.side];
+    if (!objects.includes(edge.object)) { objects.push(edge.object); }
+    const services = found.streams.get(edge.name) || new Set();
     if (edge.api) {
+        services.add(edge.api);
         found.api = edge.api;
     }
+    found.streams.set(edge.name, services);
 }
 
 /**
@@ -67,6 +62,7 @@ export function edgesOf(document) {
             const dest = serverById(document, flow.to);
             remember(edges, {
                 from: server.id,
+                name: flow.name,
                 object: objectPath(server, flow.name),
                 side: 'out',
                 to: dest.id
@@ -80,6 +76,7 @@ export function edgesOf(document) {
             remember(edges, {
                 api: flow.api,
                 from: source.id,
+                name: flow.name,
                 object: objectPath(source, flow.name),
                 side: 'in',
                 to: server.id
@@ -119,7 +116,7 @@ function covers(held, objectId) {
  *   direct({ fan_in: [], id: 'cell' });
  */
 function direct(server) {
-    const names = [];
+    const names = publishedNames(server);
     (server.fan_in || []).forEach((flow) => {
         if (isAddress(flow.from)) {
             names.push(flow.name);

package/src/application/deploy/releaseNodes.js

@@ -116,3 +116,16 @@ export function profileFor(document, server) {
     const values = { ...(profile.variables || {}), ...(server.profile.variables || {}) };
     return { ...profile, variables: values };
 }
+
+/** Selects an explicitly named service or the sole service of the source. */
+export function serviceOf(source, api) {
+    const listed = source.api || [];
+    if (!api && listed.length > 1) {
+        throw new Error(`system document server ${source.id} must name one api`);
+    }
+    const service = api ? listed.find((item) => { return item.id === api; }) : listed[0];
+    if (api && !service) {
+        throw new Error(`system document server ${source.id} provides no api ${api}`);
+    }
+    return service;
+}

package/src/application/deploy/releaseValues.js

@@ -1,5 +1,5 @@
 import { isAddress } from './expandPattern.js';
-import { clusterOf, objectPath, serverById } from './releaseNodes.js';
+import { clusterOf, objectPath, serverById, serviceOf } from './releaseNodes.js';
 
 /**
  * Maps one module name onto a chart product.
@@ -16,7 +16,7 @@ function bindOne(name, spec, secret) {
         return ['postgres', { enabled: spec.enabled !== false, secret: secret || 'scada-postgres' }];
     }
     if (name === 'message_bus') {
-        return ['rabbitmq', { enabled: spec.enabled !== false,
+        return ['rabbitmq', { ...spec.chart, enabled: spec.enabled !== false,
             ...(spec.dead_letter ? { deadLetter: spec.dead_letter } : {}) }];
     }
     if (name === 'telemetry_store') {
@@ -103,19 +103,8 @@ export function machinesOf(server) {
  *   plantUrl({ api: [{ id: 'plant', url: 'http://192.0.2.10/api/v1' }], id: 'cell' });
  */
 function plantUrl(source, api) {
-    const listed = source.api || [];
-    if (api && !listed.some((item) => {
-        return item.id === api;
-    })) {
-        throw new Error(`system document server ${source.id} provides no api ${api}`);
-    }
-    if (!api && listed.length > 1) {
-        throw new Error(`system document server ${source.id} must name one api`);
-    }
-    const plant = listed.find((item) => {
-        return item.id === 'plant';
-    });
-    return plant ? plant.url : '';
+    const service = serviceOf(source, api);
+    return service?.id === 'plant' ? service.url : '';
 }
 
 /**

package/src/application/deploy/releases.js

@@ -18,7 +18,8 @@ function withImage(profile) {
     if (!image) {
         throw new Error('system document has no scada image');
     }
-    return { image, ...bindModules(profile, app.secret) };
+    return { image, ...(app.site && { site: app.site }), ...(app.sink && { sink: app.sink }),
+        ...bindModules(profile, app.secret) };
 }
 
 /**
@@ -109,6 +110,7 @@ export default function releases(document, cluster) {
     const profile = profileFor(expanded, host);
     assertHeld(expanded, links);
     return frozen({
+        ...(profile.target && { target: profile.target }),
         apps: passedApps(profile),
         scada: scadaRelease(expanded, host, profile, links)
     });

package/src/application/deploy/subscriptions.js

@@ -0,0 +1,20 @@
+import { assertHeld, edgesOf } from './releaseEdges.js';
+import { serverById } from './releaseNodes.js';
+
+/**
+ * Lists directed stream subscriptions for a source server in an expanded document.
+ * A receiver may explicitly select a service. A sender-only declaration has none.
+ */
+export default function subscriptions(document, sourceId) {
+    serverById(document, sourceId);
+    const edges = edgesOf(document);
+    assertHeld(document, edges);
+    const rows = [];
+    for (const { from, to, streams } of edges.filter((edge) => { return edge.from === sourceId; })) {
+        for (const [name, services] of streams) {
+            if (!services.size) { rows.push({ from, to, name }); }
+            services.forEach((api) => { rows.push({ from, to, name, api }); });
+        }
+    }
+    return rows;
+}

package/src/infrastructure/deploy/executeRelease.js

@@ -0,0 +1,102 @@
+import { execFileSync } from 'node:child_process';
+
+/** Retire only explicit Deployments with a single exact app label selector. */
+function validateRetirements(plan) {
+    if (plan.retirements !== undefined && !Array.isArray(plan.retirements)) {
+        throw new Error('retirements must be an array');
+    }
+    for (const retirement of plan.retirements || []) {
+        const name = retirement?.workload?.match(/^deployment\/(?<name>[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?)$/u)?.groups.name;
+        const label = retirement?.selector?.match(/^app=(?<label>[A-Za-z0-9](?:[A-Za-z0-9_.-]*[A-Za-z0-9])?)$/u)?.groups.label;
+        if (!name || name.length > 253 || name.split('.').some((part) => { return !part || part.length > 63; })
+            || !label || label.length > 63 || (plan.workloads || []).includes(retirement.workload)) {
+            throw new Error('retirement requires an exact old deployment and app label outside desired workloads');
+        }
+    }
+}
+
+/** Validates the target before helm or kubectl can fall back to a default. */
+function validate(plan, action) {
+    if (!['render', 'check', 'diff', 'apply', 'adopt', 'check-adoption'].includes(action)) {
+        throw new Error('action must be render, check, diff or apply (adopt/check-adoption for migration)');
+    }
+    const fields = action === 'render' ? ['chart', 'release', 'namespace'] : ['chart', 'release', 'namespace', 'context', 'fieldManager'];
+    validateRetirements(plan);
+    fields.forEach((key) => {
+        if (typeof plan[key] !== 'string' || !plan[key].trim()) { throw new Error(`release requires ${key}`); }
+    });
+}
+
+/** Every Kubernetes command, including the post-rollout hook, shares this target. */
+function kubeAt(plan, execute) {
+    return (args, input, capture = false) => {
+        return execute('kubectl', ['--context', plan.context, '--namespace', plan.namespace, ...args],
+            { input, encoding: 'utf8', stdio: ['pipe', capture ? 'pipe' : 'inherit', 'inherit'] });
+    };
+}
+
+function applyWith(kube, manifests, flags, checkOnly) {
+    const args = ['apply', ...flags, '-f', '-'];
+    kube([...args, '--dry-run=server'], manifests);
+    if (!checkOnly) { kube(args, manifests); }
+}
+
+/** A missing Deployment can still have terminating pods from an interrupted attempt. */
+function retireWorkloads(plan, kube) {
+    for (const { workload, selector } of plan.retirements || []) {
+        if (kube(['get', workload, '--ignore-not-found', '-o', 'name'], undefined, true).trim()) {
+            kube(['delete', workload, '--cascade=foreground', '--wait=true', '--timeout=300s']);
+        }
+        if (kube(['get', 'pods', '-l', selector, '-o', 'name'], undefined, true).trim()) {
+            throw new Error(`retirement pods remain for ${workload} (${selector})`);
+        }
+    }
+}
+
+function preflightRetirements(plan, action, kube, manifests) {
+    if (['apply', 'adopt'].includes(action) && plan.retirements?.length) {
+        if (action === 'adopt') {
+            applyWith(kube, manifests, ['--field-manager=kubectl-client-side-apply'], true);
+        }
+        applyWith(kube, manifests, ['--server-side', `--field-manager=${plan.fieldManager}`], true);
+        retireWorkloads(plan, kube);
+    }
+}
+
+/** Adopt legacy fields, then enforce the complete manifest before waiting for rollouts. */
+function applyRelease(plan, action, kube, manifests) {
+    preflightRetirements(plan, action, kube, manifests);
+    if (['adopt', 'check-adoption'].includes(action)) {
+        applyWith(kube, manifests, ['--field-manager=kubectl-client-side-apply'], action === 'check-adoption');
+        if (action === 'check-adoption') { return ''; }
+    }
+    applyWith(kube, manifests, ['--server-side', `--field-manager=${plan.fieldManager}`], action === 'check');
+    if (action === 'check') { return ''; }
+    for (const workload of plan.workloads || []) {
+        kube(['rollout', 'status', workload, '--timeout=300s']);
+    }
+    plan.afterReady?.(plan, kube);
+    return '';
+}
+
+/**
+ * Renders a Helm release and executes the selected kubectl action synchronously.
+ * Supply chart, release, namespace and values. Cluster actions additionally require
+ * an explicit context and fieldManager. prerequisites and workloads are kubectl
+ * resource/name references. Optional retirements are { workload: "deployment/name",
+ * selector: "app=label" }; callers bind these to the old declarative app. They are
+ * removed after preflight and before any writes, with no selected pods remaining.
+ * afterReady(plan, kube) runs after a successful apply.
+ */
+export default function executeRelease(plan, action = 'render', execute = execFileSync) {
+    validate(plan, action);
+    const manifests = execute('helm', ['template', plan.release, plan.chart, '--namespace', plan.namespace, '-f', '-'],
+        { input: JSON.stringify(plan.values), encoding: 'utf8' });
+    if (action === 'render') { return manifests; }
+    const kube = kubeAt(plan, execute);
+    for (const resource of plan.prerequisites || []) { kube(['get', resource, '-o', 'name']); }
+    if (action === 'diff') {
+        return kube(['diff', '--server-side', `--field-manager=${plan.fieldManager}`, '-f', '-'], manifests);
+    }
+    return applyRelease(plan, action, kube, manifests);
+}