@yarkivaev/scada 2.3.116 → 2.4.0

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

package/src/infrastructure/streams/sqliteSink.js

@@ -0,0 +1,55 @@
+import Database from 'better-sqlite3';
+
+/**
+ * SQLite sink for batch record insertion.
+ *
+ * Opens a SQLite database in WAL mode and implements the Sink
+ * interface for use with batch collectors. Creates the target
+ * table with the given columns if it does not exist.
+ *
+ * @example
+ * const sink = sqliteSink('/tmp/metrics.db', 'metrics', ['topic', 'ts', 'value']);
+ * sink.write([{ topic: 'sensor/1', ts: 1700000000000, value: 42 }]);
+ *
+ * @param {string} path - Filesystem path to the SQLite database file
+ * @param {string} table - Target table name
+ * @param {Array<string>} columns - Column names for insertion
+ * @returns {object} Sink with write(records) and close() methods
+ */
+export default function sqliteSink(path, table, columns) {
+  if (typeof path !== 'string' || path.length === 0) {
+    throw new Error('Path 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');
+  }
+  const db = new Database(path);
+  db.pragma('journal_mode = WAL');
+  const placeholders = columns.map(() => {return '?'}).join(', ');
+  const sql = `INSERT INTO ${table} (${columns.join(', ')}) VALUES (${placeholders})`;
+  const statement = db.prepare(sql);
+  const transaction = db.transaction((records) => {
+    for (const record of records) {
+      statement.run(...columns.map((col) => {return record[col]}));
+    }
+  });
+  return {
+    /**
+     * Writes records to SQLite table inside a transaction.
+     *
+     * @param {Array} records - Array of objects with keys matching columns
+     */
+    write(records) {
+      transaction(records);
+    },
+    /**
+     * Closes the database connection.
+     */
+    close() {
+      db.close();
+    }
+  };
+}

package/src/infrastructure/streams/stompBody.js

@@ -0,0 +1,46 @@
+import positive from './positive.js';
+import budgetAccept from './budgetAccept.js';
+
+export function stompSettings(options, prefetch) {
+    const config = { acceptTimeoutMs: 10000, stopTimeoutMs: 5000, maxMessageBytes: 1048576, ...options };
+    config.maxPendingBytes ??= prefetch * config.maxMessageBytes;
+    ['acceptTimeoutMs', 'stopTimeoutMs', 'maxMessageBytes', 'maxPendingBytes'].forEach((key) => { positive(config[key], key); });
+    if (!Number.isSafeInteger(config.maxMessageBytes) || !Number.isSafeInteger(config.maxPendingBytes)) {
+        throw new TypeError('STOMP byte capacities must be safe integers');
+    }
+    return config;
+}
+function overflow() { return new Error('STOMP payload capacity exceeded'); }
+function legacyRead(message, maximum) {
+    return new Promise((resolve, reject) => {
+        message.readString('utf-8', (error, body) => {
+            if (error) { reject(error); }
+            else if (Buffer.byteLength(body) > maximum) { reject(overflow()); }
+            else { resolve(body.toString()); }
+        });
+    });
+}
+/** Native stompit frames are Readables: bound bytes before concatenating the body. */
+export async function readStomp(message, maximum) {
+    if (!message[Symbol.asyncIterator]) { return legacyRead(message, maximum); }
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of message) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > maximum) { throw overflow(); }
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks, bytes).toString('utf8');
+}
+/** Counters and global leases follow real acceptance, including after an uncertain timeout. */
+export async function acceptStomp(ctx, body, settle) {
+    if (!ctx.lifecycle.active) { throw new Error('STOMP source stopped'); }
+    const bytes = Buffer.byteLength(body);
+    if (ctx.lifecycle.bytes + bytes > ctx.lifecycle.maxPendingBytes) { throw overflow(); }
+    ctx.lifecycle.bytes += bytes;
+    try {
+        return await budgetAccept(ctx.collector, { destination: ctx.destination, payload: body, settle }, bytes,
+            ctx.lifecycle, { signal: ctx.lifecycle.controller.signal });
+    } finally { ctx.lifecycle.bytes -= bytes; }
+}

package/src/infrastructure/streams/stompSend.js

@@ -0,0 +1,89 @@
+import stompit from 'stompit';
+import deadline from './deadline.js';
+import positive from './positive.js';
+
+/**
+ * Builds STOMP connect options from a URL.
+ *
+ * @param {URL} parsed - Parsed URL object
+ * @param {object} options - Connection options
+ * @returns {object} stompit connect parameters
+ */
+/**
+ * STOMP SEND headers that persist the body on a durable RabbitMQ queue.
+ *
+ * @param {string} destination - STOMP destination
+ * @returns {object} headers including persistent true
+ */
+export function stompHeaders(destination) {
+    return {
+        destination,
+        'content-type': 'application/json',
+        persistent: 'true'
+    };
+}
+
+function connectParams(parsed, options) {
+    return {
+        host: parsed.hostname,
+        port: parseInt(parsed.port, 10) || 61613,
+        connectHeaders: {
+            host: options.host || parsed.hostname,
+            login: options.login || '',
+            passcode: options.passcode || ''
+        }
+    };
+}
+
+/**
+ * One-shot STOMP publish of a JSON payload to a destination.
+ *
+ * Connects, sends one MESSAGE frame, disconnects. For operator decisions
+ * and other low-volume outbound events.
+ *
+ * @example
+ * await stompSend('stomp://rabbitmq:61613', '/exchange/scada.user_decisions',
+ *   { machine: 'icht2', start: 1700000000, user: 'hmi', tags: ['heating'] },
+ *   { login: 'guest', passcode: 'guest', host: '/' });
+ *
+ * @param {string} url - STOMP broker URL
+ * @param {string} destination - STOMP destination
+ * @param {object|string} payload - JSON-serializable body or raw string
+ * @param {object} [options] - STOMP connection options
+ * @param {string} [options.login] - Login
+ * @param {string} [options.passcode] - Passcode
+ * @param {string} [options.host] - Virtual host header
+ * @returns {Promise<void>} Resolves when the frame is sent and client disconnects
+ */
+export default function stompSend(url, destination, payload, options = {}) {
+    if (typeof url !== 'string' || url.length === 0) {
+        throw new Error('URL must be a non-empty string');
+    }
+    if (typeof destination !== 'string' || destination.length === 0) {
+        throw new Error('Destination must be a non-empty string');
+    }
+    const parsed = new URL(url);
+    const params = connectParams(parsed, options);
+    const body = typeof payload === 'string' ? payload : JSON.stringify(payload);
+    const timeoutMs = options.timeoutMs ?? 10000;
+    positive(timeoutMs, 'timeoutMs');
+    const state = { active: true, client: null, connecting: null };
+    const sent = new Promise((resolve, reject) => {
+        state.connecting = (options.connect || stompit.connect)({ ...params, timeout: timeoutMs }, (error, client) => {
+            if (error) { reject(error); return; }
+            state.client = client;
+            if (!state.active) { client.destroy(); return; }
+            client.on('error', reject);
+            try {
+                const frame = client.send(stompHeaders(destination), { onReceipt() {
+                    if (state.active) { client.disconnect((failure) => { if (failure) { reject(failure); } else { resolve(); } }); }
+                } });
+                frame.end(body);
+            } catch (failure) { client.destroy(); reject(failure); }
+        });
+    });
+    return deadline(sent, timeoutMs, 'STOMP receipt/disconnect', () => {
+        state.active = false;
+        (state.client || state.connecting)?.destroy();
+    }).finally(() => { state.active = false; });
+}

package/src/infrastructure/streams/stompSource.js

@@ -0,0 +1,201 @@
+import stompit from 'stompit';
+import follow from './follow.js';
+import deadline from './deadline.js';
+import { acceptStomp, readStomp, stompSettings } from './stompBody.js';
+
+/**
+ * Idle state for STOMP source.
+ *
+ * @returns {object} State with subscribed() returning false
+ */
+function idle() {
+  return {
+    subscribed() {
+      return false;
+    }
+  };
+}
+
+/**
+ * Subscribed state for STOMP source.
+ *
+ * @param {object} channel - STOMP channel
+ * @returns {object} State with subscribed() returning true
+ */
+function subscribed(channel, delivery) {
+  return {
+    subscribed() {
+      return true;
+    },
+    channel() {
+      return channel;
+    },
+    delivery
+  };
+}
+
+/**
+ * Builds STOMP server configuration from a URL.
+ *
+ * @param {URL} parsed - Parsed URL object
+ * @param {object} options - Connection options
+ * @returns {object} Server config for ConnectFailover
+ */
+function serverConfig(parsed, options) {
+  return {
+    host: parsed.hostname,
+    port: parseInt(parsed.port, 10) || 61613,
+    connectHeaders: {
+      host: options.host || parsed.hostname,
+      login: options.login || '',
+      passcode: options.passcode || ''
+    }
+  };
+}
+
+/**
+ * Builds settle helpers for one STOMP frame.
+ *
+ * @param {object} channel - STOMP channel
+ * @param {object} message - STOMP frame
+ * @returns {{ ack: Function, nack: Function }}
+ */
+function settleOf(channel, message, lifecycle) {
+  let settled = false;
+  return {
+    ack() {
+      if (lifecycle.active && !settled) { channel.ack(message); settled = true; }
+    },
+    nack(requeue = true) {
+      if (lifecycle.active && !settled) { channel.nack(message, { requeue: String(requeue) }); settled = true; }
+    }
+  };
+}
+
+/**
+ * Delivers one STOMP body to the collector and settles the frame.
+ *
+ * @param {object} ctx - delivery context with channel/message/destination/collector/manualAck
+ * @param {string} body - UTF-8 payload
+ * @returns {Promise<void>}
+ */
+async function deliver(ctx, body) {
+  const settle = settleOf(ctx.channel, ctx.message, ctx.lifecycle);
+  try {
+    await deadline(Promise.resolve().then(() => {
+      return acceptStomp(ctx, body, settle);
+    }), ctx.lifecycle.acceptTimeoutMs, 'STOMP acceptance', (error) => {
+      ctx.lifecycle.fatal = error; ctx.lifecycle.active = false; ctx.lifecycle.controller.abort(error); ctx.channel.close();
+    });
+    if (!ctx.manualAck) {
+      settle.ack();
+    }
+  } catch (error) {
+    if (!ctx.manualAck) {
+      settle.nack();
+    }
+    throw error;
+  }
+}
+
+/**
+ * Subscribes a channel and routes frames to the collector.
+ * Arrivals stay in subscribe order through follow, even when persist overlaps.
+ *
+ * @param {object} channel - STOMP channel
+ * @param {string} destination - queue destination
+ * @param {object} collector - message collector
+ * @param {object} delivery - serial, manualAck and prefetch settings
+ * @returns {undefined}
+ */
+function bind(channel, destination, collector, delivery) {
+  const { serial, manualAck, prefetch, lifecycle } = delivery;
+  let pending = Promise.resolve();
+  channel.subscribe({ destination, ack: 'client-individual', 'prefetch-count': String(prefetch) }, (err, message) => {
+    if (err) {
+      return;
+    }
+    const ctx = { channel, message, destination, collector, manualAck, lifecycle };
+    pending = follow(pending, () => {
+      if (!lifecycle.active) { return Promise.reject(new Error('STOMP source stopped')); }
+      return deadline(readStomp(message, lifecycle.maxMessageBytes), lifecycle.acceptTimeoutMs, 'STOMP read').catch((error) => {
+        lifecycle.fatal = error; lifecycle.active = false; channel.close(); throw error;
+      });
+    }, (body) => {
+      const task = deliver(ctx, body);
+      lifecycle.pending.add(task);
+      return task.finally(() => { lifecycle.pending.delete(task); });
+    }, serial);
+    lifecycle.chain = pending;
+    void pending.catch((error) => {
+      try { lifecycle.onError?.(error); } catch {
+        // Reporting cannot reject a transport callback.
+      }
+    });
+  });
+}
+
+/**
+ * STOMP subscription source for streaming messages to a collector.
+ *
+ * Messages are `{destination, payload, settle}`. Default ack-after-accept;
+ * with `manualAck` the collector owns settle. Arrivals enqueue in
+ * subscribe order. With `serial: false` persist may overlap after enqueue.
+ * A finite prefetch (default 32) bounds unacknowledged broker deliveries.
+ *
+ * @param {string} url - STOMP broker URL
+ * @param {string} destination - STOMP destination
+ * @param {object} collector - Collector with accept()
+ * @param {object} [options] - Connection and delivery options
+ * @param {number} [options.prefetch=32] - Positive integer delivery window
+ * @returns {object} Source with start() and stop() methods
+ */
+export default function stompSource(url, destination, collector, options = {}) {
+  if (typeof url !== 'string' || url.length === 0) {
+    throw new Error('URL must be a non-empty string');
+  }
+  if (typeof destination !== 'string' || destination.length === 0) {
+    throw new Error('Destination must be a non-empty string');
+  }
+  if (!collector || typeof collector.accept !== 'function') {
+    throw new Error('Collector must have an accept() method');
+  }
+  const prefetch = options.prefetch ?? 32;
+  if (!Number.isSafeInteger(prefetch) || prefetch < 1) {
+    throw new Error('prefetch must be a positive safe integer');
+  }
+  const settings = stompSettings(options, prefetch);
+  const parsed = new URL(url);
+  const serial = options.serial !== false;
+  const manualAck = options.manualAck === true;
+  let state = idle();
+  return {
+    start() {
+      if (state.subscribed()) {
+        return;
+      }
+      const failover = new stompit.ConnectFailover([serverConfig(parsed, options)], {
+        initialReconnectDelay: 10,
+        maxReconnectDelay: 30000,
+        maxReconnects: -1
+      });
+      const channel = new stompit.Channel(failover);
+      const lifecycle = { ...settings, active: true, controller: new AbortController(), pending: new Set(), bytes: 0 };
+      bind(channel, destination, collector, { serial, manualAck, prefetch, lifecycle });
+      state = subscribed(channel, lifecycle);
+    },
+    stop() {
+      if (!state.subscribed()) {
+        return Promise.resolve();
+      }
+      const stopped = state;
+      stopped.delivery.active = false;
+      stopped.delivery.controller.abort(new Error('STOMP source stopped'));
+      stopped.channel().close();
+      return deadline(Promise.allSettled([stopped.delivery.chain, ...stopped.delivery.pending]), options.stopTimeoutMs ?? 5000, 'STOMP stop').then(() => {
+        if (stopped.delivery.fatal) { throw stopped.delivery.fatal; }
+        if (state === stopped) { state = idle(); }
+      });
+    }
+  };
+}