@yarkivaev/scada 1.5.0 → 2.3.45

package/src/infrastructure/messaging/stomp/alerts/stompAlertsLogic.js

@@ -0,0 +1,51 @@
+/**
+ * Shared alert record helpers for STOMP-backed alert history.
+ */
+
+/**
+ * @param {object} translations - map of rule names to messages
+ * @param {string} name - rule identifier
+ * @returns {string} translated message or original name
+ */
+function translate(translations, name) {
+    return translations[name] || name;
+}
+
+/**
+ * @param {object} fields - alert field values
+ * @returns {object} normalized alert
+ */
+export function build({ id, message, timestamp, machine, acknowledged, name }) {
+    return {
+        id: String(id),
+        message,
+        timestamp: timestamp instanceof Date ? timestamp : new Date(timestamp),
+        object: machine,
+        event: undefined,
+        acknowledged,
+        name
+    };
+}
+
+/**
+ * @param {object} raw - STOMP frame
+ * @param {object} state - shared mutable state
+ * @param {object} translations - rule name map
+ */
+export function consume(raw, state, translations) {
+    const parsed = JSON.parse(raw.payload);
+    if (parsed.status === 'pending') {
+        state.counter += 1;
+        const alert = build({ id: state.counter, message: translate(translations, parsed.name), timestamp: new Date(parsed.start * 1000), machine: parsed.machine, acknowledged: false, name: parsed.name });
+        state.items.push(alert);
+        state.bus.emit({ type: 'created', alert });
+    } else if (parsed.status === 'completed') {
+        state.items.forEach((existing, index) => {
+            if (existing.name === parsed.name && existing.object === parsed.machine && !existing.acknowledged) {
+                const replaced = build({ id: existing.id, message: existing.message, timestamp: existing.timestamp, machine: existing.object, acknowledged: true, name: existing.name });
+                state.items[index] = replaced;
+                state.bus.emit({ type: 'acknowledged', alert: replaced });
+            }
+        });
+    }
+}

package/src/infrastructure/messaging/stomp/stompTimelineSegments.js

@@ -0,0 +1,80 @@
+function timestamps(parsed) {
+    const startTime = new Date(parsed.start);
+    const endTime = new Date(parsed.end);
+    if (Number.isNaN(startTime.getTime()) || Number.isNaN(endTime.getTime())) {
+        throw new Error('Invalid segment timestamp');
+    }
+    return { startTime, endTime };
+}
+
+function mapTags(parsed) {
+    if (parsed.tags === undefined || parsed.tags === null) {
+        return undefined;
+    }
+    return typeof parsed.tags === 'string' ? parsed.tags : JSON.stringify(parsed.tags);
+}
+
+function mapProperties(parsed) {
+    if (parsed.properties === undefined) {
+        return undefined;
+    }
+    return typeof parsed.properties === 'string' ? parsed.properties : JSON.stringify(parsed.properties);
+}
+
+function segmentRow(parsed, startTime, endTime) {
+    const row = {
+        name: parsed.name,
+        start_time: startTime,
+        end_time: endTime,
+        duration: parsed.duration
+    };
+    if (parsed.options !== undefined) {
+        row.options = parsed.options;
+    }
+    const tags = mapTags(parsed);
+    if (tags !== undefined) {
+        row.tags = tags;
+    }
+    const properties = mapProperties(parsed);
+    if (properties !== undefined) {
+        row.properties = properties;
+    }
+    return row;
+}
+
+function consume(raw, buses) {
+    const parsed = JSON.parse(raw.payload);
+    const bus = buses[parsed.machine];
+    if (!bus) {
+        return;
+    }
+    const { startTime, endTime } = timestamps(parsed);
+    bus.emit({ type: 'created', segment: segmentRow(parsed, startTime, endTime) });
+}
+
+/**
+ * STOMP-to-timeline-bus bridge for segment messages.
+ *
+ * Subscribes to STOMP segment exchange and emits created events
+ * on per-machine timeline pubsub buses for SSE delivery.
+ *
+ * @param {function} source - factory(collector) returning { start(), stop() }
+ * @param {object} buses - map of machine IDs to pubsub buses with emit()
+ * @returns {object} bridge with stop() method
+ *
+ * @example
+ *   const bridge = stompTimelineSegments(sourceFactory, { m1: bus });
+ *   bridge.stop();
+ */
+export default function stompTimelineSegments(source, buses) {
+    const subscription = source({
+        accept(raw) {
+            consume(raw, buses);
+        }
+    });
+    return {
+        stop() {
+            subscription.stop();
+        }
+    };
+}

package/src/infrastructure/messaging/stomp/timeline.js

@@ -0,0 +1,21 @@
+/**
+ * STOMP-backed timeline write port for one machine.
+ *
+ * @param {object} decisions - userDecisions with publish(machine, start, tags, properties, audit)
+ * @param {string} machineId - machine identifier
+ * @returns {object} timeline write port with retag and respond
+ *
+ * @example
+ *   const stomp = stompTimeline(decisions, 'm1');
+ *   await stomp.retag(new Date(), ['on'], {}, audit);
+ */
+export default function stompTimeline(decisions, machineId) {
+    return {
+        async retag(start, tags, properties, audit) {
+            await decisions.publish(machineId, start, tags, properties, audit);
+        },
+        async respond(start, tags, properties, audit) {
+            await decisions.publish(machineId, start, tags, properties, audit);
+        }
+    };
+}

package/src/infrastructure/messaging/stomp/userDecisionBody.js

@@ -0,0 +1,25 @@
+/**
+ * Builds a user_decisions STOMP payload for supervisor DecisionMessage.Resolve.
+ *
+ * @param {string} machine - machine id
+ * @param {Date} start - segment start time
+ * @param {string[]} tags - selected tags
+ * @param {object} properties - segment properties
+ * @param {object} audit - displayName, id, decidedAt
+ * @returns {object} JSON body for stompSend
+ */
+export default function userDecisionBody(machine, start, tags, properties, audit) {
+    const epoch = start.getTime() / 1000;
+    const body = {
+        machine,
+        start: epoch,
+        user: audit.displayName,
+        tags: tags || [],
+        properties: properties || {},
+        decided_at: audit.decidedAt.getTime() / 1000
+    };
+    if (audit.id !== undefined && audit.id !== null) {
+        body.operator_id = audit.id;
+    }
+    return body;
+}

package/src/infrastructure/messaging/stomp/userDecisions.js

@@ -0,0 +1,42 @@
+import { stompSend } from '@yarkivaev/source-to-sink';
+import userDecisionBody from './userDecisionBody.js';
+
+const DEFAULT_DESTINATION = '/exchange/scada.user_decisions';
+
+/**
+ * Publishes operator tag decisions to RabbitMQ for Scala supervisor.
+ *
+ * @param {object} config - publisher configuration
+ * @param {string} config.stompUrl - STOMP broker URL
+ * @param {string} [config.destination] - STOMP destination
+ * @param {string} [config.login] - STOMP login
+ * @param {string} [config.passcode] - STOMP passcode
+ * @param {string} [config.host] - STOMP vhost header
+ * @returns {object} publisher with publish(machine, start, tags, properties, audit)
+ */
+export default function userDecisions(config) {
+    if (!config.stompUrl) {
+        throw new Error('stompUrl is required for user decision publisher');
+    }
+    const destination = config.destination || DEFAULT_DESTINATION;
+    const stompOptions = {
+        login: config.login,
+        passcode: config.passcode,
+        host: config.host
+    };
+    return {
+        /**
+         * Publishes one operator decision to STOMP.
+         *
+         * @param {string} machine - machine id
+         * @param {Date} start - segment start
+         * @param {string[]} tags - selected tags
+         * @param {object} properties - segment properties
+         * @param {object} audit - id, displayName, decidedAt
+         */
+        async publish(machine, start, tags, properties, audit) {
+            const body = userDecisionBody(machine, start, tags, properties, audit);
+            await stompSend(config.stompUrl, destination, body, stompOptions);
+        }
+    };
+}

package/src/infrastructure/operators/centralOperators.js

@@ -0,0 +1,64 @@
+import operator from '../../domain/operator/operator.js';
+import operatorExtras, { operatorIdentityKeys } from './operatorExtras.js';
+
+function operatorFromJson(row) {
+    if (row.id === undefined || row.id === null) {
+        throw new Error('central operators item missing id');
+    }
+    if (!row.cardUid) {
+        throw new Error('central operators item missing cardUid');
+    }
+    if (!row.firstName) {
+        throw new Error('central operators item missing firstName');
+    }
+    if (!row.lastName) {
+        throw new Error('central operators item missing lastName');
+    }
+    if (!row.displayName) {
+        throw new Error('central operators item missing displayName');
+    }
+    return {
+        ...operator(row.id, row.cardUid, row.firstName, row.lastName, row.displayName),
+        ...operatorExtras(row, operatorIdentityKeys())
+    };
+}
+
+/**
+ * Central plant operator catalog via HTTP (/api/v1/operators).
+ * Supports pull for sync, create for edge proxy writes, and enabled for registration flag.
+ *
+ * @param {object} client - HTTP client with getJson(path, query) and postJson(path, body)
+ * @param {string} basePath - plant API base path
+ * @returns {object} source with pull(), create(fields), enabled()
+ *
+ * @example
+ *   const source = centralOperators(stateHttpClient({ baseUrl: 'http://central:3000' }), '/api/v1');
+ *   const rows = await source.pull();
+ *   const flag = await source.enabled();
+ */
+export default function centralOperators(client, basePath) {
+    return {
+        async pull() {
+            const payload = await client.getJson(`${basePath}/operators`, {});
+            if (!payload || !Array.isArray(payload.items)) {
+                throw new Error(`central operators response missing items array from ${basePath}/operators`);
+            }
+            return payload.items.map((row) => {
+                return operatorFromJson(row);
+            });
+        },
+        async create(fields) {
+            const row = await client.postJson(`${basePath}/operators`, fields);
+            return operatorFromJson(row);
+        },
+        async enabled() {
+            const payload = await client.getJson(`${basePath}/operators/registration-enabled`, {});
+            if (!payload || typeof payload.enabled !== 'boolean') {
+                throw new Error(
+                    `central registration-enabled response missing enabled boolean from ${basePath}/operators/registration-enabled`
+                );
+            }
+            return payload.enabled;
+        }
+    };
+}

package/src/infrastructure/operators/edgeOperators.js

@@ -0,0 +1,39 @@
+/**
+ * Edge operators provider: local cache for reads, central proxy for create.
+ * Registration flag writes are central-only; edge returns 405 on permit.
+ *
+ * @param {object} cache - in-memory operators with list, replace, enabled, permit
+ * @param {object} [source] - centralOperators with create and pull, or undefined
+ * @returns {object} provider with list, create, enabled, permit
+ *
+ * @example
+ *   const provider = edgeOperators(operators(), centralOperators(client, '/api/v1'));
+ *   await provider.create({ cardUid: 'AB12', firstName: 'Ivan', lastName: 'Petrov', displayName: 'Ivan Petrov' });
+ */
+export default function edgeOperators(cache, source) {
+    return {
+        list() {
+            return cache.list();
+        },
+        async create(fields) {
+            if (!source) {
+                const err = new Error('CENTRAL_PLANT_URL is required for edge operator create');
+                err.routeCode = 'SERVICE_UNAVAILABLE';
+                err.routeStatus = 503;
+                throw err;
+            }
+            const created = await source.create(fields);
+            cache.replace(await source.pull());
+            return created;
+        },
+        enabled() {
+            return cache.enabled();
+        },
+        permit() {
+            const err = new Error('edge operator registration flag write is not supported');
+            err.routeCode = 'METHOD_NOT_ALLOWED';
+            err.routeStatus = 405;
+            return Promise.reject(err);
+        }
+    };
+}

package/src/infrastructure/operators/operatorById.js

@@ -0,0 +1,33 @@
+/**
+ * Resolves operator records by numeric id from a list provider.
+ *
+ * @param {object} provider - operators provider with list()
+ * @returns {object} resolver with resolve(operatorId)
+ *
+ * @example
+ *   const lookup = operatorById(operatorsFromPg(pool));
+ *   const row = await lookup.resolve(3);
+ */
+export default function operatorById(provider) {
+    if (!provider || typeof provider.list !== 'function') {
+        throw new Error('Provider must have a list() method');
+    }
+    return {
+        /**
+         * Finds an operator by id or returns undefined when absent.
+         *
+         * @param {number|string} operatorId - operator primary key
+         * @returns {Promise<object|undefined>} operator or undefined
+         */
+        async resolve(operatorId) {
+            const id = Number(operatorId);
+            if (!Number.isFinite(id)) {
+                throw new RangeError(`Invalid operator id ${operatorId}`);
+            }
+            const rows = await provider.list();
+            return rows.find((row) => {
+                return row.id === id;
+            });
+        }
+    };
+}

package/src/infrastructure/operators/operatorExtras.js

@@ -0,0 +1,41 @@
+const IDENTITY = ['id', 'cardUid', 'firstName', 'lastName', 'displayName'];
+const DRAFT = ['cardUid', 'firstName', 'lastName', 'displayName'];
+
+/**
+ * Copies plant-owned operator fields that are outside the shared identity shape.
+ *
+ * @param {object} row - operator JSON or domain record
+ * @param {array} reserved - identity keys owned by scada
+ * @returns {object} extra own properties from row
+ *
+ * @example
+ *   operatorExtras({ id: 1, cardUid: 'A', brigade: '2' }, ['id', 'cardUid']);
+ */
+export default function operatorExtras(row, reserved) {
+    const skip = new Set(reserved);
+    const extra = {};
+    Object.keys(row).forEach((key) => {
+        if (!skip.has(key)) {
+            extra[key] = row[key];
+        }
+    });
+    return extra;
+}
+
+/**
+ * Reserved identity keys for operator JSON serialization.
+ *
+ * @returns {array} identity key names
+ */
+export function operatorIdentityKeys() {
+    return IDENTITY.slice();
+}
+
+/**
+ * Reserved draft keys for operator create body parsing.
+ *
+ * @returns {array} draft key names
+ */
+export function operatorDraftKeys() {
+    return DRAFT.slice();
+}

package/src/infrastructure/operators/operators.js

@@ -0,0 +1,32 @@
+/**
+ * In-memory operators provider for edge site-server.
+ * Implements list()/replace(items) for central sync and enabled()/permit(flag) for registration cache.
+ *
+ * @param {array} [seed] - optional initial operators
+ * @returns {object} provider with list, replace, enabled, permit
+ *
+ * @example
+ *   const provider = operators();
+ *   provider.replace([operator(1, 'card-1', 'Ivan', 'Petrov', 'Ivan Petrov')]);
+ *   await provider.permit(true);
+ *   const rows = await provider.list();
+ */
+export default function operators(seed) {
+    let snapshot = seed ? seed.slice() : [];
+    let registration = false;
+    return {
+        list() {
+            return Promise.resolve(snapshot.slice());
+        },
+        replace(items) {
+            snapshot = items.slice();
+        },
+        enabled() {
+            return Promise.resolve(registration);
+        },
+        permit(flag) {
+            registration = flag === true;
+            return Promise.resolve(registration);
+        }
+    };
+}

package/src/infrastructure/operators/operatorsFromSeed.js

@@ -0,0 +1,18 @@
+/**
+ * In-memory operators provider for tests and local wiring.
+ * Implements the operators provider port: list().
+ *
+ * @param {array} seed - operator records supplied by caller
+ * @returns {object} provider with async list()
+ *
+ * @example
+ *   const provider = operatorsFromSeed([operator(1, 'card-1', 'Ivan', 'Petrov', 'Ivan Petrov')]);
+ *   const rows = await provider.list();
+ */
+export default function operatorsFromSeed(seed) {
+    return {
+        list() {
+            return Promise.resolve(seed);
+        }
+    };
+}

package/src/infrastructure/operators/operatorsSync.js

@@ -0,0 +1,57 @@
+const DEFAULT_INTERVAL_MS = 30000;
+
+async function refresh(source, provider) {
+    const items = await source.pull();
+    provider.replace(items);
+    if (typeof source.enabled !== 'function' || typeof provider.permit !== 'function') {
+        return;
+    }
+    await provider.permit(await source.enabled());
+}
+
+/**
+ * Periodic sync of edge operators cache from central plant API.
+ * Default interval is 30s; keeps the last successful snapshot when central is unreachable.
+ * Also copies the registration enabled flag when source.enabled and provider.permit exist.
+ *
+ * @param {object} source - centralOperators with pull() and optional enabled()
+ * @param {object} provider - operators with replace(items) and optional permit(flag)
+ * @param {object} [options] - intervalMs for sync period
+ * @returns {object} sync with start() and stop()
+ *
+ * @example
+ *   const sync = operatorsSync(source, provider, { intervalMs: 30000 });
+ *   await sync.start();
+ */
+export default function operatorsSync(source, provider, options) {
+    const intervalMs = options && options.intervalMs ? options.intervalMs : DEFAULT_INTERVAL_MS;
+    let timer;
+    let active = false;
+    async function tick() {
+        try {
+            await refresh(source, provider);
+        } catch {
+            /* next tick retries; stale snapshot remains */
+        }
+    }
+    return {
+        async start() {
+            if (active) {
+                return;
+            }
+            active = true;
+            await tick();
+            timer = setInterval(() => {
+                void tick();
+            }, intervalMs);
+        },
+        stop() {
+            if (!active) {
+                return;
+            }
+            active = false;
+            clearInterval(timer);
+            timer = undefined;
+        }
+    };
+}

package/src/infrastructure/persistence/clickhouse/connection.js

@@ -0,0 +1,58 @@
+/**
+ * ClickHouse connection factory for SCADA metrics storage.
+ *
+ * Provides connection with query and insert methods for sensor data.
+ * When username is provided, skips schema initialization (for read-only users).
+ *
+ * @param {string} host - ClickHouse host
+ * @param {object} options - connection options
+ * @param {number} options.port - ClickHouse HTTP port (default: 8123)
+ * @param {string} options.username - ClickHouse username (optional)
+ * @param {string} options.password - ClickHouse password (optional)
+ * @returns {object} connection with query, insert, and close methods
+ *
+ * @example
+ *   const conn = await clickhouseConnection('localhost', { username: 'readonly', password: 'secret' });
+ *   const rows = await conn.query('SELECT * FROM scada.metrics WHERE topic = {topic:String}', { topic: 'm1/voltage' });
+ *   await conn.close();
+ */
+import { createClient } from '@clickhouse/client';
+
+export default async function clickhouseConnection(host, options = {}) {
+    const port = options.port || 8123;
+    const {username} = options;
+    const {password} = options;
+    const config = { url: `http://${host}:${port}` };
+    if (username) {
+        config.username = username;
+        config.password = password || '';
+    }
+    const client = createClient(config);
+    if (!username) {
+        await client.command({ query: 'CREATE DATABASE IF NOT EXISTS scada' });
+        await client.command({
+            query: `CREATE TABLE IF NOT EXISTS scada.metrics (
+                topic String, ts DateTime64(3), value Float64
+            ) ENGINE = MergeTree() ORDER BY (topic, ts)`
+        });
+    }
+    return {
+        url() {
+            return `http://${host}:${port}`;
+        },
+        async query(sql, params = {}) {
+            const result = await client.query({
+                query: sql,
+                query_params: params,
+                format: 'JSONEachRow'
+            });
+            return result.json();
+        },
+        async insert(table, rows) {
+            await client.insert({ table, values: rows, format: 'JSONEachRow' });
+        },
+        async close() {
+            await client.close();
+        }
+    };
+}

package/src/infrastructure/persistence/clickhouse/pollTopicCursors.js

@@ -0,0 +1,48 @@
+/**
+ * Batched ClickHouse poll for many topic cursors.
+ *
+ * Issues a single IN-query for all topics so stream CPU stays proportional
+ * to poll pulses, not to the number of subscribed sensors.
+ *
+ * @param {object} connection - ClickHouse connection with query(sql, params)
+ * @param {Array<{topic: string, since: Date}>} cursors - per-topic watermarks
+ * @param {Date} until - exclusive upper bound
+ * @returns {Promise<Array<{topic: string, ts: string, value: number}>>} rows
+ *
+ * @example
+ *   const rows = await pollTopicCursors(conn, [
+ *     { topic: 'm1/voltage', since: lastTs }
+ *   ], new Date());
+ */
+function formatDateTime(date) {
+    return date.toISOString().replace('Z', '').replace('T', ' ');
+}
+
+export default function pollTopicCursors(connection, cursors, until) {
+    if (cursors.length === 0) {
+        return Promise.resolve([]);
+    }
+    const topics = cursors.map((cursor) => {
+        return cursor.topic;
+    });
+    let oldest = cursors[0].since;
+    cursors.forEach((cursor) => {
+        if (cursor.since.getTime() < oldest.getTime()) {
+            oldest = cursor.since;
+        }
+    });
+    return connection.query(
+        `SELECT topic, ts, value FROM scada.metrics
+         WHERE topic IN {topics:Array(String)}
+           AND ts > {since:DateTime64(3)}
+           AND ts <= {until:DateTime64(3)}
+         ORDER BY topic, ts
+         LIMIT {limit:UInt32}`,
+        {
+            topics,
+            since: formatDateTime(oldest),
+            until: formatDateTime(until),
+            limit: Math.max(100, topics.length * 100)
+        }
+    );
+}