Skip to main content

Subjects

Core NATS delivers a message to every subscription whose subject matches at the moment it arrives, to one member of a queue group, and stores nothing.

One publish to orders.eu.created: the server copies it to each matching subscription and to one member of a queue groupQueue group billingPublisherorders.eu.createdNATS servermatches thesubject againsteverysubscriptionit holds noworders.eu.createdthe same subjectorders.*.created* is one tokenorders.>> is the restorders.us.*no matchorders.*.createdmember 1 gets itorders.*.createdmember 2 does notA message no subscription matches is dropped:Core NATS stores nothing
The diagram as text
  1. Queue group billing: orders.*.created member 1 gets it; orders.*.created member 2 does not
  2. Publisher orders.eu.created → NATS server matches the subject against every subscription it holds now: publish
  3. NATS server matches the subject against every subscription it holds now → orders.eu.created the same subject
  4. NATS server matches the subject against every subscription it holds now → orders.*.created * is one token
  5. NATS server matches the subject against every subscription it holds now → orders.> > is the rest
  6. NATS server matches the subject against every subscription it holds now → orders.*.created member 1 gets it
  7. orders.us.* no match
  8. A message no subscription matches is dropped: Core NATS stores nothing

A subject is a string of tokens separated by dots. A subscription subject may hold wildcards. * stands for exactly one token. > stands for one or more tokens and comes last. A publish always names a full subject, without wildcards.

The server copies a message to each subscription that matches it. A subscription that joins later never sees it, and a message nothing matches is gone. That is at-most-once delivery: the server keeps nothing and settles nothing.

A queue group shares the work. The server hands each message to one member of the group, and a subscription outside the group still gets its own copy. The group is identified by its name alone, so members subscribed to different subjects under one name form one group.

A request is a publish that names a reply subject, an inbox the requester subscribed to first. The responder publishes the answer there. A request that no subscription matches gets an immediate "no responders" answer, so the requester does not wait for its timeout.

A message carries headers since NATS 2.2. A header name is printable ASCII without a colon, and a value is a single line. The server refuses a message over its payload limit, 1 MiB by default.

The model is the NATS server's own (subjects, publish-subscribe, queue groups, request-reply). How a stream keeps messages is on Streams, and how a consumer reads them on Consumers.