@hotmeshio/long-tail 0.25.4 → 0.26.0

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

@@ -0,0 +1,67 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NatsMachineBus = void 0;
+const nats_1 = require("nats");
+const protocol_1 = require("../protocol");
+const mqtt_session_1 = require("./mqtt-session");
+const nats_durable_1 = require("./nats-durable");
+const serial_1 = require("./serial");
+const streams_1 = require("./streams");
+class NatsMachineBus {
+    constructor(opts) {
+        this.opts = opts;
+        this.telemetry = [];
+        this.queue = new serial_1.SerialQueue();
+    }
+    get durableName() {
+        return `${this.opts.controllerId}-events`;
+    }
+    async connect() {
+        const { natsUrl, user, password, controllerId, siteId, lineId, codec } = this.opts;
+        this.nc = await (0, nats_1.connect)({ servers: natsUrl, user, pass: password, name: controllerId });
+        const jsm = await this.nc.jetstreamManager();
+        await (0, streams_1.ensureStreams)(jsm, (0, streams_1.lineStreamConfigs)(codec));
+        await (0, streams_1.ensureConsumer)(jsm, streams_1.LINE_STREAM.EVENTS, (0, streams_1.lineEventConsumer)(codec, siteId, lineId, this.durableName));
+        this.session = await mqtt_session_1.MqttSession.open(this.opts.mqtt, controllerId);
+    }
+    async consume(handler) {
+        const nc = this.nats();
+        const { codec, siteId, lineId, nakDelayMs = 1_000 } = this.opts;
+        this.messages = await (0, nats_durable_1.readDurable)(nc.jetstream(), streams_1.LINE_STREAM.EVENTS, this.durableName, this.queue, (m) => handler({ topic: (0, protocol_1.toTopic)(m.subject), payload: (0, nats_durable_1.payloadOf)(m), deliveries: m.info.deliveryCount }), nakDelayMs);
+        this.telemetry = (0, streams_1.telemetrySubjects)(codec, siteId, lineId).map((subject) => nc.subscribe(subject, {
+            callback: (_err, m) => void this.queue.run(() => handler({ topic: (0, protocol_1.toTopic)(m.subject), payload: (0, nats_durable_1.payloadOf)(m), deliveries: 1 })),
+        }));
+    }
+    async publish(topic, payload, opts = {}) {
+        await this.mqtt().publish(topic, payload, 1, opts.retain ?? false);
+    }
+    retained(filter) {
+        return this.mqtt().retained(filter);
+    }
+    async close() {
+        for (const sub of this.telemetry)
+            sub.unsubscribe();
+        await this.messages?.close();
+        await this.queue.drained();
+        await this.session?.close(true);
+        await this.nc?.drain();
+    }
+    nats() {
+        if (!this.nc)
+            throw new Error('NATS bus used before connect()');
+        return this.nc;
+    }
+    mqtt() {
+        if (!this.session)
+            throw new Error('NATS bus used before connect()');
+        return this.session;
+    }
+}
+exports.NatsMachineBus = NatsMachineBus;

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

@@ -0,0 +1,11 @@
+/**
+ * Read a durable JetStream consumer one message at a time and settle each
+ * with the handler's disposition: ack, nak with a delay, or term.
+ */
+import type { ConsumerMessages, JetStreamClient, JsMsg } from 'nats';
+import type { SerialQueue } from './serial';
+import { type Disposition } from './delivery';
+export declare function readDurable(js: JetStreamClient, stream: string, durable: string, queue: SerialQueue, handle: (msg: JsMsg) => Promise<Disposition>, nakDelayMs: number): Promise<ConsumerMessages>;
+export declare function payloadOf(m: {
+    data: Uint8Array;
+}): string;

package/build/lib/machines/transport/nats-durable.js

@@ -0,0 +1,28 @@
+"use strict";
+/**
+ * Read a durable JetStream consumer one message at a time and settle each
+ * with the handler's disposition: ack, nak with a delay, or term.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readDurable = readDurable;
+exports.payloadOf = payloadOf;
+const delivery_1 = require("./delivery");
+async function readDurable(js, stream, durable, queue, handle, nakDelayMs) {
+    const consumer = await js.consumers.get(stream, durable);
+    const messages = await consumer.consume();
+    void (async () => {
+        for await (const m of messages) {
+            const disposition = await queue.run(() => handle(m)).catch(() => delivery_1.DISPOSITION.NAK);
+            if (disposition === delivery_1.DISPOSITION.ACK)
+                m.ack();
+            else if (disposition === delivery_1.DISPOSITION.NAK)
+                m.nak(nakDelayMs);
+            else
+                m.term();
+        }
+    })();
+    return messages;
+}
+function payloadOf(m) {
+    return Buffer.from(m.data).toString('utf8');
+}

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

@@ -0,0 +1,26 @@
+/**
+ * Long Tail's escalation events for a gateway running outside Long Tail: a
+ * subscription to Long Tail's NATS. Nothing is replayed; a not-yet-actionable
+ * event is retried in this process, and the gateway reconciles open rows
+ * when it starts leading a line.
+ */
+import { type Disposition, type EscalationEvent, type EscalationFeed } from './delivery';
+type Handler = (event: EscalationEvent) => Promise<Disposition>;
+/** Long Tail publishes every LTEvent as `lt.events.<type>`. */
+export declare const LT_ESCALATION_SUBJECTS = "lt.events.system.escalation.>";
+export interface CoreFeedOptions {
+    natsUrl: string;
+    token?: string;
+    nakDelayMs?: number;
+}
+export declare class CoreEscalationFeed implements EscalationFeed {
+    private readonly opts;
+    private nc?;
+    private sub?;
+    private readonly redelivery;
+    constructor(opts: CoreFeedOptions);
+    connect(): Promise<void>;
+    consume(handler: Handler): Promise<void>;
+    close(): Promise<void>;
+}
+export {};

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

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * Long Tail's escalation events for a gateway running outside Long Tail: a
+ * subscription to Long Tail's NATS. Nothing is replayed; a not-yet-actionable
+ * event is retried in this process, and the gateway reconciles open rows
+ * when it starts leading a line.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CoreEscalationFeed = exports.LT_ESCALATION_SUBJECTS = void 0;
+const nats_1 = require("nats");
+const nats_durable_1 = require("./nats-durable");
+const serial_1 = require("./serial");
+const delivery_1 = require("./delivery");
+/** Long Tail publishes every LTEvent as `lt.events.<type>`. */
+exports.LT_ESCALATION_SUBJECTS = 'lt.events.system.escalation.>';
+function decode(payload) {
+    try {
+        return (0, delivery_1.toEscalationEvent)(JSON.parse(payload));
+    }
+    catch {
+        return null;
+    }
+}
+class CoreEscalationFeed {
+    constructor(opts) {
+        this.opts = opts;
+        this.redelivery = new serial_1.LocalRedelivery(new serial_1.SerialQueue(), opts.nakDelayMs ?? 1_000);
+    }
+    async connect() {
+        this.nc = await (0, nats_1.connect)({ servers: this.opts.natsUrl, token: this.opts.token, name: 'line-gateway-escalations' });
+    }
+    async consume(handler) {
+        if (!this.nc)
+            throw new Error('escalation feed used before connect()');
+        this.sub = this.nc.subscribe(exports.LT_ESCALATION_SUBJECTS, {
+            callback: (_err, m) => {
+                const event = decode((0, nats_durable_1.payloadOf)(m));
+                if (event)
+                    void this.redelivery.deliver(() => handler(event));
+            },
+        });
+    }
+    async close() {
+        this.sub?.unsubscribe();
+        await this.redelivery.stop();
+        await this.nc?.drain();
+    }
+}
+exports.CoreEscalationFeed = CoreEscalationFeed;

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

@@ -0,0 +1,21 @@
+import { type Disposition } from './delivery';
+/** Runs async work one item at a time, in arrival order. */
+export declare class SerialQueue {
+    private tail;
+    run<T>(work: () => Promise<T>): Promise<T>;
+    /** Resolves once everything queued so far has run. */
+    drained(): Promise<void>;
+}
+/**
+ * Delivery through a SerialQueue that tries a not-yet-actionable item again
+ * after a delay, for transports without a broker-side redelivery.
+ */
+export declare class LocalRedelivery {
+    readonly queue: SerialQueue;
+    private readonly delayMs;
+    private readonly timers;
+    private stopped;
+    constructor(queue: SerialQueue, delayMs: number);
+    deliver(attempt: (deliveries: number) => Promise<Disposition>, deliveries?: number): Promise<void>;
+    stop(): Promise<void>;
+}

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

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LocalRedelivery = exports.SerialQueue = void 0;
+const delivery_1 = require("./delivery");
+/** Runs async work one item at a time, in arrival order. */
+class SerialQueue {
+    constructor() {
+        this.tail = Promise.resolve();
+    }
+    run(work) {
+        const next = this.tail.then(work, work);
+        this.tail = next.catch(() => undefined);
+        return next;
+    }
+    /** Resolves once everything queued so far has run. */
+    drained() {
+        return this.tail.then(() => undefined);
+    }
+}
+exports.SerialQueue = SerialQueue;
+/**
+ * Delivery through a SerialQueue that tries a not-yet-actionable item again
+ * after a delay, for transports without a broker-side redelivery.
+ */
+class LocalRedelivery {
+    constructor(queue, delayMs) {
+        this.queue = queue;
+        this.delayMs = delayMs;
+        this.timers = new Set();
+        this.stopped = false;
+    }
+    deliver(attempt, deliveries = 1) {
+        return this.queue.run(async () => {
+            if (this.stopped)
+                return;
+            const disposition = await attempt(deliveries).catch(() => delivery_1.DISPOSITION.NAK);
+            if (disposition !== delivery_1.DISPOSITION.NAK)
+                return;
+            const timer = setTimeout(() => {
+                this.timers.delete(timer);
+                void this.deliver(attempt, deliveries + 1);
+            }, this.delayMs);
+            this.timers.add(timer);
+        });
+    }
+    async stop() {
+        this.stopped = true;
+        for (const t of this.timers)
+            clearTimeout(t);
+        this.timers.clear();
+        await this.queue.drained();
+    }
+}
+exports.LocalRedelivery = LocalRedelivery;

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

@@ -0,0 +1,28 @@
+/**
+ * The site's durable log. Machine events and telemetry each land in a
+ * JetStream stream; the gateway reads events through a durable consumer, so
+ * a restart or a link outage replays instead of losing.
+ */
+import { type ConsumerConfig, type JetStreamManager, type StreamConfig } from 'nats';
+import { type LineCodec } from '../protocol/codec';
+export declare const LINE_STREAM: {
+    readonly EVENTS: "LINE_EVENTS";
+    readonly TELEMETRY: "LINE_TELEMETRY";
+};
+/** What the streams need from a codec: its root, channels and topic layout. */
+export type StreamCodec = Pick<LineCodec, 'root' | 'channels' | 'topicFor'>;
+/** An MQTT filter as a NATS subject: levels become tokens, `+` becomes `*`, `#` becomes `>`. */
+export declare function filterToSubject(filter: string): string;
+/** The site's streams, for every line under the codec's root; a root alone means the generic layout. */
+export declare function lineStreamConfigs(codec: StreamCodec | string): Partial<StreamConfig>[];
+/** The telemetry subjects for one line, read live rather than replayed. */
+export declare function telemetrySubjects(codec: StreamCodec | string, siteId: string, lineId: string): string[];
+/**
+ * A durable consumer. It starts at new messages the first time (open rows
+ * are reconciled at boot); after that its position survives restarts.
+ */
+export declare function durableConsumer(name: string, filterSubjects: string[]): Partial<ConsumerConfig>;
+export declare function lineEventConsumer(codec: StreamCodec | string, siteId: string, lineId: string, name: string): Partial<ConsumerConfig>;
+/** Create or update each stream, then the consumer. Safe on every boot. */
+export declare function ensureStreams(jsm: JetStreamManager, streams: Partial<StreamConfig>[]): Promise<void>;
+export declare function ensureConsumer(jsm: JetStreamManager, stream: string, config: Partial<ConsumerConfig>): Promise<void>;

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

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * The site's durable log. Machine events and telemetry each land in a
+ * JetStream stream; the gateway reads events through a durable consumer, so
+ * a restart or a link outage replays instead of losing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LINE_STREAM = void 0;
+exports.filterToSubject = filterToSubject;
+exports.lineStreamConfigs = lineStreamConfigs;
+exports.telemetrySubjects = telemetrySubjects;
+exports.durableConsumer = durableConsumer;
+exports.lineEventConsumer = lineEventConsumer;
+exports.ensureStreams = ensureStreams;
+exports.ensureConsumer = ensureConsumer;
+const nats_1 = require("nats");
+const codec_1 = require("../protocol/codec");
+exports.LINE_STREAM = {
+    EVENTS: 'LINE_EVENTS',
+    TELEMETRY: 'LINE_TELEMETRY',
+};
+const DAY_MS = 86_400_000;
+const ACK_WAIT_MS = 30_000;
+const GENERIC = (root) => ({ root, channels: codec_1.GENERIC_CHANNELS });
+/** An MQTT filter as a NATS subject: levels become tokens, `+` becomes `*`, `#` becomes `>`. */
+function filterToSubject(filter) {
+    return filter.split('/').map((level) => (level === '+' ? '*' : level === '#' ? '>' : level)).join('.');
+}
+function subjectsFor(codec, channels, siteId, lineId) {
+    return channels.map((c) => filterToSubject((0, codec_1.topicOf)(codec, { siteId, lineId }, c)));
+}
+/** The site's streams, for every line under the codec's root; a root alone means the generic layout. */
+function lineStreamConfigs(codec) {
+    const c = typeof codec === 'string' ? GENERIC(codec) : codec;
+    return [
+        { name: exports.LINE_STREAM.EVENTS, subjects: subjectsFor(c, c.channels.events), max_age: (0, nats_1.nanos)(30 * DAY_MS), storage: nats_1.StorageType.File },
+        { name: exports.LINE_STREAM.TELEMETRY, subjects: subjectsFor(c, c.channels.telemetry), max_age: (0, nats_1.nanos)(3 * DAY_MS), storage: nats_1.StorageType.File },
+    ];
+}
+/** The telemetry subjects for one line, read live rather than replayed. */
+function telemetrySubjects(codec, siteId, lineId) {
+    const c = typeof codec === 'string' ? GENERIC(codec) : codec;
+    return subjectsFor(c, c.channels.telemetry, siteId, lineId);
+}
+/**
+ * A durable consumer. It starts at new messages the first time (open rows
+ * are reconciled at boot); after that its position survives restarts.
+ */
+function durableConsumer(name, filterSubjects) {
+    return {
+        durable_name: name,
+        ack_policy: nats_1.AckPolicy.Explicit,
+        deliver_policy: nats_1.DeliverPolicy.New,
+        ack_wait: (0, nats_1.nanos)(ACK_WAIT_MS),
+        filter_subjects: filterSubjects,
+    };
+}
+function lineEventConsumer(codec, siteId, lineId, name) {
+    const c = typeof codec === 'string' ? GENERIC(codec) : codec;
+    return durableConsumer(name, subjectsFor(c, c.channels.events, siteId, lineId));
+}
+/** Create or update each stream, then the consumer. Safe on every boot. */
+async function ensureStreams(jsm, streams) {
+    for (const config of streams) {
+        try {
+            await jsm.streams.info(config.name);
+            await jsm.streams.update(config.name, config);
+        }
+        catch (err) {
+            if (!/stream not found/i.test(err?.message ?? ''))
+                throw err;
+            await jsm.streams.add(config);
+        }
+    }
+}
+async function ensureConsumer(jsm, stream, config) {
+    let existing;
+    try {
+        existing = await jsm.consumers.info(stream, config.durable_name);
+    }
+    catch (err) {
+        if (!/consumer not found/i.test(err?.message ?? ''))
+            throw err;
+        await jsm.consumers.add(stream, config);
+        return;
+    }
+    // The consumer keeps its position; only its subjects follow the codec's channels.
+    const want = [...(config.filter_subjects ?? [])].sort();
+    const have = [...(existing.config.filter_subjects ?? [])].sort();
+    if (want.join('|') !== have.join('|'))
+        await jsm.consumers.update(stream, config.durable_name, { filter_subjects: config.filter_subjects });
+}

package/build/scripts/machine-line.d.ts

@@ -0,0 +1,33 @@
+/**
+ * machine-line: drive the machine line example end to end.
+ *
+ * Starts unit routes on the factory line and plays the people: at every
+ * station people work (and at the inspector, where every route ends) a
+ * person takes the units off the station before and receives them; a
+ * technician clears alarms; an operator decides each failed handoff. The
+ * machines and the gateway do the rest over MQTT. MIX sets the share of
+ * routes minted from the automated manifest; the rest run the manual one,
+ * through the same workflow. Rows are watched on Long Tail's NATS.
+ *
+ * Usage (after `docker compose -f docker-compose.yml -f docker-compose.nats.yml -f docker-compose.machines.yml up -d --build`):
+ *   npm run machine:line
+ *   MIX=50 UNITS=8 npm run machine:line          # half automated, half manual, same factory
+ *   UNITS=8 BATCH=2 npm run machine:line
+ *   FAULT=jam npm run machine:line               # first route jams leaving FAULT_AT; operator retries
+ *   FAULT=reject DECIDE=scrap npm run machine:line
+ *
+ * Env vars:
+ *   BASE_URL      Long Tail API (default http://localhost:3000)
+ *   SIM_URL       mock line drill server (default http://localhost:8090)
+ *   NATS_URL      Long Tail NATS (default nats://localhost:4222), NATS_TOKEN (default dev_api_secret)
+ *   UNITS         units to run (default 6); BATCH units per route (default 2)
+ *   MIX           percent of routes on the automated manifest (default 100); the rest run manual
+ *   MACHINE_LINE_CONFIG, MACHINE_MANIFESTS   line and manifests (default the factory line and route-manifests.json)
+ *   FAULT         jam | incomplete | carrier_mismatch | unreadable | stall | reject | hold | estop | offline
+ *   FAULT_AT      machine the fault happens at (default the first machine)
+ *   DECIDE        operator decision on a failed handoff: retry | manual | scrap (default retry;
+ *                 manual where the row does not offer retry)
+ *   OFFLINE_S     how long FAULT=offline keeps the machine away (default 25)
+ *   HANDOFF_TIMEOUT  per-handoff timeout (default 5m); TIMEOUT_S whole run (default 300)
+ */
+export {};