@hotmeshio/long-tail 0.25.4 → 0.26.0

package/build/lib/machines/transport/index.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./delivery"), exports);
+__exportStar(require("./memory-broker"), exports);
+__exportStar(require("./memory"), exports);
+__exportStar(require("./serial"), exports);
+__exportStar(require("./streams"), exports);
+__exportStar(require("./mqtt-session"), exports);
+__exportStar(require("./mqtt-link"), exports);
+__exportStar(require("./mqtt-bus"), exports);
+__exportStar(require("./nats-bus"), exports);
+__exportStar(require("./nats-feed"), exports);
+__exportStar(require("./callback-feed"), exports);

package/build/lib/machines/transport/memory-broker.d.ts

@@ -0,0 +1,35 @@
+/**
+ * An in-process broker with the semantics the line relies on: retained
+ * messages, wills, persistent sessions that queue QoS 1 messages while a
+ * client is away, and a durable consumer log with ack, nak and replay (the
+ * JetStream stand-in). Used by tests and single-process runs.
+ */
+import { type Disposition, type InboundMessage, type LinkWill } from './delivery';
+export interface MemoryBrokerOptions {
+    /** Delay before a nak'd message is offered again. */
+    redeliverMs?: number;
+    maxDeliver?: number;
+}
+export declare class MemoryBroker {
+    private sessions;
+    private retainedStore;
+    private log;
+    private durables;
+    private readonly redeliverMs;
+    private readonly maxDeliver;
+    constructor(opts?: MemoryBrokerOptions);
+    connect(clientId: string, will?: LinkWill): void;
+    disconnect(clientId: string, graceful: boolean): void;
+    isConnected(clientId: string): boolean;
+    subscribe(clientId: string, filter: string, handler: (msg: InboundMessage) => void): void;
+    publish(topic: string, payload: string, retain?: boolean): void;
+    retained(filter: string): InboundMessage[];
+    /** Attach a handler to a named durable consumer; it resumes from its cursor. */
+    consume(name: string, filter: string, handler: (msg: InboundMessage) => Promise<Disposition>): void;
+    /** Detach the handler; unacked and unread messages wait for the next consume. */
+    detach(name: string): void;
+    shutdown(): void;
+    private deliverToSession;
+    private pump;
+    private offer;
+}

package/build/lib/machines/transport/memory-broker.js

@@ -0,0 +1,145 @@
+"use strict";
+/**
+ * An in-process broker with the semantics the line relies on: retained
+ * messages, wills, persistent sessions that queue QoS 1 messages while a
+ * client is away, and a durable consumer log with ack, nak and replay (the
+ * JetStream stand-in). Used by tests and single-process runs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryBroker = void 0;
+const delivery_1 = require("./delivery");
+class MemoryBroker {
+    constructor(opts = {}) {
+        this.sessions = new Map();
+        this.retainedStore = new Map();
+        this.log = [];
+        this.durables = new Map();
+        this.redeliverMs = opts.redeliverMs ?? 20;
+        this.maxDeliver = opts.maxDeliver ?? 50;
+    }
+    connect(clientId, will) {
+        const session = this.sessions.get(clientId) ?? { connected: false, subs: new Map(), queued: [] };
+        session.connected = true;
+        session.will = will;
+        this.sessions.set(clientId, session);
+        const queued = session.queued.splice(0);
+        for (const msg of queued)
+            this.deliverToSession(session, msg);
+    }
+    disconnect(clientId, graceful) {
+        const session = this.sessions.get(clientId);
+        if (!session?.connected)
+            return;
+        session.connected = false;
+        const will = session.will;
+        session.will = undefined;
+        if (!graceful && will)
+            this.publish(will.topic, will.payload, will.retain);
+    }
+    isConnected(clientId) {
+        return this.sessions.get(clientId)?.connected ?? false;
+    }
+    subscribe(clientId, filter, handler) {
+        const session = this.sessions.get(clientId);
+        if (!session)
+            throw new Error(`subscribe before connect: ${clientId}`);
+        session.subs.set(filter, handler);
+        for (const [topic, payload] of this.retainedStore) {
+            if ((0, delivery_1.topicMatches)(filter, topic))
+                queueMicrotask(() => handler({ topic, payload, retained: true, deliveries: 1 }));
+        }
+    }
+    publish(topic, payload, retain = false) {
+        if (retain) {
+            if (payload === '')
+                this.retainedStore.delete(topic);
+            else
+                this.retainedStore.set(topic, payload);
+        }
+        for (const session of this.sessions.values()) {
+            this.deliverToSession(session, { topic, payload, retained: false, deliveries: 1 });
+        }
+        this.log.push({ seq: this.log.length, topic, payload, retained: retain });
+        for (const durable of this.durables.values())
+            void this.pump(durable);
+    }
+    retained(filter) {
+        return [...this.retainedStore]
+            .filter(([topic]) => (0, delivery_1.topicMatches)(filter, topic))
+            .map(([topic, payload]) => ({ topic, payload, retained: true, deliveries: 1 }));
+    }
+    /** Attach a handler to a named durable consumer; it resumes from its cursor. */
+    consume(name, filter, handler) {
+        const durable = this.durables.get(name) ?? { filter, cursor: 0, pumping: false, retries: new Map(), timers: new Set() };
+        durable.handler = handler;
+        this.durables.set(name, durable);
+        void this.pump(durable);
+    }
+    /** Detach the handler; unacked and unread messages wait for the next consume. */
+    detach(name) {
+        const durable = this.durables.get(name);
+        if (!durable)
+            return;
+        durable.handler = undefined;
+        for (const t of durable.timers)
+            clearTimeout(t);
+        durable.timers.clear();
+        if (durable.retries.size)
+            durable.cursor = Math.min(durable.cursor, ...durable.retries.keys());
+        durable.retries.clear();
+    }
+    shutdown() {
+        for (const name of this.durables.keys())
+            this.detach(name);
+    }
+    deliverToSession(session, msg) {
+        for (const [filter, handler] of session.subs) {
+            if (!(0, delivery_1.topicMatches)(filter, msg.topic))
+                continue;
+            if (session.connected)
+                queueMicrotask(() => handler(msg));
+            else
+                session.queued.push(msg);
+        }
+    }
+    async pump(durable) {
+        if (durable.pumping)
+            return;
+        durable.pumping = true;
+        try {
+            while (durable.handler && durable.cursor < this.log.length) {
+                const entry = this.log[durable.cursor++];
+                if ((0, delivery_1.topicMatches)(durable.filter, entry.topic))
+                    await this.offer(durable, entry.seq);
+            }
+        }
+        finally {
+            durable.pumping = false;
+        }
+    }
+    async offer(durable, seq) {
+        const handler = durable.handler;
+        if (!handler)
+            return;
+        const entry = this.log[seq];
+        const deliveries = (durable.retries.get(seq) ?? 0) + 1;
+        durable.retries.set(seq, deliveries);
+        let disposition;
+        try {
+            disposition = await handler({ topic: entry.topic, payload: entry.payload, retained: entry.retained, deliveries });
+        }
+        catch {
+            disposition = delivery_1.DISPOSITION.NAK;
+        }
+        if (disposition !== delivery_1.DISPOSITION.NAK || deliveries >= this.maxDeliver) {
+            durable.retries.delete(seq);
+            return;
+        }
+        const timer = setTimeout(() => {
+            durable.timers.delete(timer);
+            void this.offer(durable, seq);
+        }, this.redeliverMs);
+        durable.timers.add(timer);
+    }
+}
+exports.MemoryBroker = MemoryBroker;

package/build/lib/machines/transport/memory.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Memory adapters over one MemoryBroker: a MachineLink per mock machine, the
+ * gateway's MachineBus, and an EscalationFeed that tests publish into the
+ * way Long Tail publishes escalation events.
+ */
+import { MemoryBroker } from './memory-broker';
+import { type Disposition, type EscalationEvent, type EscalationFeed, type InboundMessage, type LinkConnectOptions, type MachineBus, type MachineLink, type PublishOptions } from './delivery';
+export declare class MemoryMachineLink implements MachineLink {
+    private readonly broker;
+    private clientId?;
+    constructor(broker: MemoryBroker);
+    get connected(): boolean;
+    connect(opts: LinkConnectOptions): Promise<void>;
+    publish(topic: string, payload: string, opts: PublishOptions): Promise<void>;
+    subscribe(filter: string, handler: (msg: InboundMessage) => void): Promise<void>;
+    disconnect(graceful: boolean): Promise<void>;
+}
+export declare class MemoryMachineBus implements MachineBus {
+    private readonly broker;
+    private readonly filter;
+    private readonly durableName;
+    constructor(broker: MemoryBroker, filter: string, durableName?: string);
+    connect(): Promise<void>;
+    consume(handler: (msg: InboundMessage) => Promise<Disposition>): Promise<void>;
+    publish(topic: string, payload: string, opts?: {
+        retain?: boolean;
+    }): Promise<void>;
+    retained(filter: string): Promise<InboundMessage[]>;
+    close(): Promise<void>;
+}
+export declare class MemoryEscalationFeed implements EscalationFeed {
+    private readonly broker;
+    private readonly durableName;
+    constructor(broker: MemoryBroker, durableName?: string);
+    /** Publish an LTEvent body as Long Tail would. */
+    emit(body: Record<string, any>): void;
+    connect(): Promise<void>;
+    consume(handler: (event: EscalationEvent) => Promise<Disposition>): Promise<void>;
+    close(): Promise<void>;
+}

package/build/lib/machines/transport/memory.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Memory adapters over one MemoryBroker: a MachineLink per mock machine, the
+ * gateway's MachineBus, and an EscalationFeed that tests publish into the
+ * way Long Tail publishes escalation events.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryEscalationFeed = exports.MemoryMachineBus = exports.MemoryMachineLink = void 0;
+const delivery_1 = require("./delivery");
+class MemoryMachineLink {
+    constructor(broker) {
+        this.broker = broker;
+    }
+    get connected() {
+        return !!this.clientId && this.broker.isConnected(this.clientId);
+    }
+    async connect(opts) {
+        this.clientId = opts.clientId;
+        this.broker.connect(opts.clientId, opts.will);
+    }
+    async publish(topic, payload, opts) {
+        if (!this.connected)
+            throw new Error(`publish while disconnected: ${topic}`);
+        this.broker.publish(topic, payload, opts.retain ?? false);
+    }
+    async subscribe(filter, handler) {
+        if (!this.clientId)
+            throw new Error('subscribe before connect');
+        this.broker.subscribe(this.clientId, filter, handler);
+    }
+    async disconnect(graceful) {
+        if (this.clientId)
+            this.broker.disconnect(this.clientId, graceful);
+    }
+}
+exports.MemoryMachineLink = MemoryMachineLink;
+class MemoryMachineBus {
+    constructor(broker, filter, durableName = 'line-gateway') {
+        this.broker = broker;
+        this.filter = filter;
+        this.durableName = durableName;
+    }
+    async connect() { }
+    async consume(handler) {
+        this.broker.consume(this.durableName, this.filter, handler);
+    }
+    async publish(topic, payload, opts = {}) {
+        this.broker.publish(topic, payload, opts.retain ?? false);
+    }
+    async retained(filter) {
+        return this.broker.retained(filter);
+    }
+    async close() {
+        this.broker.detach(this.durableName);
+    }
+}
+exports.MemoryMachineBus = MemoryMachineBus;
+const FEED_TOPIC = 'lt/events';
+class MemoryEscalationFeed {
+    constructor(broker, durableName = 'line-gateway-escalations') {
+        this.broker = broker;
+        this.durableName = durableName;
+    }
+    /** Publish an LTEvent body as Long Tail would. */
+    emit(body) {
+        this.broker.publish(FEED_TOPIC, JSON.stringify(body));
+    }
+    async connect() { }
+    async consume(handler) {
+        this.broker.consume(this.durableName, FEED_TOPIC, async (msg) => {
+            const event = (0, delivery_1.toEscalationEvent)(JSON.parse(msg.payload));
+            return event ? handler(event) : delivery_1.DISPOSITION.TERM;
+        });
+    }
+    async close() {
+        this.broker.detach(this.durableName);
+    }
+}
+exports.MemoryEscalationFeed = MemoryEscalationFeed;

package/build/lib/machines/transport/mqtt-bus.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The gateway over plain MQTT, for any broker. The persistent session keeps
+ * QoS 1 messages while the gateway is away; there is no stream to replay
+ * beyond that, and a message that is not yet actionable is retried in this
+ * process.
+ */
+import type { MqttEndpoint } from '../../../services/machines/config';
+import type { Disposition, InboundMessage, MachineBus } from './delivery';
+export declare class MqttMachineBus implements MachineBus {
+    private readonly endpoint;
+    private readonly clientId;
+    private readonly filter;
+    private session?;
+    private readonly redelivery;
+    constructor(endpoint: MqttEndpoint, clientId: string, filter: string, nakDelayMs?: number);
+    connect(): Promise<void>;
+    consume(handler: (msg: InboundMessage) => Promise<Disposition>): Promise<void>;
+    publish(topic: string, payload: string, opts?: {
+        retain?: boolean;
+    }): Promise<void>;
+    retained(filter: string): Promise<InboundMessage[]>;
+    close(): Promise<void>;
+    private connected;
+}

package/build/lib/machines/transport/mqtt-bus.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * The gateway over plain MQTT, for any broker. The persistent session keeps
+ * QoS 1 messages while the gateway is away; there is no stream to replay
+ * beyond that, and a message that is not yet actionable is retried in this
+ * process.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MqttMachineBus = void 0;
+const mqtt_session_1 = require("./mqtt-session");
+const serial_1 = require("./serial");
+class MqttMachineBus {
+    constructor(endpoint, clientId, filter, nakDelayMs = 1_000) {
+        this.endpoint = endpoint;
+        this.clientId = clientId;
+        this.filter = filter;
+        this.redelivery = new serial_1.LocalRedelivery(new serial_1.SerialQueue(), nakDelayMs);
+    }
+    async connect() {
+        this.session = await mqtt_session_1.MqttSession.open(this.endpoint, this.clientId);
+    }
+    async consume(handler) {
+        await this.connected().subscribe(this.filter, (msg) => {
+            void this.redelivery.deliver((deliveries) => handler({ ...msg, deliveries }));
+        });
+    }
+    async publish(topic, payload, opts = {}) {
+        await this.connected().publish(topic, payload, 1, opts.retain ?? false);
+    }
+    retained(filter) {
+        return this.connected().retained(filter);
+    }
+    async close() {
+        await this.redelivery.stop();
+        await this.session?.close(true);
+    }
+    connected() {
+        if (!this.session)
+            throw new Error('MQTT bus used before connect()');
+        return this.session;
+    }
+}
+exports.MqttMachineBus = MqttMachineBus;

package/build/lib/machines/transport/mqtt-link.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The machine side over MQTT: one persistent session per machine, logged in
+ * with its own credentials, with a will that marks it offline.
+ */
+import type { MqttEndpoint } from '../../../services/machines/config';
+import type { InboundMessage, LinkConnectOptions, MachineLink, PublishOptions } from './delivery';
+export declare class MqttMachineLink implements MachineLink {
+    private readonly endpoint;
+    private session?;
+    constructor(endpoint: MqttEndpoint);
+    get connected(): boolean;
+    connect(opts: LinkConnectOptions): Promise<void>;
+    publish(topic: string, payload: string, opts: PublishOptions): Promise<void>;
+    subscribe(filter: string, handler: (msg: InboundMessage) => void): Promise<void>;
+    disconnect(graceful: boolean): Promise<void>;
+}

package/build/lib/machines/transport/mqtt-link.js

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * The machine side over MQTT: one persistent session per machine, logged in
+ * with its own credentials, with a will that marks it offline.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MqttMachineLink = void 0;
+const mqtt_session_1 = require("./mqtt-session");
+class MqttMachineLink {
+    constructor(endpoint) {
+        this.endpoint = endpoint;
+    }
+    get connected() {
+        return !!this.session?.connected;
+    }
+    async connect(opts) {
+        if (this.session)
+            await this.session.close(false);
+        this.session = await mqtt_session_1.MqttSession.open(this.endpoint, opts.clientId, { will: opts.will, onRestored: opts.onRestored });
+    }
+    async publish(topic, payload, opts) {
+        if (!this.session)
+            throw new Error(`publish before connect: ${topic}`);
+        await this.session.publish(topic, payload, opts.qos, opts.retain ?? false);
+    }
+    async subscribe(filter, handler) {
+        if (!this.session)
+            throw new Error('subscribe before connect');
+        await this.session.subscribe(filter, handler);
+    }
+    async disconnect(graceful) {
+        const session = this.session;
+        this.session = undefined;
+        await session?.close(graceful);
+    }
+}
+exports.MqttMachineLink = MqttMachineLink;

package/build/lib/machines/transport/mqtt-session.d.ts

@@ -0,0 +1,34 @@
+/**
+ * One MQTT client with a persistent session (clean start off), shared by the
+ * machine link and the controller buses. A session resumed after a restart
+ * delivers queued QoS 1 messages right after the connect acknowledgement,
+ * before anyone has subscribed again; those are held in the process until a
+ * handler for their topic registers, so a queued command is not dropped.
+ */
+import type { IClientOptions, MqttClient } from 'mqtt';
+import type { MqttEndpoint } from '../../../services/machines/config';
+import { type InboundMessage, type LinkWill } from './delivery';
+type Handler = (msg: InboundMessage) => void;
+export interface SessionOptions {
+    will?: LinkWill;
+    onRestored?: () => void;
+}
+/** Client options for one identity; `{clientId}` in a path or username picks that identity's credentials. */
+export declare function mqttOptions(endpoint: MqttEndpoint, clientId: string, will?: LinkWill): IClientOptions;
+export declare class MqttSession {
+    readonly client: MqttClient;
+    private handlers;
+    private held;
+    private constructor();
+    /** Connect and wait for the broker's acknowledgement; a refusal rejects. */
+    static open(endpoint: MqttEndpoint, clientId: string, opts?: SessionOptions): Promise<MqttSession>;
+    get connected(): boolean;
+    subscribe(filter: string, handler: Handler): Promise<void>;
+    publish(topic: string, payload: string, qos: 0 | 1, retain?: boolean): Promise<void>;
+    /** Retained messages under `filter`, as the broker sends them on subscribe. */
+    retained(filter: string, settleMs?: number): Promise<InboundMessage[]>;
+    /** Graceful sends DISCONNECT, so the broker drops the will; otherwise the socket just closes. */
+    close(graceful: boolean): Promise<void>;
+    private route;
+}
+export {};

package/build/lib/machines/transport/mqtt-session.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * One MQTT client with a persistent session (clean start off), shared by the
+ * machine link and the controller buses. A session resumed after a restart
+ * delivers queued QoS 1 messages right after the connect acknowledgement,
+ * before anyone has subscribed again; those are held in the process until a
+ * handler for their topic registers, so a queued command is not dropped.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MqttSession = void 0;
+exports.mqttOptions = mqttOptions;
+const fs_1 = require("fs");
+const delivery_1 = require("./delivery");
+const HELD_LIMIT = 1_000;
+const MQTT_MISSING = 'the MQTT transport needs the "mqtt" package (npm install mqtt)';
+/** mqtt is an optional peer dependency, loaded only when an MQTT transport is used. */
+function loadMqtt() {
+    try {
+        return require('mqtt');
+    }
+    catch (err) {
+        const error = new Error(MQTT_MISSING);
+        error.cause = err;
+        throw error;
+    }
+}
+const SESSION_EXPIRY_SEC = 86_400;
+const RECONNECT_MS = 1_000;
+const CONNECT_TIMEOUT_MS = 10_000;
+/** Client options for one identity; `{clientId}` in a path or username picks that identity's credentials. */
+function mqttOptions(endpoint, clientId, will) {
+    const fill = (value) => value?.split('{clientId}').join(clientId);
+    const file = (path) => (path ? (0, fs_1.readFileSync)(fill(path)) : undefined);
+    return {
+        clientId,
+        protocolVersion: endpoint.protocolVersion,
+        clean: false,
+        ...(endpoint.protocolVersion === 5 ? { properties: { sessionExpiryInterval: SESSION_EXPIRY_SEC } } : {}),
+        ca: file(endpoint.caFile),
+        cert: file(endpoint.certFile),
+        key: file(endpoint.keyFile),
+        username: fill(endpoint.username),
+        password: endpoint.password,
+        reconnectPeriod: RECONNECT_MS,
+        connectTimeout: CONNECT_TIMEOUT_MS,
+        will: will ? { topic: will.topic, payload: Buffer.from(will.payload), qos: 1, retain: will.retain } : undefined,
+    };
+}
+class MqttSession {
+    constructor(client) {
+        this.client = client;
+        this.handlers = [];
+        this.held = [];
+        client.on('message', (topic, payload, packet) => {
+            this.route({ topic, payload: payload.toString(), retained: packet.retain, deliveries: packet.dup ? 2 : 1 });
+        });
+    }
+    /** Connect and wait for the broker's acknowledgement; a refusal rejects. */
+    static open(endpoint, clientId, opts = {}) {
+        const client = loadMqtt().connect(endpoint.url, mqttOptions(endpoint, clientId, opts.will));
+        const session = new MqttSession(client);
+        return new Promise((resolve, reject) => {
+            const fail = (err) => {
+                client.end(true);
+                reject(new Error(`MQTT ${clientId} could not connect to ${endpoint.url}: ${err.message}`));
+            };
+            client.once('error', fail);
+            client.once('connect', () => {
+                client.off('error', fail);
+                client.on('error', () => undefined);
+                client.on('connect', () => opts.onRestored?.());
+                resolve(session);
+            });
+        });
+    }
+    get connected() {
+        return this.client.connected;
+    }
+    async subscribe(filter, handler) {
+        this.handlers.push({ filter, handler });
+        const ready = this.held.filter((m) => (0, delivery_1.topicMatches)(filter, m.topic));
+        this.held = this.held.filter((m) => !(0, delivery_1.topicMatches)(filter, m.topic));
+        await this.client.subscribeAsync(filter, { qos: 1 });
+        for (const m of ready)
+            handler(m);
+    }
+    async publish(topic, payload, qos, retain = false) {
+        await this.client.publishAsync(topic, payload, { qos, retain });
+    }
+    /** Retained messages under `filter`, as the broker sends them on subscribe. */
+    async retained(filter, settleMs = 250) {
+        const seen = [];
+        const collect = (topic, payload, packet) => {
+            if (packet.retain && (0, delivery_1.topicMatches)(filter, topic))
+                seen.push({ topic, payload: payload.toString(), retained: true, deliveries: 1 });
+        };
+        this.client.on('message', collect);
+        try {
+            await this.client.subscribeAsync(filter, { qos: 1 });
+            await new Promise((r) => setTimeout(r, settleMs));
+            await this.client.unsubscribeAsync(filter);
+        }
+        finally {
+            this.client.off('message', collect);
+        }
+        return seen;
+    }
+    /** Graceful sends DISCONNECT, so the broker drops the will; otherwise the socket just closes. */
+    async close(graceful) {
+        if (graceful)
+            await this.client.endAsync(false);
+        else
+            this.client.end(true);
+    }
+    route(msg) {
+        const matching = this.handlers.filter((h) => (0, delivery_1.topicMatches)(h.filter, msg.topic));
+        if (matching.length) {
+            for (const h of matching)
+                h.handler(msg);
+            return;
+        }
+        this.held.push(msg);
+        if (this.held.length > HELD_LIMIT)
+            this.held.shift();
+    }
+}
+exports.MqttSession = MqttSession;

package/build/lib/machines/transport/nats-bus.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The gateway on the site NATS. Machine events come from the line's durable
+ * consumer on LINE_EVENTS (replayed after a restart); telemetry is read live,
+ * since it only proves a machine is alive. Commands leave through an MQTT
+ * session at QoS 1: a NATS publish reaches MQTT subscribers at QoS 0 and
+ * would not wait for a machine that is away.
+ */
+import type { MqttEndpoint } from '../../../services/machines/config';
+import { type StreamCodec } from './streams';
+import type { Disposition, InboundMessage, MachineBus } from './delivery';
+export interface NatsBusOptions {
+    natsUrl: string;
+    user?: string;
+    password?: string;
+    mqtt: MqttEndpoint;
+    /** The gateway's broker identity; also its MQTT client id. */
+    controllerId: string;
+    siteId: string;
+    lineId: string;
+    /** The codec's topics: which subjects are durable events and which are live telemetry. */
+    codec: StreamCodec;
+    nakDelayMs?: number;
+}
+export declare class NatsMachineBus implements MachineBus {
+    private readonly opts;
+    private nc?;
+    private session?;
+    private messages?;
+    private telemetry;
+    private readonly queue;
+    constructor(opts: NatsBusOptions);
+    get durableName(): string;
+    connect(): Promise<void>;
+    consume(handler: (msg: InboundMessage) => Promise<Disposition>): Promise<void>;
+    publish(topic: string, payload: string, opts?: {
+        retain?: boolean;
+    }): Promise<void>;
+    retained(filter: string): Promise<InboundMessage[]>;
+    close(): Promise<void>;
+    private nats;
+    private mqtt;
+}