GitBook: [master] 326 pages and 16 assets modified

concepts/acks.md

@@ -0,0 +1,8 @@
+# Acknowledgements
+
+In a system with at-most-once semantics, there are times when messages can be lost. If your application is doing request-reply it should use timeouts to handle any network or application failures. It is always a good idea to place a timeout on a requests and have code that deals with timeouts. When you are publishing an event or data stream, one way to ensure message delivery is to turn it into a request-reply with the concept of an acknowledgement message, or ACKs. In NATS an ACK can simply be an empty message, a message with no payload.
+
+![](../.gitbook/assets/acks.svg)
+
+Because the ACK can be empty it can take up very little network bandwidth, but the idea of the ACK turns a simple fire-and-forget into a fire-and-know world where the sender can be sure that the message was received by the other side, or with a [scatter-gather pattern](reqreply.md), several other sides.
+

concepts/intro.md

@@ -0,0 +1,10 @@
+# What is NATS
+
+NATS messaging enables the exchange of data that is segmented into messages among computer applications and services. These messages are addressed by subjects and do not depend on network location. This provides an abstraction layer between the application or service and the underlying physical network. Data is encoded and framed as a message and sent by a publisher. The message is received, decoded, and processed by one or more subscribers.
+
+NATS makes it easy for programs to communicate across different environments, languages, cloud providers and on-premise systems. Clients connect to the NATS system, usually via a single URL, and then subscribe or publish messages to subjects. With this simple design, NATS lets programs share common message-handling code, isolate resources and interdependencies, and scale by easily handling an increase in message volume, whether those are service requests or stream data.
+
+![](../.gitbook/assets/intro.svg)
+
+NATS core offers an **at most once** quality of service. If a subscriber is not listening on the subject \(no subject match\), or is not active when the message is sent, the message is not received. This is the same level of guarantee that TCP/IP provides. By default, NATS is a fire-and-forget messaging system. If you need higher levels of service, you can use [NATS Streaming](../nats-streaming-concepts/intro.md) or build additional reliability into your client applications with proven and scalable reference designs.
+

concepts/pubsub.md

@@ -0,0 +1,8 @@
+# Publish-Subscribe
+
+NATS implements a publish-subscribe message distribution model for one-to-many communication. A publisher sends a message on a subject and any active subscriber listening on that subject receives the message. Subscribers can also register interest in wildcard subjects that work a bit like a regular expression \(but only a bit\). This one-to-many pattern is sometimes called fan-out.
+
+![](../.gitbook/assets/pubsub.svg)
+
+Try NATS publish subscribe on your own, using a live server by walking through the [pub-sub tutorial](../developing-with-nats/intro-6/pubsub.md).
+

concepts/queue.md

@@ -0,0 +1,14 @@
+# Queue Groups
+
+NATS provides a built-in load balancing feature called distributed queues. Using queue subscribers will balance message delivery across a group of subscribers which can be used to provide application fault tolerance and scale workload processing.
+
+To create a queue subscription, subscribers register a queue name. All subscribers with the same queue name form the queue group. This requires no configuration. As messages on the registered subject are published, one member of the group is chosen randomly to receive the message. Although queue groups have multiple subscribers, each message is consumed by only one.
+
+One of the great features of NATS is that queue groups are defined by the application and their queue subscribers, not on the server configuration.
+
+Queue subscribers are ideal for scaling services. Scale up is as simple as running another application, scale down is terminating the application with a signal that drains the in flight requests. This flexibility and lack of any configuration changes makes NATS an excellent service communication technology that can work with all platform technologies.
+
+![](../.gitbook/assets/queue.svg)
+
+Try NATS queue subscriptions on your own, using a live server by walking through the [queueing tutorial](../developing-with-nats/intro-6/queues.md).
+

concepts/reqreply.md

@@ -0,0 +1,14 @@
+# Request-Reply
+
+Request-Reply is a common pattern in modern distributed systems. A request is sent and the application either waits on the response with a certain timeout or receives a response asynchronously. The increased complexity of modern systems requires features such as location transparency, scale up and scale down, observability and more. Many technologies need additional components, sidecars and proxies to accomplish the complete feature set.
+
+NATS supports this pattern with its core communication mechanism, publish and subscribe. A request is published on a given subject with a reply subject, and responders listen on that subject and send responses to the reply subject. Reply subjects are usually a subject called an \_INBOX that will be directed back to the requestor dynamically, regardless of location of either party.
+
+NATS allows multiple responders to run and form dynamic queue groups for transparent scale up. The ability for NATS applications to drain before exiting allows scale down with no requests being dropped. And since NATS is based on publish-subscribe, observability is as simple as running another application that can view requests and responses to measure latency, watch for anomalies, direct scalability and more.
+
+The power of NATS even allows multiple responses where the first response is utilized and the system efficiently discards the additional ones. This allows for a sophisticated pattern to have multiple responders reduce response latency and jitter.
+
+![](../.gitbook/assets/reqrepl.svg)
+
+Try NATS request reply on your own, using a live server by walking through the [request/reply tutorial](../developing-with-nats/intro-6/reqreply.md).
+

concepts/seq_num.md

@@ -0,0 +1,13 @@
+# Sequence Numbers
+
+A common problem for one-to-many messages is that a message can get lost or dropped due to a network failure. A simple pattern for resolving this situation is to include a sequence id with the message. Receivers can check the sequence id to see if they have missed anything. Sequence numbers combined with heartbeats in the absence of new data form a powerful and resilient pattern to detect loss. Systems that store and persist messages can also solve this problem, but sometimes are overkill for the problem at hand and usually cause additional management and operational cost.
+
+![](../.gitbook/assets/seqno.svg)
+
+In order to really leverage sequence ids there are a few things to keep in mind:
+
+* Each sender will have to use their own sequence
+* If possible, receivers should be able to ask for missing messages by id
+
+With NATS you can embed sequence ids in the message or include them as a token in the subject. For example, a sender can send messages to `updates.1`, `updates.2`, etc... and the subscribers can listen to `updates.*` and parse the subject to determine the sequence id. Placing a sequence token into the subject may be desireable if the payload is unknown or embedding additional data such as a sequence number in the payload is not possible.
+

concepts/subjects.md

@@ -0,0 +1,40 @@
+# Subject-Based Messaging
+
+Fundamentally NATS is about publishing and listening for messages. Both of these depend heavily on _Subjects_ which scope messages into streams or topics. At its simplest, a subject is just a string of characters that form a name the publisher and subscriber can use to find each other.
+
+![](../.gitbook/assets/subjects1.svg)
+
+The NATS server reserves a few characters as special, and the specification says that only "alpha-numeric" characters plus the "." should be used in subject names. Subjects are case-sensitive and cannot contain whitespace. For safety across clients, ASCII characters should be used, although this is subject to change in the future.
+
+## Subject Hierarchies
+
+The `.` character is used to create a subject hierarchy. For example, a world clock application might define the following to logically group related subjects:
+
+```markup
+time.us
+time.us.east
+time.us.east.atlanta
+time.eu.east
+time.eu.warsaw
+```
+
+## Wildcards
+
+NATS provides two _wildcards_ that can take the place of one or more elements in a dot-separated subject. Subscribers can use these wildcards to listen to multiple subjects with a single subscription but Publishers will always use a fully specified subject, without the wildcard.
+
+### Matching A Single Token
+
+The first wildcard is `*` which will match a single token. For example, if an application wanted to listen for eastern time zones, they could subscribe to `time.*.east`, which would match `time.us.east` and `time.eu.east`.
+
+![](../.gitbook/assets/subjects2.svg)
+
+### Matching Multiple Tokens
+
+The second wildcard is `>` which will match one or more tokens, and can only appear at the end of the subject. For example, `time.us.>` will match `time.us.east` and `time.us.east.atlanta`, while `time.us.*` would only match `time.us.east` since it can't match more than one token.
+
+![](../.gitbook/assets/subjects3.svg)
+
+### Monitoring and Wire Taps
+
+Subject to your security configuration, wildcards can be used for monitoring by creating something sometimes called a _wire tap_. In the simplest case you can create a subscriber for `>`. This application will receive all messages -- again, subject to security settings -- sent on your NATS cluster.
+