@yarkivaev/scada 2.3.85 → 2.3.86

package/src/domain/namespace/namespaceTree.js

@@ -0,0 +1,182 @@
+/**
+ * Reads a non-empty path.
+ *
+ * @param {object} node - candidate node
+ * @returns {string} path
+ *
+ * @example
+ *   pathOf({ path: 'site/unit' });
+ */
+function pathOf(node) {
+    if (typeof node.path === 'string' && node.path.length > 0) {
+        return node.path;
+    }
+    throw new Error('Namespace path is empty');
+}
+
+/**
+ * Requires a non-empty opaque kind.
+ *
+ * @param {object} node - candidate node
+ * @returns {string} kind
+ *
+ * @example
+ *   kindOf({ kind: 'metric', path: 'site/metric' });
+ */
+function kindOf(node) {
+    if (typeof node.kind === 'string' && node.kind.length > 0) {
+        return node.kind;
+    }
+    throw new Error(`Namespace kind is missing for ${pathOf(node)}`);
+}
+
+/**
+ * Requires a non-negative silence threshold in seconds.
+ *
+ * @param {object} node - candidate node
+ * @returns {number} silence seconds
+ *
+ * @example
+ *   silenceOf({ path: 'site', silenceSeconds: 60 });
+ */
+function silenceOf(node) {
+    const value = node.silenceSeconds;
+    if (typeof value === 'number' && value >= 0) {
+        return value;
+    }
+    throw new Error(`Namespace silence is missing for ${pathOf(node)}`);
+}
+
+/**
+ * Uses an explicit title or the last path segment.
+ *
+ * @param {object} node - candidate node
+ * @param {string} path - unique path
+ * @returns {string} display title
+ *
+ * @example
+ *   titled({ title: 'Unit' }, 'site/unit');
+ */
+function titled(node, path) {
+    if (typeof node.title === 'string' && node.title.length > 0) {
+        return node.title;
+    }
+    const parts = path.split('/');
+    return parts[parts.length - 1];
+}
+
+/**
+ * Copies one node into a frozen record.
+ *
+ * @param {object} node - candidate node
+ * @param {string} path - unique path
+ * @returns {object} frozen node
+ *
+ * @example
+ *   freezeNode({ kind: 'site', path: 'site', silenceSeconds: 30 }, 'site');
+ */
+function freezeNode(node, path) {
+    const frozen = {
+        kind: kindOf(node),
+        path,
+        silenceSeconds: silenceOf(node),
+        title: titled(node, path)
+    };
+    if (typeof node.source === 'string') {
+        frozen.source = node.source;
+    }
+    if (typeof node.unit === 'string') {
+        frozen.unit = node.unit;
+    }
+    return Object.freeze(frozen);
+}
+
+/**
+ * Builds a path map and rejects duplicates.
+ *
+ * @param {Array<object>} nodes - candidate nodes
+ * @returns {{ list: Array<object>, map: Map<string, object> }} index
+ *
+ * @example
+ *   indexNodes([{ kind: 'site', path: 'site', silenceSeconds: 30 }]);
+ */
+function indexNodes(nodes) {
+    const map = new Map();
+    for (const node of nodes) {
+        const path = pathOf(node);
+        if (map.has(path)) {
+            throw new Error(`Namespace path is duplicated: ${path}`);
+        }
+        map.set(path, freezeNode(node, path));
+    }
+    return { list: [...map.values()], map };
+}
+
+/**
+ * Returns the node for a path or throws when it is absent.
+ *
+ * @param {Map<string, object>} map - path index
+ * @param {string} path - requested path
+ * @returns {object} frozen node
+ *
+ * @example
+ *   lookup(new Map([['site', { path: 'site' }]]), 'site');
+ */
+function lookup(map, path) {
+    const node = map.get(path);
+    if (node) {
+        return node;
+    }
+    throw new Error(`Namespace path is missing: ${path}`);
+}
+
+/**
+ * Requires an array of nodes.
+ *
+ * @param {Array<object>} nodes - candidate nodes
+ * @returns {Array<object>} the same array when it is an array
+ *
+ * @example
+ *   nodesOf([{ kind: 'site', path: 'site', silenceSeconds: 30 }]);
+ */
+function nodesOf(nodes) {
+    if (Array.isArray(nodes)) {
+        return nodes;
+    }
+    throw new Error('Namespace nodes are missing');
+}
+
+/**
+ * Indexes plant nodes by a unique path for analytics reads.
+ *
+ * A node is an opaque kind, a silence threshold in seconds, and an optional
+ * source topic. Paths are the address. Gateway topics stay on the node and
+ * are not required.
+ *
+ * @param {Array<object>} nodes - path, kind, silenceSeconds, optional source, title, unit
+ * @returns {object} list, resolve, and below
+ *
+ * @example
+ *   const tree = namespaceTree([
+ *     { path: 'site/shop/unit', kind: 'unit', silenceSeconds: 60 }
+ *   ]);
+ *   tree.resolve('site/shop/unit').kind;
+ */
+export default function namespaceTree(nodes) {
+    const index = indexNodes(nodesOf(nodes));
+    return Object.freeze({
+        below(path) {
+            const node = lookup(index.map, path);
+            const prefix = `${node.path}/`;
+            return index.list.filter((item) => {
+                return item.path.startsWith(prefix);
+            });
+        },
+        list() {
+            return index.list.slice();
+        },
+        resolve(path) {
+            return lookup(index.map, path);
+        }
+    });
+}

package/src/domain/span/coverageSpans.js

@@ -0,0 +1,229 @@
+/**
+ * Reads epoch milliseconds from a number, Date, or parseable string.
+ *
+ * @param {Date|number|string} value - instant
+ * @returns {number} epoch milliseconds, or NaN
+ *
+ * @example
+ *   epoch('2024-11-02T03:04:05.137Z');
+ */
+function epoch(value) {
+    if (typeof value === 'number') {
+        return value;
+    }
+    if (value instanceof Date) {
+        return value.getTime();
+    }
+    return Date.parse(String(value));
+}
+
+/**
+ * Converts an instant and rejects values that are not a time.
+ *
+ * @param {Date|number|string} value - instant
+ * @returns {number} epoch milliseconds
+ *
+ * @example
+ *   stamp('2024-11-02T03:04:05.137Z');
+ */
+function stamp(value) {
+    const at = epoch(value);
+    if (Number.isNaN(at)) {
+        throw new Error(`Coverage instant is not a time: ${value}`);
+    }
+    return at;
+}
+
+/**
+ * Reads a sample instant from a raw value or a ts field.
+ *
+ * @param {Date|number|string|object} sample - sample
+ * @returns {Date|number|string} instant
+ *
+ * @example
+ *   readSample({ ts: '2024-11-02T03:04:05.137Z' });
+ */
+function readSample(sample) {
+    if (sample && typeof sample === 'object' && Object.hasOwn(sample, 'ts')) {
+        return sample.ts;
+    }
+    return sample;
+}
+
+/**
+ * Keeps samples inside the cursor-covered part of the window, in order.
+ *
+ * @param {Array} samples - raw samples
+ * @param {number} start - window start epoch
+ * @param {number} stop - covered end epoch
+ * @returns {Array<number>} sorted epochs
+ *
+ * @example
+ *   clip(['2024-11-02T03:04:05.137Z'], 0, 1);
+ */
+function clip(samples, start, stop) {
+    const picked = [];
+    for (const sample of samples) {
+        const at = stamp(readSample(sample));
+        if (at >= start && at <= stop) {
+            picked.push(at);
+        }
+    }
+    picked.sort((left, right) => {
+        return left - right;
+    });
+    return picked;
+}
+
+/**
+ * Builds one span per consecutive bound.
+ *
+ * @param {number} start - covered start
+ * @param {number} stop - covered end
+ * @param {Array<number>} points - sample epochs
+ * @param {number} silence - silence milliseconds
+ * @returns {Array<object>} unmerged spans
+ *
+ * @example
+ *   gaps(0, 10, [0, 10], 30);
+ */
+function gaps(start, stop, points, silence) {
+    const bounds = [start, ...points, stop];
+    const spans = [];
+    for (let index = 0; index < bounds.length - 1; index += 1) {
+        const left = bounds[index];
+        const right = bounds[index + 1];
+        const status = right - left > silence ? 'absent' : 'present';
+        spans.push({ from: left, status, to: right });
+    }
+    return spans;
+}
+
+/**
+ * Drops empty spans and joins neighbors that share a status.
+ *
+ * @param {Array<object>} spans - raw spans
+ * @returns {Array<object>} merged spans
+ *
+ * @example
+ *   merge([{ from: 0, status: 'present', to: 10 }]);
+ */
+function merge(spans) {
+    const open = spans.filter((span) => {
+        return span.to > span.from;
+    });
+    const kept = [];
+    for (const span of open) {
+        const last = kept[kept.length - 1];
+        if (last && last.status === span.status && last.to === span.from) {
+            kept[kept.length - 1] = { from: last.from, status: last.status, to: span.to };
+        } else {
+            kept.push({ from: span.from, status: span.status, to: span.to });
+        }
+    }
+    return kept;
+}
+
+/**
+ * Classifies the cursor-covered interval.
+ *
+ * @param {number} start - window start
+ * @param {number} stop - covered end
+ * @param {Array<number>} points - samples inside the covered interval
+ * @param {number} silence - silence milliseconds
+ * @returns {Array<object>} present and absent spans
+ *
+ * @example
+ *   paint(0, 10, [], 30);
+ */
+function paint(start, stop, points, silence) {
+    if (stop <= start) {
+        return [];
+    }
+    if (points.length === 0) {
+        return [{ from: start, status: 'absent', to: stop }];
+    }
+    return merge(gaps(start, stop, points, silence));
+}
+
+/**
+ * Renders spans as ISO-8601 instants.
+ *
+ * @param {Array<object>} spans - epoch spans
+ * @returns {Array<object>} ISO spans
+ *
+ * @example
+ *   iso([{ from: 0, status: 'unknown', to: 1 }]);
+ */
+function iso(spans) {
+    return spans.map((span) => {
+        return {
+            from: new Date(span.from).toISOString(),
+            status: span.status,
+            to: new Date(span.to).toISOString()
+        };
+    });
+}
+
+/**
+ * Requires a non-negative silence gap.
+ *
+ * @param {number} silenceMs - silence milliseconds
+ * @returns {number} silence milliseconds
+ *
+ * @example
+ *   silenceOf(60000);
+ */
+function silenceOf(silenceMs) {
+    if (typeof silenceMs === 'number' && silenceMs >= 0) {
+        return silenceMs;
+    }
+    throw new Error(`Coverage silence is missing: ${silenceMs}`);
+}
+
+/**
+ * Requires an array of samples.
+ *
+ * @param {Array} samples - raw samples
+ * @returns {Array} samples
+ *
+ * @example
+ *   samplesOf([]);
+ */
+function samplesOf(samples) {
+    if (Array.isArray(samples)) {
+        return samples;
+    }
+    throw new Error('Coverage samples are missing');
+}
+
+/**
+ * Classifies a metric window as present, absent, or unknown.
+ *
+ * Present means consecutive samples stay within the silence gap. Absent means
+ * a hole is longer than that gap and the ingest cursor has already passed it.
+ * Unknown is the part of the window after the cursor. An empty window that the
+ * cursor already covered is absent.
+ *
+ * @param {Array} samples - instants, or objects with ts
+ * @param {Date|number|string} from - window start
+ * @param {Date|number|string} to - window end
+ * @param {number} silenceMs - maximum present gap in milliseconds
+ * @param {Date|number|string} cursor - latest ingested instant
+ * @returns {Array<{from: string, to: string, status: string}>} ISO spans
+ *
+ * @example
+ *   coverageSpans(['2024-11-02T03:04:05.137Z'], '2024-11-02T03:04:05.137Z',
+ *     '2024-11-02T03:05:05.137Z', 60000, '2024-11-02T03:05:05.137Z');
+ */
+export default function coverageSpans(samples, from, to, silenceMs, cursor) {
+    const end = stamp(to);
+    const mark = stamp(cursor);
+    const silence = silenceOf(silenceMs);
+    const start = stamp(from);
+    const stop = mark < end ? Math.max(mark, start) : end;
+    const points = clip(samplesOf(samples), start, stop);
+    const known = paint(start, stop, points, silence);
+    const tail = stop < end ? [{ from: stop, status: 'unknown', to: end }] : [];
+    return iso(merge(known.concat(tail)));
+}

package/src/domain/sql/sqlGuard.js

@@ -0,0 +1,175 @@
+/**
+ * Requires SQL text.
+ *
+ * @param {string} sql - statement
+ * @param {string} engine - clickhouse or postgres
+ * @returns {string} sql
+ *
+ * @example
+ *   textOf('SELECT 1', 'postgres');
+ */
+function textOf(sql, engine) {
+    if (typeof sql === 'string') {
+        return sql;
+    }
+    throw new Error(`SQL text is missing for ${engine}`);
+}
+
+/**
+ * Strips comments and masks string literals so keyword checks see code.
+ *
+ * @param {string} sql - raw statement
+ * @returns {string} masked statement
+ *
+ * @example
+ *   mask("SELECT 'drop'");
+ */
+function mask(sql) {
+    const comments = sql.replace(/\/\*[\s\S]*?\*\//gu, ' ');
+    const lines = comments.replace(/--[^\n]*/gu, ' ');
+    return lines.replace(/'(?:''|[^'])*'/gu, '?');
+}
+
+/**
+ * Keeps a single statement and rejects empties and batches.
+ *
+ * @param {string} masked - masked SQL
+ * @param {string} engine - engine name
+ * @returns {string} trimmed statement
+ *
+ * @example
+ *   one('SELECT 1', 'postgres');
+ */
+function one(masked, engine) {
+    const trimmed = masked.trim().replace(/;+\s*$/u, '').trim();
+    if (trimmed.includes(';')) {
+        throw new Error(`SQL has more than one statement for ${engine}`);
+    }
+    if (trimmed.length === 0) {
+        throw new Error(`SQL is empty for ${engine}`);
+    }
+    return trimmed;
+}
+
+/**
+ * Shortens SQL for an error without adding a sentence period.
+ *
+ * @param {string} body - statement
+ * @returns {string} single-line preview
+ *
+ * @example
+ *   preview('SELECT 1');
+ */
+function preview(body) {
+    const flat = body.replace(/\s+/gu, ' ').trim();
+    if (flat.length > 120) {
+        return flat.slice(0, 120);
+    }
+    return flat;
+}
+
+/**
+ * Allows only SELECT and WITH.
+ *
+ * @param {string} body - one statement
+ * @param {string} engine - engine name
+ * @returns {void}
+ *
+ * @example
+ *   assertRead('SELECT 1', 'postgres');
+ */
+function assertRead(body, engine) {
+    if (/^(?:select|with)\b/iu.test(body)) {
+        return;
+    }
+    throw new Error(`SQL is not a read for ${engine}: ${preview(body)}`);
+}
+
+/**
+ * Rejects write and admin keywords.
+ *
+ * @param {string} body - masked statement
+ * @param {string} engine - engine name
+ * @returns {void}
+ *
+ * @example
+ *   assertWords('SELECT 1', 'postgres');
+ */
+function assertWords(body, engine) {
+    const found = /\b(?<word>alter|copy|delete|drop|grant|insert|system|truncate|update)\b/iu.exec(body);
+    if (found) {
+        throw new Error(`SQL contains ${found.groups.word.toLowerCase()} for ${engine}`);
+    }
+}
+
+/**
+ * Rejects the operator credential column.
+ *
+ * @param {string} body - masked statement
+ * @param {string} engine - engine name
+ * @returns {void}
+ *
+ * @example
+ *   assertUid('SELECT name FROM operators', 'postgres');
+ */
+function assertUid(body, engine) {
+    if (/\bcard_uid\b/iu.test(body)) {
+        throw new Error(`SQL references card_uid for ${engine}`);
+    }
+}
+
+/**
+ * Requires a ts comparison on ClickHouse.
+ *
+ * @param {string} body - masked statement
+ * @param {string} engine - engine name
+ * @returns {void}
+ *
+ * @example
+ *   assertTs('SELECT value FROM metrics WHERE ts >= 1', 'clickhouse');
+ */
+function assertTs(body, engine) {
+    if (engine !== 'clickhouse') {
+        return;
+    }
+    if (/\bts\s*(?:>=|<=|<>|!=|>|<|=|between\b|in\b)/iu.test(body)) {
+        return;
+    }
+    throw new Error(`ClickHouse SQL lacks a ts predicate: ${preview(body)}`);
+}
+
+/**
+ * Trims one trailing semicolon from the original text.
+ *
+ * @param {string} sql - original statement
+ * @returns {string} statement to execute
+ *
+ * @example
+ *   executable('SELECT 1;');
+ */
+function executable(sql) {
+    return sql.trim().replace(/;+\s*$/u, '').trim();
+}
+
+/**
+ * Rejects analytics SQL that is not one read-only statement.
+ *
+ * SELECT and WITH are allowed. Writes, card_uid, and extra statements are
+ * rejected before a driver sees them. ClickHouse also needs a ts predicate.
+ *
+ * @param {string} sql - one statement
+ * @param {string} engine - clickhouse or postgres
+ * @returns {string} trimmed statement safe to execute
+ *
+ * @example
+ *   sqlGuard("SELECT value FROM metrics WHERE ts >= '2024-11-02'", 'clickhouse');
+ */
+export default function sqlGuard(sql, engine) {
+    const text = textOf(sql, engine);
+    const body = one(mask(text), engine);
+    assertRead(body, engine);
+    assertWords(body, engine);
+    assertUid(body, engine);
+    assertTs(body, engine);
+    return executable(text);
+}

package/src/domain/sql/sqlShape.js

@@ -0,0 +1,16 @@
+/**
+ * Collapses SQL literals so journals group by statement shape.
+ *
+ * Quoted strings and numbers become ?. Whitespace becomes a single space.
+ *
+ * @param {string} sql - original statement
+ * @returns {string} shape
+ *
+ * @example
+ *   sqlShape("SELECT value FROM metrics WHERE topic = 'α' AND ts >= 1");
+ */
+export default function sqlShape(sql) {
+    const quotes = String(sql).replace(/'(?:''|[^'])*'/gu, '?');
+    const numbers = quotes.replace(/\b\d+(?:\.\d+)?\b/gu, '?');
+    return numbers.replace(/\s+/gu, ' ').trim();
+}