@yarkivaev/scada 2.3.116 → 2.4.1

package/src/infrastructure/streams/amqpSink/publication.js

@@ -0,0 +1,46 @@
+import { randomUUID } from 'node:crypto';
+
+function publishOptions(record) {
+    const options = record.options || {};
+    if (!options.mandatory) { return options; }
+    const headers = { ...options.headers, 'x-source-to-sink-publish-id': randomUUID() };
+    return { ...options, headers };
+}
+/** Confirms one send, without replaying an outcome the broker may already have accepted. */
+export default function publication(live, record, timeoutMs, signal) {
+    if (!record || typeof record.exchange !== 'string' || typeof record.routingKey !== 'string'
+        || !(typeof record.body === 'string' || Buffer.isBuffer(record.body))) {
+        return Promise.reject(new TypeError('AMQP record requires exchange, routingKey and string/Buffer body'));
+    }
+    if (signal?.aborted) { return Promise.reject(signal.reason || new Error('AMQP publish aborted')); }
+    const options = publishOptions(record);
+    return new Promise((resolve, reject) => {
+        const body = Buffer.isBuffer(record.body) ? record.body : Buffer.from(record.body);
+        let settled = false;
+        function abort() { live.fail(signal.reason || new Error('AMQP publish aborted')); }
+        const timer = { handle: null };
+        function settle(error) {
+            if (!settled) {
+                settled = true;
+                clearTimeout(timer.handle);
+                signal?.removeEventListener('abort', abort);
+                live.pending.delete(settle);
+                if (options.mandatory) { live.returns.delete(options.headers['x-source-to-sink-publish-id']); }
+                if (error) { reject(error); } else { resolve(); }
+            }
+        }
+        timer.handle = setTimeout(() => {
+            const error = new Error('AMQP publish confirmation timed out');
+            settle(error);
+            live.fail(error);
+        }, timeoutMs);
+        live.pending.add(settle);
+        if (options.mandatory) { live.returns.set(options.headers['x-source-to-sink-publish-id'], settle); }
+        signal?.addEventListener('abort', abort, { once: true });
+        try {
+            if (!live.channel.publish(record.exchange, record.routingKey, body, options, settle)) {
+                live.blocked = true;
+            }
+        } catch (error) { settle(error); }
+    });
+}

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

@@ -0,0 +1,105 @@
+import amqp from 'amqplib';
+import brokerClose, { destroyConnection } from '../brokerClose.js';
+import deadline from '../deadline.js';
+
+export function report(state, error) {
+    try { state.options.onError?.(error); } catch {
+        // Diagnostics cannot break recovery.
+    }
+}
+export function closeLive(live) {
+    if (!live) { return Promise.resolve(); }
+    live.closing ??= Promise.resolve().then(async () => {
+        live.pending.forEach((settle) => { settle(new Error('AMQP connection closed before confirmation')); });
+        await brokerClose([
+            () => { return live.channel?.close(); }, () => { return live.connection?.close(); }
+        ], live.options.stopTimeoutMs, 'AMQP close', () => { destroyConnection(live.connection); });
+    });
+    return live.closing;
+}
+function retry(state, epoch) {
+    if (state.wanted && state.epoch === epoch && !state.retry) {
+        state.retry = setTimeout(() => {
+            state.retry = null;
+            void state.reopen().catch((error) => { report(state, error); });
+        }, state.options.retryMs);
+    }
+}
+function drop(state, live, error) {
+    if (live.dead) { return; }
+    live.dead = true;
+    live.pending.forEach((settle) => { settle(error || new Error('AMQP connection closed')); });
+    if (state.live === live) { state.live = null; }
+    if (error) { report(state, error); }
+    void closeLive(live).then(() => { retry(state, live.epoch); }, (failure) => { state.fatal = failure; report(state, failure); });
+}
+function bind(state, live, handle) {
+    handle.on('error', (error) => { drop(state, live, error); });
+    handle.on('close', () => { drop(state, live); });
+}
+function returned(live, message) {
+    const settle = live.returns.get(message.properties?.headers?.['x-source-to-sink-publish-id']);
+    const error = new Error(`AMQP publication returned unroutable: ${message.fields?.replyText || 'NO_ROUTE'}`);
+    error.code = 'AMQP_UNROUTABLE';
+    if (settle) { settle(error); } else { live.fail(error); }
+}
+async function configure(state, live) {
+    // This attempt owns live; stop closes it after opening settles and epoch is checked below.
+    // eslint-disable-next-line require-atomic-updates
+    live.channel = await live.connection.createConfirmChannel();
+    bind(state, live, live.channel);
+    live.channel.on('return', (message) => { returned(live, message); });
+    live.channel.on('drain', () => { live.blocked = false; });
+    await Promise.all((state.options.exchanges || []).map((item) => {
+        return live.channel.assertExchange(item.name, item.type || 'topic', item.options || {durable: true});
+    }));
+}
+async function current(state, live) {
+    if (live.epoch !== state.epoch || !state.wanted) {
+        await closeLive(live);
+        return false;
+    }
+    return true;
+}
+function keep(state, live) {
+    if (live.epoch !== state.epoch || !state.wanted) { return closeLive(live); }
+    state.live = live;
+    return undefined;
+}
+async function connect(state, epoch) {
+    const live = { options: state.options, connection: null, channel: null, pending: new Set(), returns: new Map(), epoch, dead: false, blocked: false,
+        fail(error) { drop(state, live, error); } };
+    try {
+        live.connection = await (state.options.connect || amqp.connect)(state.url, { timeout: state.options.connectTimeoutMs });
+        bind(state, live, live.connection);
+        if (!await current(state, live)) { return; }
+        await configure(state, live);
+        if (live.dead) { throw new Error('AMQP session closed during initialization'); }
+        await keep(state, live);
+    } catch (error) {
+        await closeLive(live);
+        retry(state, epoch);
+        throw error;
+    }
+}
+function recover(state, timeout) {
+    if (timeout && state.fatal === timeout) {
+        state.fatal = null;
+        retry(state, state.epoch);
+    }
+}
+export function begin(state) {
+    if (state.fatal) { return Promise.reject(state.fatal); }
+    if (state.live) { return Promise.resolve(); }
+    if (state.opening) { return state.opening; }
+    if (!state.wanted) { return Promise.resolve(); }
+    clearTimeout(state.retry);
+    state.retry = null;
+    let timeout;
+    const attempt = connect(state, state.epoch);
+    void attempt.then(() => { recover(state, timeout); }, () => { recover(state, timeout); });
+    state.opening = deadline(attempt, state.options.connectTimeoutMs, 'AMQP connect', (error) => {
+        timeout = error; state.fatal = error; state.epoch += 1;
+    }).finally(() => { state.opening = null; });
+    return state.opening;
+}

package/src/infrastructure/streams/amqpSink.js

@@ -0,0 +1,47 @@
+import { begin, closeLive } from './amqpSink/session.js';
+import publication from './amqpSink/publication.js';
+
+function settings(url, options) {
+    if (typeof url !== 'string' || !/^amqps?:\/\//u.test(url)) { throw new TypeError('AMQP URL is required'); }
+    const config = { retryMs: 1000, connectTimeoutMs: 5000, confirmTimeoutMs: 10000, stopTimeoutMs: 5000, maxPending: 1024, ...options };
+    ['retryMs', 'connectTimeoutMs', 'confirmTimeoutMs', 'stopTimeoutMs', 'maxPending'].forEach((name) => {
+        if (!Number.isFinite(config[name]) || config[name] <= 0) { throw new TypeError(`${name} must be positive`); }
+    });
+    if (!Number.isInteger(config.maxPending)) { throw new TypeError('maxPending must be an integer'); }
+    return config;
+}
+function stop(state) {
+    state.request += 1;
+    state.epoch += 1;
+    state.wanted = false;
+    clearTimeout(state.retry);
+    state.retry = null;
+    const { live } = state;
+    state.live = null;
+    state.stopped = Promise.all([closeLive(live), state.opening?.catch(() => { return undefined; })]);
+    return state.stopped;
+}
+/** AMQP record sink with confirms and independent connection recovery; never automatically replays sends. */
+export default function amqpSink(url, options = {}) {
+    const state = {url, options: settings(url, options), wanted: false, epoch: 0, request: 0,
+        live: null, opening: null, retry: null, stopped: Promise.resolve(), reopen() { return begin(state); }};
+    return {
+        active() { return Boolean(state.live); },
+        start() {
+            state.wanted = true;
+            state.request += 1;
+            const { request } = state;
+            return state.stopped.then(() => { if (request === state.request) { return begin(state); } return undefined; });
+        },
+        stop() { return stop(state); },
+        write(records, { signal } = {}) {
+            if (!Array.isArray(records)) { return Promise.reject(new TypeError('AMQP records must be an array')); }
+            if (!state.live) { return Promise.reject(new Error('AMQP sink is not connected')); }
+            const { live } = state;
+            if (live.blocked || live.pending.size + records.length > state.options.maxPending) {
+                return Promise.reject(new Error('AMQP sink backpressure: retry after confirmations or drain'));
+            }
+            return Promise.all(records.map((record) => { return publication(live, record, state.options.confirmTimeoutMs, signal); }));
+        }
+    };
+}

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

@@ -0,0 +1,127 @@
+// Each session is mutated only by its generation; disposal waits for subscription.
+/* eslint-disable require-atomic-updates */
+import brokerClose, { destroyConnection } from '../brokerClose.js';
+import deadline from '../deadline.js';
+import positive from '../positive.js';
+
+async function connectBroker(url) {
+    const { default: amqp } = await import('amqplib');
+    return amqp.connect(url, { heartbeat: 10 });
+}
+function reportFailure(error) {
+    process.stderr.write(`amqp consume failed ${error.message}\n`);
+}
+async function closeLive(live, ctx) {
+    try {
+        await brokerClose([
+            () => { return live.tag ? live.channel.cancel(live.tag) : undefined; },
+            () => { return ctx.drain?.(live.channel); },
+            () => { return live.channel?.close(); },
+            () => { return live.connection?.close(); }
+        ], ctx.stopTimeoutMs, 'AMQP cleanup', () => { destroyConnection(live.connection); });
+    } catch (error) { ctx.state.fatal = error; throw error; }
+}
+function dispose(live, ctx) {
+    if (!live) { return Promise.resolve(); }
+    if (!live.closing) { live.closing = closeLive(live, ctx); }
+    return live.closing;
+}
+
+function current(ctx, generation) {
+    return !ctx.state.fatal && ctx.state.running && ctx.state.generation === generation;
+}
+function retry(ctx, generation) {
+    if (!current(ctx, generation) || ctx.state.timer !== undefined) { return; }
+    const pause = ctx.state.delay;
+    ctx.state.delay = Math.min(pause * 2, 30000);
+    ctx.state.timer = ctx.schedule(() => {
+        ctx.state.timer = undefined;
+        ctx.state.opening = deadline(ctx.open(generation), ctx.connectTimeoutMs, 'AMQP connect', (error) => {
+            ctx.state.fatal = error; ctx.state.running = false; ctx.state.generation += 1;
+        });
+        void ctx.state.opening.catch(ctx.report);
+        return ctx.state.opening;
+    }, pause);
+}
+function bind(ctx, generation, live, emitter) {
+    function lost(error) {
+        if (live.lost || !current(ctx, generation)) { return; }
+        live.lost = true;
+        if (error) { ctx.report(error); }
+        ctx.state.cleanup = live.ready.then(() => { return dispose(live, ctx); }).then(() => { retry(ctx, generation); });
+        void ctx.state.cleanup.catch(ctx.report);
+    }
+    emitter.on('error', lost);
+    emitter.on('close', lost);
+}
+async function subscribe(ctx, generation, live) {
+    if (!current(ctx, generation) || live.lost) { return; }
+    live.channel = await live.connection.createChannel();
+    bind(ctx, generation, live, live.channel);
+    if (!current(ctx, generation) || live.lost) { return; }
+    live.tag = await ctx.subscribe(live.channel);
+}
+async function open(ctx, generation) {
+    let complete;
+    const live = { closed: false, ready: new Promise((resolve) => { complete = resolve; }) };
+    try {
+        live.connection = await ctx.connect(ctx.url);
+        bind(ctx, generation, live, live.connection);
+        await subscribe(ctx, generation, live);
+        if (!current(ctx, generation) || live.lost) { await dispose(live, ctx); return; }
+        ctx.state.live = live;
+        ctx.state.delay = 1000;
+    } catch (error) {
+        ctx.report(error);
+        await dispose(live, ctx);
+        retry(ctx, generation);
+    } finally { complete(); }
+}
+async function begin(ctx) {
+    if (ctx.state.fatal) { throw ctx.state.fatal; }
+    if (ctx.state.running) { await ctx.state.opening; return; }
+    ctx.state.running = true;
+    ctx.state.generation += 1;
+    const { generation } = ctx.state;
+    await ctx.state.stopping;
+    await ctx.state.cleanup;
+    if (current(ctx, generation)) {
+        ctx.state.opening = deadline(ctx.open(generation), ctx.connectTimeoutMs, 'AMQP connect', (error) => {
+            ctx.state.fatal = error; ctx.state.running = false; ctx.state.generation += 1;
+        });
+        await ctx.state.opening;
+    }
+}
+async function end(ctx) {
+    ctx.state.running = false;
+    ctx.state.generation += 1;
+    if (ctx.state.timer !== undefined) { ctx.clear(ctx.state.timer); ctx.state.timer = undefined; }
+    await ctx.state.opening;
+    await ctx.state.cleanup;
+    await dispose(ctx.state.live, ctx);
+    ctx.state.live = undefined;
+}
+/** Shared AMQP session lifecycle; subscribe returns a consumer tag. */
+export default function amqpSession(url, subscribeChannel, options = {}) {
+    positive(options.stopTimeoutMs ?? 5000, 'stopTimeoutMs');
+    positive(options.connectTimeoutMs ?? 5000, 'connectTimeoutMs');
+    const ctx = {
+        stopTimeoutMs: options.stopTimeoutMs ?? 5000, connectTimeoutMs: options.connectTimeoutMs ?? 5000,
+        url, subscribe: subscribeChannel, drain: options.drain,
+        connect: options.connect || connectBroker,
+        schedule: options.schedule || setTimeout,
+        clear: options.clear || clearTimeout,
+        report: options.onError || options.report || reportFailure,
+        state: { generation: 0, running: false, delay: 1000 },
+        open(generation) { return open(ctx, generation); }
+    };
+    return {
+        start() { return begin(ctx); },
+        stop() {
+            ctx.state.stopping = end(ctx);
+            return ctx.state.stopping;
+        },
+        generation() { return ctx.state.generation; },
+        active() { return !ctx.state.fatal && ctx.state.running; }
+    };
+}

package/src/infrastructure/streams/amqpSource.js

@@ -0,0 +1,97 @@
+import amqpSession from './amqpSource/session.js';
+import budgetAccept from './budgetAccept.js';
+
+function capacity(options) {
+    const settings = { prefetch: 32, maxMessageBytes: 1048576, ...options };
+    settings.maxPendingBytes ??= settings.prefetch * settings.maxMessageBytes;
+    ['prefetch', 'maxMessageBytes', 'maxPendingBytes'].forEach((name) => {
+        if (!Number.isSafeInteger(settings[name]) || settings[name] < 1) { throw new TypeError(`${name} must be a positive safe integer`); }
+    });
+    return settings;
+}
+
+function deliveryFor(channel, message, options) {
+    let settled = false;
+    return {
+        content: message.content, fields: message.fields, properties: message.properties,
+        ack() {
+            if (!settled && options.active()) { channel.ack(message); settled = true; }
+        },
+        reject(requeue = true) {
+            if (!settled && options.active()) { channel.nack(message, false, requeue); settled = true; }
+        }
+    };
+}
+function reportFailure(options, error) {
+    const report = options.onError || options.report;
+    try {
+        if (report) { report(error); }
+        else { process.stderr.write(`amqp delivery failed ${error.message}\n`); }
+    } catch {
+        // Error reporting must not reject a broker callback.
+    }
+}
+function rejectDelivery(delivery, options, error) {
+    try { delivery.reject(true); }
+    catch (settlementError) { reportFailure(options, settlementError); }
+    reportFailure(options, error);
+}
+function consume(channel, collector, options) {
+    return async (message) => {
+        if (!message) { channel.emit('close'); return; }
+        const delivery = deliveryFor(channel, message, options);
+        try {
+            await budgetAccept(collector, delivery, message.content.length, options);
+            if (options.ackMode !== 'manual') { delivery.ack(); }
+        } catch (error) {
+            rejectDelivery(delivery, options, error);
+        }
+    };
+}
+function trackedConsume(channel, collector, options, pending) {
+    const accept = consume(channel, collector, options);
+    const state = { bytes: 0 };
+    return (message) => {
+        if (!options.active()) { return Promise.resolve(); }
+        const bytes = message?.content?.length ?? 0;
+        if (bytes > options.maxMessageBytes || state.bytes + bytes > options.maxPendingBytes) {
+            try { channel.nack(message, false, false); } catch (error) { reportFailure(options, error); }
+            reportFailure(options, new Error('AMQP payload capacity exceeded; rejected without requeue'));
+            return Promise.resolve();
+        }
+        state.bytes += bytes;
+        const delivery = accept(message);
+        pending.add(delivery);
+        return delivery.finally(() => { state.bytes -= bytes; pending.delete(delivery); });
+    };
+}
+async function topology(channel, queue, options) {
+    await Promise.all((options.exchanges || []).map((exchange) => {
+        return channel.assertExchange(exchange.name, exchange.type, exchange.options);
+    }));
+    const declared = await channel.assertQueue(queue, options.queueOptions || { durable: true });
+    const name = declared?.queue || queue;
+    await Promise.all((options.bindings || []).map((binding) => {
+        return channel.bindQueue(name, binding.exchange, binding.pattern, binding.args);
+    }));
+    await channel.prefetch(options.prefetch || 32);
+    return name;
+}
+/** Delivers AMQP records, acknowledging only after collector acceptance. */
+export default function amqpSource(url, queue, collector, options = {}) {
+    if (!collector || typeof collector.accept !== 'function') { throw new Error('Collector must have an accept() method'); }
+    const settings = capacity(options);
+    const pending = new Set();
+    const state = {};
+    const session = amqpSession(url, async (channel) => {
+        const generation = state.session.generation();
+        const config = { ...settings, active() {
+            return state.session.active() && state.session.generation() === generation;
+        } };
+        const name = await topology(channel, queue, settings);
+        const result = await channel.consume(name, trackedConsume(channel, collector, config, pending), { noAck: false });
+        return result.consumerTag;
+    }, { ...settings, drain() { return Promise.all([...pending]); } });
+    state.session = session;
+    return session;
+}

package/src/infrastructure/streams/brokerClose.js

@@ -0,0 +1,19 @@
+import deadline from './deadline.js';
+
+/** Attempt every cleanup stage; an uncertain stage prevents reuse even if later cleanup succeeds. */
+export default async function brokerClose(actions, timeoutMs, label, destroy) {
+    const failures = [];
+    for (const action of actions) {
+        try {
+            // Cleanup order matters, but one hung stage must not skip transport closure.
+            // eslint-disable-next-line no-await-in-loop
+            await deadline(Promise.resolve().then(action), timeoutMs, label, destroy);
+        } catch (error) {
+            if (error.name !== 'IllegalOperationError') { failures.push(error); }
+        }
+    }
+    if (failures.length) { throw failures[0]; }
+}
+export function destroyConnection(connection) {
+    connection?.connection?.stream?.destroy();
+}

package/src/infrastructure/streams/budgetAccept.js

@@ -0,0 +1,6 @@
+/** Budget leases belong to actual acceptance, never to a timeout wrapper. */
+export default async function budgetAccept(collector, record, bytes, options, context) {
+    const release = options.budget?.reserve({ bytes, records: 1 });
+    try { return await collector.accept(record, context); }
+    finally { release?.(); }
+}

package/src/infrastructure/streams/clickhouseSink.js

@@ -0,0 +1,48 @@
+import { createClient } from '@clickhouse/client';
+import deadline from './deadline.js';
+import positive from './positive.js';
+
+/**
+ * ClickHouse sink for batch record insertion.
+ *
+ * Creates a ClickHouse client internally and implements the Sink
+ * interface for use with batch collectors.
+ *
+ * @example
+ * const sink = clickhouseSink('http://localhost:8123', 'metrics');
+ * await sink.write([{ ts: Date.now(), value: 42 }]);
+ *
+ * @param {string} url - ClickHouse URL (e.g., 'http://localhost:8123')
+ * @param {string} table - Target table name
+ * @returns {object} Sink with write(records) method
+ */
+export default function clickhouseSink(url, table, 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');
+  }
+  positive(options.stopTimeoutMs ?? 5000, 'stopTimeoutMs');
+  const client = (options.createClient || createClient)({ url });
+  let stopping;
+  return {
+    /**
+     * Writes records to ClickHouse table.
+     *
+     * @param {Array} records - Array of records to insert
+     * @returns {Promise} Promise resolving when insert completes
+     */
+    write(records, { signal } = {}) {
+      if (stopping) { return Promise.reject(new Error('ClickHouse sink stopped')); }
+      if (signal?.aborted) { return Promise.reject(signal.reason || new Error('ClickHouse write aborted')); }
+      // Native ClickHouse API uses snake_case for cancellation.
+       
+      return client.insert({ table, values: records, format: 'JSONEachRow', abort_signal: signal });
+    },
+    stop() {
+      stopping ??= deadline(Promise.resolve().then(() => { return client.close(); }), options.stopTimeoutMs ?? 5000, 'ClickHouse close');
+      return stopping;
+    }
+  };
+}

package/src/infrastructure/streams/deadline.js

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

package/src/infrastructure/streams/follow.js

@@ -0,0 +1,41 @@
+/**
+ * Continues a delivery chain after a rejected prior step.
+ *
+ * @param {Promise} pending - prior chain
+ * @returns {Promise} settled chain
+ */
+function resume(pending) {
+    return pending.then((value) => {
+        return value;
+    }, (error) => {
+        return error;
+    });
+}
+
+/**
+ * Chains one arrival: read the body, then start deliver.
+ * Serial waits for deliver. Otherwise persist may overlap after enqueue.
+ *
+ * @param {Promise} pending - prior arrival
+ * @param {Function} read - returns a promise for the body
+ * @param {Function} deliver - starts persist for one body
+ * @param {boolean} serial - wait for persist before the next arrival
+ * @returns {Promise} chain
+ *
+ * @example
+ *   let pending = Promise.resolve();
+ *   pending = follow(pending, () => Promise.resolve('a'), write, false);
+ */
+export default function follow(pending, read, deliver, serial) {
+    return resume(pending).then(async () => {
+        const body = await read();
+        const run = deliver(body);
+        if (serial) {
+            return run;
+        }
+        void run.catch((error) => {
+            return error;
+        });
+        return undefined;
+    });
+}

package/src/infrastructure/streams/index.js

@@ -0,0 +1,15 @@
+/** Protocol and storage adapters composed with source-to-sink primitives. */
+export { default as clickhouseSink } from './clickhouseSink.js';
+export { default as postgresSink } from './postgresSink.js';
+export { default as mqttSource } from './mqttSource.js';
+export { default as stompSource } from './stompSource.js';
+export { default as stompSend } from './stompSend.js';
+export { default as lokiSource } from './lokiSource.js';
+export { default as modbusSource, modbusRtuSource } from './modbusSource.js';
+export { default as modbusRtuBusSource } from './modbusRtuBusSource.js';
+export { default as mqttSink } from './mqttSink.js';
+export { default as sqliteSink } from './sqliteSink.js';
+export { default as amqpSink } from './amqpSink.js';
+export { default as amqpSource } from './amqpSource.js';
+export { default as amqpSession } from './amqpSource/session.js';
+export { default as serialSource } from './serialSource.js';

package/src/infrastructure/streams/lokiSource.js

@@ -0,0 +1,88 @@
+import pollingSource from './pollingSource.js';
+import positive from './positive.js';
+
+function config(options) {
+  const settings = { requestTimeoutMs: 5000, maxResponseBytes: 1048576, pageLimit: 1000, queryLagMs: 1000, ...options };
+  ['requestTimeoutMs', 'maxResponseBytes', 'pageLimit'].forEach((key) => { positive(settings[key], key); });
+  if (!Number.isSafeInteger(settings.pageLimit) || settings.pageLimit > 10000 || !Number.isSafeInteger(settings.maxResponseBytes)) {
+    throw new TypeError('Invalid Loki response capacity');
+  }
+  if (!Number.isSafeInteger(settings.queryLagMs) || settings.queryLagMs < 0) { throw new TypeError('Invalid Loki queryLagMs'); }
+  return settings;
+}
+async function body(response, maxBytes) {
+  if (!response.ok) { throw new Error(`Loki HTTP status ${response.status}`); }
+  if (!response.body) { throw new Error('Loki response body missing'); }
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of response.body) {
+    bytes += chunk.byteLength;
+    if (bytes > maxBytes) { throw new Error('Loki response capacity exceeded'); }
+    chunks.push(chunk);
+  }
+  return JSON.parse(Buffer.concat(chunks, bytes).toString());
+}
+function entries(data, limit) {
+  if (data.status !== 'success' || !Array.isArray(data.data?.result) || data.data.resultType !== 'streams') {
+    throw new Error('Invalid Loki stream response');
+  }
+  const rows = data.data.result.flatMap((stream) => {
+    if (!Array.isArray(stream.values)) { throw new Error('Invalid Loki stream values'); }
+    return stream.values;
+  });
+  // A full page may hide older/equal-timestamp rows. Do not deliver or advance a partial window.
+  if (rows.length >= limit) { throw new Error('Loki query page saturated; history incomplete, cursor unchanged'); }
+  return rows.map(([ts, line]) => {
+    if (typeof ts !== 'string' || !/^\d+$/u.test(ts) || typeof line !== 'string') { throw new Error('Invalid Loki log entry'); }
+    return { ts: Number(ts) / 1000000, line };
+  });
+}
+function requestUrl(url, query, range, limit) {
+  const params = new URLSearchParams({ query, start: (range.since * 1000000).toString(),
+    end: (range.until * 1000000).toString(), limit: String(limit), direction: 'forward' });
+  return `${url}/loki/api/v1/query_range?${params}`;
+}
+async function request(url, settings, signal) {
+  const controller = new AbortController();
+  function abort() { controller.abort(signal.reason); }
+  if (signal?.aborted) { abort(); }
+  signal?.addEventListener('abort', abort, { once: true });
+  const timer = setTimeout(() => { controller.abort(new Error('Loki request deadline exceeded')); }, settings.requestTimeoutMs);
+  try {
+    const response = await globalThis.fetch(url, { signal: controller.signal });
+    return entries(await body(response, settings.maxResponseBytes), settings.pageLimit);
+  } catch (error) {
+    controller.abort(error);
+    try { settings.onError?.(error); } catch {
+      // Diagnostics cannot suppress the failed read or change its cursor.
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener('abort', abort);
+  }
+}
+/**
+ * Bounded Loki polling. Saturated pages fail without advancing the in-memory cursor.
+ * Windows lag wall-clock time by queryLagMs (default 1s) to allow ingestion visibility.
+ * Entries becoming visible later than this configured lag may still be missed.
+ * This live polling source does not expose portable history checkpoints or pagination.
+ *
+ * @param {string} url - Loki base URL
+ * @param {string} query - LogQL expression
+ * @param {number} interval - Polling interval in seconds
+ * @param {object} collector - Collector with accept()
+ * @param {object} clk - Clock with millis()
+ * @param {object} options - requestTimeoutMs, maxResponseBytes, pageLimit, queryLagMs, onError
+ * @returns {object} Source with async start/stop
+ */
+// Sixth optional argument preserves the established five-argument source API.
+// eslint-disable-next-line max-params
+export default function lokiSource(url, query, interval, collector, clk, options = {}) {
+  if (typeof url !== 'string' || url.length === 0) { throw new Error('URL must be a non-empty string'); }
+  if (typeof query !== 'string' || query.length === 0) { throw new Error('Query must be a non-empty string'); }
+  const settings = config(options);
+  return pollingSource((since, until, { signal } = {}) => {
+    return request(requestUrl(url, query, { since: since - settings.queryLagMs, until: until - settings.queryLagMs }, settings.pageLimit), settings, signal);
+  }, interval, collector, clk);
+}