@yarkivaev/scada 2.3.85 → 2.3.87

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();
+}

package/src/infrastructure/persistence/pg/alerts.js

@@ -1,12 +1,41 @@
 /**
- * PostgreSQL alert hydration port for supervisor-sink and plant STOMP alerts.
+ * Builds a filtered alerts SELECT.
+ *
+ * @param {object} filters - optional machine, from, to
+ * @returns {{sql: string, prm: Array}} query
+ *
+ * @example
+ *   listSql({ machine: 'm1', from: start, to: end });
+ */
+function listSql(filters) {
+    const prm = [];
+    const clauses = [];
+    const scope = filters || {};
+    if (scope.machine) {
+        prm.push(scope.machine);
+        clauses.push(`machine = $${prm.length}`);
+    }
+    if (scope.from) {
+        prm.push(scope.from);
+        clauses.push(`"timestamp" >= $${prm.length}`);
+    }
+    if (scope.to) {
+        prm.push(scope.to);
+        clauses.push(`"timestamp" <= $${prm.length}`);
+    }
+    const where = clauses.length === 0 ? '' : ` WHERE ${clauses.join(' AND ')}`;
+    return { prm, sql: `SELECT * FROM alerts${where} ORDER BY timestamp` };
+}
+
+/**
+ * PostgreSQL alert hydration and range-read port.
  *
  * @param {object} pool - pg pool
- * @returns {object} alerts port with put and listUnacknowledged
+ * @returns {object} alerts port with put, list, and listUnacknowledged
  *
  * @example
  *   const store = alertsStatePg(pool);
- *   const rows = await store.listUnacknowledged({ machine: 'm1' });
+ *   const rows = await store.list({ machine: 'm1', from, to });
  */
 export default function alertsStatePg(pool) {
     return {
@@ -25,6 +54,11 @@ export default function alertsStatePg(pool) {
             );
             return inserted.rows[0];
         },
+        async list(filters) {
+            const query = listSql(filters);
+            const result = await pool.query(query.sql, query.prm);
+            return result.rows;
+        },
         async listUnacknowledged(filters) {
             let sql = 'SELECT * FROM alerts WHERE acknowledged = FALSE';
             const prm = [];