@yarkivaev/scada 2.3.90 → 2.3.113

package/src/application/deploy/readDocument.js

@@ -0,0 +1,169 @@
+import applyIncludes from './applyIncludes.js';
+
+/**
+ * Parses one scalar token.
+ *
+ * @param {string} text - raw scalar
+ * @returns {string|number|boolean|null} scalar
+ */
+function scalar(text) {
+    const trimmed = text.trim();
+    if (trimmed === 'true') {
+        return true;
+    }
+    if (trimmed === 'false') {
+        return false;
+    }
+    if (trimmed === 'null') {
+        return null;
+    }
+    if (/^-?\d+$/u.test(trimmed)) {
+        return Number(trimmed);
+    }
+    if (trimmed.length > 1 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+
+/**
+ * Splits `key: value` on the first colon.
+ *
+ * @param {string} body - line without indent
+ * @returns {{key: string, rest: string}} key and remainder
+ */
+function splitKey(body) {
+    const mark = body.indexOf(':');
+    if (mark < 0) {
+        return { key: '', rest: body.trim() };
+    }
+    return { key: body.slice(0, mark).trim(), rest: body.slice(mark + 1).trim() };
+}
+
+/**
+ * Parses the block that starts at index.
+ *
+ * @param {Array<{indent: number, body: string}>} rows - content lines
+ * @param {number} index - first line
+ * @returns {{value: object|Array, next: number}} block and following index
+ */
+function block(rows, index) {
+    if (index >= rows.length) {
+        return { value: {}, next: index };
+    }
+    if (rows[index].body.startsWith('- ')) {
+        // eslint-disable-next-line no-use-before-define -- list and map call back into block
+        return list(rows, index);
+    }
+    // eslint-disable-next-line no-use-before-define -- list and map call back into block
+    return map(rows, index);
+}
+
+/**
+ * Parses a map whose keys share the indent of the first row.
+ *
+ * @param {Array<{indent: number, body: string}>} rows - content lines
+ * @param {number} index - first key
+ * @returns {{value: object, next: number}} map and following index
+ */
+function map(rows, index) {
+    const value = {};
+    const { indent } = rows[index];
+    let cursor = index;
+    while (cursor < rows.length && rows[cursor].indent === indent && !rows[cursor].body.startsWith('- ')) {
+        const piece = splitKey(rows[cursor].body);
+        if (piece.rest === '') {
+            const nested = block(rows, cursor + 1);
+            value[piece.key] = nested.value;
+            cursor = nested.next;
+        } else {
+            value[piece.key] = scalar(piece.rest);
+            cursor += 1;
+        }
+    }
+    return { value, next: cursor };
+}
+
+/**
+ * Parses a list whose items share the indent of the first row.
+ *
+ * @param {Array<{indent: number, body: string}>} rows - content lines
+ * @param {number} index - first item
+ * @returns {{value: Array, next: number}} list and following index
+ */
+function list(rows, index) {
+    const value = [];
+    const { indent } = rows[index];
+    let cursor = index;
+    while (cursor < rows.length && rows[cursor].indent === indent && rows[cursor].body.startsWith('- ')) {
+        // eslint-disable-next-line no-use-before-define -- item is the list element parser
+        const taken = item(rows, cursor, indent);
+        value.push(taken.value);
+        cursor = taken.next;
+    }
+    return { value, next: cursor };
+}
+
+/**
+ * Copies keys that sit under a list item after its first line.
+ *
+ * @param {Array<{indent: number, body: string}>} rows - content lines
+ * @param {number} cursor - first continuation line
+ * @param {number} indent - item indent
+ * @param {object} value - item being built
+ * @returns {number} index after those keys
+ */
+function siblings(rows, cursor, indent, value) {
+    if (cursor >= rows.length || rows[cursor].indent <= indent || rows[cursor].body.startsWith('- ')) {
+        return cursor;
+    }
+    const more = map(rows, cursor);
+    Object.assign(value, more.value);
+    return more.next;
+}
+
+/**
+ * Parses one list item, including keys on the following lines.
+ *
+ * @param {Array<{indent: number, body: string}>} rows - content lines
+ * @param {number} index - item line
+ * @param {number} indent - item indent
+ * @returns {{value: object|string|number|boolean|null, next: number}} item
+ */
+function item(rows, index, indent) {
+    const body = rows[index].body.slice(2);
+    const piece = splitKey(body);
+    if (piece.key === '') {
+        return { value: scalar(piece.rest), next: index + 1 };
+    }
+    const value = {};
+    if (piece.rest === '') {
+        const nested = block(rows, index + 1);
+        value[piece.key] = nested.value;
+        return { value, next: siblings(rows, nested.next, indent, value) };
+    }
+    value[piece.key] = scalar(piece.rest);
+    return { value, next: siblings(rows, index + 1, indent, value) };
+}
+
+/**
+ * Parses maps, lists, and scalars, then loads `include`.
+ *
+ * @example
+ *   readDocument('servers:\n  - id: cell\n');
+ *
+ * @param {string} text - document file contents
+ * @param {Function} [load] - reader for included file names
+ * @param {string[]} [stack] - includes already being read
+ * @returns {object} plain system document
+ */
+export default function readDocument(text, load, stack) {
+    const rows = [];
+    text.split('\n').forEach((raw) => {
+        if (raw.trim() !== '' && !raw.trimStart().startsWith('#')) {
+            const indent = raw.search(/\S/u);
+            rows.push({ indent, body: raw.slice(indent) });
+        }
+    });
+    return applyIncludes(block(rows, 0).value, load, stack || [], readDocument);
+}

package/src/application/deploy/releaseEdges.js

@@ -0,0 +1,185 @@
+import { isAddress } from './expandPattern.js';
+import { asPath, objectPath, serverById } from './releaseNodes.js';
+
+/**
+ * Compares two object lists without regard to order.
+ *
+ * @param {string[]} left - one side
+ * @param {string[]} right - the other side
+ * @returns {boolean} whether the lists name the same objects
+ * @example
+ *   sameObjects(['mill/a'], ['mill/a']);
+ */
+function sameObjects(left, right) {
+    const first = left.slice().sort();
+    const second = right.slice().sort();
+    return first.length === second.length && first.every((item, index) => {
+        return item === second[index];
+    });
+}
+
+/**
+ * Records one directed edge, rejecting a disagreeing second side.
+ *
+ * @param {object[]} edges - accumulated edges
+ * @param {object} edge - one side
+ * @returns {void}
+ * @example
+ *   remember([], { from: 'cell', object: 'unit', side: 'out', to: 'archive' });
+ */
+function remember(edges, edge) {
+    const 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.sides[edge.side] = prior;
+    found.objects = (found.sides.out || found.sides.in).slice();
+    if (edge.api) {
+        found.api = edge.api;
+    }
+}
+
+/**
+ * Collects fan-out and server fan-in as one edge list.
+ *
+ * @param {object} document - expanded document
+ * @returns {object[]} directed edges
+ * @example
+ *   edgesOf({ servers: [] });
+ */
+export function edgesOf(document) {
+    const edges = [];
+    (document.servers || []).forEach((server) => {
+        (server.fan_out || []).forEach((flow) => {
+            const dest = serverById(document, flow.to);
+            remember(edges, {
+                from: server.id,
+                object: objectPath(server, flow.name),
+                side: 'out',
+                to: dest.id
+            });
+        });
+        (server.fan_in || []).forEach((flow) => {
+            if (isAddress(flow.from)) {
+                return;
+            }
+            const source = serverById(document, flow.from);
+            remember(edges, {
+                api: flow.api,
+                from: source.id,
+                object: objectPath(source, flow.name),
+                side: 'in',
+                to: server.id
+            });
+        });
+    });
+    edges.forEach((edge) => {
+        const left = edge.sides.out;
+        const right = edge.sides.in;
+        if (left && right && !sameObjects(left, right)) {
+            throw new Error(`system document edge from ${edge.from} to ${edge.to} lists different objects`);
+        }
+        edge.objects = (left || right).slice();
+    });
+    return edges;
+}
+
+/**
+ * Reports whether a held path covers an object path.
+ *
+ * @param {string} held - path the server holds
+ * @param {string} objectId - object path
+ * @returns {boolean} true when one path covers the other
+ * @example
+ *   covers('mill/unit/electrical', 'mill/unit');
+ */
+function covers(held, objectId) {
+    return held === objectId || held.startsWith(`${objectId}/`) || objectId.startsWith(`${held}/`);
+}
+
+/**
+ * Lists telemetry and state paths a server holds directly.
+ *
+ * @param {object} server - candidate holder
+ * @returns {string[]} held paths
+ * @example
+ *   direct({ fan_in: [], id: 'cell' });
+ */
+function direct(server) {
+    const names = [];
+    (server.fan_in || []).forEach((flow) => {
+        if (isAddress(flow.from)) {
+            names.push(flow.name);
+        }
+    });
+    (server.ownership || []).forEach((entry) => {
+        names.push(asPath(entry));
+    });
+    (server.objects || []).forEach((entry) => {
+        names.push(asPath(entry));
+    });
+    return names;
+}
+
+/**
+ * Reports whether a server holds an object or receives it from someone who does.
+ *
+ * @param {object} document - expanded document
+ * @param {object[]} edges - directed edges
+ * @param {string} serverId - candidate holder
+ * @param {string} objectId - object path
+ * @param {string[]} stack - servers already visited
+ * @returns {boolean} whether the server holds the object
+ * @example
+ *   holds({ servers: [] }, [], 'cell', 'unit', []);
+ */
+function holds(document, edges, serverId, objectId, stack) {
+    const server = serverById(document, serverId);
+    if (direct(server).some((held) => {
+        return covers(held, objectId);
+    })) {
+        return true;
+    }
+    if (stack.includes(serverId)) {
+        throw new Error(`system document cycles ${objectId} at ${serverId}`);
+    }
+    const incoming = edges.filter((edge) => {
+        return edge.to === serverId && edge.objects.includes(objectId);
+    });
+    const next = stack.concat(serverId);
+    return incoming.some((edge) => {
+        return holds(document, edges, edge.from, objectId, next);
+    });
+}
+
+/**
+ * Rejects an edge whose source does not hold every listed object.
+ *
+ * @param {object} document - expanded document
+ * @param {object[]} edges - directed edges
+ * @returns {void}
+ * @example
+ *   assertHeld({ servers: [] }, []);
+ */
+export function assertHeld(document, edges) {
+    edges.forEach((edge) => {
+        edge.objects.forEach((objectId) => {
+            if (!holds(document, edges, edge.from, objectId, [])) {
+                throw new Error(`system document server ${edge.from} does not hold ${objectId}`);
+            }
+        });
+    });
+}

package/src/application/deploy/releaseNodes.js

@@ -0,0 +1,118 @@
+/**
+ * Reads an object entry as a path.
+ *
+ * @param {string|object} entry - object path or record
+ * @returns {string} path
+ * @example
+ *   asPath('mill/unit');
+ */
+export 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');
+}
+
+/**
+ * Finds the server object path that a flow name extends.
+ *
+ * @param {object} server - source server
+ * @param {string} name - flow name
+ * @returns {string} object path, or the flow name when none is declared
+ * @example
+ *   objectPath({ objects: ['mill/unit'] }, 'mill/unit/electrical');
+ */
+export function objectPath(server, name) {
+    const paths = (server.objects || []).map((entry) => {
+        return asPath(entry);
+    });
+    const found = paths.filter((path) => {
+        return name === path || name.startsWith(`${path}/`);
+    });
+    found.sort((left, right) => {
+        return right.length - left.length;
+    });
+    return found[0] || name;
+}
+
+/**
+ * Finds a server by id.
+ *
+ * @param {object} document - expanded document
+ * @param {string} id - server id
+ * @returns {object} server
+ * @example
+ *   serverById({ servers: [{ id: 'cell' }] }, 'cell');
+ */
+export function serverById(document, id) {
+    const found = (document.servers || []).find((server) => {
+        return server.id === id;
+    });
+    if (!found) {
+        throw new Error(`system document has no server ${id}`);
+    }
+    return found;
+}
+
+/**
+ * Reads the cluster a server selects.
+ *
+ * @param {object} document - expanded document
+ * @param {object} server - selected server
+ * @returns {string|null|undefined} cluster
+ * @example
+ *   clusterOf({ profiles: { cell: {} } }, { profile: { id: 'cell', variables: { cluster: 'cell' } } });
+ */
+export function clusterOf(document, server) {
+    const label = server.profile && server.profile.id;
+    const profile = document.profiles && document.profiles[label];
+    if (!profile) {
+        throw new Error(`system document has no profile ${label}`);
+    }
+    const values = { ...(profile.variables || {}), ...(server.profile.variables || {}) };
+    return values.cluster;
+}
+
+/**
+ * Finds the one server installed into a cluster.
+ *
+ * @param {object} document - expanded document
+ * @param {string} cluster - release selector
+ * @returns {object} server
+ * @example
+ *   serverFor({ profiles: {}, servers: [] }, 'missing');
+ */
+export function serverFor(document, cluster) {
+    const found = (document.servers || []).filter((server) => {
+        return clusterOf(document, server) === cluster;
+    });
+    if (found.length === 0) {
+        throw new Error(`system document has no server for cluster ${cluster}`);
+    }
+    if (found.length > 1) {
+        throw new Error(`system document has several servers for cluster ${cluster}`);
+    }
+    return found[0];
+}
+
+/**
+ * Loads the profile a server names, with server variables overlaid.
+ *
+ * @param {object} document - expanded document
+ * @param {object} server - selected server
+ * @returns {object} profile
+ * @example
+ *   profileFor({ profiles: { cell: {} } }, { profile: { id: 'cell' } });
+ */
+export function profileFor(document, server) {
+    const label = server.profile && server.profile.id;
+    const profile = document.profiles && document.profiles[label];
+    if (!profile) {
+        throw new Error(`system document has no profile ${label}`);
+    }
+    const values = { ...(profile.variables || {}), ...(server.profile.variables || {}) };
+    return { ...profile, variables: values };
+}

package/src/application/deploy/releaseValues.js

@@ -0,0 +1,200 @@
+import { isAddress } from './expandPattern.js';
+import { clusterOf, objectPath, serverById } from './releaseNodes.js';
+
+/**
+ * Maps one module name onto a chart product.
+ *
+ * @param {string} name - module name
+ * @param {object} spec - module spec
+ * @param {string|undefined} secret - state-store Secret name
+ * @returns {[string, object]} chart key and values
+ * @example
+ *   bindOne('telemetry_store', { enabled: true });
+ */
+function bindOne(name, spec, secret) {
+    if (name === 'state_store') {
+        return ['postgres', { enabled: spec.enabled !== false, secret: secret || 'scada-postgres' }];
+    }
+    if (name === 'message_bus') {
+        return ['rabbitmq', { enabled: spec.enabled !== false }];
+    }
+    if (name === 'telemetry_store') {
+        return ['clickhouse', { enabled: spec.enabled !== false }];
+    }
+    throw new Error(`system document has no module ${name}`);
+}
+
+/**
+ * Maps modules onto chart product keys.
+ *
+ * @param {object} profile - server profile
+ * @param {string|undefined} secret - state-store Secret name
+ * @returns {object} postgres, rabbitmq, and clickhouse fragments
+ * @example
+ *   bindModules({ modules: { telemetry_store: { enabled: true } } }, 'pg');
+ */
+export function bindModules(profile, secret) {
+    const values = {};
+    Object.keys(profile.modules || {}).forEach((name) => {
+        const [key, value] = bindOne(name, profile.modules[name], secret);
+        values[key] = value;
+    });
+    return values;
+}
+
+/**
+ * Opaque fields of an object record.
+ *
+ * @param {object} server - selected server
+ * @param {string} path - object path
+ * @returns {object} extra fields
+ * @example
+ *   recordFor({ objects: ['mill/unit'] }, 'mill/unit');
+ */
+function recordFor(server, path) {
+    const found = (server.objects || []).find((entry) => {
+        return typeof entry === 'object' && entry !== null && (entry.id === path || entry.path === path);
+    });
+    return found || {};
+}
+
+/**
+ * Local fan-in joined with the server's objects.
+ *
+ * @param {object} server - selected server
+ * @returns {object[]} machine records
+ * @example
+ *   machinesOf({ fan_in: [], id: 'cell' });
+ */
+export function machinesOf(server) {
+    const rows = [];
+    (server.fan_in || []).forEach((flow) => {
+        if (!isAddress(flow.from)) {
+            return;
+        }
+        const path = objectPath(server, flow.name);
+        const row = {
+            from: flow.from,
+            id: path.split('/').at(-1),
+            name: flow.name
+        };
+        if (flow.mapping) {
+            row.mapping = flow.mapping;
+        }
+        const extra = recordFor(server, path);
+        Object.keys(extra).forEach((key) => {
+            if (key !== 'id' && key !== 'path') {
+                row[key] = extra[key];
+            }
+        });
+        rows.push(row);
+    });
+    return rows;
+}
+
+/**
+ * Plant API URL of a source, when that source publishes one.
+ *
+ * @param {object} source - source server
+ * @param {string|undefined} api - service the edge names
+ * @returns {string} plant URL, or empty when the source publishes none
+ * @example
+ *   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 : '';
+}
+
+/**
+ * Sites for edges aimed at one server.
+ *
+ * `baseUrl` is the source plant API. A source with no plant API is skipped.
+ *
+ * @param {object} document - expanded document
+ * @param {object[]} edges - directed edges
+ * @param {object} server - receiver
+ * @returns {object[]} site entries
+ * @example
+ *   routesFor({ servers: [] }, [], { id: 'archive' });
+ */
+export function routesFor(document, edges, server) {
+    const routes = [];
+    edges.filter((edge) => {
+        return edge.to === server.id;
+    }).forEach((edge) => {
+        const source = serverById(document, edge.from);
+        const url = plantUrl(source, edge.api);
+        if (url.length === 0) {
+            return;
+        }
+        const machines = [];
+        edge.objects.forEach((path) => {
+            const id = path.split('/').at(-1);
+            if (!machines.includes(id)) {
+                machines.push(id);
+            }
+        });
+        routes.push({ baseUrl: url, machines });
+    });
+    return routes;
+}
+
+/**
+ * Bus bindings a fan-out opens on another cluster.
+ *
+ * @param {object} document - expanded document
+ * @param {object} server - sender
+ * @returns {{names: string[], url: string}[]} bus bindings
+ * @example
+ *   busesFor({ profiles: {}, servers: [] }, { fan_out: [], profile: { id: 'cell' } });
+ */
+export function busesFor(document, server) {
+    const mine = clusterOf(document, server);
+    const groups = new Map();
+    (server.fan_out || []).forEach((flow) => {
+        const dest = serverById(document, flow.to);
+        const other = clusterOf(document, dest);
+        if (other === mine) {
+            return;
+        }
+        if (!groups.has(other)) {
+            const bus = (dest.api || []).find((item) => {
+                return item.id === 'bus';
+            });
+            if (!bus) {
+                throw new Error(`system document server ${dest.id} provides no api bus`);
+            }
+            groups.set(other, { names: [], url: bus.url });
+        }
+        groups.get(other).names.push(flow.name);
+    });
+    return Array.from(groups.values());
+}
+
+/**
+ * Apps of a profile other than scada.
+ *
+ * @param {object} profile - resolved profile
+ * @returns {object[]} pass-through apps
+ * @example
+ *   passedApps({ apps: { frontend: { image: 'example.invalid/hmi:1' } } });
+ */
+export function passedApps(profile) {
+    return Object.keys(profile.apps || {}).filter((name) => {
+        return name !== 'scada';
+    }).map((name) => {
+        return { ...profile.apps[name], name };
+    });
+}