@yarkivaev/scada 2.3.116 → 2.4.0

package/src/infrastructure/ingest/pipelines/stompOptions.js

@@ -0,0 +1,7 @@
+/** Preserve driver defaults when an optional pipeline setting was omitted. */
+export default function stompOptions(config, overrides = {}) {
+    const options = { login: config.login, passcode: config.passcode, host: config.host,
+        prefetch: config.prefetch, maxMessageBytes: config.maxMessageBytes,
+        maxPendingBytes: config.maxPendingBytes, budget: config.budget, ...overrides };
+    return Object.fromEntries(Object.entries(options).filter(([, value]) => { return value !== undefined; }));
+}

package/src/infrastructure/ingest/telemetry/amqpMetricsIngest.js

@@ -1,4 +1,5 @@
-import { amqpSource, batch, circuit, clock, timedBatch } from '@yarkivaev/source-to-sink';
+import { amqpSource } from '../../streams/index.js';
+import ingestBatch from '../ingestBatch.js';
 import deliverToMqttRecord from './deliverToMqttRecord.js';
 import metricsCodec from '../mqtt/metricsTransformer.js';
 import streamNameFromTopic from './streamNameFromTopic.js';
@@ -33,10 +34,14 @@ export function acceptTelemetryDeliver(codec, fields, content, onSeen) {
 export function telemetryConsumer(codec, channel, onSeen) {
     return (msg) => {
         if (!msg) {
-            return;
+            return undefined;
+        }
+        const accepted = acceptTelemetryDeliver(codec, msg.fields, msg.content, onSeen);
+        if (accepted && typeof accepted.then === 'function') {
+            return accepted.then(() => { channel.ack(msg); });
         }
-        acceptTelemetryDeliver(codec, msg.fields, msg.content, onSeen);
         channel.ack(msg);
+        return undefined;
     };
 }
 
@@ -51,13 +56,7 @@ export function telemetryConsumer(codec, channel, onSeen) {
  */
 export default function amqpMetricsIngest(amqpUrl, queue, sink, options = {}) {
     const prefetch = options.prefetch || 32;
-    const size = options.size || 100;
-    const interval = options.interval || 5;
-    const threshold = options.threshold || 5;
-    const timeout = options.timeout || 60;
-    const clk = clock();
-    const breaker = circuit(threshold, timeout, clk);
-    const collector = timedBatch(batch(sink, size, breaker), interval);
+    const collector = ingestBatch(sink, options);
     const codec = metricsCodec(collector);
     const session = amqpSource(amqpUrl, queue, {
         accept(delivery) {
@@ -70,7 +69,7 @@ export default function amqpMetricsIngest(amqpUrl, queue, sink, options = {}) {
         },
         async stop() {
             await session.stop();
-            collector.stop();
+            await collector.stop();
         }
     };
 }

package/src/infrastructure/ingest/telemetry/amqpMqttRelay.js

@@ -1,4 +1,4 @@
-import { amqpSource } from '@yarkivaev/source-to-sink';
+import { amqpSource } from '../../streams/index.js';
 import deliverToMqttRecord from './deliverToMqttRecord.js';
 
 /**
@@ -11,11 +11,15 @@ import deliverToMqttRecord from './deliverToMqttRecord.js';
 export function relayConsumer(sink, channel) {
     return (msg) => {
         if (!msg) {
-            return;
+            return undefined;
         }
         const record = deliverToMqttRecord(msg.fields, msg.content);
-        sink.write([record]);
+        const written = sink.write([record]);
+        if (written && typeof written.then === 'function') {
+            return written.then(() => { channel.ack(msg); });
+        }
         channel.ack(msg);
+        return undefined;
     };
 }
 
@@ -23,7 +27,7 @@ export function relayConsumer(sink, channel) {
  * AMQP queue consumer that republishes messages to MQTT using routing key as topic.
  *
  * @example
- *   import { mqttSink } from '@yarkivaev/source-to-sink';
+ *   import { mqttSink } from '../../streams/index.js';
  *   const sink = mqttSink('mqtt://localhost:1883', { qos: 1 });
  *   const relay = amqpMqttRelay('amqp://localhost', 'scada.telemetry.ingest', sink);
  *   relay.start();
@@ -43,10 +47,10 @@ export default function amqpMqttRelay(amqpUrl, queue, sink, options = {}) {
         }
     }, { ...options, prefetch });
     return {
-        start() {
+        async start() {
             if (!opened) {
+                await sink.start();
                 opened = true;
-                sink.start();
             }
             return session.start();
         },

package/src/infrastructure/ingest/telemetry/foldingSink.js

@@ -12,9 +12,12 @@
  */
 export default function foldingSink(inner, fold, locate) {
     return {
-        async write(records) {
-            await inner.write(records);
+        stop() { return inner.stop?.(); },
+        async write(records, context = {}) {
+            context.signal?.throwIfAborted();
+            await inner.write(records, context);
             for (const record of records) {
+                context.signal?.throwIfAborted();
                 const sample = locate(record);
                 if (sample) {
                     // eslint-disable-next-line no-await-in-loop

package/src/infrastructure/messaging/stomp/segmentRetags.js

@@ -1,4 +1,4 @@
-import { stompSend } from '@yarkivaev/source-to-sink';
+import { stompSend } from '../../streams/index.js';
 
 const DEFAULT_DESTINATION = '/exchange/scada.segments';
 

package/src/infrastructure/messaging/stomp/userDecisions.js

@@ -1,4 +1,4 @@
-import { stompSend } from '@yarkivaev/source-to-sink';
+import { stompSend } from '../../streams/index.js';
 import userDecisionBody from './userDecisionBody.js';
 
 const DEFAULT_DESTINATION = '/exchange/scada.user_decisions';

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/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

@@ -1,4 +1,6 @@
 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) {
@@ -26,11 +28,17 @@ function disconnection(client) {
         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 = { active: true, connection, wake: null, timer: null, pending: new Set() };
+    const current = attemptState(connection, options);
     state.current = current;
     try {
         await client.connect(connection.url);
@@ -58,18 +66,20 @@ async function run(state, connection, publish, options) {
     }
 }
 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, publish, options);
+                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?.();

package/src/infrastructure/opcua/session.js

@@ -1,20 +1,30 @@
 import { checkSubscription, watchSubscription } from './subscriptionHealth.js';
 import { AttributeIds, TimestampsToReturn } from 'node-opcua';
 
-function deliver(state, channel, value, publish, options) {
-    if (state.active && !state.failure && value.statusCode.isGood()) {
+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);
+                return publish(channel, value.value.value, { signal: state.controller.signal });
             }
             return undefined;
-        }).catch((error) => {
-            try {
-                options.onError?.(error, state.connection);
-            } catch {
-                // Callback isolation.
-            }
-        }).finally(() => { state.pending.delete(accepted); });
+        }).catch((error) => { report(state, options, error); }).finally(() => {
+            state.pending.delete(accepted);
+            state.overflow = false;
+        });
         state.pending.add(accepted);
     }
 }

package/src/infrastructure/opcua/source.js

@@ -3,12 +3,13 @@ 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, ...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'].forEach((name) => { positive(settings[name], name); });
+    ['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;
@@ -19,9 +20,11 @@ export default function opcuaSource(connections, collector, options = {}) {
             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) => { return collector.accept({ channel, value }); }, settings);
+                    return endpoint(connection, (channel, value, context) => { return collector.accept({ channel, value }, context); }, settings);
                 });
                 endpoints.forEach((item) => { item.start(); });
             }

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

package/src/infrastructure/streams/README.md

@@ -0,0 +1,291 @@
+# SCADA stream adapters
+
+Protocol and storage adapters are exported by `@yarkivaev/scada/streams`.
+Generic batching, circuit and periodic sources are imported from `@yarkivaev/source-to-sink`.
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| `batch(sink, size, circuit)` | Collects records and flushes to sink when size is reached |
+| `circuit(threshold, timeout, clock)` | Circuit breaker for failure isolation |
+| `timedBatch(collector, interval)` | Adds time-based auto-flush to a collector |
+| `clock()` | System time provider |
+| `pollingSource(fetch, interval, collector, clock)` | Generic polling source with time window |
+| `clickhouseSink(url, table)` | ClickHouse sink adapter |
+| `mqttSource(url, topic, collector)` | MQTT subscription source |
+| `lokiSource(url, query, interval, collector, clock)` | Loki polling source |
+
+### STOMP delivery window
+
+`stompSource(url, destination, collector, { prefetch: 32 })` bounds broker deliveries
+that are waiting for acknowledgement. The default is 32; use a positive safe
+integer to tune throughput. A zero (unlimited) window is rejected because a
+backlog can otherwise exhaust the consumer's heap. With `manualAck: true`, the
+collector remains responsible for settling frames. If it flushes only by count,
+its batch must not exceed the prefetch window; a timed flush also avoids stalls.
+
+Manual collectors may call `settle.nack(false)` to dead-letter invalid messages. Configure a durable dead-letter queue and broker policy before enabling this; without a route RabbitMQ discards rejected messages. `settle.nack()` retains retry behaviour.
+
+
+## Transport sources and lifecycle
+
+The sources below receive a collector with `accept(record)`. Return a promise
+that resolves when processing is accepted; rejecting it reports a processing
+failure. Keep application decoding, routing, SQL queries and cursor updates in
+the collector. Await `stop()` before stopping downstream collectors or sinks,
+so in-flight acceptance can finish. A collector that never settles also prevents
+a draining stop from finishing.
+
+### Serial chunks
+
+```javascript
+import { serialSource } from '@yarkivaev/scada/streams';
+
+const source = serialSource([
+  { path: '/dev/ttyUSB0', baudRate: 9600, dataBits: 8, parity: 'none', stopBits: 1 }
+], {
+  accept({ device, chunk }) {
+    return decodeAndStore(device.path, chunk);
+  }
+}, { retryMs: 1000, onError: (error, device) => console.error(device.path, error) });
+
+await source.start();
+```
+
+Each port has its own open/retry loop. `chunk` is the original buffer and `device`
+is the original configuration object; framing and decoding belong in the
+collector. Duplicate paths are rejected. Errors or a closed port trigger cleanup
+and retry without interrupting other devices. `start()` initiates opens;
+`stop()` waits for pending opens, closes ports, removes listeners and drains
+in-flight acceptance before restart.
+
+For testing or another port implementation, pass `openPort(device)`, returning a
+port or promise for a port. The port supports EventEmitter `data`, `error` and
+`close` events plus `close(callback)`. The default opens `serialport` lazily.
+Serial input is a push stream; the source does not impose a collector backlog
+limit or pause the device.
+
+### Periodic collection
+
+```javascript
+import { intervalSource } from '@yarkivaev/source-to-sink';
+
+const source = intervalSource(1000, {
+  async accept({ ts }) {
+    const records = await readChanges(ts);
+    await publish(records);
+    // Advance a cursor only after publication succeeds.
+  }
+}, { immediate: true, onError: console.error });
+
+await source.start();
+```
+
+`intervalMs` must be positive. Ticks carry a Unix timestamp in milliseconds.
+The default `immediate: false` waits one interval before the first tick. With
+`immediate: true`, `start()` waits for the first acceptance to settle. Subsequent
+ticks wait the interval after the previous acceptance settles, so slow work never
+overlaps another tick. Rejections call `onError` and scheduling continues.
+`stop()` cancels scheduling and drains the active tick; restart waits for that
+drain. Tests can inject `schedule(callback, milliseconds)` and `clear(handle)`.
+
+### AMQP consumption
+
+```javascript
+import { amqpSource } from '@yarkivaev/scada/streams';
+
+const source = amqpSource('amqp://localhost', 'readings', {
+  async accept(delivery) {
+    await storeReading(JSON.parse(delivery.content.toString()));
+  }
+}, {
+  queueOptions: { durable: true },
+  exchanges: [{ name: 'telemetry', type: 'topic', options: { durable: true } }],
+  bindings: [{ exchange: 'telemetry', pattern: 'reading.#' }],
+  prefetch: 32,
+  onError: console.error
+});
+
+await source.start();
+```
+
+Deliveries contain `content`, `fields`, `properties`, `ack()` and
+`reject(requeue = true)`. By default the source acknowledges only after
+`collector.accept` resolves; rejection requeues the delivery and reports the
+error. Settlement is idempotent within a delivery. Set `ackMode: 'manual'` to
+let the collector choose `ack()` or `reject(false)` for dead-lettering; configure
+a broker dead-letter route if those messages must be retained. A collector that
+settles manually should still await its processing work so stop can drain it.
+
+The default queue is durable and the default prefetch is 32. Choose a finite,
+positive prefetch to bound outstanding broker deliveries. With count-based
+batching, the batch must fit within that window, or use a timed flush.
+Connection/channel failure or consumer cancellation causes reconnection with
+backoff from one to 30 seconds. `stop()` cancels the consumer, drains acceptance,
+and closes the channel and connection. `active()` means the lifecycle is running,
+including while reconnecting; it does not prove a broker connection is ready.
+
+`amqpSession(url, subscribeChannel, options)` exposes that same lifecycle for
+custom channel topology or consumption. The async `subscribeChannel(channel)`
+returns a consumer tag for cancellation. `options.drain(channel)` can await
+application work before channel closure. Both APIs accept `onError` (or `report`),
+`connect(url)`, `schedule(callback, milliseconds)` and `clear(handle)`; the latter
+three are useful for testing. The default connection uses a ten-second heartbeat.
+
+### AMQP publication
+
+```javascript
+import { amqpSink } from '@yarkivaev/scada/streams';
+
+const sink = amqpSink('amqp://localhost', {
+  exchanges: [{ name: 'telemetry', type: 'topic', options: { durable: true } }],
+  maxPending: 1024,
+  onError: console.error
+});
+await sink.start();
+await sink.write([{
+  exchange: 'telemetry', routingKey: 'reading.temperature',
+  body: JSON.stringify({ value: 42 }), options: { persistent: true }
+}]);
+await sink.stop();
+```
+
+`write(records)` resolves after broker publisher confirms for every record. Each
+record requires an exchange, routing key and string or Buffer body; `options`
+passes publication options to amqplib. A confirm does not mean a consumer has
+processed the message or that an unroutable message reached a queue.
+
+`maxPending` (default 1024) bounds outstanding confirmations. Writes reject while
+the connection is unavailable, when the channel awaits its `drain` event, or when
+the batch would exceed that bound. There is no unbounded offline queue. A write
+can partially succeed before rejection; callers must account for that when
+choosing retries or advancing cursors.
+
+Connection loss or `confirmTimeoutMs` expiry rejects uncertain publications and
+reconnects for future writes. **The sink never automatically replays records**:
+the broker may already have accepted them. Use application idempotency when
+retrying uncertain results. `active()` reports whether a live channel exists.
+`start()` waits for connection and topology setup; a failed initial attempt
+rejects while background retries continue until stopped.
+
+Other options are `retryMs` (1000), `connectTimeoutMs` (5000),
+`confirmTimeoutMs` (10000), `onError(error)`, and injectable
+`connect(url, connectionOptions)`. Exchange declarations default to type `topic`
+and durable options when omitted. `stop()` closes the session and rejects pending
+confirms; it does not flush them. For graceful shutdown, first stop and drain
+sources, await outstanding `write()` promises, then stop the sink.
+
+## Database sink ownership
+
+`clickhouseSink(url, table, options)` owns its client; await its idempotent
+`stop()` to close the client's sockets. `write(records, { signal })` forwards
+cancellation to the installed ClickHouse client's native `abort_signal` API.
+`postgresSink.stop()` ends only a pool created by the sink. An `options.pool`
+pool remains caller-owned and open; explicit transaction clients remain borrowed.
+Both stops have a `stopTimeoutMs` deadline (5000). PostgreSQL rejects already
+aborted writes but does not claim to cancel an in-flight query through AbortSignal.
+Stop/drain sources before closing their owned database sink.
+
+## Bounded operations and shutdown
+
+Await lifecycle methods and writes. In particular, `mqttSink.start()` now waits
+for MQTT CONNACK, and `mqttSink.write(records, { signal })` returns a promise.
+QoS 1/2 waits for the MQTT.js broker-confirmation callback; QoS 0 only confirms
+local handoff and is **not a durable acceptance boundary**. MQTT has no offline
+write queue or automatic replay. Connection loss, cancellation, or a missing
+confirmation retires that session; await `stop()` before starting a fresh session.
+Defaults: `maxPending: 1024`, `maxPendingBytes: 1048576`,
+`connectTimeoutMs: 5000`, `confirmTimeoutMs: 10000`, `stopTimeoutMs: 5000`.
+
+`mqttSource` defers PUBACK/PUBCOMP until asynchronous `collector.accept()` finishes.
+This only represents durability if the collector's promise represents durable
+storage. MQTT.js serializes this acceptance hook: use a source-facing batch size
+of one (or flush each acceptance), since a batch requiring future MQTT messages
+cannot fill while the current message waits for durable acknowledgement. Its MQTT 5 receive window defaults to 32 and packet limit to 1 MiB
+(`prefetch`, `maxPacketBytes`). Sources forward an optional second acceptance
+argument `{ signal }`; existing one-argument collectors remain compatible.
+
+`boundedBatch(sink, options)` provides bounded asynchronous acceptance. Options
+are `size: 100`, `maxRecords: 1000`, `maxBytes: 1048576`, `maxWaitMs: 1000`, and
+`writeTimeoutMs: 10000`. Acceptance resolves after its sink write; admission
+rejects at capacity. Explicit `flush()`/`stop()` reports failures from the drain
+it awaits. A timed-out write aborts its signal and permanently retires the batch.
+A batch rejection can represent a partially applied external write: retries and
+idempotency belong to the caller.
+
+Serial reception pauses the stream while acceptance runs and bounds queued
+chunks/bytes (`maxPending: 32`, `maxPendingBytes: 1048576`). Custom ports must
+implement `pause`/`resume` for flow control; overflow is reported through
+`onError` and permanently retires the source (including a rejected `stop()`).
+There is no implicit drop-and-retry policy. Hardware bytes that arrive despite flow control cannot be recovered
+by this library. `openTimeoutMs` and `stopTimeoutMs` default to 5000;
+`acceptTimeoutMs` defaults to 10000. Timed-out lifecycle operations quarantine
+the instance. RTU buses serialize each slave read and acceptance, recover from
+individual rejected reads, and close late connections without polling them.
+RTU options include `readTimeoutMs: 5000`, `connectTimeoutMs: 5000`,
+`acceptTimeoutMs: 10000`, and `stopTimeoutMs: 5000`.
+
+Periodic sources use `acceptTimeoutMs: 10000` and `stopTimeoutMs: 5000`.
+Polling advances its cursor only after all returned rows are accepted and fences
+late fetch results after stop. Fetch receives `(since, until, { signal })`.
+
+Loki accepts a sixth options argument: `requestTimeoutMs: 5000`,
+`maxResponseBytes: 1048576`, `pageLimit: 1000`, `queryLagMs: 1000`, and `onError`.
+HTTP body reads are capped and aborted on cancellation/deadline. A response at
+or above the page limit rejects before delivery or cursor advance; this API does
+not claim pagination or a portable historical checkpoint. Query windows lag the
+wall clock to allow ingestion visibility. Entries appearing later than the
+configured lag can still be missed; this is a bounded-lag live source.
+
+
+AMQP sources validate `prefetch` (32), `maxMessageBytes` (1048576), and
+`maxPendingBytes` (prefetch times maxMessageBytes). Oversized or aggregate-overbudget
+payloads are rejected without requeue before calling the collector and reported
+through `onError`. Broker delivery decoding still allocates the incoming message;
+configure broker message-size limits as well for hostile inputs.
+
+AMQP cleanup attempts cancellation, draining, channel close, and connection
+close even if an earlier stage hangs. Each cleanup stage uses `stopTimeoutMs`
+(default 5000); the total source cleanup budget can therefore be four times
+that value. Uncertain cleanup/connect deadlines prevent automatic reuse. Native
+AMQP socket destruction is attempted on cleanup timeout. AMQP writes accept
+`{ signal }` and reject pending confirms on cancellation. A confirmed AMQP
+publication still does not prove business processing. Set `record.options.mandatory`
+to require routing: a correlated broker return rejects with `AMQP_UNROUTABLE`
+even when the broker also confirms the publish. Supplied `messageId` values stay
+unchanged for consumer deduplication. The reserved header
+`x-source-to-sink-publish-id` is overwritten with a unique per-publication token
+for return correlation; all other supplied headers are preserved. Callers still
+own poison-message policies.
+
+`stompSend` now waits for the broker SEND receipt and graceful disconnect. Its
+`timeoutMs` (10000) bounds the whole operation and destroys the native client on
+timeout. A receipt is not proof of business processing. `stompSource.stop()`
+returns a promise, revokes late ACKs, and bounds acceptance draining with
+`stopTimeoutMs` (5000). Read/accept waits use `acceptTimeoutMs` (10000). Native STOMP frame streams are
+limited before concatenation by `maxMessageBytes` (1048576); `maxPendingBytes`
+(default prefetch times maxMessageBytes) caps bodies held by actual acceptance.
+Oversized/read-failed frames retire the channel; shared budget leases remain
+held through actual acceptance, including after timeout.
+The upstream STOMP Channel API initiates close without exposing a transport-close
+completion callback; source shutdown proves callback revocation/draining, not
+physical socket closure. Manual ACK collectors remain responsible for settlement
+and poison-message policy.
+
+AMQP, MQTT, serial, STOMP sources, and `boundedBatch` accept an optional shared `budget` with synchronous
+`reserve({ bytes, records: 1 })`, returning an idempotent release function or
+throwing on capacity. Source leases cover actual acceptance; batch leases include queued records and
+remain held until the actual sink write settles. Leases release on completion
+or rejection, including never-written queued records when a batch retires. A timed-out collector that has not actually settled
+keeps its reservation; creating another source cannot reclaim those retained
+bytes. These counters bound retained payload admission, not native decoder or
+transport heap allocations.
+
+A deadline bounds waiting; it does not prove an already-sent external operation
+was cancelled. Callers must await shutdown, treat deadline rejection as an
+uncertain resource/outcome, and quarantine it rather than immediately reuse it.
+
+## License
+
+MIT

package/src/infrastructure/streams/abortable.js

@@ -0,0 +1,14 @@
+/** Cancels the driver and revokes its result; callers still own resource cleanup. */
+export default function abortable(promise, signal, cancel) {
+    if (!signal) { return promise; }
+    const state = {};
+    function abort() {
+        const error = signal.reason || new Error('Operation aborted');
+        try { cancel(); } catch (failure) { state.reject(failure); return; }
+        state.reject(error);
+    }
+    const stopped = new Promise((resolve, reject) => { state.reject = reject; });
+    signal.addEventListener('abort', abort, { once: true });
+    if (signal.aborted) { abort(); }
+    return Promise.race([promise, stopped]).finally(() => { signal.removeEventListener('abort', abort); });
+}