@yarkivaev/scada 1.5.0 → 2.3.46

package/src/domain/segment/normalize.js

@@ -0,0 +1,31 @@
+/**
+ * Normalizes a parsed segment message into a persistence-ready record.
+ *
+ * @param {object} parsed - decoded STOMP JSON payload
+ * @returns {object} normalized segment record
+ *
+ * @example
+ *   const row = segmentNormalize({ machine: 'm1', name: 'on', start: 1, end: 2, duration: 1 });
+ */
+export default function segmentNormalize(parsed) {
+    if (typeof parsed.machine !== 'string') {
+        throw new Error('Segment missing machine field');
+    }
+    if (typeof parsed.name !== 'string') {
+        throw new Error('Segment missing name field');
+    }
+    const hasOpts = Array.isArray(parsed.options) && parsed.options.length > 0;
+    const resolved = typeof parsed.resolved === 'boolean' ? parsed.resolved : !hasOpts;
+    return {
+        type: parsed.type,
+        machine: parsed.machine,
+        name: parsed.name,
+        start_time: new Date(parsed.start).toISOString(),
+        end_time: new Date(parsed.end).toISOString(),
+        duration: parsed.duration,
+        options: parsed.options ? JSON.stringify(parsed.options) : null,
+        tags: parsed.tags ? JSON.stringify(parsed.tags) : null,
+        properties: parsed.properties ? JSON.stringify(parsed.properties) : null,
+        resolved
+    };
+}

package/src/domain/segment/silenceBudget.js

@@ -0,0 +1,16 @@
+/**
+ * Silence budget for persistence-side open segment close.
+ * Mirrors supervisor Segmentation: wall-clock idle of machine.window * 2.
+ *
+ * @param {number} window - supervisor machine window in seconds
+ * @returns {number} silence budget in seconds
+ *
+ * @example
+ *   silenceBudget(15);
+ */
+export default function silenceBudget(window) {
+    if (typeof window !== 'number' || !(window > 0)) {
+        throw new Error(`Window must be a positive number: ${window}`);
+    }
+    return window * 2;
+}

package/src/{initialized.js → domain/shared/initialized.js}

@@ -7,10 +7,9 @@
  * @returns {object} wrapper with init() and get() methods
  *
  * @example
- *   const machines = initialized({ icht1: machine }, Object.values);
- *   machines.init();        // initializes all items once
- *   machines.get().icht1;   // access by key
- *   Object.values(machines.get()); // iterate
+ *   const machines = initialized({ m1: machine }, Object.values);
+ *   machines.init();
+ *   machines.get().m1;
  */
 export default function initialized(collection, toList) {
     let done = false;

package/src/{pubsub.js → domain/shared/pubsub.js}

@@ -1,14 +1,13 @@
 /**
  * Simple publish-subscribe mechanism for event distribution.
  * Provides emit() to publish and stream() to subscribe.
- * Abstraction point for future message broker integration.
  *
  * @returns {object} bus with emit() and stream() methods
  *
  * @example
  *   const bus = pubsub();
- *   const sub = bus.stream((e) => console.log(e));
- *   bus.emit({ type: 'created', data: {...} });
+ *   const sub = bus.stream((evt) => console.log(evt));
+ *   bus.emit({ type: 'created', data: {} });
  *   sub.cancel();
  */
 export default function pubsub() {

package/src/domain/timeline/timeline.js

@@ -0,0 +1,25 @@
+/**
+ * Read-only timeline port wired to a pubsub event bus.
+ *
+ * @param {object} read - read port with list, rowAt, pending
+ * @param {object} bus - pubsub instance with stream method
+ * @returns {object} timeline with list, rowAt, pending, stream
+ *
+ * @example
+ *   const tl = timeline(pgTimeline(pool, 'm1'), bus);
+ *   await tl.list({ from: '2024-01-01' });
+ */
+export default function timeline(read, bus) {
+    return {
+        list(range) {
+            return read.list(range);
+        },
+        rowAt(start) {
+            return read.rowAt(start);
+        },
+        pending() {
+            return read.pending();
+        },
+        stream: bus.stream
+    };
+}

package/src/infrastructure/catalog/tag-catalog.json

@@ -0,0 +1,27 @@
+[
+  {
+    "id": "on",
+    "label": "On",
+    "parent": null
+  },
+  {
+    "id": "off",
+    "label": "Off",
+    "parent": null
+  },
+  {
+    "id": "heating",
+    "label": "Heating",
+    "parent": "on"
+  },
+  {
+    "id": "idle",
+    "label": "Idle",
+    "parent": "off"
+  },
+  {
+    "id": "maintenance",
+    "label": "Maintenance",
+    "parent": "off"
+  }
+]

package/src/infrastructure/catalog/tagCatalog.js

@@ -0,0 +1,65 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+/**
+ * Loads hierarchical tag catalog entries from disk or embedded JSON.
+ *
+ * Prefers TAG_CATALOG_PATH when set so deploy ConfigMaps override the
+ * package copy without rebuilding the image.
+ *
+ * @example
+ *   const catalog = tagCatalog();
+ *   catalog.labels().heating;
+ *
+ * @param {object} [env] - environment map, defaults to process.env
+ * @returns {object} catalog with entries(), labels(), roots(parent)
+ */
+export default function tagCatalog(env) {
+    const source = env || process.env;
+    const path = source.TAG_CATALOG_PATH
+        || join(dirname(fileURLToPath(import.meta.url)), 'tag-catalog.json');
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    if (!Array.isArray(raw)) {
+        throw new Error('tag catalog must be a JSON array');
+    }
+    const byId = Object.fromEntries(raw.map((row) => {
+        return [row.id, row];
+    }));
+    return Object.freeze({
+        /**
+         * @returns {Array<object>} catalog rows
+         */
+        entries() {
+            return raw.slice();
+        },
+        /**
+         * @returns {object} id to label map
+         */
+        labels() {
+            const map = {};
+            raw.forEach((row) => {
+                map[row.id] = row.label;
+            });
+            return map;
+        },
+        /**
+         * @param {string} parent - parent id or segment name
+         * @returns {Array<string>} child ids
+         */
+        children(parent) {
+            return raw.filter((row) => {
+                return row.parent === parent;
+            }).map((row) => {
+                return row.id;
+            });
+        },
+        /**
+         * @param {string} id - tag id
+         * @returns {object|undefined} catalog row
+         */
+        get(id) {
+            return byId[id];
+        }
+    });
+}

package/src/infrastructure/client/index.js

@@ -0,0 +1,20 @@
+/**
+ * SCADA Server JS Client.
+ * Provides typed methods for all API endpoints.
+ *
+ * Export ports (Query/Stream/Sink/Job) are also re-exported for callers that
+ * depend on `@yarkivaev/scada/client` only; destination adapters stay in plant packages.
+ *
+ * @example
+ *   import { scadaClient, exportQuery, exportJob } from '@yarkivaev/scada/client';
+ *   const client = scadaClient('http://localhost:3000/api/v1', fetch, EventSource);
+ *   const query = exportQuery(client);
+ */
+
+export { default as machineClient } from './machineClient.js';
+export { default as scadaClient } from './scadaClient.js';
+export { default as sseConnection } from './sseConnection.js';
+export { default as exportQuery } from '../../application/export/exportQuery.js';
+export { default as exportStream } from '../../application/export/exportStream.js';
+export { default as exportSink } from '../../application/export/exportSink.js';
+export { default as exportJob } from '../../application/export/exportJob.js';

package/src/infrastructure/client/machineClient.js

@@ -0,0 +1,159 @@
+import sseConnection from './sseConnection.js';
+import machineOperationsClient from './machineOperationsClient.js';
+
+/**
+ * Builds a JSON request payload with method, headers, and body.
+ *
+ * @param {string} method - HTTP method
+ * @param {object} data - request body data
+ * @returns {object} fetch options with method, headers, and stringified body
+ */
+function payload(method, data) {
+    return {
+        method,
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(data)
+    };
+}
+
+/**
+ * Builds a from/to query suffix for range GETs.
+ *
+ * @param {object} [options] - optional from/to timestamps
+ * @returns {string} empty string or ?from=&to= suffix
+ */
+function rangeQuery(options) {
+    const params = new URLSearchParams();
+    if (options && options.from) {
+        params.set('from', options.from);
+    }
+    if (options && options.to) {
+        params.set('to', options.to);
+    }
+    const qs = params.toString();
+    return qs ? `?${qs}` : '';
+}
+
+/**
+ * Client for single machine endpoints.
+ * Returns object with methods for machine operations.
+ *
+ * @param {string} baseUrl - API base URL
+ * @param {string} machineId - machine identifier
+ * @param {function} fetcher - fetch function
+ * @param {function} eventSource - EventSource constructor
+ * @param {object} [logger] - optional logger with error(tag, detail)
+ * @returns {object} client with info, measurements, alerts, segments, cycles, operations methods
+ *
+ * @example
+ *   const machine = machineClient(baseUrl, 'm1', fetch, EventSource, logger);
+ *   const info = await machine.info();
+ *   await machine.createOperation({ kind: 'bath', payload: { action: 'load' } });
+ *   await machine.updateOperation(key, { payload: { action: 'load' } });
+ *   await machine.deleteOperation(key);
+ */
+export default function machineClient(baseUrl, machineId, fetcher, eventSource, logger) {
+    const url = `${baseUrl}/machines/${machineId}`;
+    async function request(path, options) {
+        const fullPath = `${url}${path}`;
+        let response;
+        try {
+            response = await fetcher(fullPath, options);
+        } catch (cause) {
+            if (logger && typeof logger.error === 'function') {
+                logger.error('api.network', { path: fullPath, cause });
+            }
+            throw cause;
+        }
+        const result = await response.json();
+        if (!response.ok) {
+            if (logger && typeof logger.error === 'function') {
+                logger.error('api', { path: fullPath, body: result });
+            }
+            throw result;
+        }
+        return result;
+    }
+    return {
+        info() {
+            return request('');
+        },
+        measurements(options) {
+            const params = new URLSearchParams();
+            if (options && options.keys) {
+                params.set('keys', options.keys.join(','));
+            }
+            if (options && options.from) {
+                params.set('from', options.from);
+            }
+            if (options && options.to) {
+                params.set('to', options.to);
+            }
+            if (options && options.step) {
+                params.set('step', String(options.step));
+            }
+            const qs = params.toString();
+            return request(`/measurements${qs ? `?${qs}` : ''}`);
+        },
+        measurementStream(options) {
+            const params = new URLSearchParams();
+            if (options && options.keys) {
+                params.set('keys', options.keys.join(','));
+            }
+            if (options && options.since) {
+                params.set('since', options.since);
+            }
+            if (options && options.step) {
+                params.set('step', String(options.step));
+            }
+            const qs = params.toString();
+            return sseConnection(
+                `${url}/measurements/stream${qs ? `?${qs}` : ''}`,
+                eventSource,
+                logger
+            );
+        },
+        alerts(options) {
+            const params = new URLSearchParams();
+            if (options && options.page) {
+                params.set('page', String(options.page));
+            }
+            if (options && options.size) {
+                params.set('size', String(options.size));
+            }
+            if (options && Object.hasOwn(options, 'acknowledged')) {
+                params.set('acknowledged', String(options.acknowledged));
+            }
+            const qs = params.toString();
+            return request(`/alerts${qs ? `?${qs}` : ''}`);
+        },
+        alertStream() {
+            return sseConnection(`${url}/alerts/stream`, eventSource, logger);
+        },
+        acknowledge(alertId) {
+            return request(`/alerts/${alertId}`, payload('PATCH', { acknowledged: true }));
+        },
+        segments(options) {
+            return request(`/segments${rangeQuery(options)}`);
+        },
+        cycles(options) {
+            return request(`/cycles${rangeQuery(options)}`);
+        },
+        retag(data) {
+            return request('/segments', payload('PATCH', data));
+        },
+        segmentStream() {
+            return sseConnection(`${url}/segments/stream`, eventSource, logger);
+        },
+        requests() {
+            return request('/requests');
+        },
+        requestStream() {
+            return sseConnection(`${url}/requests/stream`, eventSource, logger);
+        },
+        respond(requestId, data) {
+            return request(`/requests/${requestId}/respond`, payload('POST', data));
+        },
+        ...machineOperationsClient(baseUrl, request, eventSource, logger)
+    };
+}

package/src/infrastructure/client/machineOperationsClient.js

@@ -0,0 +1,159 @@
+import sseConnection from './sseConnection.js';
+
+/**
+ * Builds a JSON request payload with method, headers, and body.
+ *
+ * @param {string} method - HTTP method
+ * @param {object} data - request body data
+ * @returns {object} fetch options with method, headers, and stringified body
+ */
+function payload(method, data) {
+    return {
+        method,
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(data)
+    };
+}
+
+/**
+ * Copies optional audit fields onto an API body.
+ *
+ * @param {object} data - mutable body
+ * @param {object} fields - create/update/delete fields
+ */
+function attachAudit(data, fields) {
+    if (fields.operatorId !== undefined) {
+        data.operatorId = fields.operatorId;
+    }
+    if (fields.client !== undefined) {
+        data.client = fields.client;
+    }
+}
+
+/**
+ * Maps camelCase createOperation fields to snake_case API body.
+ *
+ * @param {object} fields - kind, payload, optional occurredAt, key, operatorId, client
+ * @returns {object} POST body for /operations
+ */
+function createBody(fields) {
+    const data = {
+        kind: fields.kind,
+        payload: fields.payload
+    };
+    if (fields.occurredAt !== undefined) {
+        data.occurred_at = fields.occurredAt;
+    }
+    if (fields.key !== undefined) {
+        data.key = fields.key;
+    }
+    attachAudit(data, fields);
+    return data;
+}
+
+/**
+ * Maps camelCase updateOperation fields to snake_case API body.
+ *
+ * @param {object} fields - payload, optional kind, occurredAt, operatorId, client
+ * @returns {object} PUT body for /operations/:key
+ */
+function updateBody(fields) {
+    const data = {
+        payload: fields.payload
+    };
+    if (fields.kind !== undefined) {
+        data.kind = fields.kind;
+    }
+    if (fields.occurredAt !== undefined) {
+        data.occurred_at = fields.occurredAt;
+    }
+    attachAudit(data, fields);
+    return data;
+}
+
+/**
+ * Builds the query string for operations list filters.
+ *
+ * @param {object} [options] - optional kind, from, to
+ * @returns {string} query string including leading ? or empty
+ */
+function listQuery(options) {
+    const params = new URLSearchParams();
+    if (options && options.kind) {
+        params.set('kind', options.kind);
+    }
+    if (options && options.from) {
+        params.set('from', options.from);
+    }
+    if (options && options.to) {
+        params.set('to', options.to);
+    }
+    const qs = params.toString();
+    return qs ? `?${qs}` : '';
+}
+
+/**
+ * Sends DELETE /operations/:key with optional audit JSON body.
+ *
+ * @param {function} request - authenticated JSON request helper
+ * @param {string} key - operation external key
+ * @param {object} [fields] - optional operatorId and client
+ * @returns {Promise<*>} delete response
+ */
+function deleteRequest(request, key, fields) {
+    const data = {};
+    attachAudit(data, fields || {});
+    const path = `/operations/${encodeURIComponent(key)}`;
+    if (Object.keys(data).length === 0) {
+        return request(path, { method: 'DELETE' });
+    }
+    return request(path, payload('DELETE', data));
+}
+
+/**
+ * Machine operations list, create, update, delete, decisions, and SSE methods.
+ *
+ * @param {string} baseUrl - API base URL
+ * @param {function} request - authenticated JSON request helper
+ * @param {function} eventSource - EventSource constructor
+ * @param {object} [logger] - optional logger with error(tag, detail)
+ * @returns {object} operations client methods
+ *
+ * @example
+ *   const ops = machineOperationsClient(baseUrl, request, EventSource, logger);
+ *   await ops.createOperation({ kind: 'bath', payload: {}, operatorId: 2 });
+ *   await ops.operationDecisions(key);
+ */
+export default function machineOperationsClient(baseUrl, request, eventSource, logger) {
+    return {
+        operations(options) {
+            return request(`/operations${listQuery(options)}`).then((body) => {
+                return body.items;
+            });
+        },
+        createOperation(fields) {
+            return request('/operations', payload('POST', createBody(fields)));
+        },
+        updateOperation(key, fields) {
+            return request(
+                `/operations/${encodeURIComponent(key)}`,
+                payload('PUT', updateBody(fields))
+            );
+        },
+        deleteOperation(key, fields) {
+            return deleteRequest(request, key, fields);
+        },
+        operationDecisions(key) {
+            return request(`/operations/${encodeURIComponent(key)}/decisions`).then((body) => {
+                return body.items;
+            });
+        },
+        operationsStream(callback) {
+            const conn = sseConnection(`${baseUrl}/operations/stream`, eventSource, logger);
+            conn.on('operation_created', callback);
+            conn.on('operation_updated', callback);
+            conn.on('operation_deleted', callback);
+            return conn;
+        }
+    };
+}

package/src/infrastructure/client/scadaClient.js

@@ -0,0 +1,67 @@
+import machineClient from './machineClient.js';
+import sseConnection from './sseConnection.js';
+
+/**
+ * Main SCADA API client.
+ * Returns object with machines() and machine() methods.
+ *
+ * @param {string} baseUrl - server base URL
+ * @param {function} fetcher - fetch function
+ * @param {function} eventSource - EventSource constructor
+ * @param {object} [logger] - optional logger with error(tag, detail)
+ * @returns {object} client with machines, machine, jump, reset, simulation methods
+ *
+ * @example
+ *   const client = scadaClient('http://localhost:3000/api/v1', fetch, EventSource, logger);
+ *   const machines = await client.machines();
+ *   const machine = client.machine('m1');
+ *   await client.jump('2025-06-15T10:00:00Z');
+ *   await client.reset();
+ */
+export default function scadaClient(baseUrl, fetcher, eventSource, logger) {
+    async function requestJson(path, options) {
+        const fullPath = `${baseUrl}${path}`;
+        let response;
+        try {
+            response = await fetcher(fullPath, options);
+        } catch (cause) {
+            if (logger && typeof logger.error === 'function') {
+                logger.error('api.network', { path: fullPath, cause });
+            }
+            throw cause;
+        }
+        const payload = await response.json();
+        if (!response.ok) {
+            if (logger && typeof logger.error === 'function') {
+                logger.error('api', { path: fullPath, body: payload });
+            }
+            const error = new Error(payload.error.message);
+            error.code = payload.error.code;
+            throw error;
+        }
+        return payload;
+    }
+    return {
+        machines() {
+            return requestJson('/machines');
+        },
+        tagCatalog() {
+            return requestJson('/tag-catalog');
+        },
+        machine(machineId) {
+            return machineClient(baseUrl, machineId, fetcher, eventSource, logger);
+        },
+        jump(timestamp) {
+            return requestJson('/simulation/jump', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ timestamp }) });
+        },
+        reset() {
+            return requestJson('/simulation', { method: 'DELETE' });
+        },
+        heartbeatStream() {
+            return sseConnection(`${baseUrl}/heartbeat/stream`, eventSource, logger);
+        },
+        simulation() {
+            return requestJson('/simulation');
+        }
+    };
+}

package/src/infrastructure/client/sseConnection.js

@@ -0,0 +1,42 @@
+/**
+ * SSE connection wrapper with event callbacks.
+ * Returns immutable object with on() and close() methods.
+ *
+ * @param {string} url - SSE endpoint URL
+ * @param {function} eventSource - EventSource constructor (for testing)
+ * @param {object} [logger] - optional logger with error(tag, detail)
+ * @returns {object} connection with on, close methods
+ *
+ * @example
+ *   const conn = sseConnection(url, EventSource, logger);
+ *   conn.on('measurement', data => console.log(data));
+ *   conn.close();
+ */
+export default function sseConnection(url, EventSourceCtor, logger) {
+    const source = new EventSourceCtor(url);
+    if (logger && typeof logger.error === 'function') {
+        source.onerror = function onerror() {
+            logger.error('sse.connection', { url });
+        };
+    }
+    return {
+        on(event, notify) {
+            source.addEventListener(event, (ev) => {
+                let payload;
+                try {
+                    payload = JSON.parse(ev.data);
+                } catch (cause) {
+                    if (logger && typeof logger.error === 'function') {
+                        logger.error('sse.parse', { url, event, cause });
+                    }
+                    return;
+                }
+                notify(payload);
+            });
+            return this;
+        },
+        close() {
+            source.close();
+        }
+    };
+}