MQTT
MqttActor integriert mit MQTT-Brokern (Mosquitto, EMQ X, HiveMQ,
AWS IoT Core). Unterstützt sowohl MQTT 3.1.1 als auch 5; Topic-
Wildcards (+, #); QoS 0/1/2; Retained Messages.
Es ist das MQTT-Gegenstück zu
WebsocketClientActor: eine abstrakte
Basisklasse, von der du ableitest. Deklariere Subscriptions im
Konstruktor, verarbeite eingehenden Traffic in onMessage und publishe
mit this.publish(...). Von außen bleibt er per ref.tell(...)
steuerbar.
import { ActorSystem, ActorSystemOptions } from 'actor-ts';import { MqttActor, MqttOptions, type MqttOptionsBuilder, type MqttMessage } from 'actor-ts/io';
type Reading = { sensor: string; celsius: number };
const actorSystemOptions = ActorSystemOptions.create().withConfig({ 'actor-ts': { io: { broker: { mqtt: { 'broker-url': 'mqtt://localhost:1883' } } } }, });class TemperatureHub extends MqttActor<Reading> { constructor(options: MqttOptionsBuilder) { super(options.withQos(1).withClientId('temperature-hub')); this.subscribe('sensors/+/temp'); this.subscribe('alerts/#', { qos: 2 }); }
override onMessage(message: MqttMessage<Reading>): void { const { sensor, celsius } = message.payload.entity(); // via den Codec dekodiert this.log.info(`${sensor}: ${celsius}°C`); this.publish(`ack/${sensor}`, 'ok'); // roher String this.publish('rollup', { sensor, celsius }); // kodierte Entity }}
const system = ActorSystem.create('demo', actorSystemOptions);
system.spawn(() => new TemperatureHub(MqttOptions.create()), 'hub');T (hier Reading) typisiert das eingehende Payload —
message.payload.entity() liefert ein T zurück. Ein zweiter Generic,
TSelf, typisiert Anwendungsnachrichten, die andere Aktoren dem Ref
tellen können (siehe Externe Steuerung unten); Default ist never.
Diese überschreibst du in deiner Subklasse. onReceive und onCommand
sind versiegelt — die Basisklassen dispatchen an die Hooks unten;
überschreibe sie nicht.
| Hook | Wann |
|---|---|
onMessage(message) | Eine Nachricht traf auf einer eigenen Subscription dieses Aktors ein. Erforderlich. |
onConnected() | Die Verbindung wurde (neu) geöffnet; die Subscription-Registry ist beim Broker erneut angewendet. |
onDisconnected(cause?) | Die Verbindung brach ab; ein Reconnect-Zyklus kann folgen (gemäß Settings). |
onInvalidMessage(err, message) | onMessage warf einen MqttDecodeError (ein lazy entity() auf einem fehlerhaften Payload). Default: loggen + verwerfen. Erneut werfen zum Eskalieren. |
onSelfMessage(message) | Eine Anwendungsnachricht (TSelf) wurde diesem Ref getellt — oder etwas anderes, das keiner der eigenen Kinds des Aktors trifft, auch der Body eines entfernten Knotens. Default: ein Warn mit der Klasse der Nachricht (nie ihrem Payload), dann this.unhandled(message) — ein Dead Letter, der diesen Aktor nennt, gezählt in actor_unhandled_total{class}. |
onTerminated(signal) | Ein Aktor, den du mit context.watch beobachtest, hat gestoppt. Von BrokerActor geerbt; die Zustellziele, die dieser Aktor selbst beobachtet, sind bereits erledigt. |
Eingehende und Lifecycle-Ereignisse werden über die Mailbox zugestellt,
sodass onMessage und die Hooks stets auf dem Aktor-Thread laufen
(single-threaded, Reihenfolge pro Verbindung erhalten: connected →
Nachrichten → disconnected).
Konfiguration
Abschnitt betitelt „Konfiguration“Settings lösen mit der üblichen Präzedenz auf: Konstruktor / Builder >
HOCON (actor-ts.io.broker.mqtt) > eingebaute Defaults. Nutze den
Fluent-Builder MqttOptions oder übergib ein einfaches
Partial<MqttOptionsType>.
const options = MqttOptions.create() .withBrokerUrl('mqtts://mqtt.example.com:8883') .withClientId('my-app') .withCredentials(process.env.MQTT_USER, process.env.MQTT_PASS) .withQos(1) // Default-QoS für publish/subscribe .withProtocolVersion(5) // MQTT 5.0 aktivieren .withCleanSession(false) .withKeepAlive(30);interface MqttOptionsType extends BrokerCommonOptionsType { brokerUrl?: string; // mqtt:// mqtts:// ws:// wss:// clientId?: string; credentials?: { username?: string; password?: string }; qos?: 0 | 1 | 2; // Default-QoS für publish/subscribe cleanSession?: boolean; // Default true keepAlive?: number; // Sekunden; Default 60 protocolVersion?: 4 | 5; // Default 4 (= MQTT 3.1.1) codec?: MqttCodec<unknown>; // Default mqttJsonCodec() will?: { topic: string; payload: string | Uint8Array; qos?: 0 | 1 | 2; retain?: boolean }; tls?: TlsTransportOptionsType; // Cert-Material für mqtts:// / wss://; nur im Code}Unter actor-ts.io.broker.mqtt werden die mehrteiligen Feldnamen in
kebab-case geschrieben — broker-url, client-id, clean-session,
keep-alive, protocol-version —, und das HOCON-keep-alive ist eine
Dauer in ganzen Sekunden, der Einheit, in der MQTT es überträgt:
keep-alive = 30s ergibt 30. Ein Wert, der keine ganze Zahl von Sekunden
ist, wird beim Start abgelehnt, 1500ms ebenso wie ein nacktes 30, denn
HOCON liest eine nackte Zahl als Millisekunden; 0 schaltet keep-alive
weiterhin ab.
Häufige Muster:
withCleanSession(false)— die Session bleibt bestehen; der Broker liefert Nachrichten, die während der Trennung verpasst wurden (abhängig von der Broker-Konfiguration).withWill({ ... })— der Broker publisht das, wenn der Client unsauber die Verbindung verliert. Nützlich für Präsenz (“device-42-offline”).withProtocolVersion(5)— aktiviert MQTT-5-Features (User- Properties, Reason-Codes aufMqttMessage). Braucht einen v5-fähigen Broker.
Die Verbindung aus HOCON
Abschnitt betitelt „Die Verbindung aus HOCON“Die Blätter der Verbindung liegen ebenfalls unter actor-ts.io.broker.mqtt.
Dieses Beispiel nimmt jedes davon aus der Umgebung: Ein Blatt, dessen
Variable nicht gesetzt ist, bleibt ungesetzt, beim eingebauten Default, den
sein Kommentar nennt.
actor-ts.io.broker.mqtt { broker-url = ${?ACTOR_TS_MQTT_BROKER_URL} # mqtt:// mqtts:// ws:// wss://; required, here or in code client-id = ${?ACTOR_TS_MQTT_CLIENT_ID} credentials { username = ${?ACTOR_TS_MQTT_USERNAME} password = ${?ACTOR_TS_MQTT_PASSWORD} } qos = ${?ACTOR_TS_MQTT_QOS} # 0, 1 or 2; unset = 0 clean-session = ${?ACTOR_TS_MQTT_CLEAN_SESSION} # unset = true keep-alive = ${?ACTOR_TS_MQTT_KEEP_ALIVE} # whole seconds, such as 30s; unset = 60s protocol-version = ${?ACTOR_TS_MQTT_PROTOCOL_VERSION} # 4 (MQTT 3.1.1) or 5; unset = 4}Ein Wert aus der Umgebung wird zuerst als JSON gelesen, wo immer er sich als
JSON parsen lässt. ACTOR_TS_MQTT_KEEP_ALIVE=30 ist also die nackte Zahl 30,
die keep-alive als dreißig Millisekunden ablehnt — schreib 30s —, und eine
Client-ID oder ein Passwort, das sich wie eine Zahl liest, kommt in der
Schreibweise dieser Zahl zurück, 1e3 als 1000, 1.50 als 1.5 und eine
ganze Zahl jenseits von Number.MAX_SAFE_INTEGER womöglich mit anderen letzten
Ziffern (20261104123456789 als 20261104123456788); ein Wert, der sich wie
null, eine Liste oder ein Objekt liest, lässt den Start mit einem
ConfigError scheitern. Einen solchen Wert in der Variablen selbst quoten
(ACTOR_TS_MQTT_PASSWORD='"1e3"') oder im Code setzen.
Das Will aus HOCON
Abschnitt betitelt „Das Will aus HOCON“Das Last Will will eine Flotte üblicherweise pro Deployment setzen statt pro
Build, deshalb hat es einen eigenen Block unter actor-ts.io.broker.mqtt:
actor-ts.io.broker.mqtt { will { topic = "devices/42/status" payload = "offline" qos = 1 retain = true }}Zwei Dinge dazu.
payload ist hier ein String. Das Feld ist string | Uint8Array, und
eine Config-Datei hat keine Schreibweise für Bytes — ein binäres Will bleibt
also code-only. Ohne payload ist es das leere, was gültiges MQTT ist und
genau so ein Retained Will gelöscht wird — topic dagegen ist Pflicht, und
ein will-Block ohne eines wird beim Start abgelehnt, statt zum Broker zu
gehen und dort zu scheitern.
Der Block wird als Ganzes gelesen. withWill({ … }) im Code ersetzt das
konfigurierte Will vollständig, statt Blatt für Blatt damit zu mischen — das
ist die gewohnte Präzedenz (Konstruktor > HOCON > Defaults), angewendet auf
das Feld, das dieses Objekt ist.
Typisierte Payloads
Abschnitt betitelt „Typisierte Payloads“Eingehende MqttMessage<T> tragen ein lazy dekodierendes
MqttPayload<T>:
override onMessage(message: MqttMessage<Reading>): void { message.payload.bytes; // rohes Uint8Array message.payload.text(); // UTF-8-String (gecacht) message.payload.entity(); // dekodiertes T via den Codec (gecacht) message.payload.entity<Acknowledgment>(); // auf einem bestimmten Topic als anderen Typ dekodieren}Das Dekodieren ist lazy — es passiert erst, wenn du text() /
entity() aufrufst. Ein fehlerhaftes Payload lässt entity() einen
MqttDecodeError werfen; weil das innerhalb von onMessage geschieht,
fängt die Basisklasse ihn und leitet ihn an onInvalidMessage weiter
(Default: loggen + verwerfen, kein Neustart):
protected override onInvalidMessage(err: MqttDecodeError, message: MqttMessage<Reading>): void { this.log.warn(`bad payload on ${err.topic}: ${err.message}`);}Publishen
Abschnitt betitelt „Publishen“this.publish(topic, payload, options?) gibt false zurück, wenn die
Nachricht verworfen wurde (Encode-Fehler oder Überlauf des Outbound-
Puffers):
- ein
string- oderUint8Array-Payload wird roh gesendet; - jeder andere Wert wird via den Codec kodiert (Default JSON).
this.publish('ack/1', 'ok'); // rohe Bytes: okthis.publish('rollup', { sensor, celsius }); // JSON: {"sensor":...,"celsius":...}this.publish('cfg', data, { qos: 1, retain: true });Um einen nackten String als JSON-Entity zu publishen (die Wire-Bytes
"pong" statt pong), kodiere ihn explizit:
this.publish('topic', this.codec().encode('pong'));Der Codec wandelt Entities in Bytes und zurück. Default ist
mqttJsonCodec() (einfaches JSON über UTF-8). Übergib deinen eigenen
via withCodec(...) — z. B. einen JSON-Codec mit Laufzeit-Validierung:
import { mqttJsonCodec, MqttOptions } from 'actor-ts/io';
const codec = mqttJsonCodec<Reading>({ validate: (v) => ReadingSchema.parse(v), // zod usw.; wirft → MqttDecodeError});
MqttOptions.create().withBrokerUrl('mqtt://localhost:1883').withCodec(codec);Externe Steuerung
Abschnitt betitelt „Externe Steuerung“Über die Subklassen-API hinaus kann jeder Aktor einen MqttActor
steuern, indem er ihm ein MqttCommand tellt:
ref.tell({ kind: 'publish', publish: { topic: 't', payload: 'hi', qos: 1 } });
// Subscribe und an das eigene onMessage dieses Aktors routen (kein target):ref.tell({ kind: 'subscribe', topic: 'x/#', qos: 1 });
// Subscribe und an einen anderen Aktor fan-outen (externes target):ref.tell({ kind: 'subscribe', topic: 'y/#', target: someHandler });
ref.tell({ kind: 'unsubscribe', topic: 'y/#', target: someHandler });- Ein
subscribeohnetargetliefert passende Nachrichten an das eigeneonMessagedes Aktors; mittargetfan-outet es an jenen Aktor. Überlappende Patterns liefern an jedes Ref höchstens einmal. - Ein
unsubscribeentfernt nur, was ein externessubscribeangehängt hat: das Target, das es nennt, oder — ohnetarget— alle extern angehängten Targets auf einmal. Die eigeneonMessage-Zustellung des Aktors entfernt es nie, und ebensowenig ein Target, das die Subklasse selbst persubscribe(topic, { target })deklariert hat — auch dann nicht, wenn das Kommando genau dieses Target nennt. Ein externer Controller kann die im Konstruktor deklarierte Subscription der Subklasse nicht stummschalten, in welcher der beiden Formen sie auch deklariert wurde. Aus der Subklasse heraus entferntunsubscribe(topic, { target })jedes Target, egal wer es anhängte. - Das
qoseinessubscribegilt nur für ein Pattern, das das Kommando selbst anlegt. Nennt es ein bereits vorhandenes Pattern, hängt es sich mit dem dort registrierten QoS an; sein eigenesqoswird dabei ignoriert. Das ist das additive Gegenstück zur Regel darüber: Wer die Subscription der Subklasse nicht stummschalten kann, soll sie auch nicht unbemerkt herunterstufen können — eine mit QoS 0 neu ausgestellte QoS-2-Subscription ließe die Anwendung an Exactly-once-Zustellung glauben, während der Broker verwerfen darf. Um das QoS des eigenen Patterns zu ändern, ruf in der Subklassesubscribe(topic, { qos })auf. - Fan-out-Targets werden per Deathwatch beobachtet: stoppt ein Target- Aktor, wird er automatisch entfernt (und ein Broker-UNSUBSCRIBE feuert, sobald ein Pattern keine Konsumenten mehr hat).
- Ein externes
subscribe, das ein Filter einführt, das der Aktor noch nicht hielt, wird auf Info-Level geloggt — und ebenso eines, dessenqosdie Regel darüber aus einem bereits gehaltenen Filter heraushält: eine abgelehnte Anfrage ist für einen Betreiber so viel wert wie ein neues Filter, denn sonst sieht der Sender nur ein erfolgreiches Re-SUBSCRIBE. Ein bloßes Anhängen bleibt still: es führt weder ein Filter noch einen Konsumenten ein, den es nicht schon gab, und hat um nichts gebeten, was es nicht bekam. Ebenso das eigenesubscribe()der Subklasse, im Konstruktor wie zur Laufzeit. Umsonst ist ein Anhängen am Broker allerdings nicht — im verbundenen Zustand stellt es das SUBSCRIBE neu aus, und ein MQTT-Re-SUBSCRIBE spielt die Retained-Nachrichten des Filters an jeden Konsumenten dieses Patterns erneut aus.
Der erste Eintrag nennt das Filter, das QoS, das das SUBSCRIBE tatsächlich
trägt, und ob passende Nachrichten an das eigene onMessage des Aktors
gehen oder an einen anderen Aktor fan-outen; der zweite nennt das
angefragte QoS neben dem beibehaltenen:
MqttActor: external subscribe introduced broker filter 'tele/#' at QoS 1, delivering to actor 'actor-ts://sensors/user/mirror'MqttActor: external subscribe asked QoS 0 for filter 'own/#', which the actor already holds at QoS 2; kept QoS 2Das ist das Gegengewicht zur ersten Regel, keine Einschränkung davon. Einen
Handler an ein beliebiges Filter zu hängen, # eingeschlossen, bleibt offen,
weil es der Vertrag des Aktors ist und wer das Ref hält ohnehin überallhin
publishen kann — vertretbar ist das genau so lange, wie ein Betreiber es
sehen kann. Aus einer Nachricht wird nichts geloggt: der Eintrag beschreibt
eine Subscription, keinen Verkehr, damit aus einer Zeile pro neuem Filter nie
eine Zeile pro Payload wird. Das Filter wird vorher escaped und in der Länge
gekappt, denn es ist Text, den der Sender gewählt hat — ein Zeilenumbruch
darin würde sonst eine zweite Logzeile fälschen, die wie eine echte aussieht.
Wenn dein Topic-Schema ein Credential enthält (manche Broker legen einen
API-Key in den Pfad), beachte: es landet hier auf Info-Level im Log, genau so
wie bereits in den Warnungen dieses Aktors zu fehlgeschlagenem Subscribe und
nicht dekodierbarem Payload.
Damit ist der Besitz des Refs die Vertrauensgrenze — Cluster-Mitglieder
eingeschlossen. Ein gültiges Mitglied, das das Ref dieses Aktors hält, kann
sich auf alles subscriben, was der darunterliegende Client lesen darf, genau
wie ein lokaler Aktor; einen Trust-Hook pro Kommando gibt es nicht, und er
würde auch nicht helfen, weil die Capability am Ref hängt und nicht am
Kommando. Beachte dabei: das hier ist eine Lese-Capability, die
Publish-Regel daneben eine Schreib-Capability — in einen Topic-Baum
publishen zu können heißt nicht, alles lesen zu können, was der Broker
diesem Client ausliefert. „Es kann ohnehin publishen” erklärt also, warum
der Fan-out offen bleibt, nicht, warum Lesen harmlos wäre. Ein Feed, der
privat bleiben muss, darf seinen Aktor deshalb nicht bei der Receptionist
registrieren und sein Ref nicht über Knotengrenzen reichen. Gib diesem
Verkehr einen eigenen MqttActor, halte das Ref in dem Subsystem, dem es
gehört, und lass den extern steuerbaren die Topics tragen, deren Spiegelung
du in Kauf nimmst.
Da diese Kommandos einfache Objekte sind, halte ein selbst definiertes
TSelf von den kind-Werten publish / subscribe / unsubscribe
fern — sonst würde es als Kommando dispatcht, statt onSelfMessage zu
erreichen.
QoS-Level
Abschnitt betitelt „QoS-Level“| QoS | Zustellung | Kosten |
|---|---|---|
| 0 | At-most-once. Fire-and-Forget. | Am günstigsten; Nachrichten können verloren gehen. |
| 1 | At-least-once. Broker speichert bis ACK. | Default für die meisten Anwendungsfälle. Duplikate möglich. |
| 2 | Exactly-once. Voller Handshake. | Am langsamsten; selten nötig. |
Für IoT-Telemetrie ist QoS 1 die typische Balance. Befehle an Geräte: ebenfalls QoS 1 (oder QoS 2, falls Duplikate schädlich wären). Statusupdates, die schnell überholt werden (Sensorwerte): QoS 0 ist okay.
Topic-Wildcards
Abschnitt betitelt „Topic-Wildcards“this.subscribe('sensors/+/temp'); // passt zu sensors/dev1/temp, sensors/dev2/temp, ...this.subscribe('devices/#'); // passt zu devices/irgendwas/irgendwo/...| Wildcard | Trifft |
|---|---|
+ | Genau eine Ebene. |
# | Mehrere Ebenen (muss das letzte Segment sein). |
Retained Messages
Abschnitt betitelt „Retained Messages“this.publish('config/device-42', { mode: 'eco' }, { retain: true });Eine Retained Message wird vom Broker gespeichert und an jeden neuen
Subscriber sofort ausgeliefert. Verwende sie für Konfiguration (Geräte,
die beim Verbinden die aktuellste Config lesen) oder den letzten
bekannten Status. Lass retain bei normalem Pub/Sub weg — sonst hält
der Broker jede alte Nachricht für immer sichtbar.
Eine mqtts://- oder wss://-URL startet den Handshake, und mqtt.js
verifiziert den Broker per Default gegen den System-Trust-Store.
Hinter einer privaten CA oder für Client-Zertifikats-Auth kommt
withTls dazu:
const mqttOptions = MqttOptions.create() .withBrokerUrl('mqtts://mqtt.example.com:8883') .withTls({ ca: fs.readFileSync('./tls/ca.crt', 'utf8'), cert: fs.readFileSync('./tls/device.crt', 'utf8'), key: fs.readFileSync('./tls/device.key', 'utf8'), });Jedes Feld trägt das Material selbst, nie einen Pfad darauf —
deshalb liest das Beispiel die Dateien. cert und key ergeben nur
gemeinsam Sinn; eines ohne das andere wird beim Start des Actors
abgelehnt.
withTls konfiguriert den Handshake, statt einen zu starten — das
mqtts://- bzw. wss://-Schema bleibt also nötig. Einen Config-Key
hat es bewusst nicht: Ein Private Key gehört nicht in die
application.conf.
Peer-Dependency
Abschnitt betitelt „Peer-Dependency“npm install mqtt# oder: bun add mqttWann MQTT
Abschnitt betitelt „Wann MQTT“- IoT / Telemetrie — Geräte publishen Sensordaten und subscribieren Befehle.
- Brücken aus bestehender MQTT-Infrastruktur — wenn der Broker schon da ist.
- Leichtgewichtiges Pub/Sub — wenn Kafka Overkill ist (kleine Payloads, keine Replay-Historie nötig).
Für clusterinternes Pub/Sub ist DistributedPubSub einfacher (kein externer Broker).
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- I/O-Übersicht — das große Bild.
- BrokerActor-Basis — der gemeinsame Lifecycle.
- WebSocket-Client — dieselbe subclass-first Form.
- Kafka — für durables Streaming.
