@hotmeshio/long-tail 0.25.4 → 0.27.0

package/build/lib/machines/site/mosquitto-conf.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * The machine broker (Mosquitto), rendered from the line. Machines speak
+ * MQTT 5 to it over TLS, each with its own client certificate (the CN is
+ * its username). The ACL lets a machine publish only its own channels and
+ * read only its own commands, and lets the line controller command every
+ * machine on the line. A bridge carries the line's topics out to the site
+ * NATS, where JetStream keeps them.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderMosquittoConf = renderMosquittoConf;
+exports.renderMosquittoAcl = renderMosquittoAcl;
+const envelope_1 = require("../protocol/envelope");
+const codec_1 = require("../protocol/codec");
+const line_1 = require("../line");
+const site_conf_1 = require("./site-conf");
+function renderMosquittoConf(line, opts) {
+    return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.
+persistence true
+persistence_location /mosquitto/data/
+log_dest stdout
+log_type error
+log_type warning
+log_type notice
+
+listener 8883
+cafile ${opts.certDir}/ca.pem
+certfile ${opts.certDir}/broker.pem
+keyfile ${opts.certDir}/broker.key
+require_certificate true
+use_identity_as_username true
+acl_file ${opts.aclFile}
+max_packet_size ${opts.maxPacketBytes ?? 262_144}
+
+connection ${line.siteId}-${line.lineId}-site-nats
+address ${opts.siteNats}
+bridge_protocol_version mqttv311
+bridge_cafile ${opts.certDir}/ca.pem
+bridge_certfile ${opts.certDir}/${(0, site_conf_1.bridgeId)(line)}.pem
+bridge_keyfile ${opts.certDir}/${(0, site_conf_1.bridgeId)(line)}.key
+remote_clientid ${(0, site_conf_1.bridgeId)(line)}
+cleansession false
+try_private false
+notifications false
+topic ${opts.root}/${line.siteId}/${line.lineId}/# out 1
+`;
+}
+/**
+ * The codec's channels decide the topics: a machine writes its events and telemetry and reads its commands.
+ * A station whose address the line learns has no user of its own: `pattern` rules give every certificate
+ * the channels under its own name (%u), so its certificate's common name must be its address. On a line
+ * that also declares addresses, a certificate named for a declared address is denied that station's channels.
+ */
+function renderMosquittoAcl(line, codec) {
+    const { siteId, lineId } = line;
+    const { events, telemetry, commands } = codec.channels;
+    const own = (address, channels) => channels.map((c) => (0, codec_1.topicOf)(codec, { siteId, lineId, address }, c));
+    const rules = (prefix, address) => [
+        ...own(address, [...events, ...telemetry]).map((t) => `${prefix}write ${t}`),
+        ...own(address, commands).map((t) => `${prefix}read ${t}`),
+    ];
+    const declared = line.machines.filter((m) => !(0, line_1.learnsAddress)(line, m.machineId)).map((m) => (0, line_1.identOf)(line, m.machineId));
+    const machines = declared.map((ident) => [`user ${(0, envelope_1.clientIdOf)(ident)}`, ...rules('topic ', (0, envelope_1.addressOf)(ident))].join('\n'));
+    const learns = line.machines.some((m) => (0, line_1.learnsAddress)(line, m.machineId));
+    const learned = learns ? [['# Stations that learn their address: each certificate, under its own common name.', ...rules('pattern ', '%u')].join('\n')] : [];
+    const every = [...events, ...telemetry, ...commands];
+    const shadows = learns ? declared.map((ident) => shadowRules(line, (0, envelope_1.addressOf)(ident), own((0, envelope_1.addressOf)(ident), every))) : [];
+    const controller = [
+        `user ${(0, line_1.controllerId)(line)}`,
+        ...commands.map((c) => `topic write ${(0, codec_1.topicOf)(codec, { siteId, lineId }, c)}`),
+        `topic read ${codec.root}/${siteId}/${lineId}/#`,
+    ].join('\n');
+    return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.\n\n${[...learned, ...shadows, ...machines, controller].join('\n\n')}\n`;
+}
+/** Deny a declared station's channels to a certificate named for its address, which the patterns would grant. */
+function shadowRules(line, address, topics) {
+    const users = [(0, line_1.controllerId)(line), ...line.machines.filter((m) => !(0, line_1.learnsAddress)(line, m.machineId)).map((m) => (0, envelope_1.clientIdOf)((0, line_1.identOf)(line, m.machineId)))];
+    if (users.includes(address))
+        throw new Error(`address "${address}" is also a broker user name; a declared address on a learning line must differ from every user`);
+    return [`user ${address}`, ...topics.map((t) => `topic deny ${t}`)].join('\n');
+}

package/build/lib/machines/site/site-conf.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The site's NATS server, rendered from the line. It runs JetStream and an
+ * MQTT listener that only the machine broker's bridge logs in to (by client
+ * certificate; the CN is its user, and it may publish only under the line's
+ * topics). The gateway logs in by password and may only keep and read the
+ * line's streams through its own consumer (it can neither publish a machine
+ * subject nor delete a stream), and subscribe to its inbox and the line. The
+ * site NATS stands alone; Long Tail's escalation events stay inside Long Tail.
+ */
+import { type LineDef } from '../line';
+export interface SiteConfOptions {
+    root: string;
+    gatewayUser: string;
+    gatewayPassword: string;
+    certDir: string;
+    storeDir: string;
+    mqttPort?: number;
+}
+/** The machine broker's bridge identity for a line. */
+export declare function bridgeId(line: LineDef): string;
+/** What the gateway may publish: its streams' and its consumer's JetStream requests and acks, never a machine subject. */
+export declare function gatewayPublish(line: LineDef): string[];
+export declare function renderSiteConf(line: LineDef, opts: SiteConfOptions): string;

package/build/lib/machines/site/site-conf.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * The site's NATS server, rendered from the line. It runs JetStream and an
+ * MQTT listener that only the machine broker's bridge logs in to (by client
+ * certificate; the CN is its user, and it may publish only under the line's
+ * topics). The gateway logs in by password and may only keep and read the
+ * line's streams through its own consumer (it can neither publish a machine
+ * subject nor delete a stream), and subscribe to its inbox and the line. The
+ * site NATS stands alone; Long Tail's escalation events stay inside Long Tail.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bridgeId = bridgeId;
+exports.gatewayPublish = gatewayPublish;
+exports.renderSiteConf = renderSiteConf;
+const line_1 = require("../line");
+const protocol_1 = require("../protocol");
+const permissions_1 = require("../../messaging/nats/permissions");
+const streams_1 = require("../transport/streams");
+const q = JSON.stringify;
+/** The machine broker's bridge identity for a line. */
+function bridgeId(line) {
+    return `${line.siteId}-${line.lineId}-bridge`;
+}
+/** What the gateway may publish: its streams' and its consumer's JetStream requests and acks, never a machine subject. */
+function gatewayPublish(line) {
+    return (0, permissions_1.jsPermissions)({ streams: Object.values(streams_1.LINE_STREAM), durable: `${(0, line_1.controllerId)(line)}-events` }).publish;
+}
+function renderSiteConf(line, opts) {
+    const base = (0, protocol_1.toSubject)(`${opts.root}/${line.siteId}/${line.lineId}`);
+    const bridge = [
+        `    { user: ${q(`CN=${bridgeId(line)}`)}, allowed_connection_types: ["MQTT"],`,
+        `      permissions: { publish: [${q(`${base}.>`)}], subscribe: { deny: [">"] } } }`,
+    ].join('\n');
+    const gateway = [
+        `    { user: ${q(opts.gatewayUser)}, password: ${q(opts.gatewayPassword)}, allowed_connection_types: ["STANDARD"],`,
+        `      permissions: { publish: ${q(gatewayPublish(line))}, subscribe: ${q(['_INBOX.>', `${base}.>`])} } }`,
+    ].join('\n');
+    return `# Rendered from the line definition by site/setup.ts. Do not edit by hand.
+server_name: ${q(`${line.siteId}-${line.lineId}`)}
+port: 4222
+http: 8222
+jetstream { store_dir: ${q(opts.storeDir)} }
+
+authorization {
+  users: [
+${bridge}
+${gateway}
+  ]
+}
+
+mqtt {
+  port: ${opts.mqttPort ?? 8883}
+  tls {
+    cert_file: ${q(`${opts.certDir}/server.pem`)}
+    key_file: ${q(`${opts.certDir}/server.key`)}
+    ca_file: ${q(`${opts.certDir}/ca.pem`)}
+    verify_and_map: true
+    timeout: 5
+  }
+}
+`;
+}

package/build/lib/machines/transport/callback-feed.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Escalation events from Long Tail's in-process event adapter. With a
+ * cross-container bus configured, the adapter also receives events other
+ * containers publish. Nothing is replayed: the gateway reconciles open rows
+ * when it starts leading a line.
+ */
+import type { CallbackEventAdapter } from '../../events/callback';
+import { type EscalationEvent, type EscalationFeed } from './delivery';
+import type { MachineDisposition } from '../../../types/machines';
+export declare class CallbackEscalationFeed implements EscalationFeed {
+    private readonly adapter;
+    private off?;
+    private readonly redelivery;
+    constructor(adapter: CallbackEventAdapter, nakDelayMs?: number);
+    connect(): Promise<void>;
+    consume(handler: (event: EscalationEvent) => Promise<MachineDisposition>): Promise<void>;
+    close(): Promise<void>;
+}

package/build/lib/machines/transport/callback-feed.js

@@ -0,0 +1,31 @@
+"use strict";
+/**
+ * Escalation events from Long Tail's in-process event adapter. With a
+ * cross-container bus configured, the adapter also receives events other
+ * containers publish. Nothing is replayed: the gateway reconciles open rows
+ * when it starts leading a line.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CallbackEscalationFeed = void 0;
+const delivery_1 = require("./delivery");
+const serial_1 = require("./serial");
+const ESCALATION_EVENTS = 'system.escalation.>';
+class CallbackEscalationFeed {
+    constructor(adapter, nakDelayMs = 1_000) {
+        this.adapter = adapter;
+        this.redelivery = new serial_1.LocalRedelivery(new serial_1.SerialQueue(), nakDelayMs);
+    }
+    async connect() { }
+    async consume(handler) {
+        this.off = this.adapter.on(ESCALATION_EVENTS, (raw) => {
+            const event = (0, delivery_1.toEscalationEvent)(raw);
+            if (event)
+                void this.redelivery.deliver(() => handler(event));
+        });
+    }
+    async close() {
+        this.off?.();
+        await this.redelivery.stop();
+    }
+}
+exports.CallbackEscalationFeed = CallbackEscalationFeed;

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

@@ -0,0 +1,20 @@
+/**
+ * Two sides of the machine fabric. A machine holds a MachineLink: one MQTT
+ * client with a will, publishing under its own subtree and hearing only its
+ * own commands. The gateway holds a MachineBus: durable, ordered delivery of
+ * every machine message on the line, QoS 1 command egress, and retained reads.
+ */
+import type { Delivery } from '../../../types/messaging';
+import type { EscalationEvent, EscalationFeed, InboundMessage, LinkConnectOptions, LinkWill, MachineBus, MachineLink, PublishOptions } from '../../../types/machines';
+export type { EscalationEvent, EscalationFeed, InboundMessage, LinkConnectOptions, LinkWill, MachineBus, MachineLink, PublishOptions };
+/** What the gateway does with a machine message: the messaging capability's deliveries (nak: its row does not exist yet). */
+export declare const DISPOSITION: {
+    readonly ACK: "ack";
+    readonly NAK: "nak";
+    readonly TERM: "term";
+};
+export type Disposition = Delivery;
+/** MQTT filter match with `+` (one level) and `#` (the rest). */
+export declare function topicMatches(filter: string, topic: string): boolean;
+/** Read an LTEvent body into an EscalationEvent; null for other families. */
+export declare function toEscalationEvent(body: Record<string, any>): EscalationEvent | null;

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

@@ -0,0 +1,37 @@
+"use strict";
+/**
+ * Two sides of the machine fabric. A machine holds a MachineLink: one MQTT
+ * client with a will, publishing under its own subtree and hearing only its
+ * own commands. The gateway holds a MachineBus: durable, ordered delivery of
+ * every machine message on the line, QoS 1 command egress, and retained reads.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DISPOSITION = void 0;
+exports.topicMatches = topicMatches;
+exports.toEscalationEvent = toEscalationEvent;
+const constants_1 = require("../../messaging/constants");
+/** What the gateway does with a machine message: the messaging capability's deliveries (nak: its row does not exist yet). */
+exports.DISPOSITION = constants_1.DELIVERY;
+/** MQTT filter match with `+` (one level) and `#` (the rest). */
+function topicMatches(filter, topic) {
+    const f = filter.split('/');
+    const t = topic.split('/');
+    for (let i = 0; i < f.length; i++) {
+        if (f[i] === '#')
+            return true;
+        if (i >= t.length)
+            return false;
+        if (f[i] !== '+' && f[i] !== t[i])
+            return false;
+    }
+    return f.length === t.length;
+}
+const ESCALATION_SUBJECT = /^(?:.*\.)?system\.escalation\.([^.]+)\.([^.]+)\.([^.]+)$/;
+/** Read an LTEvent body into an EscalationEvent; null for other families. */
+function toEscalationEvent(body) {
+    const match = typeof body?.type === 'string' ? ESCALATION_SUBJECT.exec(body.type) : null;
+    if (!match)
+        return null;
+    const [, role, escalationId, verb] = match;
+    return { type: body.type, escalationId: body.escalationId ?? escalationId, role: body.role ?? role, verb, data: body.data ?? {} };
+}

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

@@ -0,0 +1,13 @@
+export * from './delivery';
+export * from './memory-broker';
+export * from './memory';
+export * from './serial';
+export * from './streams';
+export * from './mqtt-session';
+export * from './mqtt-link';
+export * from './mqtt-bus';
+export * from './stream-bus';
+export * from './nats-bus';
+export * from './nats-feed';
+export * from './pubsub-feed';
+export * from './callback-feed';

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

@@ -0,0 +1,29 @@
+"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("./stream-bus"), exports);
+__exportStar(require("./nats-bus"), exports);
+__exportStar(require("./nats-feed"), exports);
+__exportStar(require("./pubsub-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;
+}