@yarkivaev/scada 1.4.0 → 2.3.45

package/src/infrastructure/ingest/sinks/retagSink.js

@@ -0,0 +1,43 @@
+import processingErrorLog from '../processingErrorLog.js';
+
+/**
+ * Sink for applying operator-assigned tags to an existing segment row.
+ *
+ * Executes a targeted UPDATE that sets tags, properties, clears options,
+ * and marks the segment as resolved. Does not touch name, duration, or
+ * timestamps, preserving the segment's structural identity.
+ *
+ * @example
+ *   const pool = new pg.Pool({ connectionString: url });
+ *   const sink = retagSink(pool);
+ *   sink.accept({ machine: 'm2', start_time: '2024-01-01T00:00:00.000Z',
+ *                 tags: '["charge_loading"]', properties: '{}' });
+ *
+ * @param {object} pool - pg Pool (or compatible) with query() method
+ * @returns {object} Sink with accept() method
+ */
+export default function retagSink(pool) {
+    if (!pool || typeof pool.query !== 'function') {
+        throw new Error('Pool must have a query() method');
+    }
+    return {
+        /**
+         * Applies tags and properties to the segment identified by machine and start_time.
+         *
+         * @param {object} record - Record with machine, start_time, tags, properties
+         */
+        async accept({ machine, start_time: startTime, tags, properties, options, resolved }) {
+            try {
+                const opts = options === undefined || options === null ? null : options;
+                const flag = typeof resolved === 'boolean' ? resolved : true;
+                await pool.query(
+                    'UPDATE segments SET tags = $1, properties = $2, options = $3, resolved = $4 WHERE machine = $5 AND start_time = $6',
+                    [tags, properties, opts, flag, machine, startTime]
+                );
+            } catch (error) {
+                processingErrorLog('retag_sink_update', error, { machine, startTime, tags, properties });
+                throw error;
+            }
+        }
+    };
+}

package/src/infrastructure/ingest/sinks/userDecisionSink.js

@@ -0,0 +1,41 @@
+import processingErrorLog from '../processingErrorLog.js';
+
+/**
+ * Sink for inserting user tag decisions into the user_decisions audit table.
+ *
+ * Each accepted record is persisted with machine, start_time, username,
+ * operator_id, decided_at, and the full raw JSON payload.
+ *
+ * @example
+ *   const sink = userDecisionSink(pool);
+ *   sink.accept({ machine: 'm2', startTime: '2024-01-01T00:00:00.000Z',
+ *                 username: 'Ivan Petrov', operatorId: 2,
+ *                 decidedAt: '2024-01-01T00:01:00.000Z',
+ *                 payload: '{"tags":["charge_loading"]}' });
+ *
+ * @param {object} pool - pg Pool (or compatible) with query() method
+ * @returns {object} Sink with accept() method
+ */
+export default function userDecisionSink(pool) {
+    if (!pool || typeof pool.query !== 'function') {
+        throw new Error('Pool must have a query() method');
+    }
+    return {
+        /**
+         * Inserts a user decision record into the user_decisions table.
+         *
+         * @param {object} record - machine, startTime, username, operatorId, decidedAt, payload
+         */
+        async accept({ machine, startTime, username, operatorId, decidedAt, payload }) {
+            try {
+                await pool.query(
+                    'INSERT INTO user_decisions (machine, start_time, username, operator_id, decided_at, payload) VALUES ($1, $2, $3, $4, $5, $6)',
+                    [machine, startTime, username, operatorId ?? null, decidedAt, payload]
+                );
+            } catch (error) {
+                processingErrorLog('decision_sink_insert', error, { machine, startTime, username, operatorId, decidedAt, payload });
+                throw error;
+            }
+        }
+    };
+}

package/src/infrastructure/ingest/telemetry/amqpMetricsIngest.js

@@ -0,0 +1,94 @@
+import amqp from 'amqplib';
+import { batch, circuit, clock, timedBatch } from '@yarkivaev/source-to-sink';
+import deliverToMqttRecord from './deliverToMqttRecord.js';
+import metricsCodec from '../mqtt/metricsTransformer.js';
+import streamNameFromTopic from './streamNameFromTopic.js';
+
+/**
+ * Maps AMQP deliver to raw metrics message for metricsCodec.
+ *
+ * @param {object} codec - metricsCodec instance
+ * @param {object} fields - AMQP deliver fields
+ * @param {Buffer} content - message body
+ * @param {Function} [onSeen] - optional callback(streamName) for edge freshness
+ */
+export function acceptTelemetryDeliver(codec, fields, content, onSeen) {
+    const record = deliverToMqttRecord(fields, content);
+    if (typeof onSeen === 'function') {
+        const name = streamNameFromTopic(record.topic);
+        if (name) {
+            onSeen(name);
+        }
+    }
+    codec.accept({ topic: record.topic, payload: record.payload.toString() });
+}
+
+/**
+ * Builds a queue consumer callback bound to one AMQP channel.
+ *
+ * @param {object} codec - metricsCodec instance
+ * @param {object} channel - amqplib channel with ack(msg)
+ * @param {Function} [onSeen] - optional edge freshness callback
+ * @returns {Function} consume callback for ch.consume
+ */
+export function telemetryConsumer(codec, channel, onSeen) {
+    return (msg) => {
+        if (!msg) {
+            return;
+        }
+        acceptTelemetryDeliver(codec, msg.fields, msg.content, onSeen);
+        channel.ack(msg);
+    };
+}
+
+/**
+ * AMQP queue consumer that writes federated telemetry to a metrics sink.
+ *
+ * @param {string} amqpUrl - RabbitMQ AMQP URL
+ * @param {string} queue - Durable queue name to consume
+ * @param {object} sink - sink with write(records)
+ * @param {object} [options] - batch and prefetch options
+ * @returns {object} ingest with start and stop
+ */
+export default function amqpMetricsIngest(amqpUrl, queue, sink, options = {}) {
+    const prefetch = options.prefetch || 32;
+    const size = options.size || 100;
+    const interval = options.interval || 5;
+    const threshold = options.threshold || 5;
+    const timeout = options.timeout || 60;
+    let session;
+    const clk = clock();
+    const breaker = circuit(threshold, timeout, clk);
+    const collector = timedBatch(batch(sink, size, breaker), interval);
+    const codec = metricsCodec(collector);
+    return {
+        async start() {
+            if (session) {
+                return;
+            }
+            const conn = await amqp.connect(amqpUrl);
+            const ch = await conn.createChannel();
+            if (session) {
+                await ch.close();
+                await conn.close();
+                return;
+            }
+            await ch.assertQueue(queue, { durable: true });
+            ch.prefetch(prefetch);
+            const onMessage = telemetryConsumer(codec, ch, options.onSeen);
+            const tag = await ch.consume(queue, onMessage, { noAck: false });
+            session = { conn, channel: ch, tag: tag.consumerTag };
+        },
+        async stop() {
+            const active = session;
+            if (!active) {
+                return;
+            }
+            session = undefined;
+            await active.channel.cancel(active.tag);
+            await active.channel.close();
+            await active.conn.close();
+            collector.stop();
+        }
+    };
+}

package/src/infrastructure/ingest/telemetry/amqpMqttRelay.js

@@ -0,0 +1,71 @@
+import amqp from 'amqplib';
+import deliverToMqttRecord from './deliverToMqttRecord.js';
+
+/**
+ * Builds a queue consumer callback bound to one AMQP channel.
+ *
+ * @param {object} sink - sink with write(records)
+ * @param {object} channel - amqplib channel with ack(msg)
+ * @returns {Function} consume callback for ch.consume
+ */
+export function relayConsumer(sink, channel) {
+    return (msg) => {
+        if (!msg) {
+            return;
+        }
+        const record = deliverToMqttRecord(msg.fields, msg.content);
+        sink.write([record]);
+        channel.ack(msg);
+    };
+}
+
+/**
+ * AMQP queue consumer that republishes messages to MQTT using routing key as topic.
+ *
+ * @example
+ *   import { mqttSink } from '@yarkivaev/source-to-sink';
+ *   const sink = mqttSink('mqtt://localhost:1883', { qos: 1 });
+ *   const relay = amqpMqttRelay('amqp://localhost', 'scada.telemetry.ingest', sink);
+ *   relay.start();
+ *
+ * @param {string} amqpUrl - RabbitMQ AMQP URL
+ * @param {string} queue - Durable queue name to consume
+ * @param {object} sink - mqttSink with start, stop, write
+ * @param {object} [options] - prefetch count
+ * @returns {object} Relay with start and stop
+ */
+export default function amqpMqttRelay(amqpUrl, queue, sink, options = {}) {
+    const prefetch = options.prefetch || 32;
+    let session;
+    return {
+        async start() {
+            if (session) {
+                return;
+            }
+            const conn = await amqp.connect(amqpUrl);
+            const ch = await conn.createChannel();
+            if (session) {
+                await ch.close();
+                await conn.close();
+                return;
+            }
+            await ch.assertQueue(queue, { durable: true });
+            ch.prefetch(prefetch);
+            sink.start();
+            const onMessage = relayConsumer(sink, ch);
+            const tag = await ch.consume(queue, onMessage, { noAck: false });
+            session = { conn, channel: ch, tag: tag.consumerTag };
+        },
+        async stop() {
+            const active = session;
+            if (!active) {
+                return;
+            }
+            session = undefined;
+            await active.channel.cancel(active.tag);
+            await active.channel.close();
+            await active.conn.close();
+            sink.stop();
+        }
+    };
+}

package/src/infrastructure/ingest/telemetry/deliverToMqttRecord.js

@@ -0,0 +1,19 @@
+/**
+ * Maps AMQP deliver fields to MQTT publish record.
+ *
+ * @example
+ *   const record = deliverToMqttRecord({ routingKey: 'MX210.m-1.GET.AI1.VALUE' }, Buffer.from('1'));
+ *   // record.topic === 'MX210/m-1/GET/AI1/VALUE'
+ *
+ * @param {object} fields - AMQP deliver fields with routingKey
+ * @param {Buffer|string} body - Raw message body
+ * @returns {object} Record with topic and payload for mqttSink
+ */
+export default function deliverToMqttRecord(fields, body) {
+    const { routingKey } = fields;
+    if (typeof routingKey !== 'string' || routingKey.length === 0) {
+        throw new Error('routing key is empty for telemetry deliver');
+    }
+    const topic = routingKey.replace(/\./gu, '/');
+    return { topic, payload: body };
+}

package/src/infrastructure/ingest/telemetry/streamNameFromTopic.js

@@ -0,0 +1,21 @@
+/**
+ * Extracts the stream id from a metrics MQTT/AMQP topic path.
+ *
+ * @example
+ *   streamNameFromTopic('MX210/m-1/GET/AI1/VALUE') === 'm-1'
+ *
+ * @param {string} topic - Slash-separated topic
+ * @returns {string|undefined} Device/stream id
+ */
+export default function streamNameFromTopic(topic) {
+    if (typeof topic !== 'string' || topic.length === 0) {
+        return undefined;
+    }
+    const parts = topic.split('/').filter((part) => {
+        return part.length > 0;
+    });
+    if (parts.length < 2) {
+        return undefined;
+    }
+    return parts[1];
+}

package/src/infrastructure/messaging/ownership/httpOperations.js

@@ -0,0 +1,96 @@
+function trimBase(url) {
+    return String(url).replace(/\/$/u, '');
+}
+
+function authHeaders(token) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (token) {
+        headers.Authorization = `Bearer ${token}`;
+    }
+    return headers;
+}
+
+function ownerError(message, code, status, cause) {
+    const err = new Error(message);
+    err.routeCode = code;
+    err.routeStatus = status;
+    if (cause) {
+        err.cause = cause;
+    }
+    return err;
+}
+
+async function readError(res) {
+    const text = await res.text();
+    return text.length > 0 ? text : res.statusText;
+}
+
+async function readJson(res) {
+    const text = await res.text();
+    if (!text || text.trim().length === 0) {
+        return undefined;
+    }
+    return JSON.parse(text);
+}
+
+/**
+ * HTTP operations write port that proxies create/update/delete to an edge plant API.
+ *
+ * Matches the owning-edge contract: central never upserts locally for edge machines.
+ * Failures surface as route errors (503 unreachable, 502 non-ok).
+ *
+ * @param {object} site - edge owner with baseUrl and optional token/fetch
+ * @param {string} machineId - machine identifier
+ * @returns {object} operations write port
+ *
+ * @example
+ *   const port = httpOperations({ baseUrl: 'http://edge/api/v1' }, 'm2');
+ *   await port.create({ kind: 'bath', payload: {}, operatorId: 2 });
+ */
+export default function httpOperations(site, machineId) {
+    const base = trimBase(site.baseUrl);
+    const fetcher = site.fetch || fetch;
+    async function send(method, path, body) {
+        const url = `${base}${path}`;
+        let res;
+        try {
+            res = await fetcher(url, {
+                method,
+                headers: authHeaders(site.token),
+                body: body === undefined ? undefined : JSON.stringify(body)
+            });
+        } catch (cause) {
+            throw ownerError(
+                `owner operations unreachable for ${machineId}: ${cause.message}`,
+                'SERVICE_UNAVAILABLE',
+                503,
+                cause
+            );
+        }
+        if (!res.ok) {
+            throw ownerError(
+                `owner operations ${method} ${path} for ${machineId} failed: ${res.status} ${await readError(res)}`,
+                'BAD_GATEWAY',
+                502
+            );
+        }
+        return readJson(res);
+    }
+    const root = `/machines/${encodeURIComponent(machineId)}/operations`;
+    return Object.freeze({
+        create(body) {
+            return send('POST', root, body);
+        },
+        update(key, body) {
+            return send('PUT', `${root}/${encodeURIComponent(key)}`, body);
+        },
+        remove(key, body) {
+            return send('DELETE', `${root}/${encodeURIComponent(key)}`, body);
+        },
+        decisions(key) {
+            return send('GET', `${root}/${encodeURIComponent(key)}/decisions`).then((body) => {
+                return Array.isArray(body && body.items) ? body.items : [];
+            });
+        }
+    });
+}

package/src/infrastructure/messaging/ownership/httpTimeline.js

@@ -0,0 +1,99 @@
+function trimBase(url) {
+    return String(url).replace(/\/$/u, '');
+}
+
+function authHeaders(token) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (token) {
+        headers.Authorization = `Bearer ${token}`;
+    }
+    return headers;
+}
+
+function writeBody(start, tags, properties, audit) {
+    const body = {
+        start: start.toISOString(),
+        tags: tags || [],
+        properties: properties || {}
+    };
+    if (audit && audit.id !== undefined && audit.id !== null) {
+        body.operatorId = audit.id;
+    }
+    return body;
+}
+
+function ownerError(message, code, status, cause) {
+    const err = new Error(message);
+    err.routeCode = code;
+    err.routeStatus = status;
+    if (cause) {
+        err.cause = cause;
+    }
+    return err;
+}
+
+async function readError(res) {
+    const text = await res.text();
+    return text.length > 0 ? text : res.statusText;
+}
+
+/**
+ * HTTP timeline write port that proxies retag/respond to an edge plant API.
+ *
+ * Matches stompTimeline shape: retag(start, tags, properties, audit) and
+ * respond(start, tags, properties, audit). Failures surface as route errors.
+ *
+ * @param {object} site - edge owner with baseUrl and optional token/fetch
+ * @param {string} machineId - machine identifier
+ * @returns {object} timeline write port
+ *
+ * @example
+ *   const port = httpTimeline({ baseUrl: 'http://edge/api/v1' }, 'm2');
+ *   await port.retag(start, ['heat'], {}, audit);
+ */
+export default function httpTimeline(site, machineId) {
+    const base = trimBase(site.baseUrl);
+    const fetcher = site.fetch || fetch;
+    async function send(method, path, body) {
+        const url = `${base}${path}`;
+        let res;
+        try {
+            res = await fetcher(url, {
+                method,
+                headers: authHeaders(site.token),
+                body: JSON.stringify(body)
+            });
+        } catch (cause) {
+            throw ownerError(
+                `owner timeline unreachable for ${machineId}: ${cause.message}`,
+                'SERVICE_UNAVAILABLE',
+                503,
+                cause
+            );
+        }
+        if (!res.ok) {
+            throw ownerError(
+                `owner timeline ${method} ${path} for ${machineId} failed: ${res.status} ${await readError(res)}`,
+                'BAD_GATEWAY',
+                502
+            );
+        }
+        return res;
+    }
+    return Object.freeze({
+        async retag(start, tags, properties, audit) {
+            await send('PATCH', `/machines/${encodeURIComponent(machineId)}/segments`, writeBody(start, tags, properties, audit));
+        },
+        async respond(start, tags, properties, audit) {
+            const requestId = encodeURIComponent(start.toISOString());
+            const body = {
+                tags: tags || [],
+                properties: properties || {}
+            };
+            if (audit && audit.id !== undefined && audit.id !== null) {
+                body.operatorId = audit.id;
+            }
+            await send('POST', `/machines/${encodeURIComponent(machineId)}/requests/${requestId}/respond`, body);
+        }
+    });
+}

package/src/infrastructure/messaging/ownership/machineOwners.js

@@ -0,0 +1,39 @@
+/**
+ * Builds a machineId → owner registry from EDGE_SITES-style site lists.
+ *
+ * Unknown machines resolve to local (STOMP) ownership.
+ *
+ * @param {Array<{baseUrl: string, token?: string, machines: string[]}>} sites - edge sites
+ * @returns {object} frozen registry with resolve(machineId)
+ *
+ * @example
+ *   const owners = machineOwners([
+ *     { baseUrl: 'http://edge:3000/api/v1', token: 'secret', machines: ['m2'] }
+ *   ]);
+ *   owners.resolve('m2'); // { kind: 'edge', baseUrl, token }
+ *   owners.resolve('m1'); // { kind: 'local' }
+ */
+export default function machineOwners(sites) {
+    const map = new Map();
+    for (const site of sites || []) {
+        const owner = Object.freeze({
+            kind: 'edge',
+            baseUrl: site.baseUrl,
+            token: site.token
+        });
+        for (const id of site.machines || []) {
+            map.set(id, owner);
+        }
+    }
+    return Object.freeze({
+        /**
+         * Resolves ownership for one machine.
+         *
+         * @param {string} machineId - machine identifier
+         * @returns {object} { kind: 'local' } or { kind: 'edge', baseUrl, token }
+         */
+        resolve(machineId) {
+            return map.get(machineId) || Object.freeze({ kind: 'local' });
+        }
+    });
+}

package/src/infrastructure/messaging/ownership/ownerTimeline.js

@@ -0,0 +1,28 @@
+import httpTimeline from './httpTimeline.js';
+
+/**
+ * Owner-routed timeline write factory.
+ *
+ * Local machines use the injected local write port (typically stompTimeline);
+ * edge-owned machines proxy PATCH/respond to the owning plant API.
+ *
+ * @param {function(string): object} localTimeline - factory (machineId) => write port
+ * @param {object} owners - registry with resolve(machineId) → local | edge owner
+ * @returns {function(string): object} factory (machineId) => write port
+ *
+ * @example
+ *   const write = ownerTimeline(
+ *     (id) => stompTimeline(decisions, id),
+ *     machineOwners([{ baseUrl: 'http://edge/api/v1', machines: ['m2'] }])
+ *   );
+ *   await write('m2').retag(start, ['heat'], {}, audit);
+ */
+export default function ownerTimeline(localTimeline, owners) {
+    return function forMachine(machineId) {
+        const owner = owners.resolve(machineId);
+        if (owner.kind === 'edge') {
+            return httpTimeline(owner, machineId);
+        }
+        return localTimeline(machineId);
+    };
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Read-only alert collection backed by PG hydration and STOMP.
+ *
+ * Loads unacknowledged alerts from PostgreSQL on init, subscribes to
+ * STOMP for real-time in-memory updates and SSE delivery.
+ *
+ * @param {object} hydrate - pgAlerts or compatible port
+ * @param {function} source - factory returning STOMP source with start/stop
+ * @param {object} translations - map of rule names to human-readable messages
+ * @returns {object} alert collection with init, all, find, stream, trigger, stop methods
+ *
+ * @example
+ *   const history = stompAlerts(pgAlerts(pool), sourceFactory, { low_cosphi: 'Switch off...' });
+ *   await history.init();
+ *   history.all();
+ */
+import stompAlertsCollection from './stompAlertsCollection.js';
+
+export default function stompAlerts(hydrate, source, translations) {
+    return stompAlertsCollection(hydrate, source, translations);
+}

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

@@ -0,0 +1,51 @@
+import pubsub from '../../../../domain/shared/pubsub.js';
+import stompAlertsInit from './stompAlertsInit.js';
+import { build, consume } from './stompAlertsLogic.js';
+
+/**
+ * @param {object} hydrate - alert hydration port
+ * @param {function} source - STOMP source factory
+ * @param {object} translations - rule name map
+ * @returns {object} alerts collection
+ */
+export default function stompAlertsCollection(hydrate, source, translations) {
+    const items = [];
+    const bus = pubsub();
+    const state = { items, bus, counter: 0 };
+    let subscription = null;
+    return {
+        async init() {
+            await stompAlertsInit(hydrate, items, state);
+            subscription = source({
+                accept(raw) {
+                    consume(raw, state, translations);
+                }
+            });
+        },
+        trigger(message, timestamp, object, name) {
+            state.counter += 1;
+            const alert = build({ id: state.counter, message, timestamp, machine: object, acknowledged: false, name });
+            items.push(alert);
+            bus.emit({ type: 'created', alert });
+            return alert;
+        },
+        all(...filters) {
+            return items.filter((a) => {
+                return filters.every((filter) => {
+                    return filter(a);
+                });
+            });
+        },
+        find(id) {
+            return items.find((a) => {
+                return a.id === id;
+            });
+        },
+        stream: bus.stream,
+        stop() {
+            if (subscription) {
+                subscription.stop();
+            }
+        }
+    };
+}

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

@@ -0,0 +1,24 @@
+import { build } from './stompAlertsLogic.js';
+
+/**
+ * Loads initial alerts from a hydration port into memory.
+ *
+ * @param {object} hydrate - port with listUnacknowledged
+ * @param {Array} items - mutable items array
+ * @param {object} state - shared state with counter
+ * @returns {Promise<void>}
+ */
+export default async function stompAlertsInit(hydrate, items, state) {
+    const rows = await hydrate.listUnacknowledged({});
+    rows.forEach((row) => {
+        items.push(build({
+            id: row.id,
+            message: row.message,
+            timestamp: row.timestamp,
+            machine: row.machine,
+            acknowledged: row.acknowledged,
+            name: row.name
+        }));
+        state.counter = Math.max(state.counter, row.id);
+    });
+}