Zum Inhalt springen
Deutsch

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),
},
});
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 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 aus subscriptions stammte.
  • Ein erneutes subscribe auf 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).

NATS nutzt mit . getrennte Subjects:

events.user.signup
events.user.delete
orders.priority.placed
metrics.gauge.cpu

Subjects sind case-sensitive; per Konvention kleinbuchstabig + punktgetrennt.

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

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.

Drei primäre Anwendungsfälle:

  1. Hochvolumiges Pub/Sub ohne die operative Komplexität von Kafka.
  2. Microservice-Request/Reply — synchrone Calls zwischen Services über Subjects.
  3. 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.

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

Terminal-Fenster
npm install @nats-io/transport-node
# oder: bun add @nats-io/transport-node

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