Zum Inhalt springen
Deutsch

NATS JetStream

JetStreamActor integriert NATS JetStream — die dauerhafte Streaming-Schicht über Core-NATS. Wo NatsActor Fire-and-forget-Pub/Sub ist, liefert JetStreamActor persistente Streams, Replay und explizite Bestätigung mit Kafka-artiger „exactly-once-with-processing”-Semantik über den acknowledgment / negativeAcknowledgment / terminate-Handshake.

import { ActorSystem, Actor } from 'actor-ts';
import { JetStreamActor, JetStreamOptions } from 'actor-ts/io';
import type { ActorRef } from 'actor-ts';
import type { JetStreamMessage, JetStreamCommand } from 'actor-ts/io';
const jetStreamOptions = JetStreamOptions.create()
.withServers(['nats://localhost:4222'])
.withStream({ name: 'ORDERS', subjects: ['orders.>'] })
.withConsumer({ durable: 'order-processor', ackWaitMs: 30_000 })
.withTarget(orderProcessor);
const jetStream = system.spawn(
() => new JetStreamActor(
jetStreamOptions,
),
'orders-stream',
);
// Publish (idempotent when messageId is set):
jetStream.tell({
kind: 'publish',
publish: {
subject: 'orders.created',
payload: JSON.stringify(order),
messageId: order.id, // server dedupes within the stream's dedup window
},
});

Der Consumer leitet jede Nachricht an target weiter und wartet auf eine explizite Bestätigung, bevor das Ack-Fenster (ackWaitMs) abläuft — kommt keine, stellt der Server erneut zu:

class OrderProcessor extends Actor<JetStreamMessage> {
constructor(private readonly jetStream: ActorRef<JetStreamCommand>) { super(); }
async onReceive(message: JetStreamMessage): Promise<void> {
try {
await db.insertOrder(JSON.parse(new TextDecoder().decode(message.payload)));
this.jetStream.tell({ kind: 'acknowledgment', ackToken: message.ackToken });
} catch {
// redeliver after 5 s
this.jetStream.tell({
kind: 'negativeAcknowledgment',
ackToken: message.ackToken,
delayMs: 5_000,
});
}
}
}
interface JetStreamOptionsType extends BrokerCommonOptionsType {
servers?: string[] | string; // NATS server URLs
token?: string;
user?: string;
password?: string;
name?: string; // client identifier
tls?: TlsTransportOptionsType; // cert material; also enables TLS; code-only
stream?: JetStreamStreamConfig; // set when this actor owns the stream
consumer?: JetStreamConsumerConfig; // required to start a subscription
target?: ActorRef<JetStreamMessage>; // receives every consumed message
acknowledgmentTimeout?: number; // ack-wait ceiling; default consumer.ackWaitMs ?? 30_000
}

Der Builder ist der primäre Stil; ein einfaches Objekt funktioniert ebenso. Gemeinsame Broker-Felder — withReconnect, withCircuitBreaker, withOutboundBuffer — stammen aus der BrokerActor-Basis. servers ist erforderlich.

tls trägt das Zertifikats-Material — eine private CA, der vertraut werden soll, oder ein Client-Zertifikat für mTLS —, nie einen Pfad darauf. NATS hat kein tls://-URL-Schema, deshalb bringt das Setzen dieser Option nats.js zugleich dazu, TLS auszuhandeln. Sie ist identisch zu NatsOptions.withTls und hat wie diese keinen Config-Key: Ein Private Key gehört nicht in die application.conf.

Setze stream, wenn der Actor den Stream beim Verbinden anlegen oder aktualisieren soll (create ist standardmäßig true).

FeldBedeutung
nameStream-Name (erforderlich).
subjectsVom Stream erfasste Subjects, z. B. ['orders.>'] (erforderlich).
retention'limits' (Default), 'interest' oder 'workqueue'.
storage'file' (dauerhaft) oder 'memory'.
maxMessages / maxBytesAufbewahrungs-Obergrenzen. -1 bedeutet keine Grenze.
maxAgeMax. Alter in Nanosekunden (unverändert durchgereicht). 0 bedeutet keine Grenze.
createStream beim Verbinden anlegen/aktualisieren. Default true.

Die Schreibweisen für „keine Grenze“ stammen von NATS selbst und sind nicht symmetrisch: die beiden Mengen-Obergrenzen nehmen -1, maxAge nimmt 0 — es ist eine Nanosekunden-Spanne, bei der ein negativer Wert nichts bedeuten würde. Sie werden unverändert an den Server durchgereicht. Jeder andere nicht positive Wert wird beim Start abgelehnt, -2 bleibt also der Tippfehler, der er ist.

Setze consumer, um eine dauerhafte Subscription zu binden.

FeldBedeutung
durableDauerhafter Consumer-Name (erforderlich — übersteht Neustarts).
mode'push' (Default) oder 'pull' (siehe unten).
deliverPolicy'all' (Default), 'last', 'new', { kind: 'by-start-sequence', startSeq } oder { kind: 'by-start-time', startTimeMs }.
ackPolicy'explicit' (Default — ack/nak/term erforderlich), 'none' oder 'all'.
ackWaitMsZeit, bevor der Server ohne Ack erneut zustellt. Default 30_000.
filterSubjectSubject-Filter — standardmäßig alle Subjects des Streams.
maxAcknowledgmentPendingMax. unbestätigte Nachrichten in Flight. Default 1024; -1 bedeutet keine Grenze.
createConsumer beim Verbinden anlegen/aktualisieren. Default true.

ackWaitMs hat keine solche Schreibweise — NATS liest ein Ack-Wait von null als „Server-Default verwenden“, und genau das sagt bereits ein nicht gesetztes Feld — der Wert muss also positiv sein.

Welchen Stream ein Actor besitzt und welches Durable er bindet, ist Deployment-Gestalt und keine Anwendungslogik — beide Gruppen sind deshalb unter actor-ts.io.broker.jetstream lesbar, ebenso die Verbindung, so geschrieben wie auf der NATS-Seite, und die Ack-Wait-Obergrenze:

actor-ts.io.broker.jetstream {
servers = ["nats://nats-1:4222", "nats://nats-2:4222"] # a list, even for one server
name = "billing"
user = "billing"
password = ${?ACTOR_TS_NATS_PASSWORD}
# token = ${?ACTOR_TS_NATS_TOKEN} # instead of user and password
acknowledgment-timeout = 45s
stream {
name = "BILLING"
subjects = ["billing.>"]
retention = "workqueue"
storage = "file"
max-messages = 1000000
max-bytes = 8M
max-age = 3600000000000 # NANOseconds, passed through verbatim
create = true
}
consumer {
durable = "billing-proc"
mode = "push"
deliver-policy = "all"
ack-policy = "explicit"
ack-wait = 30s
filter-subject = "billing.charges"
max-acknowledgment-pending = 1024
create = true
}
}

deliver-policy nimmt auch seine beiden parametrisierten Formen, als Objekt. Das kind behält seine TypeScript-Schreibweise, weil es ein Wert ist, der unverändert in der Union landet — und diese Schreibweise ist kebab-case, wie jeder Wert, den ein HOCON-Schlüssel annimmt:

consumer {
durable = "billing-proc"
deliver-policy { kind = "by-start-sequence", start-seq = 4242 }
# deliver-policy { kind = "by-start-time", start-time = 1767225600000 } # or this; epoch ms
}

Ein unbekanntes kind wird beim Start abgelehnt, statt still auf all zurückzufallen — das würde bei einem Tippfehler einen ganzen Stream erneut zustellen. Das gilt ebenso für ein im Code gebautes Objekt, dem ein Cast oder reines JavaScript jedes beliebige kind mitgeben kann: Es wird beim Start mit einem OptionsError abgelehnt, der die vorhandenen Kinds nennt — oder, bei einer abgelösten Schreibweise, diejenige, die sie ersetzt hat.

Auch der Startwert wird beim Start geprüft, sodass ein Consumer, den der Server beim Connect ablehnen und die Reconnect-Schleife endlos wiederholen würde, schon vorher scheitert und das Feld nennt. start-seq (startSeq) ist eine positive Ganzzahl bis Number.MAX_SAFE_INTEGER: Stream-Sequenzen beginnen bei 1, und jenseits dieser Grenze hält eine Zahl nicht mehr jede Ganzzahl, die gesendete Sequenz wäre also nicht immer die geschriebene. start-time (startTimeMs) ist ein Zeitpunkt in Epoch-Millisekunden von 0 bis 253402300799999, also 9999-12-31T23:59:59.999Z: Der Server liest ihn als RFC-3339-Zeit, deren Jahr vier Stellen hat, und eine Epoch in Mikrosekunden, für Millisekunden gehalten, landet weit dahinter.

Beide Gruppen werden als Ganzes gelesen: withStream({ … }) / withConsumer({ … }) im Code ersetzen den konfigurierten Block, statt sich hineinzumischen — die gewohnte Präzedenz (Konstruktor > HOCON > Defaults), angewendet auf das Feld, das das jeweilige Objekt ist. name + subjects sowie durable sind Pflicht; ein Block ohne eines wird beim Start abgelehnt und benennt das Blatt.

target hat keinen Config-Key — eine ActorRef benennt einen lebenden Actor in diesem Prozess, und den kann eine Config-Datei nicht bezeichnen. tls ebenso wenig: es trägt das Zertifikatsmaterial selbst.

JetStreamActor akzeptiert einen JetStreamCommand (diskriminiert über kind):

kindFelderZweck
publishpublish: JetStreamPublishNachricht publizieren (siehe idempotentes Publish).
acknowledgmentackTokenZugestellte Nachricht bestätigen — Server markiert sie als konsumiert.
negativeAcknowledgmentackToken, delayMs?Erneut zustellen (optional nach delayMs).
terminateackToken, reason?Endgültiger Fehler — Server verwirft die Nachricht dauerhaft.
inProgressackTokenHeartbeat — verlängert das Ack-Fenster für einen langen Handler.
fetchbatch, expiresMs?Nur Pull-Modus — bis zu batch Nachrichten anfordern.

Jede eingehende JetStreamMessage trägt subject, payload (Uint8Array), replyTo, streamSequence, consumerSequence, deliveries (Zustellungszähler — 1 beim ersten Versuch), ackToken, timestamp und headers.

Mit dem Default ackPolicy: 'explicit' muss jede zugestellte Nachricht mit genau einem von acknowledgment, negativeAcknowledgment oder terminate aufgelöst werden, adressiert über ackToken:

  • acknowledgment — Verarbeitung erfolgreich; der Server rückt den Consumer vor.
  • negativeAcknowledgment — erneut versuchen; der Server stellt erneut zu (nach delayMs, falls angegeben).
  • terminate — endgültig aufgeben; keine erneute Zustellung.
  • inProgress — nicht terminal; setzt den Ack-Wait-Timer zurück, damit ein langsamer Handler nicht mitten in der Arbeit erneut zugestellt wird.

ackToken ist eine opake Zahl, die der Actor pro Zustellung vergibt und mit der Nachricht ausliefert. Es ist bewusst nicht streamSequence: Die Stream-Sequenz identifiziert die Nachricht, und JetStream verwendet sie bei jeder erneuten Zustellung unverändert weiter (nur consumerSequence und deliveries bewegen sich). Zwei Zustellungen einer Nachricht können gleichzeitig in Flight sein — im Pull-Modus regelmäßig, weil sich Fetch-Batches überlappen —, und nur ackToken unterscheidet sie. Sende es nie an den Broker zurück und persistiere es nicht: Außerhalb der Actor-Instanz, die es vergeben hat, bedeutet es nichts, und es übersteht keinen Reconnect.

Setze ackPolicy: 'none' für reine Fire-and-Hose-Zustellung ohne erwartetes Ack. Nachrichten tragen auch in diesem Modus ein ackToken, aber das Token benennt nichts: Der Actor registriert keine Zustellung, also wird jedes acknowledgment / negativeAcknowledgment / terminate / inProgress darauf ignoriert. Ein Consumer, der vorsorglich quittiert, macht dabei nichts falsch — der Drop wird hier auf debug gemeldet, nicht auf warn.

Ein Settle-Befehl, der in einem anderen Modus ins Leere läuft, wird auf warn gemeldet, bei allen vier Befehlen, mit Nennung des Befehls und des Tokens: Die adressierte Zustellung ist bereits abgelaufen, wurde bereits aufgelöst oder stammt von vor einem Reconnect — die Nachricht wird also erneut zugestellt und erneut verarbeitet.

Ein Verbindungsverlust löst jede laufende Zustellung lokal auf. Jede wird fehlgeschlagen, best-effort nak’t, damit der Server sie erneut zustellt, und ihr Ack-Timeout wird entschärft — der Reconnect startet also mit leerer Pending-Map, und ein Settle-Befehl, der noch für eine Zustellung von vor dem Verbindungsverlust unterwegs ist, läuft ins Leere (siehe oben). Der Verlust ist eine warn-Zeile, die nennt, wie viele Zustellungen in Flight waren; das Detail pro Zustellung geht auf debug, denn eine flatternde Verbindung würde bei einem Consumer mit maxAcknowledgmentPending im dreistelligen Bereich sonst Hunderte Warnungen pro Flattern schreiben. Ein Ack-Timeout bleibt auf warn: Das benennt einen einzelnen Handler, der nicht rechtzeitig geantwortet hat.

  • Push (Default) — der Server streamt Nachrichten; die interne Pumpe des Actors verteilt jede an target und wartet pro Nachricht auf den Ack-Handshake. Der natürliche Fit für Actor-artiges Fan-out.
  • Pull (mode: 'pull') — die Anwendung bestimmt das Tempo selbst, indem sie { kind: 'fetch', batch, expiresMs } sendet. Jedes Fetch liefert bis zu batch Nachrichten (kehrt nach expiresMs früher zurück, Default 5_000); jede Nachricht durchläuft weiterhin denselben Ack-Handshake. Passt besser zu langsamen/schubweisen Consumern als Push-Fan-out.

Fetches überlappen sich — so gewollt. Ein fetch-Befehl gibt den Mailbox-Turn sofort zurück, sodass ein zweites fetch bedient wird, während die Acks des ersten Batches noch ausstehen — und das muss so sein, denn diese Acks treffen selbst als Mailbox-Nachrichten ein, und ein fetch, das seinen Turn offen hielte, liefe darauf in einen Deadlock. Fetches zu pipelinen ist deshalb unterstützt, und genau darum wird eine Zustellung über ackToken adressiert und nicht über streamSequence.

JetStreamPublish unterstützt JetStreams serverseitige Deduplizierung und optimistische Nebenläufigkeit:

jetStream.tell({
kind: 'publish',
publish: {
subject: 'orders.created',
payload: JSON.stringify(order),
messageId: order.id, // sent as Nats-Msg-Id — dedupes re-publishes in the stream's window
expectedLastSequence: lastSequence, // server rejects the publish if the stream head moved (optimistic concurrency)
},
});
Terminal-Fenster
npm install @nats-io/transport-node @nats-io/jetstream
# or: bun add @nats-io/transport-node @nats-io/jetstream

Seit nats.js v3 sind es zwei Pakete: der Transport verbindet, @nats-io/jetstream trägt Streams, Consumer und deren Acknowledgments.