@yarkivaev/scada 2.3.115 → 2.4.0

package/src/infrastructure/opcua/certificates.js

@@ -0,0 +1,11 @@
+import { getDefaultCertificateManager } from 'node-opcua';
+
+let initialization;
+/** node-opcua's shared manager is not safe to initialize concurrently on a cold PKI. */
+export default function certificates() {
+    initialization ??= getDefaultCertificateManager('PKI').initialize().catch((error) => {
+        initialization = undefined;
+        throw error;
+    });
+    return initialization;
+}

package/src/infrastructure/opcua/config.js

@@ -0,0 +1,38 @@
+export function positive(value, name) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive number`);
+    }
+}
+function validateChannels(channels) {
+    if (!Array.isArray(channels) || channels.length === 0) {
+        throw new TypeError('channels must be a nonempty array');
+    }
+    const nodes = new Set();
+    channels.forEach(({ nodeId }) => {
+        if (typeof nodeId !== 'string' || !nodeId.trim() || nodes.has(nodeId)) {
+            throw new TypeError('invalid or duplicate nodeId');
+        }
+        nodes.add(nodeId);
+    });
+}
+
+function validUrl(value) {
+    const url = new URL(value);
+    return url.protocol === 'opc.tcp:' && Boolean(url.hostname) && !url.username && !url.password;
+}
+export function validateConnections(connections) {
+    if (!Array.isArray(connections)) {
+        throw new TypeError('connections must be an array');
+    }
+    const urls = new Set();
+    connections.forEach((connection) => {
+        if (typeof connection.url !== 'string' || !validUrl(connection.url) || urls.has(connection.url)) {
+            throw new TypeError('invalid or duplicate OPC UA URL');
+        }
+        urls.add(connection.url);
+        positive(connection.publishMs, 'publishMs');
+        positive(connection.heartbeatMs, 'heartbeatMs');
+        validateChannels(connection.channels);
+    });
+    return connections;
+}

package/src/infrastructure/opcua/delivery.js

@@ -0,0 +1,38 @@
+function reservation(pending, bytes, size, options) {
+    if (pending.size >= options.maxPending || bytes + size > options.maxPendingBytes) {
+        throw new Error('OPC UA delivery capacity exceeded; live value dropped');
+    }
+    return options.budget?.reserve({ bytes: size, records: 1 }) ?? (() => { return undefined; });
+}
+/** Deadline bounds the caller; capacity stays reserved until the actual write settles. */
+export default function delivery(publish, options) {
+    const pending = new Set();
+    let bytes = 0;
+    return async (channel, value, context = {}) => {
+        const size = Buffer.byteLength(JSON.stringify({ channel, value }));
+        const releaseBudget = reservation(pending, bytes, size, options);
+        const controller = new AbortController();
+        function abort() { controller.abort(context.signal.reason); }
+        context.signal?.addEventListener('abort', abort, { once: true });
+        const actual = Promise.resolve().then(() => {
+            if (context.signal?.aborted) { abort(); }
+            controller.signal.throwIfAborted();
+            return publish(channel, value, { signal: controller.signal });
+        });
+        pending.add(actual);
+        bytes += size;
+        function release() { pending.delete(actual); bytes -= size; releaseBudget(); }
+        actual.then(release, release);
+        let timer;
+        const deadline = new Promise((resolve, reject) => {
+            timer = setTimeout(() => {
+                controller.abort(new Error('OPC UA delivery deadline exceeded; outcome uncertain'));
+                reject(controller.signal.reason);
+            }, options.deliveryTimeoutMs);
+        });
+        return await Promise.race([actual, deadline]).finally(() => {
+            clearTimeout(timer);
+            context.signal?.removeEventListener('abort', abort);
+        });
+    };
+}

package/src/infrastructure/opcua/endpoint.js

@@ -0,0 +1,90 @@
+import { OPCUAClient } from 'node-opcua';
+import { setMaxListeners } from 'node:events';
+import delivery from './delivery.js';
+import session from './session.js';
+
+function report(options, error, connection) {
+    try {
+        options.onError?.(error, connection);
+    } catch {
+        // Observability callbacks must not break endpoint recovery.
+    }
+}
+function delay(state, milliseconds) {
+    return new Promise((resolve) => {
+        state.wake = resolve;
+        state.timer = setTimeout(resolve, milliseconds);
+    }).finally(() => { clearTimeout(state.timer); });
+}
+function clientFor(options) {
+    return OPCUAClient.create({ endpointMustExist: false, keepSessionAlive: false,
+        connectionStrategy: { maxRetry: 0 }, transportTimeout: options.connectTimeoutMs,
+        defaultTransactionTimeout: options.requestTimeoutMs, requestedSessionTimeout: options.requestTimeoutMs * 2 });
+}
+function disconnection(client) {
+    let pending;
+    return () => {
+        pending ??= client.disconnect();
+        return pending;
+    };
+}
+function attemptState(connection, options) {
+    const controller = new AbortController();
+    // Each admitted delivery registers one cancellation listener on this bounded fan-out.
+    setMaxListeners(options.maxPending + 1, controller.signal);
+    return { active: true, connection, wake: null, timer: null, pending: new Set(), controller };
+}
+async function attempt(state, connection, publish, options) {
+    const client = clientFor(options);
+    const close = disconnection(client);
+    state.close = close;
+    const current = attemptState(connection, options);
+    state.current = current;
+    try {
+        await client.connect(connection.url);
+        if (state.active) {
+            await session(current, client, connection, publish, options);
+        }
+    } catch (error) {
+        if (state.active) {
+            report(options, error, connection);
+        }
+    } finally {
+        current.active = false;
+        try { await close(); } finally { await Promise.all(current.pending); }
+    }
+}
+async function run(state, connection, publish, options) {
+    while (state.active) {
+        // Each endpoint deliberately serializes attempts and heartbeat reads.
+        // eslint-disable-next-line no-await-in-loop
+        await attempt(state, connection, publish, options);
+        if (state.active) {
+            // eslint-disable-next-line no-await-in-loop
+            await delay(state, options.retryMs);
+        }
+    }
+}
+export default function endpoint(connection, publish, options) {
+    const send = delivery(publish, options);
+    const state = { active: false, close: null, current: null, task: null, wake: null, timer: null };
+    return {
+        start() {
+            if (!state.active) {
+                state.active = true;
+                state.task = run(state, connection, send, options);
+            }
+        },
+        async stop() {
+            state.active = false;
+            if (state.current) {
+                state.current.active = false;
+                state.current.controller.abort();
+                state.current.wake?.();
+            }
+            state.wake?.();
+            await state.close?.();
+            await state.task;
+        }
+    };
+}

package/src/infrastructure/opcua/index.js

@@ -0,0 +1,10 @@
+import opcuaSource from './source.js';
+export { validateConnections } from './config.js';
+
+/** Compatibility adapter for callback-based SCADA consumers. */
+export default function opcuaConnections(connections, publish, options = {}) {
+    if (typeof publish !== 'function') { throw new TypeError('publish must be a function'); }
+    return opcuaSource(connections, { accept: ({ channel, value }) => { return publish(channel, value); } }, options);
+}
+
+export { default as opcuaSource } from './source.js';

package/src/infrastructure/opcua/session.js

@@ -0,0 +1,70 @@
+import { checkSubscription, watchSubscription } from './subscriptionHealth.js';
+import { AttributeIds, TimestampsToReturn } from 'node-opcua';
+
+function report(state, options, error) {
+    try { options.onError?.(error, state.connection); } catch {
+        // Callback isolation.
+    }
+}
+function admitted(state, options) {
+    if (state.pending.size < options.maxPending) { return true; }
+    if (!state.overflow) {
+        state.overflow = true;
+        report(state, options, new Error('OPC UA notification capacity exceeded; live value dropped'));
+    }
+    return false;
+}
+export function deliver(state, channel, value, publish, options) {
+    if (state.active && !state.failure && value.statusCode.isGood() && admitted(state, options)) {
+        const accepted = Promise.resolve().then(() => {
+            if (state.active && !state.failure) {
+                return publish(channel, value.value.value, { signal: state.controller.signal });
+            }
+            return undefined;
+        }).catch((error) => { report(state, options, error); }).finally(() => {
+            state.pending.delete(accepted);
+            state.overflow = false;
+        });
+        state.pending.add(accepted);
+    }
+}
+async function monitors(subscription, state, connection, publish, options) {
+    await Promise.all(connection.channels.map(async (channel) => {
+        const item = await subscription.monitor({ nodeId: channel.nodeId, attributeId: AttributeIds.Value },
+            { samplingInterval: connection.publishMs, discardOldest: true, queueSize: 10 }, TimestampsToReturn.Both);
+        if (!item.statusCode.isGood()) {
+            throw new Error(`Cannot monitor ${channel.nodeId}: ${item.statusCode.toString()}`);
+        }
+        item.on('changed', (value) => { deliver(state, channel, value, publish, options); });
+    }));
+}
+function pause(state, milliseconds) {
+    return new Promise((resolve) => {
+        state.wake = resolve;
+        state.timer = setTimeout(resolve, milliseconds);
+    }).finally(() => { clearTimeout(state.timer); });
+}
+async function heartbeat(state, activeSession, connection, publish, options) {
+    while (state.active) {
+        checkSubscription(state, options);
+        // Fresh reads are serialized; a slow read cannot overlap the next heartbeat.
+        // eslint-disable-next-line no-await-in-loop
+        await pause(state, connection.heartbeatMs);
+        if (state.active) {
+            checkSubscription(state, options);
+            // eslint-disable-next-line no-await-in-loop
+            const values = await activeSession.read(connection.channels.map(({ nodeId }) => { return { nodeId, attributeId: AttributeIds.Value }; }), 0);
+            values.forEach((value, index) => { deliver(state, connection.channels[index], value, publish, options); });
+        }
+    }
+}
+export default async function session(state, client, connection, publish, options) {
+    const activeSession = await client.createSession();
+    if (state.active) {
+        const subscription = await activeSession.createSubscription2({ requestedPublishingInterval: connection.publishMs,
+            requestedLifetimeCount: 30, requestedMaxKeepAliveCount: 3, maxNotificationsPerPublish: 0, publishingEnabled: true, priority: 0 });
+        watchSubscription(state, subscription);
+        await monitors(subscription, state, connection, publish, options);
+        await heartbeat(state, activeSession, connection, publish, options);
+    }
+}

package/src/infrastructure/opcua/source.js

@@ -0,0 +1,38 @@
+import { positive, validateConnections } from './config.js';
+export { validateConnections } from './config.js';
+
+/** Independent OPC UA endpoints delivering opaque channel metadata and values. */
+export default function opcuaSource(connections, collector, options = {}) {
+    const settings = { retryMs: 1000, connectTimeoutMs: 5000, requestTimeoutMs: 5000, deliveryTimeoutMs: 5000, maxPending: 100, maxPendingBytes: 1048576, ...options };
+    validateConnections(connections);
+    if (!collector || typeof collector.accept !== 'function') {
+        throw new TypeError('Collector must have an accept() method');
+    }
+    ['retryMs', 'connectTimeoutMs', 'requestTimeoutMs', 'deliveryTimeoutMs', 'maxPending', 'maxPendingBytes'].forEach((name) => { positive(settings[name], name); });
+    if (!Number.isSafeInteger(settings.maxPending)) { throw new TypeError('maxPending must be a safe integer'); }
+    let endpoints;
+    let stopping = Promise.resolve();
+    let revision = 0;
+    return {
+        async start() {
+            revision += 1;
+            const requested = revision;
+            await stopping;
+            // Importing the package or validating a factory never loads node-opcua.
+            const { default: endpoint } = await import('./endpoint.js');
+            const { default: certificates } = await import('./certificates.js');
+            await certificates();
+            if (requested === revision) {
+                endpoints ??= connections.map((connection) => {
+                    return endpoint(connection, (channel, value, context) => { return collector.accept({ channel, value }, context); }, settings);
+                });
+                endpoints.forEach((item) => { item.start(); });
+            }
+        },
+        stop() {
+            revision += 1;
+            stopping = Promise.all((endpoints ?? []).map((item) => { return item.stop(); }));
+            return stopping;
+        }
+    };
+}

package/src/infrastructure/opcua/subscriptionHealth.js

@@ -0,0 +1,28 @@
+function failed(state, message) {
+    if (state.active) {
+        state.failure = new Error(message);
+        state.wake?.();
+    }
+}
+export function watchSubscription(state, subscription) {
+    state.lastPublish = Date.now();
+    state.subscription = subscription;
+    subscription.on('keepalive', () => { state.lastPublish = Date.now(); });
+    subscription.on('received_notifications', () => { state.lastPublish = Date.now(); });
+    subscription.on('terminated', () => { failed(state, 'OPC UA subscription terminated'); });
+    subscription.on('status_changed', (status) => {
+        if (!status.isGood()) {
+            failed(state, `OPC UA subscription status: ${status.toString()}`);
+        }
+    });
+}
+export function checkSubscription(state, options) {
+    const { subscription } = state;
+    const silence = Math.max(subscription.publishingInterval * subscription.maxKeepAliveCount * 3, options.requestTimeoutMs);
+    if (Date.now() - state.lastPublish > silence) {
+        failed(state, 'OPC UA subscription stopped publishing');
+    }
+    if (state.failure) {
+        throw state.failure;
+    }
+}

package/src/infrastructure/operators/operatorsSync.js

@@ -1,3 +1,5 @@
+import { intervalSource } from '@yarkivaev/source-to-sink';
+
 const DEFAULT_INTERVAL_MS = 30000;
 
 async function refresh(source, provider) {
@@ -25,33 +27,7 @@ async function refresh(source, provider) {
  */
 export default function operatorsSync(source, provider, options) {
     const intervalMs = options && options.intervalMs ? options.intervalMs : DEFAULT_INTERVAL_MS;
-    let timer;
-    let active = false;
-    async function tick() {
-        try {
-            await refresh(source, provider);
-        } catch {
-            /* next tick retries; stale snapshot remains */
-        }
-    }
-    return {
-        async start() {
-            if (active) {
-                return;
-            }
-            active = true;
-            await tick();
-            timer = setInterval(() => {
-                void tick();
-            }, intervalMs);
-        },
-        stop() {
-            if (!active) {
-                return;
-            }
-            active = false;
-            clearInterval(timer);
-            timer = undefined;
-        }
-    };
+    return intervalSource(intervalMs, {
+        accept() { return refresh(source, provider); }
+    }, { immediate: true });
 }

package/src/infrastructure/persistence/clickhouse/streamHub.js

@@ -9,14 +9,16 @@
  *   const sub = hub.watch('m1/V', since, 1000, onRow, { unit: 'V', clock });
  *   sub.cancel();
  */
+import { intervalSource } from '@yarkivaev/source-to-sink';
 import pollTopicCursors from './pollTopicCursors.js';
 
 const hubs = new WeakMap();
 
 function defaultSchedule(step, fn) {
-    const timer = setInterval(fn, step);
+    const source = intervalSource(step, { accept: fn });
+    void source.start();
     return () => {
-        clearInterval(timer);
+        return source.stop();
     };
 }
 
@@ -74,21 +76,25 @@ function cursorsOf(bucket) {
     return cursors;
 }
 
+function advance(watcher, timestamp) {
+    if (timestamp.getTime() > watcher.lastTs.getTime()) {
+        watcher.lastTs = timestamp;
+    }
+}
+
 function dispatch(bucket, rows) {
-    rows.forEach((row) => {
+    return rows.reduce(async (previous, row) => {
+        await previous;
         const group = bucket.watchers.get(row.topic);
-        if (!group) {
-            return;
-        }
+        if (!group) { return; }
         const timestamp = parseTimestamp(row.ts);
-        group.forEach((watcher) => {
-            if (timestamp.getTime() <= watcher.lastTs.getTime()) {
-                return;
-            }
-            watcher.callback({ timestamp, value: row.value, unit: watcher.unit });
-            watcher.lastTs = timestamp;
-        });
-    });
+        await [...group].reduce(async (previousWatcher, watcher) => {
+            await previousWatcher;
+            if (timestamp.getTime() <= watcher.lastTs.getTime()) { return; }
+            await watcher.callback({ timestamp, value: row.value, unit: watcher.unit });
+            advance(watcher, timestamp);
+        }, Promise.resolve());
+    }, Promise.resolve());
 }
 
 function buildHub(connection, schedule) {
@@ -106,7 +112,7 @@ function buildHub(connection, schedule) {
                     cursorsOf(bucket),
                     bucket.clock()
                 );
-                dispatch(bucket, rows);
+                await dispatch(bucket, rows);
             } catch (err) {
                 console.error( // eslint-disable-line no-console
                     `Stream batch failed on ${connection.url()}:`,

package/src/infrastructure/persistence/metricsSensor.js

@@ -1,3 +1,4 @@
+import { intervalSource } from '@yarkivaev/source-to-sink';
 import seriesRows, { parseTimestamp } from './seriesRows.js';
 
 function pollStream(spec) {
@@ -6,21 +7,23 @@ function pollStream(spec) {
         return new Date();
     });
     let lastTs = since;
-    const timer = setInterval(async () => {
+    const source = intervalSource(step, { async accept() {
         try {
             const rows = await read.poll(topic, lastTs.toISOString(), time().toISOString());
-            rows.forEach((row) => {
+            await rows.reduce(async (previous, row) => {
+                await previous;
                 const timestamp = parseTimestamp(row.ts);
-                callback({ timestamp, value: row.value, unit });
+                await callback({ timestamp, value: row.value, unit });
                 lastTs = timestamp;
-            });
+            }, Promise.resolve());
         } catch {
             /* next poll retries */
         }
-    }, step);
+    } });
+    void source.start();
     return {
         cancel() {
-            clearInterval(timer);
+            return source.stop();
         }
     };
 }

package/src/infrastructure/persistence/runtime/taskStatePg.js

@@ -0,0 +1,24 @@
+/** Atomic state compare-and-swap; distributed ownership must be integrated separately. */
+export default function taskStatePg(pool, { maxBytes = 1048576 } = {}) {
+    return {
+        async load(taskId) {
+            const result = await pool.query('SELECT version, document FROM collector_task_state WHERE task_id = $1', [taskId]);
+            if (!result.rows.length) { return null; }
+            return { ...result.rows[0].document, version: Number(result.rows[0].version) };
+        },
+        async commit(input) {
+            if (!Number.isSafeInteger(input.expectedVersion) || input.expectedVersion < 0) { throw new TypeError('Invalid expectedVersion'); }
+            if (input.ownership !== undefined) { throw new Error('This store has no external ownership integration'); }
+            const { expectedVersion } = input;
+            const document = { taskId: input.taskId, stateVersion: input.stateVersion, compatibilityKey: input.compatibilityKey,
+                checkpoint: input.checkpoint, pending: input.pending };
+            const json = JSON.stringify(document);
+            if (Buffer.byteLength(json) > maxBytes) { throw new Error('Task state capacity exceeded'); }
+            const result = expectedVersion === 0
+                ? await pool.query('INSERT INTO collector_task_state (task_id, version, document) VALUES ($1, 1, $2::jsonb) ON CONFLICT DO NOTHING RETURNING version', [input.taskId, json])
+                : await pool.query('UPDATE collector_task_state SET version = version + 1, document = $2::jsonb, updated_at = now() WHERE task_id = $1 AND version = $3 RETURNING version', [input.taskId, json, expectedVersion]);
+            if (!result.rows.length) { throw new Error('Task state conflict'); }
+            return Number(result.rows[0].version);
+        }
+    };
+}