actor-ts 0.9.1 → 0.11.0

package/dist/io/broker/MqttActor.js

@@ -1,82 +1,369 @@
 import { match } from 'ts-pattern';
 import { ConfigKeys } from '../../config/ConfigKeys.js';
+import { Terminated } from '../../SystemMessages.js';
 import { Lazy } from '../../util/Lazy.js';
 import { lazyImportModule } from '../../util/LazyImport.js';
 import { BrokerActor } from './BrokerActor.js';
+import { mqttJsonCodec, MqttDecodeError } from './MqttCodec.js';
+import { MqttOptionsValidator } from './MqttOptions.js';
+import { MqttPayload, mqttConnectedSignal, mqttDisconnectedSignal, mqttInboundSignal, } from './MqttMessages.js';
 /**
- * MQTT 3.1.1 / 5.0 actor backed by the `mqtt` peer-dep.  Inbound
- * messages are routed to subscribers via the base class' fan-out;
- * wildcard subscriptions (`+`, `#`) are honoured on the broker side
- * and locally we deliver based on the *concrete* topic the message
- * was received on (matching Paho/mqtt.js semantics).
+ * Typed, subclass-first MQTT 3.1.1 / 5.0 actor backed by the `mqtt`
+ * peer-dep — the MQTT counterpart to `WebsocketClientActor`.  Extend it,
+ * declare subscriptions in the constructor, and handle inbound traffic
+ * in `onMessage`:
  *
- * The `subscriptions` setting wires up topic→actor mappings at
- * connect-time; runtime `tell({ kind: 'subscribe', ... })` adds more.
+ *     class MyClient extends MqttActor {
+ *       constructor(opts: MqttOptions) {
+ *         super(opts.withQos(1).withClientId('my-client'));
+ *         this.subscribe('some/thing/#');
+ *       }
+ *       override onMessage(msg: MqttMessage): void {
+ *         this.log.info(msg.payload.text());
+ *         this.publish(msg.topic, 'pong');
+ *       }
+ *     }
+ *
+ * `T` types the inbound payload (`msg.payload.entity(): T`); `TSelf`
+ * types application messages other actors may `tell` this ref (defaults
+ * to `never`).  It is still externally controllable: `ref.tell(cmd)`
+ * with a {@link MqttCommand} publishes / subscribes / unsubscribes; a
+ * `subscribe` command with no `target` routes to this actor's own
+ * `onMessage`, with a `target` fans out to that actor.
+ *
+ * Lifecycle events (inbound / connected / disconnected) are delivered
+ * through the mailbox, so `onMessage` and the hooks always run on the
+ * actor thread (single-threaded, per-connection order preserved).
  */
 export class MqttActor extends BrokerActor {
     client = null;
+    _codec = null;
+    /** False until `preStart` — before that `subscribe()` only records. */
+    _started = false;
+    /** Single source of truth: pattern → routing entry. */
+    registry = new Map();
+    /** Deathwatch bookkeeping: ref.path → its watched ref + the patterns it consumes. */
+    watched = new Map();
+    /** Subscriptions requested in the constructor, flushed in `preStart`. */
+    pendingSubs = [];
+    constructor(options = {}) {
+        super(options);
+    }
+    /** The connection (re)opened; the registry has been re-applied on the broker. */
+    onConnected() { }
+    /** The connection dropped; a reconnect cycle may follow (per options). */
+    onDisconnected(_cause) { }
+    /**
+     * `onMessage` threw an {@link MqttDecodeError} — typically from a lazy
+     * `payload.entity()` on a malformed payload.  Default: log + drop (bad
+     * wire data shouldn't restart the actor).  Rethrow to escalate to the
+     * supervisor.
+     */
+    onInvalidMessage(error, _msg) {
+        this.log.warn(`MqttActor: dropping undecodable payload on '${error.topic ?? '<unknown>'}': ${error.message}`);
+    }
+    /** App-level message told to this actor's ref (reachable only when TSelf ≠ never). */
+    onSelfMessage(msg) {
+        this.log.warn(`MqttActor: unhandled self message: ${String(msg)}`);
+    }
+    /* ----------------------- protected API ------------------------- */
+    /**
+     * Register a subscription.  Constructor-safe: before start it is only
+     * recorded (no context/options access) and flushed on first connect.
+     * At runtime it also issues a broker SUBSCRIBE when connected;
+     * otherwise the registry entry is applied on the next connect.  Omit
+     * `target` to deliver to this actor's own `onMessage`.
+     */
+    subscribe(topic, opts = {}) {
+        if (!this._started) {
+            this.pendingSubs.push({ topic, qos: opts.qos, target: opts.target });
+            return;
+        }
+        this.registerSubscription(topic, opts);
+    }
+    /**
+     * Remove a subscription.  With `target`, removes that foreign target;
+     * without, removes this actor's own `onMessage` delivery for `topic`.
+     * A broker UNSUBSCRIBE fires once the pattern has no consumers left.
+     */
+    unsubscribe(topic, opts = {}) {
+        this.removeSubscription(topic, opts.target, false);
+    }
+    publish(topic, payload, opts = {}) {
+        let bytes;
+        if (typeof payload === 'string' || payload instanceof Uint8Array) {
+            bytes = payload;
+        }
+        else {
+            try {
+                bytes = this.codec().encode(payload);
+            }
+            catch (err) {
+                this.log.error(`MqttActor: encode failed, dropping publish to '${topic}': ${err.message}`);
+                return false;
+            }
+        }
+        return this.enqueueOutbound({
+            topic,
+            payload: bytes,
+            qos: opts.qos,
+            retain: opts.retain,
+            userProperties: opts.userProperties,
+        });
+    }
+    /**
+     * The actor's payload codec (default {@link mqttJsonCodec}).  Exposed
+     * so subclasses can encode/decode explicitly — e.g. to publish a bare
+     * string as a JSON entity.  Only valid after `preStart`.
+     */
+    codec() {
+        return (this._codec ??= this.options.codec ?? mqttJsonCodec());
+    }
+    /* ----------------------- sealed dispatch ----------------------- */
+    /** @internal Sealed — override onMessage + hooks instead. */
+    onReceive(cmd) {
+        // Terminated is delivered through onReceive (ActorCell) but isn't part
+        // of the typed mailbox union — narrow via a guard.
+        if (isTerminated(cmd)) {
+            this.removeTerminatedTarget(cmd.actor);
+            return;
+        }
+        // Uniform `kind` dispatch over internal signals + external commands.
+        const kind = cmd.kind;
+        switch (kind) {
+            case 'mqtt-inbound': return this.routeInbound(cmd.message);
+            case 'mqtt-connected': return this.onConnected();
+            case 'mqtt-disconnected': return this.onDisconnected(cmd.cause);
+            case 'publish':
+            case 'subscribe':
+            case 'unsubscribe':
+                return this.handleCommand(cmd);
+            default:
+                return this.onSelfMessage(cmd);
+        }
+    }
+    handleCommand(cmd) {
+        // Exhaustive over MqttCommand — a new command variant forces a handler here.
+        match(cmd)
+            .with({ kind: 'publish' }, (command) => { this.enqueueOutbound(command.publish); })
+            .with({ kind: 'subscribe' }, (command) => {
+            this.registerSubscription(command.topic, { qos: command.qos, target: command.target });
+        })
+            .with({ kind: 'unsubscribe' }, (command) => {
+            this.removeSubscription(command.topic, command.target, true);
+        })
+            .exhaustive();
+    }
+    /* ----------------------- inbound routing ----------------------- */
+    async routeInbound(msg) {
+        let toSelf = false;
+        const seen = new Set();
+        for (const [pattern, entry] of this.registry) {
+            if (!matchesMqttPattern(pattern, msg.topic))
+                continue;
+            if (entry.deliverToSelf)
+                toSelf = true;
+            for (const ref of entry.targets) {
+                if (!seen.has(ref)) {
+                    seen.add(ref);
+                    ref.tell(msg);
+                }
+            }
+        }
+        if (!toSelf)
+            return;
+        try {
+            await this.onMessage(msg);
+        }
+        catch (err) {
+            if (err instanceof MqttDecodeError)
+                return this.onInvalidMessage(err, msg);
+            throw err; // ordinary supervision
+        }
+    }
+    /* ----------------------- subscription registry ----------------- */
+    registerSubscription(topic, opts) {
+        let entry = this.registry.get(topic);
+        if (!entry) {
+            entry = { qos: opts.qos, deliverToSelf: false, targets: new Set() };
+            this.registry.set(topic, entry);
+        }
+        else if (opts.qos !== undefined) {
+            entry.qos = opts.qos; // last-writer-wins when a QoS is given
+        }
+        if (opts.target) {
+            entry.targets.add(opts.target);
+            this.watchTarget(opts.target, topic);
+        }
+        else {
+            entry.deliverToSelf = true;
+        }
+        if (this.connectionState === 'connected' && this.client) {
+            this.brokerSubscribe(topic, entry.qos);
+        }
+    }
     /**
-     * topic-pattern → subscribers.  Patterns can be wildcard (`a/+/c`,
-     * `a/#`).  We test inbound topics against every pattern at delivery
-     * time — O(n) but n is small in practice (sub-100 patterns).
+     * @param fromExternal true for an external `unsubscribe` command with
+     *   no target — drops all foreign targets but keeps the actor's own
+     *   subscription (a controller must not be able to silence the
+     *   subclass's constructor-declared subscription).  false for the
+     *   protected `unsubscribe(topic)` — drops only the own delivery.
      */
-    patternSubs = new Map();
-    constructor(settings = {}) { super(settings); }
+    removeSubscription(topic, target, fromExternal) {
+        const entry = this.registry.get(topic);
+        if (!entry)
+            return;
+        if (target) {
+            entry.targets.delete(target);
+            this.unwatchTarget(target, topic);
+        }
+        else if (fromExternal) {
+            for (const ref of entry.targets)
+                this.unwatchTarget(ref, topic);
+            entry.targets.clear();
+        }
+        else {
+            entry.deliverToSelf = false;
+        }
+        if (!entry.deliverToSelf && entry.targets.size === 0) {
+            this.registry.delete(topic);
+            this.brokerUnsubscribe(topic);
+        }
+    }
+    removeTerminatedTarget(ref) {
+        const key = ref.path.toString();
+        const watchEntry = this.watched.get(key);
+        if (!watchEntry)
+            return;
+        // The cell already dropped the watch on Terminated delivery — just
+        // clean our own bookkeeping (no context.unwatch).
+        this.watched.delete(key);
+        for (const pattern of watchEntry.patterns) {
+            const entry = this.registry.get(pattern);
+            if (!entry)
+                continue;
+            for (const target of entry.targets) {
+                if (target.path.toString() === key) {
+                    entry.targets.delete(target);
+                    break;
+                }
+            }
+            if (!entry.deliverToSelf && entry.targets.size === 0) {
+                this.registry.delete(pattern);
+                this.brokerUnsubscribe(pattern);
+            }
+        }
+    }
+    watchTarget(ref, pattern) {
+        const key = ref.path.toString();
+        let watchEntry = this.watched.get(key);
+        if (!watchEntry) {
+            watchEntry = { ref, patterns: new Set() };
+            this.watched.set(key, watchEntry);
+            this.context.watch(ref);
+        }
+        watchEntry.patterns.add(pattern);
+    }
+    unwatchTarget(ref, pattern) {
+        const key = ref.path.toString();
+        const watchEntry = this.watched.get(key);
+        if (!watchEntry)
+            return;
+        watchEntry.patterns.delete(pattern);
+        if (watchEntry.patterns.size === 0) {
+            this.watched.delete(key);
+            this.context.unwatch(ref);
+        }
+    }
+    brokerSubscribe(topic, qos) {
+        this.client?.subscribe(topic, { qos: qos ?? this.options.qos ?? 0 }, (err) => {
+            if (err)
+                this.log.warn(`MqttActor: subscribe '${topic}' failed: ${err.message}`);
+        });
+    }
+    brokerUnsubscribe(topic) {
+        if (this.connectionState !== 'connected' || !this.client)
+            return;
+        this.client.unsubscribe(topic, undefined, (err) => {
+            if (err)
+                this.log.warn(`MqttActor: unsubscribe '${topic}' failed: ${err.message}`);
+        });
+    }
+    /* ----------------------- BrokerActor plumbing ------------------ */
+    async preStart() {
+        // Context is attached before preStart; options resolve inside
+        // super.preStart().  Flush constructor subscriptions into the
+        // registry (idempotent) so connectImplementation applies them on connect.
+        for (const pendingSub of this.pendingSubs) {
+            this.registerSubscription(pendingSub.topic, { qos: pendingSub.qos, target: pendingSub.target });
+        }
+        this._started = true;
+        await super.preStart();
+    }
     configKey() { return ConfigKeys.io.broker.mqtt; }
-    builtInDefaults() {
-        return { defaultQos: 0, cleanSession: true, keepAliveSec: 60 };
+    builtInDefaultOptions() {
+        return { qos: 0, cleanSession: true, keepAlive: 60 };
     }
-    readSettingsFromConfig(c) {
+    readOptionsFromConfig(config) {
         const out = {};
-        if (c.hasPath('brokerUrl'))
-            out.brokerUrl = c.getString('brokerUrl');
-        if (c.hasPath('clientId'))
-            out.clientId = c.getString('clientId');
-        if (c.hasPath('credentials')) {
-            const cc = c.getConfig('credentials');
+        if (config.hasPath('brokerUrl'))
+            out.brokerUrl = config.getString('brokerUrl');
+        if (config.hasPath('clientId'))
+            out.clientId = config.getString('clientId');
+        if (config.hasPath('credentials')) {
+            const cc = config.getConfig('credentials');
             out.credentials = {
                 username: cc.hasPath('username') ? cc.getString('username') : undefined,
                 password: cc.hasPath('password') ? cc.getString('password') : undefined,
             };
         }
-        if (c.hasPath('defaultQos'))
-            out.defaultQos = c.getInt('defaultQos');
-        if (c.hasPath('cleanSession'))
-            out.cleanSession = c.getBoolean('cleanSession');
-        if (c.hasPath('keepAliveSec'))
-            out.keepAliveSec = c.getInt('keepAliveSec');
-        if (c.hasPath('protocolVersion')) {
-            const v = c.getInt('protocolVersion');
-            if (v !== 4 && v !== 5) {
-                throw new Error(`MqttActor: protocolVersion must be 4 or 5, got ${v}`);
-            }
-            out.protocolVersion = v;
-        }
+        if (config.hasPath('qos'))
+            out.qos = config.getInt('qos');
+        if (config.hasPath('cleanSession'))
+            out.cleanSession = config.getBoolean('cleanSession');
+        if (config.hasPath('keepAlive'))
+            out.keepAlive = config.getInt('keepAlive');
+        // Value validation (protocolVersion ∈ {4,5}, etc.) is enforced uniformly
+        // by optionsValidator() on the merged options — see MqttOptionsValidator.
+        if (config.hasPath('protocolVersion'))
+            out.protocolVersion = config.getInt('protocolVersion');
         return out;
     }
-    requiredSettings() { return ['brokerUrl']; }
-    endpointLabel() { return this.settings.brokerUrl ?? '<unknown>'; }
-    async connectImpl() {
-        const mqtt = await mqttLazy.get();
+    requiredOptions() { return ['brokerUrl']; }
+    optionsValidator() { return new MqttOptionsValidator(); }
+    endpointLabel() { return this.options.brokerUrl ?? '<unknown>'; }
+    /** @internal Test seam — override to inject a fake mqtt module. */
+    mqttModule() { return mqttLazy.get(); }
+    async connectImplementation() {
+        const mqtt = await this.mqttModule();
         const opts = {
-            clientId: this.settings.clientId,
-            username: this.settings.credentials?.username,
-            password: this.settings.credentials?.password,
-            clean: this.settings.cleanSession,
-            keepalive: this.settings.keepAliveSec,
-            protocolVersion: this.settings.protocolVersion ?? 4,
+            clientId: this.options.clientId,
+            username: this.options.credentials?.username,
+            password: this.options.credentials?.password,
+            clean: this.options.cleanSession,
+            keepalive: this.options.keepAlive,
+            protocolVersion: this.options.protocolVersion ?? 4,
         };
-        if (this.settings.will) {
+        if (this.options.will) {
             opts.will = {
-                topic: this.settings.will.topic,
-                payload: this.settings.will.payload,
-                qos: this.settings.will.qos ?? 0,
-                retain: this.settings.will.retain ?? false,
+                topic: this.options.will.topic,
+                payload: this.options.will.payload,
+                qos: this.options.will.qos ?? 0,
+                retain: this.options.will.retain ?? false,
             };
         }
         return new Promise((resolve, reject) => {
-            const client = mqtt.connect(this.settings.brokerUrl, opts);
+            const client = mqtt.connect(this.options.brokerUrl, opts);
             let done = false;
+            let down = false;
+            // mqtt.js can fire 'error' then 'close' for one drop — collapse them.
+            const onDown = (cause) => {
+                if (down)
+                    return;
+                down = true;
+                this.self.tell(mqttDisconnectedSignal(cause));
+                this.handleConnectionLost(cause);
+            };
             client.once('connect', () => {
                 if (done)
                     return;
@@ -84,29 +371,26 @@ export class MqttActor extends BrokerActor {
                 client.removeAllListeners('error');
                 this.client = client;
                 client.on('message', (topic, payload, packet) => {
-                    // MQTT 5.0 v5 properties live under `packet.properties` per
-                    // mqtt-packet's shape; absent on 3.1.1.  We pass them
-                    // through verbatim so subscribers that care can read user-
-                    // properties / reasonCode straight off the inbound
-                    // message, and those that don't are unaffected.
-                    this.dispatchInbound({
-                        topic, payload,
+                    // No user code on the mqtt.js loop: wrap into a lazily-decoding
+                    // payload and hand the message to our own mailbox.
+                    this.self.tell(mqttInboundSignal({
+                        topic,
+                        payload: new MqttPayload(payload, this.codec(), topic),
                         qos: (packet?.qos ?? 0),
                         retain: packet?.retain ?? false,
                         userProperties: packet?.properties?.userProperties,
                         reasonCode: packet?.properties?.reasonCode,
-                    });
+                    }));
                 });
-                client.on('error', (e) => this.handleConnectionLost(e));
-                client.on('close', () => this.handleConnectionLost(new Error('mqtt connection closed')));
-                // Wire up initial subscriptions (and re-subscribe after reconnect).
-                for (const sub of this.settings.subscriptions ?? []) {
-                    this.patternSubscribe(sub.topic, sub.target);
-                    client.subscribe(sub.topic, { qos: sub.qos ?? this.settings.defaultQos ?? 0 }, (err) => {
-                        if (err)
-                            this.log.warn(`MqttActor: initial subscribe to '${sub.topic}' failed: ${err.message}`);
-                    });
+                client.on('error', (e) => onDown(e));
+                client.on('close', () => onDown(new Error('mqtt connection closed')));
+                // (Re)apply the whole registry on every (re)connect — this is
+                // what makes runtime subscriptions survive reconnects and
+                // subscribe-while-disconnected land on the broker.
+                for (const [pattern, entry] of this.registry) {
+                    this.brokerSubscribe(pattern, entry.qos);
                 }
+                this.self.tell(mqttConnectedSignal());
                 resolve();
             });
             client.once('error', (e) => {
@@ -121,107 +405,49 @@ export class MqttActor extends BrokerActor {
             });
         });
     }
-    async disconnectImpl() {
+    async disconnectImplementation() {
         if (!this.client)
             return;
-        const c = this.client;
+        const client = this.client;
         this.client = null;
         return new Promise((resolve) => {
-            c.removeAllListeners();
-            c.end(false, {}, () => resolve());
+            client.removeAllListeners();
+            client.end(false, {}, () => resolve());
             setTimeout(resolve, 1_000);
         });
     }
     async dispatchOutgoing(env) {
         if (!this.client)
             throw new Error('MqttActor: not connected');
-        const p = env.payload;
-        const qos = p.qos ?? this.settings.defaultQos ?? 0;
-        const retain = p.retain ?? false;
-        const protocolVersion = this.settings.protocolVersion ?? 4;
+        const payload = env.payload;
+        const qos = payload.qos ?? this.options.qos ?? 0;
+        const retain = payload.retain ?? false;
+        const protocolVersion = this.options.protocolVersion ?? 4;
         const opts = { qos, retain };
-        // User properties only carry on MQTT 5.0 — silently drop them
-        // on 3.1.1 (the wire format has no slot for them).  Same
-        // pattern mqtt.js follows when the option mismatches the
-        // negotiated protocol version.
-        const properties = buildPublishProperties(p, protocolVersion);
+        const properties = buildPublishProperties(payload, protocolVersion);
         if (properties)
             opts.properties = properties;
         return new Promise((resolve, reject) => {
-            this.client.publish(p.topic, p.payload, opts, (err) => {
+            this.client.publish(payload.topic, payload.payload, opts, (err) => {
                 err ? reject(err) : resolve();
             });
         });
     }
-    onReceive(cmd) {
-        // Compile-time exhaustiveness: adding a new MqttCmd variant
-        // forces this site to handle it explicitly.
-        match(cmd)
-            .with({ kind: 'publish' }, (c) => {
-            this.enqueueOutbound(c.publish);
-        })
-            .with({ kind: 'subscribe' }, (c) => {
-            this.patternSubscribe(c.topic, c.target);
-            // If already connected, register on the broker too.  Reconnect
-            // re-runs the initial subscriptions; runtime additions persist
-            // only via the local pattern map — we don't try to "remember"
-            // them across reconnect (caller can re-tell after `BrokerConnected`).
-            if (this.connectionState === 'connected' && this.client) {
-                this.client.subscribe(c.topic, { qos: c.qos ?? this.settings.defaultQos ?? 0 }, (err) => { if (err)
-                    this.log.warn(`MqttActor: subscribe '${c.topic}' failed: ${err.message}`); });
-            }
-        })
-            .with({ kind: 'unsubscribe' }, (c) => {
-            if (c.target)
-                this.patternUnsubscribe(c.topic, c.target);
-            else
-                this.patternSubs.delete(c.topic);
-            if (this.connectionState === 'connected' && this.client) {
-                this.client.unsubscribe(c.topic, undefined, (err) => {
-                    if (err)
-                        this.log.warn(`MqttActor: unsubscribe '${c.topic}' failed: ${err.message}`);
-                });
-            }
-        })
-            .exhaustive();
-    }
-    /* ----------------------------- internals ------------------------------ */
-    patternSubscribe(pattern, ref) {
-        let set = this.patternSubs.get(pattern);
-        if (!set) {
-            set = new Set();
-            this.patternSubs.set(pattern, set);
-        }
-        set.add(ref);
-    }
-    patternUnsubscribe(pattern, ref) {
-        const set = this.patternSubs.get(pattern);
-        if (!set)
-            return;
-        set.delete(ref);
-        if (set.size === 0)
-            this.patternSubs.delete(pattern);
-    }
-    dispatchInbound(msg) {
-        for (const [pattern, subs] of this.patternSubs) {
-            if (matchesMqttPattern(pattern, msg.topic)) {
-                for (const ref of subs)
-                    ref.tell(msg);
-            }
-        }
-    }
+}
+/* --------------------------- helpers ---------------------------- */
+/** Terminated arrives via onReceive but isn't in the typed mailbox union. */
+function isTerminated(message) {
+    return message instanceof Terminated;
 }
 /* --------------------------- MQTT 5.0 helpers -------------------------- */
 /**
  * Build the mqtt-packet `properties` object for an outbound publish,
  * or `undefined` if there's nothing v5-specific to attach.  Pure
- * function — testable without a real broker or mqtt.js install
- * (see `tests/unit/io/broker/MqttActor.test.ts`).
+ * function — testable without a real broker or mqtt.js install.
  *
  * `protocolVersion < 5` always returns undefined: the 3.1.1 wire
- * format has no slot for user properties, so we drop them rather
- * than letting them leak into the publish callsite and confuse
- * downstream tooling.
+ * format has no slot for user properties, so we drop them rather than
+ * letting them leak into the publish callsite.
  */
 export function buildPublishProperties(p, protocolVersion) {
     if (protocolVersion < 5)
@@ -239,14 +465,14 @@ export function matchesMqttPattern(pattern, topic) {
     const ps = pattern.split('/');
     const ts = topic.split('/');
     for (let i = 0; i < ps.length; i++) {
-        const p = ps[i];
-        if (p === '#')
+        const patternSegment = ps[i];
+        if (patternSegment === '#')
             return true;
         if (i >= ts.length)
             return false;
-        if (p === '+')
+        if (patternSegment === '+')
             continue;
-        if (p !== ts[i])
+        if (patternSegment !== ts[i])
             return false;
     }
     return ps.length === ts.length;