Zum Inhalt springen
Deutsch

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.

HookWann
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).

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 auf MqttMessage). Braucht einen v5-fähigen Broker.

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 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.

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}`);
}

this.publish(topic, payload, options?) gibt false zurück, wenn die Nachricht verworfen wurde (Encode-Fehler oder Überlauf des Outbound- Puffers):

  • ein string- oder Uint8Array-Payload wird roh gesendet;
  • jeder andere Wert wird via den Codec kodiert (Default JSON).
this.publish('ack/1', 'ok'); // rohe Bytes: ok
this.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);

Ü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 subscribe ohne target liefert passende Nachrichten an das eigene onMessage des Aktors; mit target fan-outet es an jenen Aktor. Überlappende Patterns liefern an jedes Ref höchstens einmal.
  • Ein unsubscribe entfernt nur, was ein externes subscribe angehängt hat: das Target, das es nennt, oder — ohne target — alle extern angehängten Targets auf einmal. Die eigene onMessage-Zustellung des Aktors entfernt es nie, und ebensowenig ein Target, das die Subklasse selbst per subscribe(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 entfernt unsubscribe(topic, { target }) jedes Target, egal wer es anhängte.
  • Das qos eines subscribe gilt 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 eigenes qos wird 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 Subklasse subscribe(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, dessen qos die 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 eigene subscribe() 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 2

Das 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.

QoSZustellungKosten
0At-most-once. Fire-and-Forget.Am günstigsten; Nachrichten können verloren gehen.
1At-least-once. Broker speichert bis ACK.Default für die meisten Anwendungsfälle. Duplikate möglich.
2Exactly-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.

this.subscribe('sensors/+/temp'); // passt zu sensors/dev1/temp, sensors/dev2/temp, ...
this.subscribe('devices/#'); // passt zu devices/irgendwas/irgendwo/...
WildcardTrifft
+Genau eine Ebene.
#Mehrere Ebenen (muss das letzte Segment sein).
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.

Terminal-Fenster
npm install mqtt
# oder: bun add mqtt
  1. IoT / Telemetrie — Geräte publishen Sensordaten und subscribieren Befehle.
  2. Brücken aus bestehender MQTT-Infrastruktur — wenn der Broker schon da ist.
  3. 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).