NATS
NatsActor integriert mit NATS — dem leichtgewichtigen Pub/Sub-
Broker. Core-NATS ist Fire-and-Forget ohne Durability; für
durable Streams siehe die JetStream-Variante.
import { ActorSystem } from 'actor-ts';import { NatsActor, NatsOptions } from 'actor-ts/io';
const natsOptions = NatsOptions.create() .withServers(['nats://nats-1:4222', 'nats://nats-2:4222']) .withName('my-app');const nats = system.spawn( () => new NatsActor( natsOptions, ), 'nats',);
// Subscribieren (Wildcards unterstützt):nats.tell({ kind: 'subscribe', subject: 'events.>', target: eventHandler,});
// Publishen:nats.tell({ kind: 'publish', publish: { subject: 'events.user.signup', payload: JSON.stringify(event), },});Settings
Abschnitt betitelt „Settings“interface NatsOptionsType extends BrokerCommonOptionsType { servers: string[] | string; name?: string; // Client-Identifier user?: string; password?: string; token?: string; subscriptions?: { subject: string; target: ActorRef<NatsMessage> }[]; // beim Connect eingerichtet tls?: TlsTransportOptionsType; // Cert-Material; aktiviert TLS; nur im Code}Dieselben Settings kommen auch aus HOCON, unter actor-ts.io.broker.nats,
unterhalb expliziter Optionen und oberhalb der eingebauten Defaults:
actor-ts.io.broker.nats { servers = ["nats://nats-1:4222", "nats://nats-2:4222"] # a list, even for one server name = "my-app" user = "my-app" password = ${?ACTOR_TS_NATS_PASSWORD} # token = ${?ACTOR_TS_NATS_TOKEN} # instead of user and password}Ein Wert aus der Umgebung wird zuerst als JSON gelesen, wo immer er sich als
JSON parsen lässt. Ein Passwort oder Token, 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) —, und eines, das
sich wie null, eine Liste oder ein Objekt liest, lässt den Start mit einem
ConfigError scheitern; ein schlichtes 12345 bleibt unverändert.
Einen solchen Wert in der Variablen selbst quoten
(ACTOR_TS_NATS_PASSWORD='"1e3"') oder im Code setzen.
Benutzer und Passwort in einem servers-Eintrag
(nats://user:secret@nats-1:4222) sind keine Zugangsdaten: nats.js
schickt sie nie mit, und sie können dazu führen, dass es Host oder Port des
Eintrags falsch liest. Der Actor lehnt einen solchen Eintrag beim Start ab —
der NATS-Actor wie die drei JetStream-Actors — und maskiert die Zugangsdaten
in der Ablehnung. Zugangsdaten gehören in user und password oder in
token. subscriptions und tls haben kein Blatt — das eine benennt
Actors, das andere ist Zertifikatsmaterial. Die Reconnect-,
Circuit-Breaker- und Outbound-Buffer-Blätter, die sich alle Broker teilen,
gehören unter denselben Root — siehe
BrokerActor-Basis.
Subscriptions und Reconnects
Abschnitt betitelt „Subscriptions und Reconnects“subscriptions und das subscribe-Kommando zur Laufzeit speisen dieselbe
gewünschte Menge, die von der
BrokerActor-Basisklasse
gehalten wird und nicht von der Verbindung. Praktische Folgen:
- Jede Subscription — konfiguriert oder zur Laufzeit hinzugefügt — wird nach einem Reconnect auf der neuen Verbindung neu gesetzt.
- Ein
subscribe, das gesendet wird während der Actor getrennt ist, wird beim nächsten Connect angewandt statt verworfen. { kind: 'unsubscribe', subject }entfernt das Subject endgültig: es kommt beim nächsten Reconnect nicht zurück, auch nicht wenn es aussubscriptionsstammte.- Ein erneutes
subscribeauf einem lebenden Subject tauscht dessen Target — die vorherige Subscription wird zuerst abgebaut, es empfängt also genau ein Actor.
// Zur Laufzeit hinzugefügt; nach einem Broker-Neustart weiterhin da.nats.tell({ kind: 'subscribe', subject: 'audit.>', target: auditor });// Dasselbe Subject auf einen anderen Actor lenken.nats.tell({ kind: 'subscribe', subject: 'audit.>', target: newAuditor });// Endgültig weg.nats.tell({ kind: 'unsubscribe', subject: 'audit.>' });Das betrifft die Subscription, nicht die Nachrichten: Core-NATS hat keine Durability, alles was während der Trennung publiziert wurde ist weiterhin verloren (siehe den Warnhinweis unten).
Subjects (NATS-Topics)
Abschnitt betitelt „Subjects (NATS-Topics)“NATS nutzt mit . getrennte Subjects:
events.user.signupevents.user.deleteorders.priority.placedmetrics.gauge.cpuSubjects sind case-sensitive; per Konvention kleinbuchstabig + punktgetrennt.
Wildcards
Abschnitt betitelt „Wildcards“| Wildcard | Trifft |
|---|---|
* | Genau ein Token (trifft user in events.user.signup). |
> | Ein oder mehr Tokens (trifft user.signup in events.user.signup). |
'events.>' → events.user.signup, events.user.delete, events.order.placed'events.*.signup' → events.user.signup, events.admin.signup> darf nur als letztes Token vorkommen.
Request / Reply
Abschnitt betitelt „Request / Reply“Core-NATS modelliert Request/Reply über ein Reply-Subject: Der
Requester publisht mit einem replyTo-Subject und hört darauf; der
Responder schickt seine Antwort dorthin. Es gibt kein dediziertes
request-Command — du setzt es aus publish / subscribe und dem
replyTo-Feld zusammen.
// Requester — auf einem privaten Reply-Subject hören, dann den// Request mit `replyTo` darauf zeigend publishen:nats.tell({ kind: 'subscribe', subject: 'reply.balance.42', target: replyHandler });nats.tell({ kind: 'publish', publish: { subject: 'account.balance', payload: JSON.stringify({ accountId: '42' }), replyTo: 'reply.balance.42', // Responder antwortet auf diesem Subject },});
// Responder — das Request-Subject subscriben, auf `replyTo` antworten:class BalanceService extends Actor<NatsMessage> { constructor(private readonly nats: ActorRef<NatsCommand>) { super(); } override onReceive(message: NatsMessage): void { if (!message.replyTo) return; this.nats.tell({ kind: 'publish', publish: { subject: message.replyTo, payload: JSON.stringify({ balance: 100 }), }, }); }}Eingehende NatsMessages tragen subject, payload (ein
Uint8Array) und replyTo (ein leerer String, wenn der Publisher
keins gesetzt hat). Das ist das “RPC über NATS”-Muster — ein paar
hundert Mikrosekunden Round-Trip auf localhost.
NATS hat kein tls://-URL-Schema, deshalb erledigt withTls hier
beides: Es bringt nats.js dazu, TLS auszuhandeln, und sagt, was der
Handshake vertrauen soll. mTLS ist die übliche Produktions-Haltung:
const natsOptions = NatsOptions.create() .withServers(['nats://nats.example.com:4222']) .withTls({ ca: fs.readFileSync('./tls/ca.crt', 'utf8'), cert: fs.readFileSync('./tls/client.crt', 'utf8'), key: fs.readFileSync('./tls/client.key', 'utf8'), });new NatsActor(natsOptions);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. Ohne withTls ist die Verbindung Klartext, sofern der
Server TLS nicht erzwingt — dann verifiziert nats.js ihn gegen den
System-Trust-Store.
JetStreamActor nimmt dieselbe Option. Beide haben bewusst keinen
Config-Key: Ein Private Key gehört nicht in die application.conf.
Wann NATS
Abschnitt betitelt „Wann NATS“Drei primäre Anwendungsfälle:
- Hochvolumiges Pub/Sub ohne die operative Komplexität von Kafka.
- Microservice-Request/Reply — synchrone Calls zwischen Services über Subjects.
- Leichtgewichtige Event-Verteilung — Fire-and-Forget- Benachrichtigungen, Metriken, Log-Streams.
Für durable Streams (Replay, Historie, ACK-Semantik) siehe JetStream unten. Für clusterinternes Pub/Sub ist DistributedPubSub einfacher.
JetStream
Abschnitt betitelt „JetStream“Für NATS mit Durability nimm JetStreamActor:
import { JetStreamActor, JetStreamOptions } from 'actor-ts/io';
const jetStreamOptions = JetStreamOptions.create() .withServers(['nats://nats-1:4222']) .withStream({ name: 'ORDERS', subjects: ['orders.>'], storage: 'file', maxAge: 86_400 * 7 * 1_000_000_000, // 7 Tage (maxAge ist in Nanosekunden) });const js = system.spawn( () => new JetStreamActor( jetStreamOptions, ), 'js',);JetStream-Schichten:
- Stream — durables Log, Subjects → Records.
- Consumer — Lese-Cursor; mehrere Consumer können denselben Stream unabhängig lesen.
- ACK-Semantik — wie bei AMQP acken Consumer jede Nachricht.
Nimm JetStream, wenn du brauchst:
- Replay — Consumer können zu beliebigen Offsets zurückspulen.
- Persistenz — überlebt Broker-Neustarts (dateibasierter Storage).
- Geordneter Konsum pro Subject.
Kafka schlägt JetStream weiterhin bei massiver Skalierung (Milliarden Events/s über Hunderte Partitionen). JetStream ist der Sweet Spot für “weniger als Kafka, mehr als Core-NATS”.
Peer-Dependency
Abschnitt betitelt „Peer-Dependency“npm install @nats-io/transport-node# oder: bun add @nats-io/transport-nodenats.js v3 teilt das frühere Einzelpaket nats auf: der Transport trägt
Core-NATS, JetStream, Key-Value und Object-Store bringen je ein eigenes Paket
mit. Installiere nur, was du nutzt — Core-NATS braucht allein die erste Zeile.
Wohin als Nächstes
Abschnitt betitelt „Wohin als Nächstes“- I/O-Übersicht — das große Bild.
- BrokerActor-Basis — der gemeinsame Lifecycle.
- Kafka — schwereres durables Streaming.
- MQTT — IoT-fokussierte Alternative.
- DistributedPubSub — für clusterinternes Pub/Sub.
