NATS JetStream
このコンテンツはまだ日本語訳がありません。
JetStreamActor integrates with NATS JetStream — the durable
streaming layer on top of core NATS. Where NatsActor
is fire-and-forget pub/sub, JetStreamActor gives you persistent
streams, replay, and explicit acknowledgment with Kafka-style
“exactly-once-with-processing” semantics via the
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 },});The consumer forwards every message to target and waits for an
explicit ack before the ack-window (ackWaitMs) expires — if none
arrives, the server redelivers:
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, }); } }}Settings
Section titled “Settings”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}The builder is the primary style; a plain object works too. Common
broker fields — withReconnect, withCircuitBreaker,
withOutboundBuffer — come from the shared
BrokerActor base. servers is required.
tls carries the certificate material — a private CA to trust,
or a client certificate for mTLS — never a path to it. NATS has no
tls:// URL scheme, so setting it is also what asks nats.js to
negotiate TLS. It is identical to
NatsOptions.withTls, and like it has no config key:
a private key does not belong in application.conf.
Stream config
Section titled “Stream config”Set stream when the actor should create or update the stream at
connect time (create defaults to true).
| Field | Meaning |
|---|---|
name | Stream name (required). |
subjects | Subjects captured by the stream, e.g. ['orders.>'] (required). |
retention | 'limits' (default), 'interest', or 'workqueue'. |
storage | 'file' (durable) or 'memory'. |
maxMessages / maxBytes | Retention caps. -1 means no limit. |
maxAge | Max age in nanoseconds (passed through verbatim). 0 means no limit. |
create | Create/update the stream at connect time. Default true. |
The “no limit” spellings are NATS’s own and are not symmetric: the two
count caps take -1, maxAge takes 0 — a nanosecond span, where a negative
value would mean nothing. They pass through to the server verbatim. Any
other non-positive value is refused at startup, so -2 stays the typo it is.
Consumer config
Section titled “Consumer config”Set consumer to bind a durable subscription.
| Field | Meaning |
|---|---|
durable | Durable consumer name (required — survives restarts). |
mode | 'push' (default) or 'pull' (see below). |
deliverPolicy | 'all' (default), 'last', 'new', { kind: 'by-start-sequence', startSeq }, or { kind: 'by-start-time', startTimeMs }. |
ackPolicy | 'explicit' (default — ack/nak/term required), 'none', or 'all'. |
ackWaitMs | Time before the server redelivers without an ack. Default 30_000. |
filterSubject | Subject filter — defaults to all subjects in the stream. |
maxAcknowledgmentPending | Max in-flight unacked messages. Default 1024; -1 means no limit. |
create | Create/update the consumer at connect time. Default true. |
ackWaitMs has no such spelling — NATS reads a zero ack-wait as “use the
server default”, which is what leaving the field unset already says — so it
must be positive.
Both groups, from HOCON
Section titled “Both groups, from HOCON”Which stream an actor owns and which durable it binds is deployment shape, not
application logic, so both groups are readable under
actor-ts.io.broker.jetstream — as are the connection, the way the
NATS page spells it, and the ack-wait ceiling:
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 also takes its two parameterised forms, as an object. The
kind keeps its TypeScript spelling because it is a value that lands in the
union unchanged, and that spelling is kebab-case like every value a HOCON key
takes:
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}An unrecognised kind is refused at startup rather than quietly falling back
to all, which would replay a whole stream on a typo. That holds for an
object built in code as well, where a cast or plain JavaScript can hand over
any kind: it is refused at startup with an OptionsError naming the kinds
there are — or, for a retired spelling, the one that replaced it.
The start value is checked at startup too, so a consumer the server would
refuse at connect, and the reconnect loop would retry for ever, fails before
it gets there, naming the field. start-seq (startSeq) is a positive
integer up to Number.MAX_SAFE_INTEGER: stream sequences start at 1, and past
that bound a number no longer holds every integer, so the sequence sent would
not always be the one written. start-time (startTimeMs) is an instant in
epoch milliseconds from 0 up to 253402300799999, which is
9999-12-31T23:59:59.999Z: the server reads it as an RFC 3339 time, whose year
has four digits, and an epoch in microseconds mistaken for milliseconds lands
far past that.
Both groups are read whole: withStream({ … }) / withConsumer({ … }) in
code replace the configured block rather than merging into it, which is the
ordinary precedence (constructor > HOCON > defaults) applied at the field each
object is. name + subjects and durable are required, and a block
missing one is refused at start, naming the leaf.
target has no config key — an ActorRef names a live actor in this process,
which a config file cannot denote. Neither has tls, which carries the
certificate material itself.
Commands
Section titled “Commands”JetStreamActor accepts a JetStreamCommand (discriminated on kind):
kind | Fields | Purpose |
|---|---|---|
publish | publish: JetStreamPublish | Publish a message (see idempotent publish). |
acknowledgment | ackToken | Ack a delivered message — the server marks it consumed. |
negativeAcknowledgment | ackToken, delayMs? | Redeliver (optionally after delayMs). |
terminate | ackToken, reason? | Terminal failure — server drops the message permanently. |
inProgress | ackToken | Heartbeat — extend the ack-wait window for a long handler. |
fetch | batch, expiresMs? | Pull mode only — request up to batch messages. |
Every inbound JetStreamMessage carries subject, payload
(Uint8Array), replyTo, streamSequence, consumerSequence, deliveries
(delivery count — 1 on first try), ackToken, timestamp, and
headers.
The ack handshake
Section titled “The ack handshake”With the default ackPolicy: 'explicit', every delivered message must
be resolved with exactly one of acknowledgment, negativeAcknowledgment,
or terminate, keyed by ackToken:
acknowledgment— processing succeeded; the server advances the consumer.negativeAcknowledgment— retry; the server redelivers (afterdelayMsif given).terminate— give up permanently; the server will not redeliver.inProgress— not terminal; resets the ack-wait timer so a slow handler isn’t redelivered mid-flight.
ackToken is an opaque number the actor mints per delivery and hands
you on the message. It is deliberately not streamSequence: a stream sequence
identifies the message, and JetStream reuses it verbatim on every
redelivery (only consumerSequence and deliveries move). Two deliveries of
one message can be in flight at once — routinely so in pull mode, where
fetch batches overlap — and only ackToken tells them apart. Never send
it back to the broker or persist it: it means nothing outside the actor
instance that issued it, and it does not survive a reconnect.
Set ackPolicy: 'none' for pure fire-and-hose delivery where no ack is
expected. Messages still carry an ackToken in that mode, but the token
names nothing: the actor registers no delivery, so every
acknowledgment / negativeAcknowledgment / terminate / inProgress
naming it is ignored. A consumer that settles defensively is not doing
anything wrong — the drop is reported at debug there, not at warn.
A settle command that misses in any other mode is reported at warn,
by all four commands, naming the command and the token: the delivery it
addressed already timed out, was settled, or predates a reconnect, so the
message will be redelivered and reprocessed.
A connection loss settles every in-flight delivery locally. Each one is
failed, nak’d best-effort so the server redelivers it, and its ack-timeout
disarmed — the reconnect then starts from an empty pending map, and any
settle command still travelling for a pre-disconnect delivery misses (see
above). The loss is one warn naming how many deliveries were in
flight; the per-delivery detail goes to debug, because a flapping
connection on a consumer with maxAcknowledgmentPending in the hundreds
would otherwise write hundreds of warnings per flap. An ack-timeout stays
at warn: that one names a single handler that did not answer in time.
Push vs pull consumers
Section titled “Push vs pull consumers”- Push (default) — the server streams messages; the actor’s
internal pump fans each one to
targetand waits per-message for the ack handshake. The natural fit for actor-style fan-out. - Pull (
mode: 'pull') — the application self-paces by sending{ kind: 'fetch', batch, expiresMs }. Each fetch delivers up tobatchmessages (returning early afterexpiresMs, default5_000); every message still goes through the same ack handshake. Fits slow/bursty consumers better than push fan-out.
Fetches overlap, by design. A fetch command returns the mailbox turn
immediately, so a second fetch is served while the first batch’s acks are
still outstanding — it has to be, because those acks arrive as mailbox
messages and a fetch that held its turn open would deadlock on them.
Pipelining fetches is therefore supported, and it is why a delivery is
addressed by ackToken rather than by streamSequence.
Idempotent publish
Section titled “Idempotent publish”JetStreamPublish supports JetStream’s server-side dedup and
optimistic concurrency:
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) },});Peer dependency
Section titled “Peer dependency”npm install @nats-io/transport-node @nats-io/jetstream# or: bun add @nats-io/transport-node @nats-io/jetstreamTwo packages since nats.js v3: the transport connects, and
@nats-io/jetstream carries the streams, consumers and their
acknowledgments.
Where to next
Section titled “Where to next”- JetStream KV + Object Store — the bucket sub-APIs.
- NATS — core (non-durable) pub/sub + request-reply.
- Kafka — heavier durable streaming at massive scale.
- BrokerActor base — the shared reconnect / buffer / circuit-breaker lifecycle.
- I/O overview — the bigger picture.
