Skip to content

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 Fanout subscription is a plain NATS subscription. A Competing one is a queue subscription on the subscription's Group.
  • The subscription's Bound becomes 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 as Refused. 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.Request uses 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 finite MaxReconnects and the client gave up, or the session was closed.

JetStream

JetStream is bound to a stream and survives a restart. It has two paths:

  • AtMostOnce is core NATS on the same client. A subscriber that asks for nothing durable gets nothing durable: no consumer, no cursor and no replay.
  • AtLeastOnce is a durable pull consumer on the stream, named by the subscription's DurableName. 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.