@yarkivaev/scada 1.5.0 → 2.3.46

package/src/infrastructure/http/edge/edgeApi.js

@@ -0,0 +1,54 @@
+import http from 'http';
+import checkpointRoutes from './routes/checkpoint/checkpointRoutes.js';
+import metricsRoutes from './routes/metrics/metricsRoutes.js';
+import retentionRoutes from './routes/retention/retentionRoutes.js';
+import { routes } from '@yarkivaev/simple-server';
+
+/**
+ * Builds edge HTTP API (metrics, checkpoint, retention only).
+ *
+ * @param {object} dataAccess - metrics and checkpoints backends
+ * @param {object} [options] - token, retention, metrics flags
+ * @returns {object} routes with list() and handle()
+ */
+export function createEdgeApi(dataAccess, options) {
+    const opt = options || {};
+    const token = Object.hasOwn(opt, 'token') ? opt.token : null;
+    const retentionDays = opt.retentionDays ?? 30;
+    const metricsEnabled = opt.metricsEnabled !== false;
+    const { metrics, checkpoints } = dataAccess;
+    const purge = opt.runRetention;
+    const admin = opt.retentionEnabled && opt.pool && purge
+        ? retentionRoutes(token, opt.pool, retentionDays, purge)
+        : [];
+    const metricRoutes = metricsEnabled
+        ? metricsRoutes(token, metrics)
+        : [];
+    return routes([
+        ...admin,
+        ...checkpointRoutes(token, checkpoints),
+        ...metricRoutes
+    ], { requestTimeoutMs: opt.requestTimeoutMs });
+}
+
+/**
+ * HTTP server for edge persistence API (/v1).
+ *
+ * @param {object} dataAccess - injected persistence backends
+ * @param {object} options - listen port, auth token, retention, metrics flags
+ * @returns {object} server with start() and stop()
+ */
+export default function edgeApi(dataAccess, options) {
+    const api = createEdgeApi(dataAccess, options);
+    const server = http.createServer((req, res) => {
+        return api.handle(req, res);
+    });
+    return {
+        start() {
+            server.listen(options.port);
+        },
+        stop() {
+            server.close();
+        }
+    };
+}

package/src/infrastructure/http/edge/httpMetricsRead.js

@@ -0,0 +1,34 @@
+/**
+ * Read port adapter for supervisor-sink metrics HTTP API.
+ *
+ * @param {object} client - stateHttpClient
+ * @returns {object} read port for metricsSensor
+ */
+export default function httpMetricsRead(client) {
+    return {
+        async current(topic) {
+            const data = await client.getJson('/v1/metrics/current', { topic });
+            if (!data.found) {
+                return { found: false };
+            }
+            return { found: true, ts: data.ts, value: data.value };
+        },
+        async range(topic, startIso, endIso, stepMs) {
+            const data = await client.getJson('/v1/metrics/range', {
+                topic,
+                start: startIso,
+                end: endIso,
+                stepMs: String(stepMs)
+            });
+            return data.items;
+        },
+        async poll(topic, afterIso, untilIso) {
+            const data = await client.getJson('/v1/metrics/poll', {
+                topic,
+                after: afterIso,
+                until: untilIso
+            });
+            return data.items;
+        }
+    };
+}

package/src/infrastructure/http/edge/metricsSensor.js

@@ -0,0 +1,15 @@
+import metricsSensor from '../../persistence/metricsSensor.js';
+import httpMetricsRead from './httpMetricsRead.js';
+
+/**
+ * Sensor reading metrics via supervisor-sink HTTP API.
+ *
+ * @param {object} client - stateHttpClient
+ * @param {string} topic - metrics topic key
+ * @param {string} displayName - label
+ * @param {string} unit - unit string
+ * @returns {object} sensor with name current measurements stream
+ */
+export default function stateHttpMetricsSensor(client, topic, displayName, unit) {
+    return metricsSensor(httpMetricsRead(client), topic, displayName, unit);
+}

package/src/infrastructure/http/edge/parseStateHttpTimeoutMs.js

@@ -0,0 +1,20 @@
+import { parseRequestTimeoutMs } from '@yarkivaev/simple-server';
+
+const DEFAULT_STATE_HTTP_TIMEOUT_MS = 25000;
+
+/**
+ * Resolves outbound supervisor-sink client timeout from environment.
+ *
+ * @param {NodeJS.ProcessEnv} env - process environment
+ * @returns {number} timeout in milliseconds
+ */
+export default function parseStateHttpTimeoutMs(env = process.env) {
+    if (env.STATE_HTTP_TIMEOUT_MS !== undefined && env.STATE_HTTP_TIMEOUT_MS !== '') {
+        return parseRequestTimeoutMs(env.STATE_HTTP_TIMEOUT_MS);
+    }
+    if (env.REQUEST_TIMEOUT_MS !== undefined && env.REQUEST_TIMEOUT_MS !== '') {
+        const total = parseRequestTimeoutMs(env.REQUEST_TIMEOUT_MS);
+        return Math.max(1000, Math.floor(total / 2));
+    }
+    return DEFAULT_STATE_HTTP_TIMEOUT_MS;
+}

package/src/infrastructure/http/edge/routes/checkpoint/checkpointRoutes.js

@@ -0,0 +1,79 @@
+import { hasAccess, sendForbidden } from '../../stateAccess.js';
+import { errorResponse, jsonResponse, route } from '@yarkivaev/simple-server';
+
+function parseFrom(raw) {
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : null;
+}
+
+function toTopicList(topicParam) {
+    if (Array.isArray(topicParam)) {
+        return topicParam;
+    }
+    if (typeof topicParam === 'string' && topicParam.length > 0) {
+        return [topicParam];
+    }
+    return [];
+}
+
+function segmentRoute(token, checkpointState) {
+    return route('GET', '/v1/checkpoint/segment', async (req, res, params, query) => {
+        void params;
+        if (!hasAccess(req, token)) {
+            sendForbidden(res);
+            return;
+        }
+        if (!query.machineId) {
+            errorResponse('BAD_REQUEST', 'machineId is required', 400).send(res);
+            return;
+        }
+        const start = parseFrom(query.start);
+        if (start === null) {
+            errorResponse('BAD_REQUEST', 'start must be a number', 400).send(res);
+            return;
+        }
+        const item = await checkpointState.segment(query.machineId, start);
+        jsonResponse({ item }).send(res);
+    });
+}
+
+export default function checkpointRoutes(token, checkpointState) {
+    return [
+        route('GET', '/v1/checkpoint/replay-cursor', async (req, res, params, query) => {
+            void params;
+            if (!hasAccess(req, token)) {
+                sendForbidden(res);
+                return;
+            }
+            if (!query.machineId) {
+                errorResponse('BAD_REQUEST', 'machineId is required', 400).send(res);
+                return;
+            }
+            const cursor = await checkpointState.replayCursor(query.machineId);
+            jsonResponse({ machineId: query.machineId, cursor }).send(res);
+        }),
+        segmentRoute(token, checkpointState),
+        route('GET', '/v1/checkpoint/pending-segments', async (req, res) => {
+            if (!hasAccess(req, token)) {
+                sendForbidden(res);
+                return;
+            }
+            const items = await checkpointState.pendingSegments();
+            jsonResponse({ items }).send(res);
+        }),
+        route('GET', '/v1/checkpoint/readings', async (req, res, params, query) => {
+            void params;
+            if (!hasAccess(req, token)) {
+                sendForbidden(res);
+                return;
+            }
+            const from = parseFrom(query.from);
+            if (from === null) {
+                errorResponse('BAD_REQUEST', 'from must be a number', 400).send(res);
+                return;
+            }
+            const items = await checkpointState.readings(toTopicList(query.topic), from);
+            jsonResponse({ items }).send(res);
+        })
+    ];
+}

package/src/infrastructure/http/edge/routes/metrics/metricsBatch.js

@@ -0,0 +1,59 @@
+import { hasAccess, sendForbidden } from '../../stateAccess.js';
+import { errorResponse, jsonResponse, readBody } from '@yarkivaev/simple-server';
+
+/**
+ * @param {string} raw - JSON body
+ * @returns {Array<{topic: string, ts: string|Date, value: number}>}
+ */
+function itemsFromBody(raw) {
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.items)) {
+        throw new Error('body must be an object with items array');
+    }
+    return parsed.items;
+}
+
+/**
+ * @param {import('http').IncomingMessage} req
+ * @param {import('http').ServerResponse} res
+ * @param {object} metrics - metrics state port
+ * @returns {Promise<void>}
+ */
+async function runBatch(req, res, metrics) {
+    let items;
+    try {
+        items = itemsFromBody(await readBody(req));
+    } catch (err) {
+        errorResponse('BAD_REQUEST', String(err.message), 400).send(res);
+        return;
+    }
+    if (items.length === 0) {
+        jsonResponse({ inserted: 0 }).send(res);
+        return;
+    }
+    if (items.length > 500) {
+        errorResponse('BAD_REQUEST', 'items length exceeds maximum of 500', 400).send(res);
+        return;
+    }
+    await metrics.insertRows(items);
+    jsonResponse({ inserted: items.length }).send(res);
+}
+
+/**
+ * Batch insert into metrics (MQTT pipeline sink).
+ *
+ * @param {string|null} token - optional bearer token
+ * @param {object} metrics - metrics state port
+ * @returns {function} route handler
+ */
+export default function metricsBatch(token, metrics) {
+    return async (req, res, params, query) => {
+        void params;
+        void query;
+        if (!hasAccess(req, token)) {
+            sendForbidden(res);
+            return;
+        }
+        await runBatch(req, res, metrics);
+    };
+}

package/src/infrastructure/http/edge/routes/metrics/metricsCurrent.js

@@ -0,0 +1,29 @@
+import { hasAccess, sendForbidden } from '../../stateAccess.js';
+import { errorResponse, jsonResponse } from '@yarkivaev/simple-server';
+
+/**
+ * Latest metric row for a topic (same semantics as postgresSensor.current).
+ *
+ * @param {string|null} token - optional bearer token
+ * @param {object} metrics - metrics state port
+ * @returns {function} route handler
+ */
+export default function metricsCurrent(token, metrics) {
+    return async (req, res, params, query) => {
+        void params;
+        if (!hasAccess(req, token)) {
+            sendForbidden(res);
+            return;
+        }
+        if (!query.topic) {
+            errorResponse('BAD_REQUEST', 'topic query parameter is required', 400).send(res);
+            return;
+        }
+        const row = await metrics.latestForTopic(query.topic);
+        if (!row) {
+            jsonResponse({ found: false }).send(res);
+            return;
+        }
+        jsonResponse({ found: true, ts: row.ts, value: row.value }).send(res);
+    };
+}

package/src/infrastructure/http/edge/routes/metrics/metricsPoll.js

@@ -0,0 +1,25 @@
+import { hasAccess, sendForbidden } from '../../stateAccess.js';
+import { errorResponse, jsonResponse } from '@yarkivaev/simple-server';
+
+/**
+ * Raw metric rows since a timestamp (postgresSensor.stream polling query).
+ *
+ * @param {string|null} token - optional bearer token
+ * @param {object} metrics - metrics state port
+ * @returns {function} route handler
+ */
+export default function metricsPoll(token, metrics) {
+    return async (req, res, params, query) => {
+        void params;
+        if (!hasAccess(req, token)) {
+            sendForbidden(res);
+            return;
+        }
+        if (!query.topic || !query.after || !query.until) {
+            errorResponse('BAD_REQUEST', 'topic after and until query parameters are required', 400).send(res);
+            return;
+        }
+        const items = await metrics.pollTopic(query.topic, query.after, query.until);
+        jsonResponse({ items }).send(res);
+    };
+}

package/src/infrastructure/http/edge/routes/metrics/metricsRange.js

@@ -0,0 +1,26 @@
+import { hasAccess, sendForbidden } from '../../stateAccess.js';
+import { errorResponse, jsonResponse } from '@yarkivaev/simple-server';
+
+/**
+ * Downsampled metric range (same date_bin semantics as postgresSensor.measurements).
+ *
+ * @param {string|null} token - optional bearer token
+ * @param {object} metrics - metrics state port
+ * @returns {function} route handler
+ */
+export default function metricsRange(token, metrics) {
+    return async (req, res, params, query) => {
+        void params;
+        if (!hasAccess(req, token)) {
+            sendForbidden(res);
+            return;
+        }
+        if (!query.topic || !query.start || !query.end) {
+            errorResponse('BAD_REQUEST', 'topic start and end query parameters are required', 400).send(res);
+            return;
+        }
+        const stepMs = parseInt(query.stepMs || '60000', 10);
+        const items = await metrics.rangeForTopic(query.topic, query.start, query.end, stepMs);
+        jsonResponse({ items }).send(res);
+    };
+}

package/src/infrastructure/http/edge/routes/metrics/metricsRoutes.js

@@ -0,0 +1,21 @@
+import metricsBatch from './metricsBatch.js';
+import metricsCurrent from './metricsCurrent.js';
+import metricsPoll from './metricsPoll.js';
+import metricsRange from './metricsRange.js';
+import { route } from '@yarkivaev/simple-server';
+
+/**
+ * Metrics read/write routes for /v1.
+ *
+ * @param {string|null} token - optional bearer token
+ * @param {object} metrics - metrics state port
+ * @returns {Array<object>} route definitions
+ */
+export default function metricsRoutes(token, metrics) {
+    return [
+        route('GET', '/v1/metrics/current', metricsCurrent(token, metrics)),
+        route('GET', '/v1/metrics/range', metricsRange(token, metrics)),
+        route('GET', '/v1/metrics/poll', metricsPoll(token, metrics)),
+        route('POST', '/v1/metrics/batch', metricsBatch(token, metrics))
+    ];
+}

package/src/infrastructure/http/edge/routes/retention/retentionRoutes.js

@@ -0,0 +1,41 @@
+import { hasAccess, sendForbidden } from '../../stateAccess.js';
+import { errorResponse, jsonResponse, route } from '@yarkivaev/simple-server';
+
+function parseDays(raw, fallback) {
+    if (raw === undefined || raw === '') {
+        return fallback;
+    }
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1) {
+        return null;
+    }
+    return value;
+}
+
+/**
+ * Admin retention route for scheduled database cleanup.
+ *
+ * @param {string|null} token - optional bearer token
+ * @param {object} pool - database pool passed to purge callback
+ * @param {number} defaultDays - retention window from deployment env
+ * @param {function} purge - async (pool, days) => cleanup result
+ * @returns {Array<object>} route definitions
+ */
+export default function retentionRoutes(token, pool, defaultDays, purge) {
+    return [
+        route('POST', '/v1/admin/retention', async (req, res, params, query) => {
+            void params;
+            if (!hasAccess(req, token)) {
+                sendForbidden(res);
+                return;
+            }
+            const days = parseDays(query.days, defaultDays);
+            if (days === null) {
+                errorResponse('BAD_REQUEST', 'days must be a positive integer', 400).send(res);
+                return;
+            }
+            const body = await purge(pool, days);
+            jsonResponse(body).send(res);
+        })
+    ];
+}

package/src/infrastructure/http/edge/startTestEdgeApi.js

@@ -0,0 +1,39 @@
+import http from 'http';
+import { createEdgeApi } from './edgeApi.js';
+
+/**
+ * Starts a test edge HTTP server on ephemeral port.
+ *
+ * @param {object} dataAccess - persistence backends
+ * @param {object} options - token, port
+ * @returns {Promise<{baseUrl: string, stop: function}>}
+ */
+export default async function startTestEdgeApi(dataAccess, options) {
+    const opt = options || {};
+    const token = Object.hasOwn(opt, 'token') ? opt.token : null;
+    const port = Object.hasOwn(opt, 'port') ? opt.port : 0;
+    const api = createEdgeApi(dataAccess, { token });
+    const server = http.createServer((req, res) => {
+        return api.handle(req, res);
+    });
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => {
+            resolve();
+        });
+    });
+    const addr = server.address();
+    const baseUrl = `http://127.0.0.1:${addr.port}`;
+    async function stop() {
+        await new Promise((resolve, reject) => {
+            server.close((err) => {
+                if (err) {
+                    reject(err);
+                } else {
+                    resolve();
+                }
+            });
+        });
+    }
+    return { baseUrl, stop };
+}

package/src/infrastructure/http/edge/stateAccess.js

@@ -0,0 +1,13 @@
+import { errorResponse } from '@yarkivaev/simple-server';
+
+export function hasAccess(request, token) {
+    if (!token) {
+        return true;
+    }
+    const header = request.headers.authorization || '';
+    return header === `Bearer ${token}`;
+}
+
+export function sendForbidden(res) {
+    errorResponse('FORBIDDEN', 'forbidden', 403).send(res);
+}

package/src/infrastructure/http/edge/stateHttpClient.js

@@ -0,0 +1,106 @@
+import stateHttpTimeoutError from './stateHttpTimeoutError.js';
+
+const DEFAULT_TIMEOUT_MS = 25000;
+
+function trimBase(url) {
+    return url.replace(/\/$/u, '');
+}
+
+function authHeaders(token, json) {
+    const headers = {};
+    if (json) {
+        headers['Content-Type'] = 'application/json';
+    }
+    if (token) {
+        headers.Authorization = `Bearer ${token}`;
+    }
+    return headers;
+}
+
+async function readError(res) {
+    const text = await res.text();
+    return text.length > 0 ? text : res.statusText;
+}
+
+function buildUrl(base, path, query) {
+    const qs = new URLSearchParams(query).toString();
+    return qs ? `${base}${path}?${qs}` : `${base}${path}`;
+}
+
+async function expectJson(res, verb, path) {
+    if (!res.ok) {
+        throw new Error(`supervisor state ${verb} ${path} failed: ${res.status} ${await readError(res)}`);
+    }
+    const payload = await res.json();
+    return payload;
+}
+
+function resolveTimeoutMs(options) {
+    if (options.timeoutMs === undefined || options.timeoutMs === null) {
+        return DEFAULT_TIMEOUT_MS;
+    }
+    const ms = Number(options.timeoutMs);
+    if (!Number.isFinite(ms) || ms <= 0) {
+        return DEFAULT_TIMEOUT_MS;
+    }
+    return ms;
+}
+
+function isAbortTimeout(err) {
+    return err && (err.name === 'TimeoutError' || err.name === 'AbortError');
+}
+
+async function fetchJson(url, init, verb, path, limit) {
+    const signal = AbortSignal.timeout(limit);
+    try {
+        return await fetch(url, { ...init, signal });
+    } catch (err) {
+        if (isAbortTimeout(err)) {
+            throw stateHttpTimeoutError(verb, path, limit);
+        }
+        throw err;
+    }
+}
+
+/**
+ * HTTP client for supervisor-sink system state API (/v1).
+ *
+ * @param {object} options - connection options
+ * @param {string} options.baseUrl - origin (no trailing slash)
+ * @param {string} [options.token] - optional Bearer token
+ * @param {number} [options.timeoutMs] - per-request deadline (default 25000)
+ * @returns {object} frozen client with getJson patchJson postJson
+ *
+ * @example
+ *   const client = stateHttpClient({ baseUrl: 'http://localhost:8081', token: 'secret' });
+ *   const data = await client.getJson('/v1/alerts', {});
+ */
+export default function stateHttpClient(options) {
+    const { baseUrl: rawBase, token } = options;
+    const limit = resolveTimeoutMs(options);
+    const base = trimBase(rawBase);
+    async function getJson(path, query) {
+        const url = buildUrl(base, path, query);
+        const res = await fetchJson(url, { headers: authHeaders(token, false) }, 'GET', path, limit);
+        return expectJson(res, 'GET', path);
+    }
+    async function patchJson(path, body) {
+        const url = `${base}${path}`;
+        const res = await fetchJson(url, {
+            method: 'PATCH',
+            headers: authHeaders(token, true),
+            body: JSON.stringify(body)
+        }, 'PATCH', path, limit);
+        return expectJson(res, 'PATCH', path);
+    }
+    async function postJson(path, body) {
+        const url = `${base}${path}`;
+        const res = await fetchJson(url, {
+            method: 'POST',
+            headers: authHeaders(token, true),
+            body: JSON.stringify(body)
+        }, 'POST', path, limit);
+        return expectJson(res, 'POST', path);
+    }
+    return Object.freeze({ getJson, patchJson, postJson, baseUrl: base, timeoutMs: limit });
+}

package/src/infrastructure/http/edge/stateHttpTimeoutError.js

@@ -0,0 +1,13 @@
+/**
+ * Error for supervisor-sink HTTP client deadline exceeded.
+ *
+ * @param {string} verb - HTTP method
+ * @param {string} path - request path
+ * @param {number} limit - timeout milliseconds
+ * @returns {Error} error with code TIMEOUT
+ */
+export default function stateHttpTimeoutError(verb, path, limit) {
+    const err = new Error(`supervisor state ${verb} ${path} exceeded ${limit}ms`);
+    err.code = 'TIMEOUT';
+    return err;
+}

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

@@ -0,0 +1,44 @@
+function iso(value) {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    return new Date(value).toISOString();
+}
+
+function body(raw) {
+    if (typeof raw !== 'string') {
+        return raw;
+    }
+    return JSON.parse(raw);
+}
+
+/**
+ * Maps a user_decisions audit row to Plant API JSON item.
+ *
+ * @param {object} row - username, operatorId, decidedAt, payload
+ * @returns {object} JSON-serializable decision with operator display and tags
+ *
+ * @example
+ *   decisionJson({
+ *     username: 'Elena Volkov', operatorId: 2,
+ *     decidedAt: new Date('2024-06-01T12:05:00.000Z'),
+ *     payload: '{"tags":["charge_loading"]}'
+ *   });
+ */
+export default function decisionJson(row) {
+    const payload = body(row.payload);
+    const item = {
+        operator: row.username,
+        payload
+    };
+    if (row.operatorId !== undefined && row.operatorId !== null) {
+        item.operatorId = row.operatorId;
+    }
+    if (row.decidedAt !== undefined && row.decidedAt !== null) {
+        item.decidedAt = iso(row.decidedAt);
+    }
+    if (payload && Array.isArray(payload.tags)) {
+        item.tags = payload.tags;
+    }
+    return item;
+}

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

@@ -0,0 +1,28 @@
+function iso(value) {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    return new Date(value).toISOString();
+}
+
+/**
+ * Maps persistence operation row to Plant API JSON item.
+ *
+ * @param {object} row - operation row from persistence
+ * @returns {object} API item with external_key and source_updated_at
+ *
+ * @example
+ *   operationJson({ key: 'nb-1', occurred_at: new Date(), kind: 'chem', payload: {}, machine: 'm1' });
+ */
+export default function operationJson(row) {
+    const occurred = iso(row.occurred_at);
+    const updated = row.source_updated_at ? iso(row.source_updated_at) : occurred;
+    return {
+        external_key: row.key,
+        occurred_at: occurred,
+        kind: row.kind,
+        payload: row.payload,
+        machine: row.machine,
+        source_updated_at: updated
+    };
+}