@yarkivaev/scada 1.5.0 → 2.3.45

package/src/application/export/exportJob.js

@@ -0,0 +1,118 @@
+/**
+ * Pulls one topic from Query for the given scope.
+ *
+ * @param {object} query - exportQuery port
+ * @param {object} scope - { kind, machine, from, to, step, keys, ... }
+ * @returns {Promise<*>} topic payload
+ */
+function pull(query, scope) {
+    const { kind } = scope;
+    if (kind === 'machines') {
+        return query.machines();
+    }
+    if (kind === 'measurements') {
+        return query.measurements(scope.machine, scope);
+    }
+    if (kind === 'segments') {
+        return query.segments(scope.machine, scope);
+    }
+    if (kind === 'alerts') {
+        return query.alerts(scope.machine, scope);
+    }
+    if (kind === 'operations') {
+        return query.operations(scope.machine, scope);
+    }
+    throw new Error(`export job cannot pull unknown kind ${kind}`);
+}
+
+/**
+ * Opens one Stream subscription for the given scope.
+ *
+ * @param {object} stream - exportStream port
+ * @param {object} scope - { kind, machine, ... }
+ * @returns {object} connection with on/close
+ */
+function open(stream, scope) {
+    const { kind } = scope;
+    if (kind === 'measurements') {
+        return stream.measurements(scope.machine, scope);
+    }
+    if (kind === 'segments') {
+        return stream.segments(scope.machine);
+    }
+    if (kind === 'alerts') {
+        return stream.alerts(scope.machine);
+    }
+    if (kind === 'operations') {
+        return stream.operations(scope.machine);
+    }
+    throw new Error(`export job cannot pipe unknown kind ${kind}`);
+}
+
+/**
+ * Default SSE event names for a stream kind.
+ *
+ * @param {string} kind - stream topic
+ * @returns {string[]} event names
+ */
+function defaultEvents(kind) {
+    if (kind === 'measurements') {
+        return ['measurement'];
+    }
+    if (kind === 'segments') {
+        return ['segment_created', 'segment_resolved'];
+    }
+    if (kind === 'alerts') {
+        return ['alert'];
+    }
+    if (kind === 'operations') {
+        return ['operation_created', 'operation_updated'];
+    }
+    return [];
+}
+
+/**
+ * Export Job: pulls Query or Stream, transforms, then writes to Sink.
+ *
+ * Query path uses run(scope). Stream path uses pipe(scope) and returns stop().
+ * Transform and destination wiring belong to the caller (plant packages).
+ *
+ * @param {object} ports - { query?, stream?, transform?, sink }
+ * @returns {object} frozen job with run and pipe
+ *
+ * @example
+ *   const job = exportJob({ query, transform: (rows) => rows, sink });
+ *   await job.run({ kind: 'segments', machine: 'furnace-α', from, to });
+ *
+ *   const live = exportJob({ stream, transform: (rows) => rows, sink });
+ *   const handle = live.pipe({ kind: 'segments', machine: 'furnace-α', events: ['segment_created'] });
+ *   handle.stop();
+ */
+export default function exportJob(ports) {
+    const transform = ports.transform || function identity(rows) {
+        return rows;
+    };
+    return Object.freeze({
+        async run(scope) {
+            const rows = await pull(ports.query, scope);
+            const batch = await Promise.resolve(transform(rows));
+            return ports.sink.write(batch);
+        },
+        pipe(scope) {
+            const conn = open(ports.stream, scope);
+            const events = scope.events || defaultEvents(scope.kind);
+            events.forEach((name) => {
+                conn.on(name, (payload) => {
+                    Promise.resolve(transform([payload])).then((batch) => {
+                        return ports.sink.write(batch);
+                    });
+                });
+            });
+            return Object.freeze({
+                stop() {
+                    conn.close();
+                }
+            });
+        }
+    });
+}

package/src/application/export/exportQuery.js

@@ -0,0 +1,32 @@
+/**
+ * On-demand export Query port over plantApi via scadaClient.
+ *
+ * Reads machines, measurements, segments, alerts, and operations by range.
+ * Does not talk to storage directly and carries no plant-specific names.
+ *
+ * @param {object} client - scadaClient (or fake) with machines() and machine(id)
+ * @returns {object} frozen query with machines, measurements, segments, alerts, operations
+ *
+ * @example
+ *   const query = exportQuery(scadaClient(url, fetch, EventSource));
+ *   const rows = await query.segments('furnace-α', { from, to });
+ */
+export default function exportQuery(client) {
+    return Object.freeze({
+        machines() {
+            return client.machines();
+        },
+        measurements(machineId, range) {
+            return client.machine(machineId).measurements(range);
+        },
+        segments(machineId, range) {
+            return client.machine(machineId).segments(range);
+        },
+        alerts(machineId, options) {
+            return client.machine(machineId).alerts(options || {});
+        },
+        operations(machineId, options) {
+            return client.machine(machineId).operations(options || {});
+        }
+    });
+}

package/src/application/export/exportSink.js

@@ -0,0 +1,25 @@
+/**
+ * Generic export Sink port for outbound batches and artifacts.
+ *
+ * Destination adapters (HTTP, file, plant integrations) live outside this package.
+ * This factory only freezes the write/send contract.
+ *
+ * @param {object} destination - object with write(records) and/or send(artifact)
+ * @returns {object} frozen sink with write and send
+ *
+ * @example
+ *   const sink = exportSink({
+ *     write(records) { return http.post('/hook', records); },
+ *     send(artifact) { return http.post('/doc', artifact); }
+ *   });
+ */
+export default function exportSink(destination) {
+    return Object.freeze({
+        write(records) {
+            return destination.write(records);
+        },
+        send(artifact) {
+            return destination.send(artifact);
+        }
+    });
+}

package/src/application/export/exportStream.js

@@ -0,0 +1,33 @@
+/**
+ * Streaming export Stream port over plantApi SSE via scadaClient.
+ *
+ * Opens measurement, segment, alert, and operation subscriptions.
+ * Returns the same connection shape as scada/client (on/close).
+ *
+ * @param {object} client - scadaClient (or fake) with machine(id) stream methods
+ * @returns {object} frozen stream with measurements, segments, alerts, operations
+ *
+ * @example
+ *   const stream = exportStream(client);
+ *   const conn = stream.segments('furnace-α');
+ *   conn.on('segment_created', (row) => { sink.write([row]); });
+ */
+export default function exportStream(client) {
+    return Object.freeze({
+        measurements(machineId, options) {
+            return client.machine(machineId).measurementStream(options || {});
+        },
+        segments(machineId) {
+            return client.machine(machineId).segmentStream();
+        },
+        alerts(machineId) {
+            return client.machine(machineId).alertStream();
+        },
+        operations(machineId, notify) {
+            const listen = notify || ((payload) => {
+                return payload;
+            });
+            return client.machine(machineId).operationsStream(listen);
+        }
+    });
+}

package/src/application/machineInPlant.js

@@ -0,0 +1,20 @@
+/**
+ * Locates a machine inside a plant by id.
+ *
+ * @param {object} plant - plant with shops
+ * @param {string} id - machine id
+ * @returns {object|undefined} machine and shop or undefined
+ *
+ * @example
+ *   const found = machineInPlant(plant, 'm1');
+ *   found.machine.sensors;
+ */
+export default function machineInPlant(plant, id) {
+    for (const area of Object.values(plant.shops.get())) {
+        const found = area.machines.get()[id];
+        if (found) {
+            return { machine: found, shop: area };
+        }
+    }
+    return undefined;
+}

package/src/application/metricsPlant.js

@@ -0,0 +1,35 @@
+import plant from '../domain/plant/plant.js';
+import initialized from '../domain/shared/initialized.js';
+import postgresPool from '../infrastructure/persistence/postgresPool.js';
+
+/**
+ * Generic plant factory wiring sensors and a shop factory over a connection.
+ *
+ * @param {Array<{device: string, machine: string}>} machines - machine descriptors
+ * @param {object} options - connection, buildSensors, shopFactory, pool, alerts, userDecisions, shopName
+ * @returns {Promise<object>} plant with shops and init
+ *
+ * @example
+ *   const p = await metricsPlant(machines, {
+ *     connection: () => clickhouseConnection(host, opts),
+ *     buildSensors: (conn, entry) => ({ voltage: sensor(conn, entry) }),
+ *     shopFactory: genericShop
+ *   });
+ */
+export default async function metricsPlant(machines, options) {
+    const connection = await options.connection();
+    const pool = postgresPool(options);
+    const entries = machines.map((entry) => {
+        return {
+            name: entry.machine,
+            sensors: options.buildSensors(connection, entry)
+        };
+    });
+    const shop = options.shopFactory(entries, {
+        pool,
+        alerts: options.alerts,
+        userDecisions: options.userDecisions,
+        shopName: options.shopName
+    });
+    return plant(initialized({ [shop.name()]: shop }, Object.values));
+}

package/src/application/plantApi.js

@@ -0,0 +1,49 @@
+import machineRoute from '../infrastructure/http/plant/routes/machineRoute.js';
+import measurementRoute from '../infrastructure/http/plant/routes/measurementRoute.js';
+import measurementStream from '../infrastructure/http/plant/streams/measurementStream.js';
+import alertRoute from '../infrastructure/http/plant/routes/alertRoute.js';
+import alertStream from '../infrastructure/http/plant/streams/alertStream.js';
+import timelineRoute from '../infrastructure/http/plant/routes/timelineRoute.js';
+import timelineStream from '../infrastructure/http/plant/streams/timelineStream.js';
+import operationRoute from '../infrastructure/http/plant/routes/operationRoute.js';
+import operationStream from '../infrastructure/http/plant/streams/operationStream.js';
+import heartbeatStream from '../infrastructure/http/plant/streams/heartbeatStream.js';
+import simulationRoute from '../infrastructure/http/plant/routes/simulationRoute.js';
+import catalogRoute from '../infrastructure/http/plant/routes/catalogRoute.js';
+import { routes } from '@yarkivaev/simple-server';
+
+/**
+ * Composable plant HTTP API factory.
+ *
+ * @param {string} basePath - base URL path
+ * @param {object} plant - plant domain object with operations (optional kindSources at construction)
+ * @param {object} [config] - clock, extraRoutes, requestTimeoutMs, heartbeat
+ * @returns {object} routes with list() and handle()
+ *
+ * @example
+ *   const api = plantApi('/api/v1', plant, { extraRoutes: siteRoute('/api/v1', plant) });
+ */
+export default function plantApi(basePath, plant, config) {
+    const opts = config || {};
+    plant.init();
+    const time = opts.clock || (() => {
+        return new Date();
+    });
+    const extra = opts.extraRoutes || [];
+    const routeList = [
+        ...catalogRoute(basePath, opts.tagCatalog),
+        ...machineRoute(basePath, plant),
+        ...measurementStream(basePath, plant, time),
+        ...measurementRoute(basePath, plant, time),
+        ...alertStream(basePath, plant, time),
+        ...alertRoute(basePath, plant),
+        ...timelineRoute(basePath, plant, opts.timelineOperator),
+        ...timelineStream(basePath, plant, time),
+        ...operationRoute(basePath, plant, opts.timelineOperator, opts.operationDecisions, opts.owners),
+        ...operationStream(basePath, plant, time),
+        ...heartbeatStream(basePath, time, opts.heartbeat),
+        ...(time.jump ? simulationRoute(basePath, time) : []),
+        ...extra
+    ];
+    return routes(routeList, { requestTimeoutMs: opts.requestTimeoutMs });
+}

package/src/application/plantOperations.js

@@ -0,0 +1,19 @@
+import operations from '../domain/operation/operations.js';
+import pubsub from '../domain/shared/pubsub.js';
+
+/**
+ * Wires operations persistence to domain operations with SSE pubsub.
+ *
+ * Optional kindSources inject non-PG kinds into listForMachine merges.
+ *
+ * @param {object} persistence - operations store with upsert, get, remove, listForMachine
+ * @param {object} [kindSources] - map of kind to { list(machineId, range) }
+ * @returns {object} operations with listForMachine, upsert, get, remove, and stream
+ *
+ * @example
+ *   const ops = plantOperations(dataAccess.operations, { temp: temperaturePort });
+ *   plant(shops, { operations: ops });
+ */
+export default function plantOperations(persistence, kindSources) {
+    return operations(persistence, pubsub(), kindSources);
+}

package/src/application/plantServer.js

@@ -0,0 +1,107 @@
+import http from 'http';
+import { stompSource } from '@yarkivaev/source-to-sink';
+import plantApi from './plantApi.js';
+import pgAlerts from '../infrastructure/persistence/pg/alerts.js';
+import postgresPool from '../infrastructure/persistence/postgresPool.js';
+import stompAlerts from '../infrastructure/messaging/stomp/alerts/stompAlerts.js';
+import stompTimelineSegments from '../infrastructure/messaging/stomp/stompTimelineSegments.js';
+import userDecisions from '../infrastructure/messaging/stomp/userDecisions.js';
+import { parseRequestTimeoutMs, virtualClock } from '@yarkivaev/simple-server';
+
+function stompCollectorFactory(stompUrl, destination, credentials) {
+    return (collector) => {
+        const src = stompSource(stompUrl, destination, collector, credentials);
+        src.start();
+        return src;
+    };
+}
+
+function timelineBusesInPlant(p) {
+    const buses = {};
+    for (const area of Object.values(p.shops.get())) {
+        for (const [id, item] of Object.entries(area.machines.get())) {
+            if (item.timeline && item.timeline.bus) {
+                buses[id] = item.timeline.bus;
+            }
+        }
+    }
+    return buses;
+}
+
+function wireTimelineSegments(stomp, plant) {
+    if (!stomp || !stomp.url) {
+        return undefined;
+    }
+    const buses = timelineBusesInPlant(plant);
+    if (Object.keys(buses).length === 0) {
+        return undefined;
+    }
+    const credentials = { login: stomp.login, passcode: stomp.passcode, host: stomp.host };
+    return stompTimelineSegments(
+        stompCollectorFactory(stomp.url, '/exchange/scada.segments', credentials),
+        buses
+    );
+}
+
+async function initStomp(stomp, translations, requirePool) {
+    if (!stomp || !stomp.url) {
+        return {};
+    }
+    const pool = postgresPool({});
+    if (requirePool && !pool) {
+        throw new Error('SUPERVISOR_STATE_PG_URL is required for plant server alerts');
+    }
+    const credentials = { login: stomp.login, passcode: stomp.passcode, host: stomp.host };
+    let alerts;
+    if (pool) {
+        alerts = stompAlerts(pgAlerts(pool), stompCollectorFactory(stomp.url, '/exchange/scada.alerts', credentials), translations || {});
+        await alerts.init();
+    }
+    const decisions = userDecisions({
+        stompUrl: stomp.url,
+        login: stomp.login,
+        passcode: stomp.passcode,
+        host: stomp.host
+    });
+    return { alerts, userDecisions: decisions };
+}
+
+/**
+ * Generic HTTP plant server with optional STOMP alerts and user decisions.
+ *
+ * Multi-kind operations come from plant.operations built with kindSources
+ * (e.g. plantOperations(persistence, { temp })).
+ *
+ * @param {object} config - port, basePath, plantFactory, extraRoutes, translations, stomp, requirePool
+ * @returns {Promise<object>} server, plant, api, segments
+ *
+ * @example
+ *   await plantServer({ port: 3000, basePath: '/api/v1', plantFactory, extraRoutes });
+ */
+export default async function plantServer(config) {
+    const { alerts, userDecisions: decisions } = await initStomp(config.stomp, config.translations, config.requirePool);
+    const p = await config.plantFactory({ alerts, userDecisions: decisions });
+    const segments = wireTimelineSegments(config.stomp, p);
+    const clock = virtualClock(() => {
+        return new Date();
+    });
+    const requestTimeoutMs = parseRequestTimeoutMs(process.env.REQUEST_TIMEOUT_MS);
+    const basePath = config.basePath || '/api/v1';
+    const extra = config.extraRoutes ? config.extraRoutes(basePath, p, clock) : [];
+    const api = plantApi(basePath, p, {
+        clock,
+        heartbeat: config.heartbeat || 1000,
+        requestTimeoutMs,
+        extraRoutes: extra,
+        timelineOperator: config.timelineOperator,
+        operationDecisions: config.operationDecisions,
+        owners: config.owners
+    });
+    const server = http.createServer((req, res) => {
+        return api.handle(req, res);
+    });
+    await new Promise((resolve) => {
+        server.listen(config.port, resolve);
+    });
+    return { server, plant: p, api, segments };
+}

package/src/application/shopWithTimeline.js

@@ -0,0 +1,112 @@
+import pubsub from '../domain/shared/pubsub.js';
+import timeline from '../domain/timeline/timeline.js';
+import pgTimeline from '../infrastructure/persistence/pg/timeline.js';
+import memoryTimelineStore, { memoryTimelineRead } from '../infrastructure/persistence/memory/timeline.js';
+import ownerTimeline from '../infrastructure/messaging/ownership/ownerTimeline.js';
+import stompTimeline from '../infrastructure/messaging/stomp/timeline.js';
+
+function parseStart(requestId) {
+    const raw = decodeURIComponent(String(requestId));
+    const start = new Date(raw);
+    if (Number.isNaN(start.getTime())) {
+        throw new RangeError(`Invalid request start time ${raw}`);
+    }
+    return start;
+}
+
+function resolvedStub(start, tags, properties) {
+    return {
+        name: '',
+        start_time: start,
+        end_time: start,
+        duration: 0,
+        tags: JSON.stringify(tags),
+        properties: JSON.stringify(properties)
+    };
+}
+
+function memoryTimelinePort(store, bus) {
+    const port = memoryTimelineRead(store, bus);
+    return {
+        list: port.list,
+        rowAt: port.rowAt,
+        pending: port.pending,
+        stream: port.stream,
+        bus,
+        retag(start, tags, properties, audit) {
+            const found = store.items.find((item) => {
+                return item.start_time.getTime() === start.getTime();
+            });
+            if (found) {
+                found.tags = tags;
+                found.properties = properties;
+                delete found.options;
+            }
+            bus.emit({ type: 'resolved', segment: resolvedStub(start, tags, properties), audit });
+        },
+        respond(requestId, body, audit) {
+            const start = parseStart(requestId);
+            const found = store.pending.find((item) => {
+                return item.start_time.getTime() === start.getTime();
+            });
+            if (found) {
+                found.resolved = true;
+                found.tags = body.tags;
+                found.properties = body.properties;
+            }
+            bus.emit({ type: 'resolved', request: { id: requestId, start }, audit });
+            return { id: requestId, ...body };
+        }
+    };
+}
+
+function writePort(name, decisions, owners) {
+    if (!owners) {
+        return stompTimeline(decisions, name);
+    }
+    return ownerTimeline((id) => {
+        return stompTimeline(decisions, id);
+    }, owners)(name);
+}
+
+/**
+ * Builds a machine timeline from PostgreSQL persistence and STOMP user decisions.
+ *
+ * Optional owners registry routes retag/respond to an edge HTTP plant API.
+ *
+ * @param {string} name - machine id
+ * @param {object} options - pool, userDecisions, optional owners
+ * @returns {object} timeline port with list, rowAt, pending, stream, retag, respond, bus
+ *
+ * @example
+ *   const tl = shopWithTimeline('machine1', { pool, userDecisions, owners });
+ */
+export default function shopWithTimeline(name, options) {
+    const { pool, userDecisions: decisions, owners } = options;
+    if (pool && decisions) {
+        const bus = pubsub();
+        const read = pgTimeline(pool, name);
+        const write = writePort(name, decisions, owners);
+        const port = timeline(read, bus);
+        return {
+            list: port.list,
+            rowAt: port.rowAt,
+            pending: port.pending,
+            stream: port.stream,
+            bus,
+            async retag(start, tags, properties, audit) {
+                await write.retag(start, tags, properties, audit);
+                bus.emit({ type: 'resolved', segment: resolvedStub(start, tags, properties), audit });
+            },
+            async respond(requestId, body, audit) {
+                const start = parseStart(requestId);
+                await write.respond(start, body.tags, body.properties || {}, audit);
+                bus.emit({ type: 'resolved', request: { id: requestId, start }, audit });
+                return { id: requestId, ...body };
+            }
+        };
+    }
+    const store = memoryTimelineStore();
+    const bus = pubsub();
+    return memoryTimelinePort(store, bus);
+}

package/src/application/siteOperatorCatalog.js

@@ -0,0 +1,78 @@
+import operatorsFromPg from '../infrastructure/persistence/pg/operators.js';
+import userDecisionsFromPg from '../infrastructure/persistence/pg/userDecisions.js';
+import operatorRoute from '../infrastructure/http/plant/routes/operatorRoute.js';
+import decisionRoute from '../infrastructure/http/plant/routes/decisionRoute.js';
+import edgeOperatorCatalog from './edgeOperatorCatalog.js';
+
+/**
+ * Central-only operator and user_decisions routes backed by Postgres.
+ *
+ * @param {string} basePath - plant API base path
+ * @param {object} sink - supervisor sink with pool and profile
+ * @returns {object} routes, provider, decisions
+ */
+function centralOperatorRoutes(basePath, sink, owners) {
+    if (sink.sinkDbProfile !== 'central') {
+        return { routes: [], provider: undefined, decisions: undefined };
+    }
+    const provider = operatorsFromPg(sink.pool);
+    const decisions = userDecisionsFromPg(sink.pool);
+    return {
+        routes: [
+            ...operatorRoute(basePath, provider),
+            ...decisionRoute(basePath, decisions, owners)
+        ],
+        provider,
+        decisions
+    };
+}
+
+/**
+ * Resolves operator HTTP catalog for central or edge sink profile.
+ *
+ * @param {string} basePath - plant API base path
+ * @param {object} sink - supervisor sink
+ * @param {object} env - process environment
+ * @param {object} [owners] - machineOwners registry for edge decision proxy
+ * @returns {object} routes, provider, decisions, sync
+ *
+ * @example
+ *   siteOperatorCatalog('/api/v1', sink, process.env, owners);
+ */
+export default function siteOperatorCatalog(basePath, sink, env, owners) {
+    if (sink.sinkDbProfile === 'central') {
+        return { ...centralOperatorRoutes(basePath, sink, owners), sync: undefined };
+    }
+    if (sink.sinkDbProfile === 'edge') {
+        const edge = edgeOperatorCatalog(basePath, env);
+        if (!sink.pool) {
+            return { ...edge, decisions: undefined };
+        }
+        const decisions = userDecisionsFromPg(sink.pool);
+        return {
+            ...edge,
+            routes: [...edge.routes, ...decisionRoute(basePath, decisions, owners)],
+            decisions
+        };
+    }
+    return { routes: [], sync: undefined, provider: undefined, decisions: undefined };
+}
+
+/**
+ * Picks plant operatorCatalog override or the built-in site catalog.
+ *
+ * @param {object} config - siteServer config, may include operatorCatalog factory
+ * @param {string} basePath - plant API base path
+ * @param {object} sink - supervisor sink
+ * @param {object} env - process environment
+ * @returns {object} routes, provider, decisions, sync
+ *
+ * @example
+ *   buildSiteOperatorCatalog({ operatorCatalog: plantCatalog }, '/api/v1', sink, env);
+ */
+export function buildSiteOperatorCatalog(config, basePath, sink, env) {
+    const factory = config && config.operatorCatalog
+        ? config.operatorCatalog
+        : siteOperatorCatalog;
+    return factory(basePath, sink, env, config && config.owners);
+}