@yarkivaev/scada 1.5.0 → 2.3.46

package/src/infrastructure/http/plant/json/operatorJson.js

@@ -0,0 +1,22 @@
+import operatorExtras, { operatorIdentityKeys } from '../../../operators/operatorExtras.js';
+
+/**
+ * Maps an operator domain record to REST JSON shape.
+ * Plant-owned attributes beyond identity are passed through unchanged.
+ *
+ * @param {object} row - operator with id, cardUid, firstName, lastName, displayName
+ * @returns {object} JSON-serializable operator
+ *
+ * @example
+ *   operatorJson({ id: 1, cardUid: 'dev-card-001', firstName: 'Ivan', lastName: 'Petrov', displayName: 'Ivan Petrov' });
+ */
+export default function operatorJson(row) {
+    return {
+        id: row.id,
+        cardUid: row.cardUid,
+        firstName: row.firstName,
+        lastName: row.lastName,
+        displayName: row.displayName,
+        ...operatorExtras(row, operatorIdentityKeys())
+    };
+}

package/src/infrastructure/http/plant/json/segmentJson.js

@@ -0,0 +1,27 @@
+/**
+ * Maps a timeline segment row to REST JSON shape.
+ *
+ * @param {object} row - segment with start_time, end_time, duration
+ * @returns {object} JSON-serializable segment
+ *
+ * @example
+ *   segmentJson({ name: 'on', start_time: new Date(), end_time: new Date(), duration: 60 });
+ */
+export default function segmentJson(row) {
+    const mapped = {
+        name: row.name,
+        start: row.start_time.toISOString(),
+        end: row.duration === 0 ? new Date().toISOString() : row.end_time.toISOString(),
+        duration: row.duration
+    };
+    if (row.options) {
+        mapped.options = row.options;
+    }
+    if (row.tags) {
+        mapped.tags = row.tags;
+    }
+    if (row.properties) {
+        mapped.properties = row.properties;
+    }
+    return mapped;
+}

package/src/infrastructure/http/plant/operationAudit.js

@@ -0,0 +1,56 @@
+/**
+ * Stamps operator audit into an operation payload and builds decision rows.
+ *
+ * @example
+ *   const next = stampPayload(payload, audit);
+ *   const row = decisionRow(machine, item, audit, 'create');
+ */
+
+/**
+ * Copies payload and adds operator display fields from audit.
+ *
+ * @param {*} payload - original operation payload
+ * @param {object} audit - { id, displayName, decidedAt }
+ * @returns {object} stamped payload object
+ */
+export function stampPayload(payload, audit) {
+    const base = payload && typeof payload === 'object' && !Array.isArray(payload)
+        ? { ...payload }
+        : { value: payload };
+    base.operator = audit.displayName;
+    base.decided_at = audit.decidedAt.toISOString();
+    if (audit.id !== undefined && audit.id !== null) {
+        base.operator_id = audit.id;
+    }
+    return base;
+}
+
+/**
+ * Builds a user_decisions insert row for an operation write.
+ *
+ * @param {string} machine - machine id
+ * @param {object} item - operation with key, kind, occurred_at, payload
+ * @param {object} audit - resolved operator audit
+ * @param {string} verb - create | update | delete
+ * @returns {object} insert row for userDecisions.insert
+ */
+export function decisionRow(machine, item, audit, verb) {
+    return {
+        machine,
+        startTime: item.occurred_at instanceof Date
+            ? item.occurred_at
+            : new Date(item.occurred_at),
+        username: audit.displayName,
+        operatorId: audit.id,
+        decidedAt: audit.decidedAt,
+        payload: {
+            kind: 'operation_op',
+            verb,
+            key: item.key,
+            operation_kind: item.kind,
+            occurred_at: item.occurred_at instanceof Date
+                ? item.occurred_at.toISOString()
+                : new Date(item.occurred_at).toISOString()
+        }
+    };
+}

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

@@ -0,0 +1,93 @@
+import { errorResponse, jsonResponse, pagination, route } from '@yarkivaev/simple-server';
+
+/**
+ * Alert routes factory.
+ * Creates routes for GET and PATCH /machines/:machineId/alerts.
+ *
+ * @param {string} basePath - base URL path
+ * @param {object} plant - plant domain object from scada package
+ * @returns {array} array of route objects
+ *
+ * @example
+ *   const routes = alertRoute('/api/v1', plant);
+ */
+export default function alertRoute(basePath, plant) {
+    function find(id) {
+        for (const shop of Object.values(plant.shops.get())) {
+            const machine = shop.machines.get()[id];
+            if (machine) {
+                return machine;
+            }
+        }
+        return undefined;
+    }
+    function findAlert(alertId) {
+        for (const shop of Object.values(plant.shops.get())) {
+            for (const machine of Object.values(shop.machines.get())) {
+                const alert = machine.alerts().find((a) => {
+                    return a.id === alertId;
+                });
+                if (alert) {
+                    return alert;
+                }
+            }
+        }
+        return undefined;
+    }
+    return [
+        route(
+            'GET',
+            `${basePath}/machines/:machineId/alerts`,
+            (req, res, params, query) => {
+                const machine = find(params.machineId);
+                if (!machine) {
+                    jsonResponse({ items: [], page: 1, size: 10, total: 0 }).send(res);
+                    return;
+                }
+                const page = query.page ? parseInt(query.page, 10) : 1;
+                const size = query.size ? parseInt(query.size, 10) : 10;
+                let alerts = machine.alerts();
+                if (query.acknowledged === 'true') {
+                    alerts = alerts.filter((a) => {
+                        return a.acknowledged === true;
+                    });
+                } else if (query.acknowledged === 'false') {
+                    alerts = alerts.filter((a) => {
+                        return a.acknowledged === false;
+                    });
+                }
+                const mapped = alerts.map((a) => {
+                    return { id: a.id, message: a.message, timestamp: a.timestamp.toISOString(), object: a.object, acknowledged: a.acknowledged, name: a.name };
+                });
+                const paginated = pagination(page, size, mapped).result();
+                jsonResponse({ items: paginated.items, page: paginated.page, size: paginated.size, total: paginated.total }).send(res);
+            }
+        ),
+        route(
+            'PATCH',
+            `${basePath}/machines/:machineId/alerts/:alertId`,
+            (req, res, params) => {
+                let body = '';
+                req.on('data', (chunk) => {
+                    body += chunk;
+                });
+                req.on('end', () => {
+                    const changes = JSON.parse(body);
+                    const alert = findAlert(params.alertId);
+                    if (!alert) {
+                        errorResponse(
+                            'NOT_FOUND',
+                            `Alert '${params.alertId}' not found`,
+                            404
+                        ).send(res);
+                        return;
+                    }
+                    if (changes.acknowledged === true && !alert.acknowledged) {
+                        alert.acknowledge();
+                    }
+                    jsonResponse({ id: alert.id, message: alert.message, timestamp: alert.timestamp.toISOString(), object: alert.object, acknowledged: true, name: alert.name }).send(res);
+                });
+            }
+        )
+    ];
+}

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

@@ -0,0 +1,21 @@
+import { jsonResponse, route } from '@yarkivaev/simple-server';
+import tagCatalog from '../../../catalog/tagCatalog.js';
+
+/**
+ * Tag catalog HTTP routes for HMI label/cascade lookup.
+ *
+ * @param {string} basePath - base URL path
+ * @param {object} [catalog] - optional preloaded catalog
+ * @returns {array} route objects
+ *
+ * @example
+ *   catalogRoute('/api/v1');
+ */
+export default function catalogRoute(basePath, catalog) {
+    const loaded = catalog || tagCatalog();
+    return [
+        route('GET', `${basePath}/tag-catalog`, (req, res) => {
+            jsonResponse({ items: loaded.entries() }).send(res);
+        })
+    ];
+}

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

@@ -0,0 +1,60 @@
+import decisionJson from '../json/decisionJson.js';
+import httpOperations from '../../../messaging/ownership/httpOperations.js';
+import { errorResponse, jsonResponse, route } from '@yarkivaev/simple-server';
+
+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);
+}
+
+/**
+ * Segment and operation user_decisions history routes.
+ *
+ * Operation chronology for edge-owned machines is proxied to the owner API.
+ *
+ * @param {string} basePath - base URL path
+ * @param {object} catalog - user decisions port with list and listByKey
+ * @param {object} [owners] - machineOwners registry
+ * @returns {array} route objects
+ *
+ * @example
+ *   decisionRoute('/api/v1', userDecisionsFromPg(pool), owners);
+ */
+export default function decisionRoute(basePath, catalog, owners) {
+    return [
+        route('GET', `${basePath}/machines/:machineId/segments/:start/decisions`, async (req, res, params) => {
+            const start = new Date(decodeURIComponent(params.start));
+            if (Number.isNaN(start.getTime())) {
+                errorResponse('BAD_REQUEST', `Invalid segment start '${params.start}'`, 400).send(res);
+                return;
+            }
+            const rows = await catalog.list(decodeURIComponent(params.machineId), start);
+            jsonResponse({ items: rows.map(decisionJson) }).send(res);
+        }),
+        route('GET', `${basePath}/machines/:machineId/operations/:key/decisions`, async (req, res, params) => {
+            const machineId = decodeURIComponent(params.machineId);
+            const key = decodeURIComponent(params.key);
+            if (!key) {
+                errorResponse('BAD_REQUEST', 'operation key is required', 400).send(res);
+                return;
+            }
+            const port = edgePort(owners, machineId);
+            if (port) {
+                jsonResponse({ items: await port.decisions(key) }).send(res);
+                return;
+            }
+            if (typeof catalog.listByKey !== 'function') {
+                jsonResponse({ items: [] }).send(res);
+                return;
+            }
+            const rows = await catalog.listByKey(machineId, key);
+            jsonResponse({ items: rows.map(decisionJson) }).send(res);
+        })
+    ];
+}

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

@@ -0,0 +1,35 @@
+import machineInPlant from '../../../../application/machineInPlant.js';
+import { errorResponse, jsonResponse, route } from '@yarkivaev/simple-server';
+
+/**
+ * Machine list and info routes.
+ *
+ * @param {string} basePath - base URL path
+ * @param {object} plant - plant domain object
+ * @returns {array} route objects
+ *
+ * @example
+ *   machineRoute('/api/v1', plant);
+ */
+export default function machineRoute(basePath, plant) {
+    function all() {
+        return Object.values(plant.shops.get()).flatMap((area) => {
+            return Object.values(area.machines.get()).map((item) => {
+                return { id: item.name(), name: item.name() };
+            });
+        });
+    }
+    return [
+        route('GET', `${basePath}/machines`, (req, res) => {
+            jsonResponse({ items: all() }).send(res);
+        }),
+        route('GET', `${basePath}/machines/:machineId`, (req, res, params) => {
+            const result = machineInPlant(plant, params.machineId);
+            if (!result) {
+                errorResponse('NOT_FOUND', `Machine '${params.machineId}' not found`, 404).send(res);
+                return;
+            }
+            jsonResponse({ id: result.machine.name(), name: result.machine.name() }).send(res);
+        })
+    ];
+}

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

@@ -0,0 +1,60 @@
+import machineInPlant from '../../../../application/machineInPlant.js';
+import { jsonResponse, route, timeExpression } from '@yarkivaev/simple-server';
+
+/**
+ * Measurement routes factory.
+ * Creates route for GET /machines/:machineId/measurements.
+ *
+ * @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 = measurementRoute('/api/v1', plant, clock);
+ */
+export default function measurementRoute(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;
+    }
+    return [
+        route(
+            'GET',
+            `${basePath}/machines/:machineId/measurements`,
+            async (req, res, params, query) => {
+                const machine = find(params.machineId);
+                if (!machine) {
+                    jsonResponse({ items: [] }).send(res);
+                    return;
+                }
+                const requested = query.keys ? query.keys.split(',') : Object.keys(machine.sensors);
+                const keys = requested.filter((key) => {return machine.sensors[key]});
+                const fromExpr = query.from || 'now-1M';
+                const toExpr = query.to || 'now';
+                const from = timeExpression(fromExpr, clock, beginning).resolve();
+                const to = timeExpression(toExpr, clock, beginning).resolve();
+                const step = query.step ? parseInt(query.step, 10) * 1000 : 1000;
+                const range = { start: from, end: to };
+                const promises = keys.map(async (key) => {
+                    const sensor = machine.sensors[key];
+                    const measurements = await sensor.measurements(range, step);
+                    const unit = measurements.length > 0 ? measurements[0].unit : '';
+                    const values = measurements.map((row) => {return {
+                        timestamp: row.timestamp.toISOString(),
+                        value: row.value
+                    }});
+                    return { key, name: sensor.name(), unit, values };
+                });
+                const items = await Promise.all(promises);
+                jsonResponse({ items }).send(res);
+            }
+        )
+    ];
+}

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

@@ -0,0 +1,79 @@
+import { randomUUID } from 'node:crypto';
+
+function reject(code, message, status) {
+    const err = new Error(message);
+    err.routeCode = code;
+    err.routeStatus = status;
+    return err;
+}
+
+/**
+ * Builds a create draft from a parsed POST body.
+ *
+ * @param {string} machineId - machine id
+ * @param {object} parsed - JSON body
+ * @returns {object} operation draft
+ */
+export function draftFromBody(machineId, parsed) {
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw reject('BAD_REQUEST', 'operation body must be a JSON object', 400);
+    }
+    if (typeof parsed.kind !== 'string' || parsed.kind.length === 0) {
+        throw reject('BAD_REQUEST', 'kind is required', 400);
+    }
+    if (parsed.payload === undefined) {
+        throw reject('BAD_REQUEST', 'payload is required', 400);
+    }
+    const occurred = parsed.occurred_at === undefined ? new Date() : new Date(parsed.occurred_at);
+    if (Number.isNaN(occurred.getTime())) {
+        throw reject('BAD_REQUEST', 'occurred_at must be a valid timestamp', 400);
+    }
+    const key = parsed.key === undefined || parsed.key === null
+        ? `${parsed.kind}:${machineId}:${randomUUID()}`
+        : parsed.key;
+    if (typeof key !== 'string' || key.length === 0) {
+        throw reject('BAD_REQUEST', 'key must be a non-empty string', 400);
+    }
+    return {
+        machine: machineId,
+        kind: parsed.kind,
+        key,
+        occurred_at: occurred,
+        payload: parsed.payload
+    };
+}
+
+/**
+ * Builds an update draft from existing row and parsed PUT body.
+ *
+ * @param {string} machineId - machine id
+ * @param {string} key - operation key
+ * @param {object} existing - current row
+ * @param {object} parsed - JSON body
+ * @returns {object} operation draft
+ */
+export function draftFromUpdate(machineId, key, existing, parsed) {
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw reject('BAD_REQUEST', 'operation body must be a JSON object', 400);
+    }
+    if (parsed.payload === undefined) {
+        throw reject('BAD_REQUEST', 'payload is required', 400);
+    }
+    const kind = parsed.kind === undefined ? existing.kind : parsed.kind;
+    if (typeof kind !== 'string' || kind.length === 0) {
+        throw reject('BAD_REQUEST', 'kind must be a non-empty string', 400);
+    }
+    const occurred = parsed.occurred_at === undefined
+        ? new Date(existing.occurred_at)
+        : new Date(parsed.occurred_at);
+    if (Number.isNaN(occurred.getTime())) {
+        throw reject('BAD_REQUEST', 'occurred_at must be a valid timestamp', 400);
+    }
+    return {
+        machine: machineId,
+        kind,
+        key,
+        occurred_at: occurred,
+        payload: parsed.payload
+    };
+}

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

@@ -0,0 +1,80 @@
+import machineInPlant from '../../../../application/machineInPlant.js';
+import operationJson from '../json/operationJson.js';
+import timelineOperator from '../timelineOperator.js';
+import operationWrites from './operationWrites.js';
+import { jsonResponse, route } from '@yarkivaev/simple-server';
+
+function parseRange(query) {
+    const range = {};
+    if (query.from) {
+        range.from = new Date(query.from);
+    }
+    if (query.to) {
+        range.to = new Date(query.to);
+    }
+    return range;
+}
+
+function resolveKinds(query) {
+    if (query.kinds) {
+        return query.kinds.split(',').map((token) => {
+            return token.trim();
+        }).filter((token) => {
+            return token.length > 0;
+        });
+    }
+    if (query.kind) {
+        return [query.kind];
+    }
+    return undefined;
+}
+
+/**
+ * Operations REST routes for machine-scoped reads and writes.
+ *
+ * Writes resolve operator via timelineOperator and stamp payload.operator.
+ * Edge-owned machines proxy create/update/delete to the owning plant API
+ * (no local upsert or decision insert). Optional owners registry mirrors timeline.
+ *
+ * @param {string} basePath - base URL path
+ * @param {object} plant - plant domain object
+ * @param {object} [operatorOptions] - timelineOperator options
+ * @param {object} [decisions] - userDecisions port with insert
+ * @param {object} [owners] - machineOwners registry
+ * @returns {array} route objects
+ *
+ * @example
+ *   operationRoute('/api/v1', plant, timelineOperatorOpts, decisions, owners);
+ */
+export default function operationRoute(basePath, plant, operatorOptions, decisions, owners) {
+    const writes = operationWrites({
+        plant,
+        gate: timelineOperator(operatorOptions),
+        decisions,
+        owners
+    });
+    return [
+        route('GET', `${basePath}/machines/:machineId/operations`, async (req, res, params, query) => {
+            const result = machineInPlant(plant, params.machineId);
+            if (!result || !plant.operations) {
+                jsonResponse({ items: [] }).send(res);
+                return;
+            }
+            const rows = await plant.operations.listForMachine(
+                params.machineId,
+                resolveKinds(query),
+                parseRange(query)
+            );
+            jsonResponse({ items: rows.map(operationJson) }).send(res);
+        }),
+        route('POST', `${basePath}/machines/:machineId/operations`, async (req, res, params) => {
+            await writes.writeCreate(params.machineId, req, res);
+        }),
+        route('PUT', `${basePath}/machines/:machineId/operations/:key`, async (req, res, params) => {
+            await writes.writeUpdate(params.machineId, decodeURIComponent(params.key), req, res);
+        }),
+        route('DELETE', `${basePath}/machines/:machineId/operations/:key`, async (req, res, params) => {
+            await writes.writeDelete(params.machineId, decodeURIComponent(params.key), req, res);
+        })
+    ];
+}