GitBook: [master] 326 pages and 16 assets modified

developing-with-nats/intro-3/README.md

@@ -0,0 +1,10 @@
+# Receiving Messages
+
+In general, applications can receive messages asynchronously or synchronously. Receiving messages with NATS can be library dependent.
+
+Some languages, like Go or Java, provide synchronous and asynchronous APIs, while others may only support one type of subscription.
+
+In all cases, the process of subscribing involves having the client library tell the NATS system that an application is interested in a particular subject.
+
+Under the covers, the client library will assign a unique id to each subscription. This id is used as a closure when the server sends messages to a specific subscription. Each subscription gets a unique id, so if the same connection is used multiple times for the same subject, the server will send multiple copies of the same message. When an application is done with a subscription it unsubscribes which tells the server to stop sending messages.
+

developing-with-nats/intro-3/async.md

@@ -0,0 +1,8 @@
+# Asynchronous Subscriptions
+
+Asynchronous subscriptions use callbacks of some form to notify an application when a message arrives. These subscriptions are usually easier to work with, but do represent some form of internal work and resource usage, i.e. threads, by the library. Check your library's documentation for any resource usage associated with asynchronous subscriptions.
+
+The following example subscribes to the subject `updates` and handles the incoming messages:
+
+!INCLUDE "../../\_examples/subscribe\_async.html"
+

developing-with-nats/intro-3/drain.md

@@ -0,0 +1,33 @@
+# Draining Messages Before Disconnect
+
+A feature recently added across the NATS client libraries is the ability to drain connections or subscriptions. Closing a connection, or unsubscribing from a subscription, are generally considered immediate requests. When you close or unsubscribe the library will halt messages in any pending queue or cache for subscribers. When you drain a subscription or connection, it will process any inflight and cached/pending messages before closing.
+
+Drain provides clients that use queue subscriptions with a way to bring down applications without losing any messages. A client can bring up a new queue member, drain and shut down the old queue member, all without losing messages sent to the old client. Without drain, there is the possibility of lost messages due to delivery timing.
+
+The libraries can provide drain on a connection or on a subscriber, or both.
+
+For a connection the process is essentially:
+
+1. Drain all subscriptions
+2. Stop new messages from being published
+3. Flush any remaining published messages
+4. Close
+
+The API for drain can generally be used instead of close:
+
+As an example of draining a connection:
+
+!INCLUDE "../../\_examples/drain\_conn.html"
+
+The mechanics of drain for a subscription are simpler:
+
+1. Unsubscribe
+2. Process all cached or inflight messages
+3. Clean up
+
+The API for drain can generally be used instead of unsubscribe:
+
+!INCLUDE "../../\_examples/drain\_sub.html"
+
+Because draining can involve messages flowing to the server, for a flush and asynchronous message processing, the timeout for drain should generally be higher than the timeout for a simple message request/reply or similar.
+

developing-with-nats/intro-3/queues.md

@@ -0,0 +1,14 @@
+# Queue Subscriptions
+
+Subscribing to a queue group is only slightly different than subscribing to a subject alone. The application simply includes a queue name with the subscription. The effect of including the group is fairly major, since the server will now load balance messages between the members of the queue group, but the code differences are minimal.
+
+Keep in mind that the queue groups in NATS are dynamic and do not require any server configuration. You can almost think of a regular subscription as a queue group of 1, but it is probably not worth thinking too much about that.
+
+![](../../.gitbook/assets/queues.svg)
+
+As an example, to subscribe to the queue `workers` with the subject `updates`:
+
+!INCLUDE "../../\_examples/subscribe\_queue.html"
+
+If you run this example with the publish examples that send to `updates`, you will see that one of the instances gets a message while the others you run won't. But the instance that receives the message will change.
+

developing-with-nats/intro-3/reply.md

@@ -0,0 +1,8 @@
+# Replying to a Message
+
+Incoming messages have an optional reply-to field. If that field is set, it will contain a subject to which a reply is expected.
+
+For example, the following code will listen for that request and respond with the time.
+
+!INCLUDE "../../\_examples/subscribe\_w\_reply.html"
+

developing-with-nats/intro-3/structure.md

@@ -0,0 +1,8 @@
+# Structured Data
+
+Client libraries may provide tools to help receive structured data, like JSON. The core traffic to the NATS server will always be opaque byte arrays. The server does not process message payloads in any form. For libraries that don't provide helpers, you can always encode and decode data before sending the associated bytes to the NATS client.
+
+For example, to receive JSON you could do:
+
+!INCLUDE "../../\_examples/subscribe\_json.html"
+

developing-with-nats/intro-3/sync.md

@@ -0,0 +1,8 @@
+# Synchronous Subscriptions
+
+Synchronous subscriptions require the application to wait for messages. This type of subscription is easy to set-up and use, but requires the application to deal with looping if multiple messages are expected. For situations where a single message is expected, synchronous subscriptions are sometimes easier to manage, depending on the language.
+
+For example, to subscribe to the subject `updates` and receive a single message you could do:
+
+!INCLUDE "../../\_examples/subscribe\_sync.html"
+

developing-with-nats/intro-3/unsub_after.md

@@ -0,0 +1,16 @@
+# Unsubscribing After N Messages
+
+NATS provides a special form of unsubscribe that is configured with a message count and takes effect when that many messages are sent to a subscriber. This mechanism is very useful if only a single message is expected.
+
+The message count you provide is the total message count for a subscriber. So if you unsubscribe with a count of 1, the server will stop sending messages to that subscription after it has received one message. If the subscriber has already received one or more messages, the unsubscribe will be immediate. This action based on history can be confusing if you try to auto unsubscribe on a long running subscription, but is logical for a new one.
+
+> Auto unsubscribe is based on the total messages sent to a subscriber, not just the new ones.
+
+Auto unsubscribe can also result in some tricky edge cases if a server cluster is used. The client will tell the server of the unsubscribe count when the application requests it. But if the client disconnects before the count is reached, it may have to tell another server of the remaining count. This dance between previous server notifications and new notifications on reconnect can result in unplanned behavior.
+
+Finally, most of the client libraries also track the max message count after an auto unsubscribe request. Which means that the client will stop allowing messages to flow even if the server has miscounted due to reconnects or some other failure in the client library.
+
+The following example shows unsubscribe after a single message:
+
+!INCLUDE "../../\_examples/unsubscribe\_auto.html"
+

developing-with-nats/intro-3/unsubscribing.md

@@ -0,0 +1,8 @@
+# Unsubscribing
+
+The client libraries provide a means to unsubscribe a previous subscription request.
+
+This process requires an interaction with the server, so for an asynchronous subscription there may be a small window of time where a message comes through as the unsubscribe is processed by the library. Ignoring that slight edge case, the client library will clean up any outstanding messages and tell the server that the subscription is no longer used.
+
+!INCLUDE "../../\_examples/unsubscribe.html"
+

developing-with-nats/intro-3/wildcards.md

@@ -0,0 +1,18 @@
+# Wildcard Subscriptions
+
+There is no special code to subscribe with a wildcard subject. Wildcards are a normal part of the subject name.
+
+However, there is a common technique that may come in to play when you use wildcards. This technique is to use the subject provided with the incoming message to determine what to do with the message.
+
+For example, you can subscribe using `*` and then act based on the actual subject.
+
+!INCLUDE "../../\_examples/subscribe\_star.html"
+
+or do something similar with `>`:
+
+!INCLUDE "../../\_examples/subscribe\_arrow.html"
+
+The following example can be used to test these two subscribers. The `*` subscriber should receive at most 2 messages, while the `>` subscriber receives 4. More importantly the `time.*.east` subscriber won't receive on `time.us.east.atlanta` because that won't match.
+
+!INCLUDE "../../\_examples/wildcard\_tester.html"
+