In a system with at-most-once semantics, there are times when messages are lost. If your application is doing request-reply then it can simply use timeouts to handle network and application failures. When you are using one-way messaging the easiest way to insure 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 body.
digraph nats_request_reply {
@@ -1928,7 +2449,7 @@ digraph nats_request_reply {
NATS messaging involves the electronic exchange of data among computer applications and provides a layer between the application and the underlying physical network. Application data is encoded as a message and sent by a publisher. The message is received, decoded, and processed by one or more subscribers.
-By providing a central, easily discovered broker, NATS makes it easy for programs to communicate across different environments, languages, and systems. All clients have to do is connect to the broker, subscribe or publish to a subject and process messages. 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.
+By providing a scalable service via a single URL, NATS makes it easy for programs to communicate across different environments, languages, and systems. All clients have to do is connect to the broker, subscribe or publish to a subject and process messages. 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.
graph nats {
graph [splines=ortho, nodesep=1];
@@ -1918,7 +2439,7 @@ graph nats {
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.
digraph nats_pub_sub {
@@ -1918,7 +2439,7 @@ digraph nats_pub_sub {
NATS provides a load balancing feature called queue subscriptions. Using queue subscribers will load 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. 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 subscribers, not on the server. Applications can create new queue groups without any server change.
@@ -1921,7 +2442,7 @@ digraph nats_queues { diff --git a/docs/developer/concepts/reqreply.html b/docs/developer/concepts/reqreply.html index 00557d1..cba1dfa 100644 --- a/docs/developer/concepts/reqreply.html +++ b/docs/developer/concepts/reqreply.html @@ -25,6 +25,10 @@ + + + + @@ -126,11 +130,742 @@ +NATS supports two flavors of request reply messaging: point-to-point or one-to-many. Point-to-point involves the fastest or first to respond. In a one-to-many exchange, you can set a limit on the number of responses the requestor may receive or use a timeout to limit on the speed of the response. One-to-many request reply is sometimes called scatter gather.
In a request-response exchange the publish request operation publishes a message with a reply subject expecting a response on that reply subject. Many libraries allow you to use a function that will automatically wait for a response with a timeout. You can also handle that waiting process yourself.
The common pattern used by the libraries is that the request creates a unique inbox and performs a request call with the inbox reply and returns the first reply received. This is optimized in the case of multiple responses by ignoring later responses automatically.
@@ -1935,7 +2456,7 @@ digraph nats_request_reply { diff --git a/docs/developer/concepts/seq_num.html b/docs/developer/concepts/seq_num.html index 881f723..2e9226c 100644 --- a/docs/developer/concepts/seq_num.html +++ b/docs/developer/concepts/seq_num.html @@ -25,6 +25,10 @@ + + + + @@ -126,11 +130,742 @@ +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 miss anything.
digraph nats_pub_sub {
@@ -1922,7 +2443,7 @@ digraph nats_pub_sub {
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 used to find each other.
digraph g {
rankdir=LR
publisher [shape=box, style="rounded", label="PUB time.us"];
- subject [shape=circle, label="gnatsd"];
+ subject [shape=circle, fixedsize="true", width="1.0", height="1.0", label="nats-server"];
sub1 [shape=box, style="rounded", label="SUB time.us"];
sub2 [shape=box, style="rounded", label="SUB time.us"];
@@ -1873,24 +2394,24 @@ digraph g {
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 can not contain whitespace. For safety across clients, ASCII characters should be used, although this is subject to change in the future.
-The . character is used to create a subject hierarchy. For example, a world clock application might define the following to logically group related subjects:
time.us
time.us.east
time.us.east.atlanta
time.eu.east
-time.us.east.warsaw
+time.eu.warsaw
to logically group related subjects.
-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.
-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.
digraph g {
rankdir=LR
publisher [shape=box, style="rounded", label="PUB time.us.east"];
- subject [shape=circle, label="gnatsd"];
+ subject [shape=circle, fixedsize="true", width="1.0", height="1.0", label="nats-server"];
sub1 [shape=box, style="rounded", label="SUB time.*.east"];
sub2 [shape=box, style="rounded", label="SUB time.us.east"];
@@ -1900,13 +2421,13 @@ digraph g {
}
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.
digraph g {
rankdir=LR
publisher [shape=box, style="rounded", label="PUB time.us.east.atlanta"];
- subject [shape=circle, label="gnatsd"];
+ subject [shape=circle, fixedsize="true", width="1.0", height="1.0", label="nats-server"];
sub1 [shape=box, style="rounded", label="SUB time.us.east.atlanta"];
sub2 [shape=box, style="rounded", label="SUB time.us.*"];
sub3 [shape=box, style="rounded", label="SUB time.us.>"];
@@ -1918,7 +2439,7 @@ digraph g {
}
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.
When connecting to a cluster, there are a few things to think about.
Each library has its own, language preferred way, to pass connection options. One of the most common options is a connection timeout. To set the maximum time to connect to a server to 10 seconds:
Some libraries also provide a special way to connect to a default url, which is general nats://localhost:4222:
Some libraries also provide a special way to connect to a default url, which is generally nats://localhost:4222:
Most client libraries provide several ways to connect to the NATS server. The server itself is identified by a standard URL with the nats protocol. Throughout these examples we will rely on a test server, provided by nats.io, at nats://demo.nats.io:4222, where 4222 is the default port for NATS.
NATS clients also support the tls protocol to indicate that the client wants to use TLS. So in the previous example we can replace nats with tls to get tls://demo.nats.io:4222.
The protocol requirement is being removed from many libraries, so that you can use demo.nats.io:4222 as the URL and let the client and server resolve whether or not TLS is required.