NATS Frequently Asked Questions
- What is the difference between Request() and Publish()?
- Can multiple subscribers receive a Request?
- How can I monitor my NATS cluster?
- Does NATS do queuing? Does NATS do load balancing?
- Can I list the subjects that exist in my NATS cluster?
- Does NATS support subject wildcards?
- What do ‘verbose’ and ‘pedantic’ mean when using CONNECT?
- Does NATS offer any guarantee of message ordering?
- Is there a message size limitation in NATS?
- Does NATS impose any limits on the # of subjects?
- Does NATS guarantee message delivery?
- Does NATS support replay/redelivery of historical data?
- How do I gracefully shut down an asynchronous subscriber?
- How do I create subjects?
NATS is an open source, lightweight, high-performance cloud native infrastructure messaging system. It implements a highly scalable and elegant publish-subscribe (pub/sub) distribution model. The performant nature of NATS make it an ideal base for building modern, reliable, scalable cloud native distributed systems.
NATS is offered in two interoperable modules: the core NATS platform (referred to simply as “NATS” throughout this site), and NATS Streaming, an event streaming service that can be employed to add event streaming, delivery guarantees, and historical data replay to NATS.
NATS was created by Derek Collison, who has over 20 years designing, building, and using publish-subscribe messaging systems. NATS is sponsored and maintained by Apcera.
The NATS server (
gnatsd) is written in Go. There is client support for a wide variety of languages. Please see the Download page for more info.
NATS is sponsored and supported by Apcera, the trusted application platform company founded by Derek Collison. The Apcera team maintain the NATS server, as well as the Go, Ruby, Node.js, C, C#, Java and several other client libraries. Our very active user community also contributes client libraries for several other implementation languages. Please see the download page for the complete list, and links to the relevant source repositories and documentation.
Please see the Download page for the latest list of Apcera- and community-sponsored NATS clients.
Publish() sends a message to
gnatsd with a subject as its address, and
gnatsd delivers the message to any interested/eligible subscriber of that subject. Optionally, you may also send along a reply subject with your message, which provides a way for subscribers who have received your message(s) to send messages back to you.
Request() is simply a convenience API that does this for you in a pseudo-synchronous fashion, using a timeout supplied by you. It creates an INBOX (a type of subject that is unique to the requestor), subscribes to it, then publishes your request message with the reply address set to the inbox subject. It will then wait for a response, or the timeout period to elapse, whichever comes first.
Yes. NATS is a publish and subscribe system that also has distributed queueing functionality on a per subscriber basis. When you publish a message, for instance at the beginning of a request, every subscriber will receive the message. If subscribers form a queue group, only one subscriber will be picked at random to receive the message. However, note that the requestor does not know or control this information. What the requestor does control is that it only wants one answer to the request, and NATS handles this very well by actively pruning the interest graph.
There are several options available, thanks to the active NATS community:
nats-top is a top-like monitoring tool developed by Wally Quevedo of Apcera.
natsboard is a monitoring tool developed by Fatih Cetinkaya.
nats-mon is a monitoring tool developed by Raül Pérez and Adrià Cidre.
A more detailed overview of monitoring is available under Server Monitoring.
The term ‘queueing’ implies different things in different contexts, so we must be careful with its use. NATS implements non-persistent distributed queuing via subscriber queue groups. Subscriber queue groups offer a form of message-distribution load balancing. Subject subscriptions in NATS may be either ‘individual’ subscriptions or queue group subscriptions. The choice to join a queue group is made when the subscription is created, by supplying an optional queue group name. For individual subject subscribers,
gnatsd will attempt to deliver a copy of every message published to that subject to every eligible subscriber of that subject. For subscribers in a queue group,
gnatsd will attempt to deliver each successive message to exactly one subscriber in the group, chosen at random.
This form of distributed queueing is done in real time, and messages are not persisted to secondary storage. Further, the distribution is based on interest graphs (subscriptions), so it is not a publisher operation, but instead is controlled entirely by
NATS maintains and constantly updates the interest graph (subjects and their subscribers) in real time. Do not think of it as a “directory” that is aggregated over time. The interest graph dynamic, and will change constantly as publishers and subscribers come and go.
If you are determined to gather this information, it can be indirectly derived at any instant in time by polling the monitoring endpoint for /connz and /routez. See Server Monitoring for more information.
Yes. The valid wildcards are as follows:
The dot character
'.' is the token separator.
The asterisk character
'*' is a token wildcard match.
e.g foo.* matches foo.bar, foo.baz, but not foo.bar.baz.
The greater-than symbol
'>' is a full wildcard match.
e.g. foo.> matches foo.bar, foo.baz, foo.bar.baz, foo.bar.1, etc.
‘Verbose’ means all protocol commands will be acked with a +OK or -ERR. If verbose is off, you don’t get the +OK for each command. Pedantic means the server does lots of extra checking, mostly around properly formed subjects, etc. Verbose mode is ON by default for new connections; most client implementations disable verbose mode by default in their INFO handshake during connection.
NATS implements source ordered delivery per publisher. That is to say, messages from a given single publisher will be delivered to all eligible subscribers in the order in which they were originally published. There are no guarantees of message delivery order amongst multiple publishers.
NATS does have a message size limitation that is enforced by the server and communicated to the client during connection setup. Currently, the limit is 1MB.
The maximum number of subjects is currently 2^32 (i.e. the max value of Go’s uint32 type). This may change in the future. The current implementation (which predates some native Go data structures) is a custom Hashmap. We will eventually move to native Go data structures as we test and verify relative performance.
NATS is offered as two components: the basic platform (referred to simply as “NATS”) and NATS Streaming, which is a data streaming service based on NATS.
NATS implements what is commonly referred to as “at-most-once” delivery. This means that messages are guaranteed to arrive intact, in order from a given publisher, but not across different publishers. NATS does everything required to remain on and provide a dial-tone. However, if a subscriber is problematic or goes offline it will not receive messages, as the basic NATS platform is a simple pub-sub transport system that offers only TCP reliability.
NATS Streaming offers at-least-once delivery guarantees by implementing publish and delivery acknowledgements, and persisting messages to memory or a secondary store until messages have been successfully delivered, or until resource limits or other administrator-defined limits have been reached.
Yes, historical data may be persisted to memory or secondary storage and replayed using NATS Streaming, an event streaming service based on (and compatible with) NATS.
To gracefully shutdown an asynchronous subscriber so that any outstanding MsgHandlers have a chance to complete outstanding work, call sub.Unsubscribe(). There is a Go routine per subscription. These will be cleaned up on Unsubscribe(), or upon connection teardown.
Subjects are created and pruned (deleted) dynamically based on interest (subscriptions). This means that a subject does not exist in a NATS cluster until a client subscribes to it, and the subject goes away after the last subscribing client unsubscribes from that subject.