@yarkivaev/scada 2.3.115 → 2.4.0

package/src/infrastructure/streams/modbusSource.js

@@ -0,0 +1,185 @@
+import pollingSource from './pollingSource.js';
+import deadline from './deadline.js';
+import abortable from './abortable.js';
+import { attempt, create, drop, idle, opening, resume } from './modbusConnection.js';
+
+function read(bag, address, count) {
+  return async function fetch(since, until, { signal } = {}) {
+    const { client } = bag;
+    try {
+      const result = await abortable(client.readHoldingRegisters(address, count), signal, () => { drop(client); });
+      return [result.data];
+    } catch (err) {
+      if (bag.client === client) { bag.lost(); }
+      throw err;
+    }
+  };
+}
+
+/**
+ * Shared Modbus polling lifecycle for TCP and RTU transports.
+ *
+ * @param {object} options - connect, target, address, count, interval, collector, clk, client, log
+ * @returns {object} Source with start() and stop() methods
+ */
+function modbusPollingSource(options) {
+  const { address, count, interval, collector, clk } = options;
+  const bag = {
+    ...options,
+    client: undefined,
+    state: idle(),
+    epoch: 0,
+    maxDelay: 300,
+    delay: interval
+  };
+  bag.lost = function lost() {
+    resume(bag);
+  };
+  bag.source = pollingSource(read(bag, address, count), interval, collector, clk);
+  return {
+    /**
+     * Connects to the Modbus device and starts polling.
+     */
+    start() {
+      if (bag.fatal) { return Promise.reject(bag.fatal); }
+      if (bag.state.connected() || bag.state.retrying() || bag.state.opening()) {
+        return Promise.resolve();
+      }
+      const token = bag.epoch;
+      bag.state = opening();
+      return Promise.resolve(bag.stopping).then(() => { if (token === bag.epoch) { attempt(bag); } });
+    },
+    /**
+     * Stops polling and disconnects from the Modbus device.
+     */
+    stop() {
+      bag.epoch += 1;
+      const drained = bag.source.stop();
+      if (bag.state.retrying()) {
+        bag.state.cancel();
+      }
+      const { client } = bag;
+      bag.client = undefined;
+      bag.state = idle();
+      drop(client);
+      bag.stopping = deadline(Promise.all([drained, bag.opened]), 5000, 'Modbus stop', (error) => { bag.fatal = error; }).then(() => {
+        if (bag.fatal) { throw bag.fatal; }
+      });
+      return bag.stopping;
+    }
+  };
+}
+
+/**
+ * Modbus TCP polling source for reading holding registers.
+ *
+ * Connects to a Modbus TCP device and polls holding registers
+ * at a specified interval. Forwards register arrays to the
+ * collector via pollingSource.
+ *
+ * @example
+ * const source = modbusSource('192.168.2.148', 502, 4000, 14, 5, collector, clock);
+ * source.start();
+ *
+ * @param {string} host - Modbus TCP host address
+ * @param {number} port - Modbus TCP port
+ * @param {number} address - Starting register address
+ * @param {number} count - Number of registers to read
+ * @param {number} interval - Polling interval in seconds
+ * @param {object} collector - Collector with accept() method
+ * @param {object} clk - Clock with millis() method
+ * @param {object} [log] - Logger with error() method for connection failures
+ * @returns {object} Source with start() and stop() methods
+ */
+// Preserve the established positional adapter API.
+// eslint-disable-next-line max-params
+export default function modbusSource(host, port, address, count, interval, collector, clk, log = console) {
+  if (typeof host !== 'string' || host.length === 0) {
+    throw new Error('Host must be a non-empty string');
+  }
+  if (typeof port !== 'number' || port <= 0) {
+    throw new Error(`Port must be a positive number, got: ${port}`);
+  }
+  if (typeof address !== 'number' || address < 0) {
+    throw new Error(`Address must be a non-negative number, got: ${address}`);
+  }
+  if (typeof count !== 'number' || count <= 0) {
+    throw new Error(`Count must be a positive number, got: ${count}`);
+  }
+  function connect(modbusClient) {
+    return modbusClient.connectTCP(host, { port });
+  }
+  return modbusPollingSource({
+    create,
+    connect,
+    target: `${host}:${port}`,
+    address,
+    count,
+    interval,
+    collector,
+    clk,
+    log
+  });
+}
+
+/**
+ * Modbus RTU polling source for reading holding registers over serial.
+ *
+ * Connects to a Modbus RTU device on a serial port and polls holding registers
+ * at a specified interval. Forwards register arrays to the collector via pollingSource.
+ *
+ * @example
+ * const source = modbusRtuSource('/dev/ttyUSB0', { baudRate: 9600, slaveId: 1 }, 4000, 44, 5, collector, clock);
+ * source.start();
+ *
+ * @param {string} path - Serial device path (e.g. /dev/ttyUSB0)
+ * @param {object} serial - baudRate, dataBits, stopBits, parity, slaveId
+ * @param {number} address - Starting register address
+ * @param {number} count - Number of registers to read
+ * @param {number} interval - Polling interval in seconds
+ * @param {object} collector - Collector with accept() method
+ * @param {object} clk - Clock with millis() method
+ * @param {object} [log] - Logger with error() method for connection failures
+ * @returns {object} Source with start() and stop() methods
+ */
+// Preserve the established positional adapter API.
+// eslint-disable-next-line max-params
+export function modbusRtuSource(path, serial, address, count, interval, collector, clk, log = console) {
+  if (typeof path !== 'string' || path.length === 0) {
+    throw new Error('Serial path must be a non-empty string');
+  }
+  if (!serial || typeof serial !== 'object') {
+    throw new Error('Serial config must be an object');
+  }
+  if (typeof serial.baudRate !== 'number' || serial.baudRate <= 0) {
+    throw new Error(`Baud rate must be a positive number, got: ${serial.baudRate}`);
+  }
+  if (typeof address !== 'number' || address < 0) {
+    throw new Error(`Address must be a non-negative number, got: ${address}`);
+  }
+  if (typeof count !== 'number' || count <= 0) {
+    throw new Error(`Count must be a positive number, got: ${count}`);
+  }
+  const slaveId = serial.slaveId || 1;
+  function connect(modbusClient) {
+    return modbusClient.connectRTUBuffered(path, {
+      baudRate: serial.baudRate,
+      dataBits: serial.dataBits || 8,
+      stopBits: serial.stopBits || 1,
+      parity: serial.parity || 'none'
+    }).then(() => {
+      modbusClient.setID(slaveId);
+    });
+  }
+  return modbusPollingSource({
+    create,
+    connect,
+    target: path,
+    address,
+    count,
+    interval,
+    collector,
+    clk,
+    log
+  });
+}

package/src/infrastructure/streams/mqttSink/session.js

@@ -0,0 +1,51 @@
+import deadline from '../deadline.js';
+
+export function terminate(live, error) {
+    if (live.dead) { return live.closing; }
+    live.dead = true;
+    live.ready = false;
+    live.pending.forEach((settle) => { settle(error || new Error('MQTT connection closed')); });
+    live.closing = deadline(new Promise((resolve) => {
+        live.client.end(true, {}, resolve);
+    }), live.options.stopTimeoutMs, 'MQTT disconnect');
+    // An event callback cannot surface a rejected shutdown. stop() still returns it.
+    void live.closing.catch(() => { return undefined; });
+    return live.closing;
+}
+export function connect(live) {
+    return deadline(new Promise((resolve, reject) => {
+        function fail(error) { reject(error); void terminate(live, error); }
+        live.client.on('error', fail);
+        live.client.on('close', () => { fail(new Error('MQTT connection closed')); });
+        live.client.on('offline', () => { fail(new Error('MQTT connection offline')); });
+        live.client.on('connect', () => {
+            if (!live.dead) { live.ready = true; resolve(); }
+        });
+        live.pending.add(reject);
+    }), live.options.connectTimeoutMs, 'MQTT connect', (error) => { void terminate(live, error); });
+}
+export function publish(live, record, signal) {
+    return new Promise((resolve, reject) => {
+        let done = false;
+        const timer = { handle: null };
+        function abort() { void terminate(live, signal.reason || new Error('MQTT publish aborted')); }
+        function settle(error) {
+            if (done) { return; }
+            done = true;
+            clearTimeout(timer.handle);
+            signal?.removeEventListener('abort', abort);
+            live.pending.delete(settle);
+            live.count -= 1;
+            if (error) { reject(error); } else { resolve(); }
+        }
+        timer.handle = setTimeout(() => { void terminate(live, new Error('MQTT confirmation timed out; outcome uncertain')); }, live.options.confirmTimeoutMs);
+        live.pending.add(settle);
+        signal?.addEventListener('abort', abort, { once: true });
+        if (signal?.aborted) { abort(); return; }
+        try { live.client.publish(record.topic, record.payload, { qos: live.options.qos }, (error) => {
+            settle(error);
+            if (error) { void terminate(live, error); }
+        }); }
+        catch (error) { void terminate(live, error); }
+    });
+}

package/src/infrastructure/streams/mqttSink.js

@@ -0,0 +1,54 @@
+import mqtt from 'mqtt';
+import positive from './positive.js';
+import { connect, publish, terminate } from './mqttSink/session.js';
+
+function settings(options) {
+    const config = { qos: 0, maxPending: 1024, maxPendingBytes: 1048576, connectTimeoutMs: 5000, confirmTimeoutMs: 10000, stopTimeoutMs: 5000, ...options };
+    ['maxPending', 'maxPendingBytes', 'connectTimeoutMs', 'confirmTimeoutMs', 'stopTimeoutMs'].forEach((key) => { positive(config[key], key); });
+    if (!Number.isSafeInteger(config.maxPending)) { throw new TypeError('maxPending must be a safe integer'); }
+    if (![0, 1, 2].includes(config.qos)) { throw new TypeError('qos must be 0, 1, or 2'); }
+    return config;
+}
+function write(live, records, signal) {
+    if (!live?.ready || live.dead) { throw new Error('Sink is not connected'); }
+    if (!Array.isArray(records) || records.some((record) => {
+        return !record || typeof record.topic !== 'string' || !record.topic || !(typeof record.payload === 'string' || Buffer.isBuffer(record.payload));
+    })) { return Promise.reject(new TypeError('MQTT records require a topic and string/Buffer payload')); }
+    if (signal?.aborted) { return Promise.reject(signal.reason || new Error('MQTT publish aborted')); }
+    const bytes = records.reduce((total, record) => { return total + Buffer.byteLength(record.payload) + Buffer.byteLength(record.topic); }, 0);
+    if (live.bytes + bytes > live.options.maxPendingBytes || live.count + records.length > live.options.maxPending) { return Promise.reject(new Error('MQTT pending capacity exceeded')); }
+    live.count += records.length;
+    live.bytes += bytes;
+    return Promise.all(records.map((record) => {
+        if (live.dead) { live.count -= 1; return Promise.reject(new Error('MQTT connection closed')); }
+        return publish(live, record, signal);
+    })).finally(() => { live.bytes -= bytes; });
+}
+/** start awaits CONNACK; write awaits publish completion (broker confirmation at QoS 1/2).
+ * QoS 0 only confirms local handoff. No automatic replay of uncertain writes.
+ */
+export default function mqttSink(url, options = {}) {
+    if (typeof url !== 'string' || !url) { throw new Error('URL must be a non-empty string'); }
+    const config = settings(options);
+    let live;
+    return {
+        start() {
+            if (live && !live.dead) { return live.opening; }
+            if (live?.dead) { return Promise.reject(new Error('MQTT session retired; create a new sink after stop')); }
+            const client = (options.connect || mqtt.connect)(url, {
+                ...options.connectionOptions, clientId: options.clientId, protocolVersion: 5,
+                reconnectPeriod: 0, queueQoSZero: false, connectTimeout: config.connectTimeoutMs
+            });
+            live = { client, options: config, pending: new Set(), count: 0, bytes: 0, ready: false, dead: false };
+            live.opening = connect(live);
+            return live.opening;
+        },
+        write(records, { signal } = {}) { return write(live, records, signal); },
+        stop() {
+            const stopped = live;
+            return (stopped ? terminate(stopped, new Error('MQTT sink stopped')) : Promise.resolve()).then(() => {
+                if (live === stopped) { live = undefined; }
+            });
+        }
+    };
+}

package/src/infrastructure/streams/mqttSource.js

@@ -0,0 +1,66 @@
+import mqtt from 'mqtt';
+import positive from './positive.js';
+import deadline from './deadline.js';
+import budgetAccept from './budgetAccept.js';
+
+function report(options, error) {
+    try { options.onError?.(error); } catch {
+        // Diagnostics cannot break transport callbacks.
+    }
+}
+function bind(live, collector, options) {
+    live.client.on('error', (error) => { report(options, error); });
+    // MQTT.js serializes handleMessage and sends PUBACK/PUBCOMP only on successful completion.
+    live.client.handleMessage = (packet, callback) => {
+        const accepted = Promise.resolve().then(() => {
+            if (!live.active) { throw new Error('MQTT source stopped'); }
+            return budgetAccept(collector, { topic: packet.topic, payload: packet.payload.toString() }, packet.payload.length, options, { signal: live.controller.signal });
+        });
+        live.pending.add(accepted);
+        void accepted.finally(() => { live.pending.delete(accepted); }).catch(() => { return undefined; });
+        deadline(accepted, options.acceptTimeoutMs, 'MQTT acceptance', (error) => {
+            live.active = false; live.controller.abort(error); live.client.end(true);
+        }).then(() => {
+            callback(live.active ? undefined : new Error('MQTT source stopped'));
+        }, (error) => { callback(error); report(options, error); });
+    };
+}
+function open(url, list, collector, options) {
+    const client = (options.connect || mqtt.connect)(url, {
+        ...options.connectionOptions, clientId: options.clientId, clean: !options.clientId, protocolVersion: 5,
+        properties: { sessionExpiryInterval: options.clientId ? options.sessionExpiryInterval ?? 3600 : 0,
+            receiveMaximum: options.prefetch ?? 32, maximumPacketSize: options.maxPacketBytes ?? 1048576 }
+    });
+    const live = { client, active: true, pending: new Set(), controller: new AbortController() };
+    bind(live, collector, options);
+    client.on('connect', () => {
+        if (live.active) { client.subscribe(list, { qos: options.qos ?? (options.clientId ? 1 : 0) }); }
+    });
+    return live;
+}
+/** ACK follows asynchronous acceptance, not merely receipt. Acceptance is not necessarily durable. */
+export default function mqttSource(url, topics, collector, options = {}) {
+    if (typeof url !== 'string' || !url) { throw new Error('URL must be a non-empty string'); }
+    if (typeof topics !== 'string' || !topics.trim()) { throw new Error('Topic must be a non-empty string'); }
+    if (typeof collector?.accept !== 'function') { throw new Error('Collector must have an accept() method'); }
+    const config = { acceptTimeoutMs: 10000, stopTimeoutMs: 5000, ...options };
+    positive(config.acceptTimeoutMs, 'acceptTimeoutMs');
+    positive(config.stopTimeoutMs, 'stopTimeoutMs');
+    const list = topics.split(',').map((topic) => { return topic.trim(); }).filter(Boolean);
+    let live;
+    return {
+        start() {
+            if (!live) { live = open(url, list, collector, config); }
+        },
+        stop() {
+            if (!live) { return Promise.resolve(); }
+            const stopped = live;
+            stopped.active = false;
+            stopped.controller.abort(new Error('MQTT source stopped'));
+            const closing = new Promise((resolve) => { stopped.client.end(true, {}, resolve); });
+            return deadline(Promise.all([closing, ...stopped.pending]), config.stopTimeoutMs, 'MQTT stop').then(() => {
+                if (live === stopped) { live = undefined; }
+            });
+        }
+    };
+}

package/src/infrastructure/streams/pollingSource.js

@@ -0,0 +1 @@
+export { pollingSource as default } from '@yarkivaev/source-to-sink';

package/src/infrastructure/streams/positive.js

@@ -0,0 +1,5 @@
+export default function positive(value, name) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new TypeError(`${name} must be a positive number`);
+    }
+}

package/src/infrastructure/streams/postgresSink.js

@@ -0,0 +1,124 @@
+import pg from 'pg';
+import deadline from './deadline.js';
+import positive from './positive.js';
+
+/**
+ * Removes duplicate records by conflict key within a batch.
+ *
+ * PostgreSQL rejects INSERT batches where ON CONFLICT would update
+ * the same row twice. This keeps the last occurrence for each
+ * unique combination of conflict column values.
+ *
+ * @example
+ *   deduplicate(
+ *     [{ machine: 'a', start: 1, name: 'pending' },
+ *      { machine: 'a', start: 1, name: 'completed' }],
+ *     ['machine', 'start']
+ *   );
+ *   // => [{ machine: 'a', start: 1, name: 'completed' }]
+ *
+ * @param {Array} records - Array of record objects
+ * @param {Array<string>} keys - Conflict column names
+ * @returns {Array} Deduplicated records
+ */
+export function deduplicate(records, keys) {
+  if (keys.length === 0) {return records;}
+  const seen = new Map();
+  for (const record of records) {
+    const key = keys.map(k => {return record[k]}).join('\0');
+    seen.set(key, record);
+  }
+  return Array.from(seen.values());
+}
+
+/**
+ * Builds the ON CONFLICT SQL suffix from options.
+ *
+ * @param {object} options - Sink options with conflict, update, and optional updateWhere
+ * @returns {string} SQL suffix or empty string
+ */
+function buildSuffix(options) {
+  if (!Array.isArray(options.conflict) || options.conflict.length === 0) {return '';}
+  const cols = options.conflict.join(', ');
+  if (Array.isArray(options.update) && options.update.length > 0) {
+    const sets = options.update.map((col) => {return `${col} = EXCLUDED.${col}`}).join(', ');
+    const guard = typeof options.updateWhere === 'string' && options.updateWhere.length > 0
+      ? ` WHERE ${options.updateWhere}`
+      : '';
+    return ` ON CONFLICT (${cols}) DO UPDATE SET ${sets}${guard}`;
+  }
+  return ` ON CONFLICT (${cols}) DO NOTHING`;
+}
+
+/**
+ * PostgreSQL sink for batch record insertion.
+ *
+ * Creates a pg.Pool internally unless `options.pool` is supplied.
+ * Supports optional conflict resolution via ON CONFLICT DO NOTHING or
+ * ON CONFLICT DO UPDATE SET. `write` accepts an optional queryable
+ * client so callers can run inserts inside an existing transaction.
+ *
+ * @example
+ * const sink = postgresSink('postgresql://localhost:5432/db', 'metrics', ['ts', 'value']);
+ * await sink.write([{ ts: Date.now(), value: 42 }]);
+ *
+ * @example
+ * const sink = postgresSink(url, 'segments', cols, { pool, conflict: ['machine', 'start_time'] });
+ * await sink.write([{ machine: 'a', name: 'on', start_time: '2024-01-01' }], client);
+ *
+ * @param {string} url - PostgreSQL URL (e.g., 'postgresql://localhost:5432/db')
+ * @param {string} table - Target table name
+ * @param {Array<string>} columns - Column names for insertion
+ * @param {object} [options] - Optional configuration
+ * @param {Array<string>} [options.conflict] - Columns for ON CONFLICT clause
+ * @param {Array<string>} [options.update] - Columns for DO UPDATE SET clause
+ * @param {string} [options.updateWhere] - Optional WHERE guard on DO UPDATE
+ * @param {object} [options.pool] - Existing pg Pool to reuse
+ * @returns {object} Sink with write(records, client?) method
+ */
+export default function postgresSink(url, table, columns, options = {}) {
+  if (typeof url !== 'string' || url.length === 0) {
+    throw new Error('URL must be a non-empty string');
+  }
+  if (typeof table !== 'string' || table.length === 0) {
+    throw new Error('Table must be a non-empty string');
+  }
+  if (!Array.isArray(columns) || columns.length === 0) {
+    throw new Error('Columns must be a non-empty array');
+  }
+  positive(options.stopTimeoutMs ?? 5000, 'stopTimeoutMs');
+  const pool = options.pool || (options.createPool || ((config) => { return new pg.Pool(config); }))({ connectionString: url });
+  let stopping;
+  const suffix = buildSuffix(options);
+  const conflict = Array.isArray(options.conflict) ? options.conflict : [];
+  return {
+    /**
+     * Writes records to PostgreSQL table.
+     *
+     * @param {Array} records - Array of objects with keys matching columns
+     * @param {object} [client] - Optional pg client/pool with query()
+     * @returns {Promise} Promise resolving when insert completes
+     */
+    write(records, client) {
+      if (stopping) { return Promise.reject(new Error('PostgreSQL sink stopped')); }
+      if (client?.signal?.aborted) { return Promise.reject(client.signal.reason || new Error('PostgreSQL write aborted')); }
+      const unique = deduplicate(records, conflict);
+      const placeholders = unique.map((record, i) => {
+        const offset = i * columns.length;
+        const row = columns.map((__, j) => {return `$${offset + j + 1}`}).join(', ');
+        return `(${row})`;
+      }).join(', ');
+      const query = `INSERT INTO ${table} (${columns.join(', ')}) VALUES ${placeholders}${suffix}`;
+      const values = unique.flatMap((record) => {return columns.map((col) => {return record[col]})});
+      const runner = client && typeof client.query === 'function' ? client : pool;
+      return runner.query(query, values);
+    },
+    stop() {
+      stopping ??= deadline(Promise.resolve().then(() => {
+        if (!options.pool) { return pool.end(); }
+        return undefined;
+      }), options.stopTimeoutMs ?? 5000, 'PostgreSQL pool close');
+      return stopping;
+    }
+  };
+}

package/src/infrastructure/streams/serialReceive.js

@@ -0,0 +1,80 @@
+import deadline from './deadline.js';
+
+export function report(options, error, device) {
+    try { options.onError?.(error, device); } catch {
+        // Diagnostics cannot prevent shutdown.
+    }
+}
+export function closePort(port, timeoutMs) {
+    if (port.isOpen === false) { return Promise.resolve(); }
+    return deadline(new Promise((resolve, reject) => {
+        port.close((error) => { if (error) { reject(error); } else { resolve(); } });
+    }), timeoutMs, 'Serial close', () => { port.destroy?.(); }).catch((error) => {
+        error.resourceUncertain = true;
+        throw error;
+    });
+}
+function reserve(ctx, size) {
+    try {
+        const release = ctx.options.budget?.reserve({ bytes: size, records: 1 });
+        ctx.port.pause?.();
+        return { release };
+    }
+    catch (error) {
+        Object.assign(ctx.state, { fatal: error, active: false });
+        ctx.state.controller.abort(error);
+        ctx.fail(error);
+        return null;
+    }
+}
+function accept(ctx, chunk, release) {
+    const accepted = Promise.resolve().then(() => {
+        if (ctx.state.active && !ctx.failed) { return ctx.collector.accept({ device: ctx.device, chunk }, { signal: ctx.state.controller.signal }); }
+        return undefined;
+    });
+    void accepted.finally(() => { release?.(); }).catch(() => { return undefined; });
+    return deadline(accepted, ctx.options.acceptTimeoutMs, 'Serial acceptance', (error) => {
+        ctx.state.fatal = error; ctx.state.active = false; ctx.state.controller.abort(error);
+    });
+}
+function enqueue(ctx, chunk) {
+    if (!ctx.state.active) { return; }
+    const size = chunk.length ?? Buffer.byteLength(String(chunk));
+    if (ctx.count >= ctx.options.maxPending || ctx.bytes + size > ctx.options.maxPendingBytes) {
+        const error = new Error('Serial receive capacity exceeded; source retired');
+        Object.assign(ctx.state, { fatal: error, active: false });
+        ctx.state.controller.abort(error);
+        ctx.fail(error);
+        return;
+    }
+    const lease = reserve(ctx, size);
+    if (!lease) { return; }
+    Object.assign(ctx, { count: ctx.count + 1, bytes: ctx.bytes + size });
+    ctx.pending = ctx.pending.then(() => {
+        if (ctx.state.active && !ctx.failed) {
+            return accept(ctx, chunk, lease.release);
+        }
+        lease.release?.();
+        return undefined;
+    }).catch(ctx.fail).finally(() => {
+        ctx.count -= 1;
+        ctx.bytes -= size;
+        if (!ctx.count && ctx.state.active && !ctx.failed) { ctx.port.resume?.(); }
+    });
+}
+/** Bound data even if a custom driver ignores pause; pause/resume the native stream. */
+export default async function receive(state, port, device, collector, options) {
+    const ctx = { state, port, device, collector, options, pending: Promise.resolve(), count: 0, bytes: 0, failed: false };
+    const closed = new Promise((resolve) => { state.wake = resolve; });
+    ctx.fail = (error) => { ctx.failed = true; report(options, error, device); state.wake?.(); };
+    function data(chunk) { enqueue(ctx, chunk); }
+    function close() { state.wake?.(); }
+    port.on('data', data).on('error', ctx.fail).on('close', close);
+    if (!state.active) { state.wake(); }
+    await closed;
+    port.off('data', data);
+    try {
+        await closePort(port, options.stopTimeoutMs);
+        await deadline(ctx.pending, options.stopTimeoutMs, 'Serial acceptance', (error) => { state.controller.abort(error); });
+    } finally { port.off('error', ctx.fail).off('close', close); }
+}

package/src/infrastructure/streams/serialSource.js

@@ -0,0 +1,87 @@
+import positive from './positive.js';
+
+import deadline from './deadline.js';
+import receive, { closePort, report } from './serialReceive.js';
+
+async function openPort(device) {
+    const { SerialPort } = await import('serialport');
+    const port = new SerialPort({ ...device, autoOpen: false });
+    await new Promise((resolve, reject) => { port.open((error) => { if (error) { reject(error); } else { resolve(); } }); });
+    return port;
+}
+function pause(state, milliseconds) {
+    return new Promise((resolve) => { state.wake = resolve; state.timer = setTimeout(resolve, milliseconds); })
+        .finally(() => { clearTimeout(state.timer); state.wake = null; });
+}
+async function run(state, device, collector, options) {
+    while (state.active) {
+        try {
+            // Each port has an independent serialized open/close/retry loop.
+            const attempt = { timedOut: false };
+            const opening = Promise.resolve().then(() => { return options.openPort(device, { signal: state.controller.signal }); });
+            void opening.then((late) => {
+                if (attempt.timedOut) { return closePort(late, options.stopTimeoutMs); }
+                return undefined;
+            }).catch((error) => { report(options, error, device); });
+            // A timed-out open is uncertain; never open a second handle in this instance.
+            // eslint-disable-next-line no-await-in-loop
+            const port = await deadline(opening, options.openTimeoutMs, 'Serial open', (error) => { attempt.timedOut = true; state.controller.abort(error); });
+            // eslint-disable-next-line no-await-in-loop
+            await receive(state, port, device, collector, options);
+        } catch (error) {
+            if (error.resourceUncertain || error.code === 'OPERATION_TIMEOUT') { Object.assign(state, { fatal: error, active: false }); }
+            report(options, error, device);
+        }
+        if (state.active) {
+            // eslint-disable-next-line no-await-in-loop
+            await pause(state, options.retryMs);
+        }
+    }
+}
+function validate(devices, collector) {
+    if (!Array.isArray(devices)) { throw new TypeError('devices must be an array'); }
+    if (!collector || typeof collector.accept !== 'function') { throw new TypeError('Collector must have an accept() method'); }
+    const paths = new Set();
+    devices.forEach((device) => {
+        if (!device || typeof device.path !== 'string' || !device.path.trim() || paths.has(device.path)) {
+            throw new TypeError('invalid or duplicate serial path');
+        }
+        paths.add(device.path);
+    });
+}
+/** Independent serial devices; chunks and device metadata pass through unchanged. */
+export default function serialSource(devices, collector, options = {}) {
+    validate(devices, collector);
+    const settings = { retryMs: 1000, openTimeoutMs: 5000, acceptTimeoutMs: 10000, stopTimeoutMs: 5000, maxPending: 32, maxPendingBytes: 1048576,
+        ...options, openPort: options.openPort ?? openPort };
+    ['retryMs', 'acceptTimeoutMs', 'openTimeoutMs', 'stopTimeoutMs', 'maxPending', 'maxPendingBytes'].forEach((key) => { positive(settings[key], key); });
+    if (!Number.isSafeInteger(settings.maxPending) || !Number.isSafeInteger(settings.maxPendingBytes)) { throw new TypeError('Serial capacities must be safe integers'); }
+    const states = devices.map(() => { return { active: false, task: null, wake: null, timer: null }; });
+    let revision = 0;
+    let stopping = Promise.resolve();
+    return {
+        async start() {
+            revision += 1;
+            const requested = revision;
+            await stopping;
+            const failed = states.find((state) => { return state.fatal; });
+            if (failed) { throw failed.fatal; }
+            if (requested === revision) {
+                states.forEach((state, index) => {
+                    if (!state.active) { state.active = true; state.controller = new AbortController(); state.task = run(state, devices[index], collector, settings); }
+                });
+            }
+        },
+        stop() {
+            revision += 1;
+            states.forEach((state) => { state.active = false; state.controller?.abort(new Error('Serial source stopped')); state.wake?.(); });
+            stopping = deadline(Promise.all(states.map((state) => { return state.task; })), settings.stopTimeoutMs, 'Serial stop', (error) => {
+                states.forEach((state) => { state.fatal = error; });
+            }).then(() => {
+                const failed = states.find((state) => { return state.fatal; });
+                if (failed) { throw failed.fatal; }
+            });
+            return stopping;
+        }
+    };
+}