NATS Protocols

This section of the documentation contains the reference documentation for the NATS wire protocols including the following:

• Client - The protocol used between a client and server.
  • JetStream - The JSON API on top of the client protocol used for Streaming, Key-Value, and Object Store.
• Cluster - The protocol used between servers within a cluster.
• Gateway - The protocol used between two clusters.
• Leafnode - The protocol used between a server and a leafnode.

Structure

All NATS wire protocols are text-based and follow a standard structure.

Control Line with Optional Content

Each interaction between the client and server consists of a control, or protocol, line of text followed, optionally by message content. Most of the protocol messages don't require content, only PUB, MSG, HPUB, and HMSG include payloads.

Field Delimiters

The fields of NATS protocol messages are delimited by whitespace characters (space) or (tab). Multiple whitespace characters will be treated as a single field delimiter.

Newlines

NATS uses ␍ followed by ␊ (␍␊, 0x0D0A) to terminate protocol messages. This newline sequence is also used to mark the end of the message payload in PUB, MSG, HPUB, and HMSG protocol messages.

Subject names

Subject names, including reply subject names, are case-sensitive and must be non-empty alphanumeric strings with no embedded whitespace. All ascii alphanumeric characters except spaces/tabs and separators which are . and > are allowed. Subject names can be optionally token-delimited using the dot character (.), e.g.:

FOO, BAR, foo.bar, foo.BAR, FOO.BAR and FOO.BAR.BAZ are all valid subject names

FOO. BAR, foo. .bar andfoo..bar are not valid subject names

A subject is comprised of 1 or more tokens. Tokens are separated by . and can be any non space ascii alphanumeric character. The full wildcard token > is only valid as the last token and matches all tokens past that point. A token wildcard, * matches any token in the position it was listed. Wildcard tokens should only be used in a wildcard capacity and not part of a literal token.

Character Encoding

Subject names should be ascii characters for maximum interoperability. Due to language constraints and performance, some clients may support UTF-8 subject names, as may the server. No guarantees of non-ASCII support are provided.

Wildcards

NATS supports the use of wildcards in subject subscriptions.

• The asterisk character (*) matches a single token at any level of the subject.
• The greater than symbol (>), also known as the full wildcard, matches one or more tokens at the tail of a subject, and must be the last token. The wildcarded subject foo.> will match foo.bar or foo.bar.baz.1, but not foo.
• Wildcards must be a separate token (foo.*.baz or foo.> are syntactically valid; foo*.bar, f*o.b*r and foo> are not)

For example, the wildcard subscriptions foo.*.quux and foo.> both match foo.bar.quux, but only the latter matches foo.bar.baz. With the full wildcard, it is also possible to express interest in every subject that may exist in NATS: sub > 1, limited of course by authorization settings.