Core NATS or JetStream¶
The adapter has two backends because Capabilities.SurvivesRestart is declared rather than discovered,
and core NATS and JetStream answer it differently. One backend with a flag would have to lie in one
position or the other. The capability tables say what each declares.
Core¶
Core is core NATS: volatile and at-most-once, the shape the core's in-memory backend was built to
mimic. A publish is written to the socket, and under SurvivesRestart: false a nil error means no more
than that. Nothing is stored and nothing is replayed.
- A
Fanoutsubscription is a plain NATS subscription. ACompetingone is a queue subscription on the subscription'sGroup. - The subscription's
Boundbecomes the NATS subscription's pending message limit. The channel the core reads is unbuffered, so a slow reader applies backpressure into that pending buffer, where NATS sheds under its own policy and the adapter counts what it shed asRefused. See what happens at a full queue. - It answers requests: a responder is a queue subscription answering on the message's reply subject,
and
Bus.Requestuses a reply inbox the session owns, so it can count a late reply as unclaimed. See Ask for an answer. - A dropped connection does not end a subscription. With the client's default of retrying for ever,
NATS restores the subscription when the server returns. A subscription ends only when the connection
reaches
CLOSED: the caller set a finiteMaxReconnectsand the client gave up, or the session was closed.
JetStream¶
JetStream is bound to a stream and survives a restart. It has two paths:
AtMostOnceis core NATS on the same client. A subscriber that asks for nothing durable gets nothing durable: no consumer, no cursor and no replay.AtLeastOnceis a durable pull consumer on the stream, named by the subscription'sDurableName. The attempt count is the server's. The lease starts when the message is received.
Every publish through a JetStream backend is a JetStream publish that waits for the server's
acknowledgement, whichever path a subscriber is on, so a nil error means the stream has the message.
That has a consequence: a subject no stream carries cannot be published to through this backend. The
stream must carry every subject the bus will publish to, including those only at-most-once subscribers
read.
A publish carries a deduplication ID (Nats-Msg-Id) derived from the event: the SHA-256 of its Source
and ID, joined by a NUL byte, in hexadecimal. A publish retried after a lost acknowledgement is stored
once within the stream's duplicate window.
JetStream does not declare RequestReply. Request and reply is the Core backend's alone.
Choosing¶
Use Core when a lost message is acceptable and you want request and reply. Use JetStream when a
message must outlive a restart of either side, or a new consumer must be able to read what came before.
A deployment can run both backends, one bus on each, against the same server. They share nothing but the server.
Source: core.go, session.go, jetstream.go, jetsession.go.