@yarkivaev/scada 1.4.0 → 2.3.45

package/src/infrastructure/http/plant/routes/operationWrites.js

@@ -0,0 +1,186 @@
+import machineInPlant from '../../../../application/machineInPlant.js';
+import operationJson from '../json/operationJson.js';
+import { decisionRow, stampPayload } from '../operationAudit.js';
+import { draftFromBody, draftFromUpdate } from './operationDrafts.js';
+import httpOperations from '../../../messaging/ownership/httpOperations.js';
+import { errorResponse, jsonResponse, readBody, sendRouteError } from '@yarkivaev/simple-server';
+
+function isMissing(err) {
+    return typeof err.message === 'string' && err.message.includes('not found for machine');
+}
+
+function sendFailure(gate, res, err) {
+    if (gate && gate.sendError(res, err)) {
+        return;
+    }
+    if (err.routeCode && err.routeStatus) {
+        errorResponse(err.routeCode, err.message, err.routeStatus).send(res);
+        return;
+    }
+    if (isMissing(err)) {
+        errorResponse('NOT_FOUND', err.message, 404).send(res);
+        return;
+    }
+    sendRouteError(res, err);
+}
+
+function machineMissing(plant, machineId, res) {
+    const result = machineInPlant(plant, machineId);
+    if (!result || !plant.operations) {
+        errorResponse('NOT_FOUND', `Machine '${machineId}' not found`, 404).send(res);
+        return true;
+    }
+    return false;
+}
+
+async function record(decisions, machine, item, audit, verb) {
+    if (!decisions || typeof decisions.insert !== 'function') {
+        return;
+    }
+    await decisions.insert(decisionRow(machine, item, audit, verb));
+}
+
+async function readJson(req) {
+    if (typeof req.on !== 'function') {
+        return {};
+    }
+    const raw = await readBody(req);
+    if (!raw || String(raw).trim().length === 0) {
+        return {};
+    }
+    return JSON.parse(raw);
+}
+
+function edgePort(owners, machineId) {
+    if (!owners || typeof owners.resolve !== 'function') {
+        return undefined;
+    }
+    const owner = owners.resolve(machineId);
+    if (!owner || owner.kind !== 'edge') {
+        return undefined;
+    }
+    return httpOperations(owner, machineId);
+}
+
+function forwardBody(parsed, audit) {
+    const body = { ...parsed };
+    if (audit.id !== undefined && audit.id !== null) {
+        body.operatorId = audit.id;
+    }
+    return body;
+}
+
+function ownerItem(machineId, key, response, parsed) {
+    return {
+        machine: machineId,
+        key: (response && (response.external_key || response.key)) || key || parsed.key,
+        kind: (response && response.kind) || parsed.kind,
+        occurred_at: (response && response.occurred_at) || parsed.occurred_at || new Date(),
+        payload: (response && response.payload) || parsed.payload
+    };
+}
+
+async function localCreate(ctx, machineId, parsed, audit) {
+    const item = draftFromBody(machineId, parsed);
+    item.payload = stampPayload(item.payload, audit);
+    await ctx.plant.operations.upsert(item);
+    await record(ctx.decisions, machineId, item, audit, 'create');
+    return item;
+}
+
+async function localUpdate(ctx, machineId, key, parsed, audit) {
+    const existing = await ctx.plant.operations.get(machineId, key);
+    const item = draftFromUpdate(machineId, key, existing, parsed);
+    item.payload = stampPayload(item.payload, audit);
+    await ctx.plant.operations.upsert(item);
+    await record(ctx.decisions, machineId, item, audit, 'update');
+    return item;
+}
+
+async function localDelete(ctx, machineId, key, audit) {
+    const item = await ctx.plant.operations.remove(machineId, key);
+    await record(ctx.decisions, machineId, item, audit, 'delete');
+    return item;
+}
+
+async function writeCreate(ctx, machineId, req, res) {
+    if (machineMissing(ctx.plant, machineId, res)) {
+        return;
+    }
+    try {
+        const parsed = await readJson(req);
+        const audit = await ctx.gate.resolve(parsed);
+        const port = edgePort(ctx.owners, machineId);
+        if (port) {
+            const created = await port.create(forwardBody(parsed, audit));
+            await record(ctx.decisions, machineId, ownerItem(machineId, undefined, created, parsed), audit, 'create');
+            jsonResponse(created).send(res);
+            return;
+        }
+        jsonResponse(operationJson(await localCreate(ctx, machineId, parsed, audit))).send(res);
+    } catch (err) {
+        sendFailure(ctx.gate, res, err);
+    }
+}
+
+async function writeUpdate(ctx, machineId, key, req, res) {
+    if (machineMissing(ctx.plant, machineId, res)) {
+        return;
+    }
+    try {
+        const parsed = await readJson(req);
+        const audit = await ctx.gate.resolve(parsed);
+        const port = edgePort(ctx.owners, machineId);
+        if (port) {
+            const updated = await port.update(key, forwardBody(parsed, audit));
+            await record(ctx.decisions, machineId, ownerItem(machineId, key, updated, parsed), audit, 'update');
+            jsonResponse(updated).send(res);
+            return;
+        }
+        jsonResponse(operationJson(await localUpdate(ctx, machineId, key, parsed, audit))).send(res);
+    } catch (err) {
+        sendFailure(ctx.gate, res, err);
+    }
+}
+
+async function writeDelete(ctx, machineId, key, req, res) {
+    if (machineMissing(ctx.plant, machineId, res)) {
+        return;
+    }
+    try {
+        const parsed = await readJson(req);
+        const audit = await ctx.gate.resolve(parsed);
+        const port = edgePort(ctx.owners, machineId);
+        if (port) {
+            const removed = await port.remove(key, forwardBody(parsed, audit));
+            await record(ctx.decisions, machineId, ownerItem(machineId, key, removed, parsed), audit, 'delete');
+            jsonResponse(removed).send(res);
+            return;
+        }
+        jsonResponse(operationJson(await localDelete(ctx, machineId, key, audit))).send(res);
+    } catch (err) {
+        sendFailure(ctx.gate, res, err);
+    }
+}
+
+/**
+ * Builds create/update/delete handlers for operationRoute.
+ *
+ * Edge-owned machines proxy to the owning plant API without local upsert.
+ *
+ * @param {object} ctx - plant, gate, decisions, owners
+ * @returns {object} writeCreate, writeUpdate, writeDelete
+ */
+export default function operationWrites(ctx) {
+    return {
+        writeCreate(machineId, req, res) {
+            return writeCreate(ctx, machineId, req, res);
+        },
+        writeUpdate(machineId, key, req, res) {
+            return writeUpdate(ctx, machineId, key, req, res);
+        },
+        writeDelete(machineId, key, req, res) {
+            return writeDelete(ctx, machineId, key, req, res);
+        }
+    };
+}

package/src/infrastructure/http/plant/routes/operatorRoute.js

@@ -0,0 +1,143 @@
+import operatorJson from '../json/operatorJson.js';
+import operatorExtras, { operatorDraftKeys } from '../../../operators/operatorExtras.js';
+import { errorResponse, jsonResponse, readBody, route, sendRouteError } from '@yarkivaev/simple-server';
+
+function routeFailure(code, message, status) {
+    const err = new Error(message);
+    err.routeCode = code;
+    err.routeStatus = status;
+    return err;
+}
+
+function sendKnown(res, err) {
+    if (err && err.routeCode && err.routeStatus) {
+        errorResponse(err.routeCode, err.message, err.routeStatus).send(res);
+        return true;
+    }
+    return false;
+}
+
+function report(logger, message, err) {
+    if (logger && typeof logger.error === 'function') {
+        logger.error(message, err);
+        return;
+    }
+    console.error(message, err); // eslint-disable-line no-console
+}
+
+function normalizeUid(raw) {
+    return String(raw).trim().toUpperCase();
+}
+
+function draftFromBody(parsed) {
+    if (!parsed || typeof parsed !== 'object') {
+        throw routeFailure('BAD_REQUEST', 'operator body must be a JSON object', 400);
+    }
+    const { firstName, lastName, displayName } = parsed;
+    const cardUid = normalizeUid(parsed.cardUid === undefined || parsed.cardUid === null ? '' : parsed.cardUid);
+    if (!cardUid) {
+        throw routeFailure('BAD_REQUEST', 'cardUid is required', 400);
+    }
+    if (typeof firstName !== 'string' || !firstName.trim()) {
+        throw routeFailure('BAD_REQUEST', 'firstName is required', 400);
+    }
+    if (typeof lastName !== 'string' || !lastName.trim()) {
+        throw routeFailure('BAD_REQUEST', 'lastName is required', 400);
+    }
+    if (typeof displayName !== 'string' || !displayName.trim()) {
+        throw routeFailure('BAD_REQUEST', 'displayName is required', 400);
+    }
+    return {
+        cardUid,
+        firstName,
+        lastName,
+        displayName,
+        ...operatorExtras(parsed, operatorDraftKeys())
+    };
+}
+
+function flagFromBody(parsed) {
+    if (!parsed || typeof parsed !== 'object') {
+        throw routeFailure('BAD_REQUEST', 'registration body must be a JSON object', 400);
+    }
+    if (typeof parsed.enabled !== 'boolean') {
+        throw routeFailure('BAD_REQUEST', 'enabled must be a boolean', 400);
+    }
+    return parsed.enabled;
+}
+
+async function handleGetEnabled(provider, logger, basePath, res) {
+    try {
+        const enabled = await provider.enabled();
+        jsonResponse({ enabled }).send(res);
+    } catch (err) {
+        report(logger, `GET ${basePath}/operators/registration-enabled failed: ${err && err.message ? err.message : 'unknown error'}`, err);
+        sendRouteError(res, err);
+    }
+}
+
+async function handlePutEnabled(provider, logger, basePath, req, res) {
+    try {
+        const enabled = flagFromBody(JSON.parse(await readBody(req)));
+        const stored = await provider.permit(enabled);
+        jsonResponse({ enabled: stored }).send(res);
+    } catch (err) {
+        if (sendKnown(res, err)) {
+            return;
+        }
+        report(logger, `PUT ${basePath}/operators/registration-enabled failed: ${err && err.message ? err.message : 'unknown error'}`, err);
+        sendRouteError(res, err);
+    }
+}
+
+async function handleList(provider, logger, basePath, res) {
+    try {
+        const rows = await provider.list();
+        jsonResponse({ items: rows.map(operatorJson) }).send(res);
+    } catch (err) {
+        report(logger, `GET ${basePath}/operators failed: ${err && err.message ? err.message : 'unknown error'}`, err);
+        sendRouteError(res, err);
+    }
+}
+
+async function handleCreate(provider, logger, basePath, req, res) {
+    try {
+        const draft = draftFromBody(JSON.parse(await readBody(req)));
+        const created = await provider.create(draft);
+        jsonResponse(operatorJson(created)).send(res);
+    } catch (err) {
+        if (sendKnown(res, err)) {
+            return;
+        }
+        report(logger, `POST ${basePath}/operators failed: ${err && err.message ? err.message : 'unknown error'}`, err);
+        sendRouteError(res, err);
+    }
+}
+
+/**
+ * Operator catalog and registration routes for central plant API.
+ *
+ * @param {string} basePath - base URL path
+ * @param {object} provider - operators provider with list, create, enabled, permit
+ * @param {object} [logger] - optional logger with error(message, err)
+ * @returns {array} route objects
+ *
+ * @example
+ *   operatorRoute('/api/v1', operatorsFromPg(pool));
+ */
+export default function operatorRoute(basePath, provider, logger) {
+    return [
+        route('GET', `${basePath}/operators/registration-enabled`, async (req, res) => {
+            await handleGetEnabled(provider, logger, basePath, res);
+        }),
+        route('PUT', `${basePath}/operators/registration-enabled`, async (req, res) => {
+            await handlePutEnabled(provider, logger, basePath, req, res);
+        }),
+        route('GET', `${basePath}/operators`, async (req, res) => {
+            await handleList(provider, logger, basePath, res);
+        }),
+        route('POST', `${basePath}/operators`, async (req, res) => {
+            await handleCreate(provider, logger, basePath, req, res);
+        })
+    ];
+}

package/src/infrastructure/http/plant/routes/simulationRoute.js

@@ -0,0 +1,61 @@
+import { errorResponse, jsonResponse, route } from '@yarkivaev/simple-server';
+
+/**
+ * Simulation control routes factory.
+ * Creates routes for jumping, resetting, and querying virtual clock.
+ *
+ * @param {string} basePath - base URL path
+ * @param {function} clock - virtual clock with jump, reset, offset methods
+ * @returns {array} array of route objects
+ *
+ * @example
+ *   const routes = simulationRoute('/api', virtualClock(() => new Date()));
+ */
+export default function simulationRoute(basePath, clock) {
+    return [
+        route(
+            'POST',
+            `${basePath}/simulation/jump`,
+            (req, res) => {
+                let body = '';
+                req.on('data', (chunk) => {
+                    body += chunk;
+                });
+                req.on('end', () => {
+                    const parsed = JSON.parse(body);
+                    const target = new Date(parsed.timestamp);
+                    if (isNaN(target.getTime())) {
+                        errorResponse('BAD_REQUEST', 'Invalid timestamp', 400).send(res);
+                        return;
+                    }
+                    clock.jump(target);
+                    jsonResponse({
+                        timestamp: clock().toISOString(),
+                        offset: clock.offset()
+                    }).send(res);
+                });
+            }
+        ),
+        route(
+            'DELETE',
+            `${basePath}/simulation`,
+            (req, res) => {
+                clock.reset();
+                jsonResponse({
+                    timestamp: clock().toISOString(),
+                    offset: clock.offset()
+                }).send(res);
+            }
+        ),
+        route(
+            'GET',
+            `${basePath}/simulation`,
+            (req, res) => {
+                jsonResponse({
+                    timestamp: clock().toISOString(),
+                    offset: clock.offset()
+                }).send(res);
+            }
+        )
+    ];
+}

package/src/infrastructure/http/plant/routes/timelineRoute.js

@@ -0,0 +1,112 @@
+import machineInPlant from '../../../../application/machineInPlant.js';
+import segmentJson from '../json/segmentJson.js';
+import timelineOperator from '../timelineOperator.js';
+import { errorResponse, jsonResponse, readBody, route, sendRouteError } from '@yarkivaev/simple-server';
+
+async function handleOperatorWrite(gate, parsed, write) {
+    const audit = await gate.resolve(parsed);
+    await write(audit);
+}
+
+async function respondToRequest(gate, timeline, requestId, req, res) {
+    const raw = await readBody(req);
+    const parsed = JSON.parse(raw);
+    let response;
+    await handleOperatorWrite(gate, parsed, async (audit) => {
+        response = await timeline.respond(requestId, parsed, audit);
+    });
+    if (!response) {
+        errorResponse('NOT_FOUND', `Request '${requestId}' not found`, 404).send(res);
+        return;
+    }
+    jsonResponse({ id: requestId, status: 'resolved' }).send(res);
+}
+
+/**
+ * Timeline REST routes for segments and label requests.
+ *
+ * @param {string} basePath - base URL path
+ * @param {object} plant - plant domain object
+ * @param {object} [operatorOptions] - provider, requireOperator, defaultUser
+ * @returns {array} route objects
+ *
+ * @example
+ *   timelineRoute('/api/v1', plant, { provider, requireOperator: true, defaultUser: 'hmi-kiosk' });
+ */
+export default function timelineRoute(basePath, plant, operatorOptions) {
+    const gate = timelineOperator(operatorOptions);
+    return [
+        route('GET', `${basePath}/machines/:machineId/segments`, async (req, res, params, query) => {
+            const result = machineInPlant(plant, params.machineId);
+            if (!result) {
+                jsonResponse({ items: [] }).send(res);
+                return;
+            }
+            const options = {};
+            if (query.from) {
+                options.from = query.from;
+            }
+            if (query.to) {
+                options.to = query.to;
+            }
+            const rows = await result.machine.timeline.list(options);
+            jsonResponse({ items: rows.map(segmentJson) }).send(res);
+        }),
+        route('PATCH', `${basePath}/machines/:machineId/segments`, async (req, res, params) => {
+            const result = machineInPlant(plant, params.machineId);
+            if (!result) {
+                errorResponse('NOT_FOUND', `Machine '${params.machineId}' not found`, 404).send(res);
+                return;
+            }
+            try {
+                const raw = await readBody(req);
+                const parsed = JSON.parse(raw);
+                await handleOperatorWrite(gate, parsed, async (audit) => {
+                    await result.machine.timeline.retag(new Date(parsed.start), parsed.tags, parsed.properties, audit);
+                });
+                jsonResponse({ status: 'updated' }).send(res);
+            } catch (err) {
+                if (gate.sendError(res, err)) {
+                    return;
+                }
+                sendRouteError(res, err);
+            }
+        }),
+        route('GET', `${basePath}/machines/:machineId/requests`, async (req, res, params) => {
+            const result = machineInPlant(plant, params.machineId);
+            if (!result) {
+                jsonResponse({ items: [] }).send(res);
+                return;
+            }
+            const rows = await result.machine.timeline.pending();
+            const items = rows.map(({ id, name, start_time: startTime, end_time: endTime, duration, options }) => {
+                return {
+                    id,
+                    segment: {
+                        name,
+                        start: startTime.toISOString(),
+                        end: endTime.toISOString(),
+                        duration
+                    },
+                    options
+                };
+            });
+            jsonResponse({ items }).send(res);
+        }),
+        route('POST', `${basePath}/machines/:machineId/requests/:requestId/respond`, async (req, res, params) => {
+            const result = machineInPlant(plant, params.machineId);
+            if (!result) {
+                errorResponse('NOT_FOUND', `Machine '${params.machineId}' not found`, 404).send(res);
+                return;
+            }
+            try {
+                await respondToRequest(gate, result.machine.timeline, params.requestId, req, res);
+            } catch (err) {
+                if (gate.sendError(res, err)) {
+                    return;
+                }
+                sendRouteError(res, err);
+            }
+        })
+    ];
+}

package/src/infrastructure/http/plant/streams/alertStream.js

@@ -0,0 +1,68 @@
+import { route, sseResponse } from '@yarkivaev/simple-server';
+
+/**
+ * Alert stream route factory.
+ * Creates SSE route for /machines/:machineId/alerts/stream.
+ * Streams alert_created and alert_updated events for the specified machine.
+ *
+ * @param {string} basePath - base URL path
+ * @param {object} plant - plant domain object from scada package
+ * @param {function} clock - time provider
+ * @returns {array} array of route objects
+ *
+ * @example
+ *   const routes = alertStream('/api/v1', plant, clock);
+ */
+export default function alertStream(basePath, plant, clock) {
+    function find(machineId) {
+        for (const shop of Object.values(plant.shops.get())) {
+            const machine = shop.machines.get()[machineId];
+            if (machine) {
+                return { machine, shop };
+            }
+        }
+        return undefined;
+    }
+    return [
+        route(
+            'GET',
+            `${basePath}/machines/:machineId/alerts/stream`,
+            (req, res, params) => {
+                const sse = sseResponse(res, clock);
+                sse.heartbeat();
+                const result = find(params.machineId);
+                if (!result) {
+                    sse.close();
+                    return;
+                }
+                const { machine, shop } = result;
+                const subscription = shop.alerts.stream((event) => {
+                    if (event.alert.object === machine.name()) {
+                        if (event.type === 'created') {
+                            sse.emit('alert_created', {
+                                id: event.alert.id,
+                                message: event.alert.message,
+                                timestamp: event.alert.timestamp.toISOString(),
+                                object: event.alert.object,
+                                acknowledged: event.alert.acknowledged,
+                                name: event.alert.name
+                            });
+                        } else if (event.type === 'acknowledged') {
+                            sse.emit('alert_updated', {
+                                id: event.alert.id,
+                                acknowledged: true
+                            });
+                        }
+                    }
+                });
+                const heartbeat = setInterval(() => {
+                    sse.heartbeat();
+                }, 30000);
+                req.on('close', () => {
+                    clearInterval(heartbeat);
+                    subscription.cancel();
+                });
+            }
+        )
+    ];
+}

package/src/infrastructure/http/plant/streams/heartbeatStream.js

@@ -0,0 +1,34 @@
+import { route, sseResponse } from '@yarkivaev/simple-server';
+
+/**
+ * Heartbeat stream route factory.
+ * Creates SSE route for /heartbeat/stream that sends periodic heartbeat events.
+ * Used by frontend watchdog to detect connection loss.
+ *
+ * @param {string} basePath - base URL path
+ * @param {function} clock - time provider
+ * @param {number} period - interval between heartbeats in milliseconds (default: 5000)
+ * @returns {array} array of route objects
+ *
+ * @example
+ *   const routes = heartbeatStream('/api/v1', () => new Date(), 1000);
+ */
+export default function heartbeatStream(basePath, clock, period) {
+    const ms = period || 5000;
+    return [
+        route(
+            'GET',
+            `${basePath}/heartbeat/stream`,
+            (req, res) => {
+                const sse = sseResponse(res, clock);
+                sse.heartbeat();
+                const interval = setInterval(() => {
+                    sse.heartbeat();
+                }, ms);
+                req.on('close', () => {
+                    clearInterval(interval);
+                });
+            }
+        )
+    ];
+}

package/src/infrastructure/http/plant/streams/measurementStream.js

@@ -0,0 +1,90 @@
+import machineInPlant from '../../../../application/machineInPlant.js';
+import { route, sseResponse, timeExpression } from '@yarkivaev/simple-server';
+
+/**
+ * Measurement stream route factory.
+ * Creates SSE route for /machines/:machineId/measurements/stream.
+ *
+ * @param {string} basePath - base URL path
+ * @param {object} plant - plant domain object from scada package
+ * @param {function} clock - time provider
+ * @returns {array} array of route objects
+ *
+ * @example
+ *   const routes = measurementStream('/api/v1', plant, clock);
+ */
+const RETAIN_MS = 10000;
+
+export default function measurementStream(basePath, plant, clock) {
+    function beginning() {
+        return new Date(clock().getTime() - 30 * 24 * 60 * 60 * 1000);
+    }
+    function find(id) {
+        const result = machineInPlant(plant, id);
+        if (result) {
+            return result.machine;
+        }
+        return undefined;
+    }
+    function subscribe(machine, keys, since, step, sse) {
+        const subscriptions = [];
+        keys.forEach((key) => {
+            if (machine.sensors[key]) {
+                const subscription = machine.sensors[key].stream(since, step, (item) => {
+                    sse.emit('measurement', {
+                        key,
+                        timestamp: item.timestamp.toISOString(),
+                        value: item.value
+                    });
+                }, clock);
+                subscriptions.push(subscription);
+            }
+        });
+        return subscriptions;
+    }
+    async function retain(machine, keys, sse) {
+        for (const key of keys) {
+            if (machine.sensors[key]) {
+                // eslint-disable-next-line no-await-in-loop
+                const reading = await machine.sensors[key].current();
+                if (reading.found && clock().getTime() - reading.timestamp.getTime() < RETAIN_MS) {
+                    sse.emit('measurement', {
+                        key,
+                        timestamp: reading.timestamp.toISOString(),
+                        value: reading.value
+                    });
+                }
+            }
+        }
+    }
+    return [
+        route(
+            'GET',
+            `${basePath}/machines/:machineId/measurements/stream`,
+            async (req, res, params, query) => {
+                const sse = sseResponse(res, clock);
+                sse.heartbeat();
+                const machine = find(params.machineId);
+                if (!machine) {
+                    sse.close();
+                    return;
+                }
+                const keys = query.keys ? query.keys.split(',') : Object.keys(machine.sensors);
+                const sinceExpr = query.since || 'now';
+                const since = timeExpression(sinceExpr, clock, beginning).resolve();
+                const step = query.step ? parseInt(query.step, 10) * 1000 : 1000;
+                const subscriptions = subscribe(machine, keys, since, step, sse);
+                const heartbeat = setInterval(() => {
+                    sse.heartbeat();
+                }, 30000);
+                req.on('close', () => {
+                    clearInterval(heartbeat);
+                    subscriptions.forEach((subscription) => {
+                        subscription.cancel();
+                    });
+                });
+                await retain(machine, keys, sse);
+            }
+        )
+    ];
+}