mirror of
https://github.com/taigrr/nats.docs
synced 2025-01-18 04:03:23 -08:00
Moved tools to _tools
Broke up develoepr doc into tree Small CSS tweak to give diagrams more room
This commit is contained in:
Stephen Asbury
parent
57db99feba
commit
9618415569
2
Makefile
2
Makefile
@ -8,4 +8,4 @@ serve:
|
||||
gitbook serve
|
||||
|
||||
examples:
|
||||
go run tools/examplecompiler/main.go -o _examples -r tools/examplecompiler/example_repos.json -t tools/examplecompiler/example_template.tmp
|
||||
go run _tools/examplecompiler/main.go -o _examples -r _tools/examplecompiler/example_repos.json -t _tools/examplecompiler/example_template.tmp
|
||||
|
||||
62
SUMMARY.md
62
SUMMARY.md
@ -1,9 +1,67 @@
|
||||
# Summary
|
||||
|
||||
* [Introduction](README.md)
|
||||
|
||||
## Administering NATS
|
||||
|
||||
* [NATS Server](nats_server/README.md)
|
||||
* [Installing](nats_server/installation.md)
|
||||
* [Running](nats_server/running.md)
|
||||
* [Clients](nats_server/clients.md)
|
||||
* [Developing with NATS](developer/README.md)
|
||||
* [Connecting](developer/connecting.md)
|
||||
|
||||
## Developing With NATS
|
||||
|
||||
* [Concepts](developer/concepts/intro.md)
|
||||
* [Publish-Subscribe](developer/concepts/pubsub.md)
|
||||
* [Request-Reply](developer/concepts/reqreply.md)
|
||||
* [Using Queues to Share Work](developer/concepts/queue.md)
|
||||
* [Subject-Based Messaging](developer/concepts/subjects.md)
|
||||
|
||||
* [Connecting](developer/connecting/intro.md)
|
||||
* [Connecting to the Default Server](developer/connecting/default_server.md)
|
||||
* [Connecting to a Specific Server](developer/connecting/specific_server.md)
|
||||
* [Connecting to a Cluster](developer/connecting/cluster.md)
|
||||
* [Setting a Connect Timeout](developer/connecting/connect_timeout.md)
|
||||
* [Ping/Pong Protocol](developer/connecting/pingpong.md)
|
||||
* [Controlling the Client/Server Protocol](developer/connecting/protocol.md)
|
||||
* [Turning Off Echo'd Messages](developer/connecting/noecho.md)
|
||||
|
||||
* [Automatic Reconnections](developer/reconnect/intro.md)
|
||||
* [Disabling Reconnect](developer/reconnect/disable.md)
|
||||
* [Set the Number of Reconnect Attempts](developer/reconnect/max.md)
|
||||
* [Pausing Between Reconnect Attempts](developer/reconnect/wait.md)
|
||||
* [Avoiding the Thundering Herd](developer/reconnect/random.md)
|
||||
* [Listening for Reconnect Events](developer/reconnect/events.md)
|
||||
* [Buffering Messages During Reconnect Attempts](developer/reconnect/buffer.md)
|
||||
|
||||
* [Securing Connections](developer/security/intro.md)
|
||||
* [Authenticating with a User and Password](developer/security/userpass.md)
|
||||
* [Authenticating with a Token](developer/security/token.md)
|
||||
* [Encrypting Connections with TLS](developer/security/tls.md)
|
||||
|
||||
* [Sending Messages](developer/sending/intro.md)
|
||||
* [Including a Reply Subject](developer/sending/replyto.md)
|
||||
* [Request-Reply Semantics](developer/sending/request_reply.md)
|
||||
* [Caches, Flush and Ping](developer/sending/caches.md)
|
||||
* [Sending Structured Data](developer/sending/structure.md)
|
||||
|
||||
* [Receiving Messages](developer/receiving/intro.md)
|
||||
* [Synchronous Subscriptions](developer/receiving/sync.md)
|
||||
* [Asynchronous Subscriptions](developer/receiving/async.md)
|
||||
* [Unsubscribing](developer/receiving/unsubscribing.md)
|
||||
* [Unsubscribing After N Messages](developer/receiving/unsub_after.md)
|
||||
* [Replying to a Message](developer/receiving/reply.md)
|
||||
* [Wildcard Subscriptions](developer/receiving/wildcards.md)
|
||||
* [Queue Subscriptions](developer/receiving/queues.md)
|
||||
* [Draining Messages Before Disconnect](developer/receiving/drain.md)
|
||||
* [Structured Data](developer/receiving/structure.md)
|
||||
|
||||
* [Advanced Topics](developer/advanced/intro.md)
|
||||
* [Getting the Connection Status](developer/advanced/server_status.md)
|
||||
* [Listen for Connection Events](developer/advanced/events.md)
|
||||
* [Slow Consumers](developer/advanced/slow.md)
|
||||
|
||||
* [Tutorials](developer/tutorials/intro.md)
|
||||
* [Explore NATS Pub/Sub](developer/tutorials/pubsub.md)
|
||||
* [Explore NATS Request/Reply](developer/tutorials/reqreply.md)
|
||||
* [Explore NATS Queueing](developer/tutorials/queues.md)
|
||||
|
||||
@ -162,7 +162,7 @@
|
||||
border: 0;
|
||||
padding-top: 15px;
|
||||
padding-right: 15px;
|
||||
padding-bottom: 15px;
|
||||
padding-bottom: 25px;
|
||||
padding-left: 15px;
|
||||
}
|
||||
|
||||
@ -179,7 +179,7 @@
|
||||
position: relative;
|
||||
list-style: none;
|
||||
background-color: #fff;
|
||||
margin: 10px 0;
|
||||
margin: 20px 0;
|
||||
/* box-shadow: 0 1px 3px rgba(0, 0, 0, 0.12), 0 1px 2px rgba(0, 0, 0, 0.24);*/
|
||||
}
|
||||
|
||||
|
||||
@ -9,3 +9,7 @@ To build the examples
|
||||
```bash
|
||||
% go run tools/examplecompiler/main.go -o developer/examples -r tools/examplecompiler/example_repos.json -t tools/examplecompiler/example_template.tmp
|
||||
```
|
||||
|
||||
or just use the make file `make` will download the gitbook plugins, build the example html and build the book.
|
||||
|
||||
`make serve` will just serve the files without all the other prep work.
|
||||
@ -1,121 +0,0 @@
|
||||
# NATS Messaging Concepts
|
||||
|
||||
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. A subscriber can process a NATS message synchronously or asynchronously, depending on the client library used.
|
||||
|
||||
## Asynchronous
|
||||
|
||||
Asynchronous processing uses a callback message handler to process messages. When a message arrives, the registered callback handler receives control to process the message. The client or the consuming application is not blocked from performing other work while it is waiting for a message. Asynchronous processing lets you create multi-threaded dispatching designs.
|
||||
|
||||
## Synchronous
|
||||
|
||||
Synchronous processing requires that application code explicitly call a method to process an incoming message. Typically the message request is a blocking call that suspends processing until a message becomes available and if no message is available, the period for which the message processing call blocks, would be set by the client. Synchronous processing is typically used by a server whose purpose is to wait for and process incoming request messages and to send replies to the requesting application.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
graph nats {
|
||||
graph [splines=ortho, nodesep=1];
|
||||
|
||||
publisher [shape="record", label="{Application 1 | <nats> NATS Publisher}"];
|
||||
application [shape="record", label="{Application 3 | <nats> }"];
|
||||
gnatsd [shape="box", label="", width=4, height=0, penwidth=1];
|
||||
subscriber [shape="record", label="{<nats> NATS Subscriber | Application 2}"];
|
||||
|
||||
publisher:nats -- gnatsd [penwidth=2];
|
||||
application:nats -- gnatsd;
|
||||
gnatsd -- subscriber:nats [penwidth=2, dir="forward"];
|
||||
}
|
||||
</code></div>
|
||||
|
||||
NATS makes it easy for programs to communicate across different environments, languages, and systems because all a client has to do is parse the message. NATS lets programs share common message-handling code, isolate resources and interdependencies, and scale by easily handling an increase in message volume.
|
||||
|
||||
## <a name="pubsub"></a>Publish Subscribe
|
||||
|
||||
NATS implements a publish subscribe message distribution model as a 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. NATS and NATS Streaming combine to offer two qualities of service:
|
||||
|
||||
- **At Most Once Delivery (NATS w/TCP reliability)** - In the basic NATS platform, 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. NATS is a fire-and-forget messaging system. If you need higher levels of service, you can either use [NATS Streaming](/documentation/streaming/nats-streaming-intro/), or build the additional reliability into your client(s) yourself.
|
||||
|
||||
- **At Least Once Delivery ([NATS Streaming](/documentation/streaming/nats-streaming-intro/))** - Some applications require higher levels of service and more stringent delivery guarantees but at the potential cost of lower message throughput and higher end-to-end delivery latency. These applications rely on the underlying messaging transport to ensure that messages are delivered to subscribers irrespective of network outages or whether or not a subscriber is offline at a particular point in time.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
digraph nats_pub_sub {
|
||||
rankdir=LR
|
||||
publisher [shape=box, style="rounded", label="Publisher"];
|
||||
subject [shape=circle, label="Subject"];
|
||||
sub1 [shape=box, style="rounded", label="Subscriber"];
|
||||
sub2 [shape=box, style="rounded", label="Subscriber"];
|
||||
sub3 [shape=box, style="rounded", label="Subscriber"];
|
||||
|
||||
publisher -> subject [label="msg1"];
|
||||
subject -> sub1 [label="msg1"];
|
||||
subject -> sub2 [label="msg1"];
|
||||
subject -> sub3 [label="msg1"];
|
||||
}
|
||||
</code></div>
|
||||
|
||||
Try NATS publish subscribe on your own, using a live server by walking through the [pub-sub tutorial](/doc/additional_documentation/nats-pub-sub).
|
||||
|
||||
## <a name="reqrep"></a>Request Reply
|
||||
|
||||
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 set a limit on the number of responses the requestor may receive.
|
||||
|
||||
In a request-response exchange, publish request operation publishes a message with a reply subject expecting a response on that reply subject. You can request to automatically wait for a response inline.
|
||||
|
||||
The request creates an 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.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
digraph nats_request_reply {
|
||||
rankdir=LR
|
||||
|
||||
subgraph {
|
||||
publisher [shape=box, style="rounded", label="Publisher"];
|
||||
}
|
||||
|
||||
subgraph {
|
||||
subject [shape=circle, label="Subject"];
|
||||
reply [shape=circle, label="Reply"];
|
||||
{rank = same subject reply}
|
||||
}
|
||||
|
||||
subgraph {
|
||||
sub1 [shape=box, style="rounded", label="Subscriber"];
|
||||
sub2 [shape=box, style="rounded", label="Subscriber"];
|
||||
sub3 [shape=box, style="rounded", label="Subscriber"];
|
||||
}
|
||||
|
||||
publisher -> subject [label="msg1"];
|
||||
publisher -> reply [style="invis", weight=2];
|
||||
reply -> sub3 [style="invis", weight=2];
|
||||
subject -> sub1 [label="msg1", style="dotted"];
|
||||
subject -> sub2 [label="msg1", style="dotted"];
|
||||
subject -> sub3 [label="msg1"];
|
||||
sub3 -> reply;
|
||||
reply -> publisher;
|
||||
}
|
||||
</code></div>
|
||||
|
||||
Try NATS request reply on your own, using a live server by walking through the [request/reply tutorial](/doc/additional_documentation/nats-req-rep).
|
||||
|
||||
## <a name="queue"></a>Queue Subscribers & Sharing Work
|
||||
|
||||
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.
|
||||
|
||||
Queue subscribers can be asynchronous, in which case the message handler callback function processes the delivered message. Synchronous queue subscribers must build in logic to process the message. Queue subscribers are ideal for auto scaling as you can add or remove them anytime, without any configuration changes or restarting the server or clients.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
digraph nats_queues {
|
||||
rankdir=LR
|
||||
publisher [shape=box, style="rounded", label="Publisher"];
|
||||
subject [shape=circle, label="Queue"];
|
||||
sub1 [shape=box, style="rounded", label="Subscriber"];
|
||||
sub2 [shape=box, style="rounded", label="Subscriber"];
|
||||
sub3 [shape=box, style="rounded", label="Subscriber"];
|
||||
|
||||
publisher -> subject [label="msgs 1,2,3"];
|
||||
subject -> sub1 [label="msg 2"];
|
||||
subject -> sub2 [label="msg 1"];
|
||||
subject -> sub3 [label="msg 3"];
|
||||
}
|
||||
</code></div>
|
||||
|
||||
Try NATS queue subscriptions on your own, using a live server by walking through the [queueing tutorial](/doc/additional_documentation/nats-queueing).
|
||||
17
developer/advanced/events.md
Normal file
17
developer/advanced/events.md
Normal file
@ -0,0 +1,17 @@
|
||||
# Listen for Connection Events
|
||||
|
||||
While the status is interesting, it is perhaps more interesting to know when the status changes. Most, if not all, of the NATS client libraries provide a way to listen for events related to the connection and its status. The actual API for these listeners is language dependent, but the following examples show a few of the more common use cases. See the API documentation for the client library you are using for more specific instructions. Connection events may include the connection being closed, disconnected or reconnected. Reconnecting involves a disconnect and connect, but depending on the library implementation may also include multiple disconnects as the client tries to find a server, or the server is rebooted.
|
||||
|
||||
!INCLUDE "../../_examples/connection_listener.html"
|
||||
|
||||
## Listen for New Servers
|
||||
|
||||
When working with a cluster, servers may be added or changed. Some of the clients allow you to listen for this notification:
|
||||
|
||||
!INCLUDE "../../_examples/servers_added.html"
|
||||
|
||||
## Listen for Errors
|
||||
|
||||
The client library may separate server-to-client errors from events. Many server events are not handled by application code and result in the connection being closed. Listening for the errors can be very useful for debugging problems.
|
||||
|
||||
!INCLUDE "../../_examples/error_listener.html"
|
||||
3
developer/advanced/intro.md
Normal file
3
developer/advanced/intro.md
Normal file
@ -0,0 +1,3 @@
|
||||
# Advanced Topics
|
||||
|
||||
Managing the interaction with the server is primarily the job of the client library but most of the libraries also provide some insight into what is happening under the covers.
|
||||
5
developer/advanced/server_status.md
Normal file
5
developer/advanced/server_status.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Get the Connection Status
|
||||
|
||||
The client library may provide a mechanism to get the connection's current status.
|
||||
|
||||
!INCLUDE "../../_examples/connect_status.html"
|
||||
27
developer/advanced/slow.md
Normal file
27
developer/advanced/slow.md
Normal file
@ -0,0 +1,27 @@
|
||||
# Slow Consumers
|
||||
|
||||
NATS is designed to move messages through the server quickly. As a result, NATS depends on the applications to consider and respond to changing message rates. The server will do a bit of impedance matching, but if a client is too slow the server will eventually cut them off. One way some of the libraries deal with bursty message traffic is to cache incoming messages for a subscription. So if an application can handle 10 messages per second and sometimes receives 20 messages per second, the library may hold the extra 10 to give the application time to catch up. To the server, the application will appear to be handling the messages and consider the connection healthy. It is up to the client library to decide what to do when the cache is too big, but most client libraries will drop incoming messages.
|
||||
|
||||
Receiving and dropping messages from the server keeps the connection to the server healthy, but creates an application requirement. There are several common patterns:
|
||||
|
||||
* Use request/reply to throttle the sender and prevent overloading the subscriber
|
||||
* Use a queue with multiple subscribers splitting the work
|
||||
* Persist/cache messages with something like NATS streaming
|
||||
|
||||
Libraries that cache incoming messages may provide two controls on the incoming queue, or pending messages. These are useful if the problem is bursty publishers and not a continuous performance mismatch. Disabling these limits can be dangerous in production and although setting these limits to 0 may help find problems, it is also a dangerous proposition in production.
|
||||
|
||||
> Check your libraries documentation for the default settings, and support for disabling these limits.
|
||||
|
||||
The incoming cache is usually per subscriber, but again, check the specific documentation for your client library.
|
||||
|
||||
## Limiting Incoming/Pending Messages by Count and Bytes
|
||||
|
||||
The first way that the incoming queue can be limited is by message count. The second way to limit the incoming queue is by total size. For example, to limit the incoming cache to 1,000 messages or 5mb whichever comes first:
|
||||
|
||||
!INCLUDE "../../_examples/slow_pending_limits.html"
|
||||
|
||||
## Detect a Slow Consumer and Check for Dropped Messages
|
||||
|
||||
When a slow consumer is detected and messages are about to be dropped, the library may notify the application. This process may be similar to other errors or may involve a custom callback. Some libraries, like Java, will not send this notification on every dropped message because that could be noisy. Rather the notification may be sent once per time the subscriber gets behind. Libraries may also provide a way to get a count of dropped messages so that applications can at least detect a problem is occurring.
|
||||
|
||||
!INCLUDE "../../_examples/slow_listener.html"
|
||||
24
developer/concepts/intro.md
Normal file
24
developer/concepts/intro.md
Normal file
@ -0,0 +1,24 @@
|
||||
# NATS Messaging Concepts
|
||||
|
||||
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. A subscriber can process a NATS message synchronously or asynchronously, depending on the client library used.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
graph nats {
|
||||
graph [splines=ortho, nodesep=1];
|
||||
|
||||
publisher [shape="record", label="{Application 1 | <nats> NATS Publisher}"];
|
||||
application [shape="record", label="{Application 3 | <nats> }"];
|
||||
gnatsd [shape="box", label="", width=4, height=0, penwidth=1];
|
||||
subscriber [shape="record", label="{<nats> NATS Subscriber | Application 2}"];
|
||||
|
||||
publisher:nats -- gnatsd [penwidth=2];
|
||||
application:nats -- gnatsd;
|
||||
gnatsd -- subscriber:nats [penwidth=2, dir="forward"];
|
||||
}
|
||||
</code></div>
|
||||
|
||||
Asynchronous processing uses a callback message handler to process messages. When a message arrives, the registered callback handler receives control to process the message. The client or the consuming application is not blocked from performing other work while it is waiting for a message. Asynchronous processing lets you create multi-threaded dispatching designs.
|
||||
|
||||
Synchronous processing requires that application code explicitly call a method to process an incoming message. Typically the message request is a blocking call that suspends processing until a message becomes available and if no message is available, the period for which the message processing call blocks, would be set by the client. Synchronous processing is typically used by a server whose purpose is to wait for and process incoming request messages and to send replies to the requesting application.
|
||||
|
||||
NATS makes it easy for programs to communicate across different environments, languages, and systems because all a client has to do is parse the message. NATS lets programs share common message-handling code, isolate resources and interdependencies, and scale by easily handling an increase in message volume.
|
||||
25
developer/concepts/pubsub.md
Normal file
25
developer/concepts/pubsub.md
Normal file
@ -0,0 +1,25 @@
|
||||
# Publish Subscribe
|
||||
|
||||
NATS implements a publish subscribe message distribution model as a 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. NATS and NATS Streaming combine to offer two qualities of service:
|
||||
|
||||
- **At Most Once Delivery (NATS w/TCP reliability)** - In the basic NATS platform, 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. NATS is a fire-and-forget messaging system. If you need higher levels of service, you can either use NATS Streaming, or build the additional reliability into your client(s) yourself.
|
||||
|
||||
- **At Least Once Delivery (NATS Streaming)** - Some applications require higher levels of service and more stringent delivery guarantees but at the potential cost of lower message throughput and higher end-to-end delivery latency. These applications rely on the underlying messaging transport to ensure that messages are delivered to subscribers irrespective of network outages or whether or not a subscriber is offline at a particular point in time.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
digraph nats_pub_sub {
|
||||
rankdir=LR
|
||||
publisher [shape=box, style="rounded", label="Publisher"];
|
||||
subject [shape=circle, label="Subject"];
|
||||
sub1 [shape=box, style="rounded", label="Subscriber"];
|
||||
sub2 [shape=box, style="rounded", label="Subscriber"];
|
||||
sub3 [shape=box, style="rounded", label="Subscriber"];
|
||||
|
||||
publisher -> subject [label="msg1"];
|
||||
subject -> sub1 [label="msg1"];
|
||||
subject -> sub2 [label="msg1"];
|
||||
subject -> sub3 [label="msg1"];
|
||||
}
|
||||
</code></div>
|
||||
|
||||
Try NATS publish subscribe on your own, using a live server by walking through the [pub-sub tutorial](../tutorials/pubsub.md).
|
||||
25
developer/concepts/queue.md
Normal file
25
developer/concepts/queue.md
Normal file
@ -0,0 +1,25 @@
|
||||
# Queue Subscribers & Sharing Work
|
||||
|
||||
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.
|
||||
|
||||
Queue subscribers can be asynchronous, in which case the message handler callback function processes the delivered message. Synchronous queue subscribers must build in logic to process the message. Queue subscribers are ideal for auto scaling as you can add or remove them anytime, without any configuration changes or restarting the server or clients.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
digraph nats_queues {
|
||||
rankdir=LR
|
||||
publisher [shape=box, style="rounded", label="Publisher"];
|
||||
subject [shape=circle, label="Queue"];
|
||||
sub1 [shape=box, style="rounded", label="Subscriber"];
|
||||
sub2 [shape=box, style="rounded", label="Subscriber"];
|
||||
sub3 [shape=box, style="rounded", label="Subscriber"];
|
||||
|
||||
publisher -> subject [label="msgs 1,2,3"];
|
||||
subject -> sub1 [label="msg 2"];
|
||||
subject -> sub2 [label="msg 1"];
|
||||
subject -> sub3 [label="msg 3"];
|
||||
}
|
||||
</code></div>
|
||||
|
||||
Try NATS queue subscriptions on your own, using a live server by walking through the [queueing tutorial](../tutorials/queues.md).
|
||||
40
developer/concepts/reqreply.md
Normal file
40
developer/concepts/reqreply.md
Normal file
@ -0,0 +1,40 @@
|
||||
# Request Reply
|
||||
|
||||
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 set a limit on the number of responses the requestor may receive.
|
||||
|
||||
In a request-response exchange, publish request operation publishes a message with a reply subject expecting a response on that reply subject. You can request to automatically wait for a response inline.
|
||||
|
||||
The request creates an 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.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
digraph nats_request_reply {
|
||||
rankdir=LR
|
||||
|
||||
subgraph {
|
||||
publisher [shape=box, style="rounded", label="Publisher"];
|
||||
}
|
||||
|
||||
subgraph {
|
||||
subject [shape=circle, label="Subject"];
|
||||
reply [shape=circle, label="Reply"];
|
||||
{rank = same subject reply}
|
||||
}
|
||||
|
||||
subgraph {
|
||||
sub1 [shape=box, style="rounded", label="Subscriber"];
|
||||
sub2 [shape=box, style="rounded", label="Subscriber"];
|
||||
sub3 [shape=box, style="rounded", label="Subscriber"];
|
||||
}
|
||||
|
||||
publisher -> subject [label="msg1"];
|
||||
publisher -> reply [style="invis", weight=2];
|
||||
reply -> sub3 [style="invis", weight=2];
|
||||
subject -> sub1 [label="msg1", style="dotted"];
|
||||
subject -> sub2 [label="msg1", style="dotted"];
|
||||
subject -> sub3 [label="msg1"];
|
||||
sub3 -> reply;
|
||||
reply -> publisher;
|
||||
}
|
||||
</code></div>
|
||||
|
||||
Try NATS request reply on your own, using a live server by walking through the [request/reply tutorial](../tutorials/reqreply.md).
|
||||
75
developer/concepts/subjects.md
Normal file
75
developer/concepts/subjects.md
Normal file
@ -0,0 +1,75 @@
|
||||
# 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 used to find each other.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
digraph g {
|
||||
rankdir=LR
|
||||
publisher [shape=box, style="rounded", label="PUB time.us"];
|
||||
subject [shape=circle, label="gnatsd"];
|
||||
sub1 [shape=box, style="rounded", label="SUB time.us"];
|
||||
sub2 [shape=box, style="rounded", label="SUB time.us"];
|
||||
|
||||
publisher -> subject [label="msg"];
|
||||
subject -> sub1 [label="msg"];
|
||||
subject -> sub2 [label="msg"];
|
||||
}
|
||||
</code></div>
|
||||
|
||||
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.
|
||||
|
||||
## 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.us.east.warsaw
|
||||
```
|
||||
|
||||
to logically group related subjects.
|
||||
|
||||
## 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`.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
digraph g {
|
||||
rankdir=LR
|
||||
publisher [shape=box, style="rounded", label="PUB time.us.east"];
|
||||
subject [shape=circle, label="gnatsd"];
|
||||
sub1 [shape=box, style="rounded", label="SUB time.*.east"];
|
||||
sub2 [shape=box, style="rounded", label="SUB time.us.east"];
|
||||
|
||||
publisher -> subject [label="msg"];
|
||||
subject -> sub1 [label="msg"];
|
||||
subject -> sub2 [label="msg"];
|
||||
}
|
||||
</code></div>
|
||||
|
||||
### 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.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
digraph g {
|
||||
rankdir=LR
|
||||
publisher [shape=box, style="rounded", label="PUB time.us.east.atlanta"];
|
||||
subject [shape=circle, label="gnatsd"];
|
||||
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.>"];
|
||||
|
||||
publisher -> subject [label="msg"];
|
||||
subject -> sub2 [style="invis"];
|
||||
subject -> sub1 [label="msg"];
|
||||
subject -> sub3 [label="msg"];
|
||||
}
|
||||
</code></div>
|
||||
@ -1,79 +0,0 @@
|
||||
# Connecting to NATS
|
||||
|
||||
Most client libraries provide several ways to connect to the NATS server, gnatsd. 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](https://nats.io), at `nats://demo.nats.io:4222`, where `4222` is the default port for NATS.
|
||||
|
||||
## Connecting to a Specific Server
|
||||
|
||||
For example, to connect to the demo server with a URL:
|
||||
|
||||
!INCLUDE "../_examples/connect_url.html"
|
||||
|
||||
## Connecting to the Default Server
|
||||
|
||||
Some libraries also provide a special way to connect to a *default* url, which is general `nats://localhost:4222`:
|
||||
|
||||
!INCLUDE "../_examples/connect_default.html"
|
||||
|
||||
## Setting a Connect Timeout
|
||||
|
||||
Each library has its own, language preferred way, to pass connection options. For example, to set the maximum time to connect to a server to 10 seconds:
|
||||
|
||||
!INCLUDE "../_examples/connect_options.html"
|
||||
|
||||
The available options are discussed more below, in other pages, and in the documentation for your client library.
|
||||
|
||||
## Connecting to a Cluster
|
||||
|
||||
When connecting to a cluster, there are a few things to think about.
|
||||
|
||||
* Passing a URL for each cluster member (semi-optional)
|
||||
* The connection algorithm
|
||||
* The reconnect algorithm (discussed later)
|
||||
* Server provided URLs
|
||||
|
||||
When a client connects to the server, the server may provide a list of URLs for additional known servers. This allows a client to connect to one server and still have other servers available during reconnect. However, the initial connection cannot depend on these additional servers. Rather, the additional connection will try to connect to each of the URLs provided in the connect call and will fail if it is unable to connect to any of them. *Note, failure behavior is library dependent, please check the documentation for your client library on information about what happens if the connect fails.*
|
||||
|
||||
!INCLUDE "../_examples/connect_multiple.html"
|
||||
|
||||
## Reconnecting
|
||||
|
||||
Most, if not all, of the client libraries will reconnect to the server if they are disconnected due to a network problem. The reconnect logic can differ by library, so check your client libraries. In general, the client will try to connect to all of the servers it knows about, either through the URLs provided in `connect` or the URLs provided by its most recent server. The library may have several options to help control reconnect behavior.
|
||||
|
||||
### Disable Reconnect
|
||||
|
||||
For example, you can disable reconnect:
|
||||
|
||||
!INCLUDE "../_examples/reconnect_none.html"
|
||||
|
||||
### Set the Number of Reconnect Attempts
|
||||
|
||||
Applications can set the maximum reconnect attempts. Generally, this will limit the actual number of attempts total, but check your library documentation. For example, in Java, if the client knows about 3 servers and the maximum reconnects is set to 2, it will not try all of the servers. On the other hand, if the maximum is set to 6 it will try all of the servers twice before considering the reconnect a failure and closing.
|
||||
|
||||
!INCLUDE "../_examples/reconnect_10x.html"
|
||||
|
||||
### Pausing Between Reconnect Attempts
|
||||
|
||||
It doesn’t make much sense to try to connect to the same server over and over. To prevent this sort of thrashing, and wasted reconnect attempts, libraries provide a wait setting. This setting will pause the reconnect logic if the same server is being tried multiple times. In the previous example, if you have 3 servers and 6 attempts, the Java library would loop over the three servers. If none were connectable, it will then try all three again. However, the Java client doesn’t wait between each attempt, only when trying the same server again, so in that example the library may never wait. If on the other hand, you only provide a single server URL and 6 attempts, the library will wait between each attempt.
|
||||
|
||||
!INCLUDE "../_examples/reconnect_10s.html"
|
||||
|
||||
### Avoiding the Thundering Herd
|
||||
|
||||
When a server goes down, there is a possible anti-pattern called the *Thundering Herd* where all of the clients try to reconnect immediately creating a denial of service attack. In order to prevent this, most NATS client libraries randomize the servers they attempt to connect to. This setting has no effect if only a single server is used, but in the case of a cluster, randomization, or shuffling, will ensure that no one server bears the brunt of the client reconnect attempts.
|
||||
|
||||
!INCLUDE "../_examples/reconnect_no_random.html"
|
||||
|
||||
### Listening for Reconnect Events
|
||||
|
||||
Because reconnect is primarily under the covers many libraries provide an event listener you can use to be notified of reconnect events. This event can be especially important for applications sending a lot of messages.
|
||||
|
||||
!INCLUDE "../_examples/reconnect_event.html"
|
||||
|
||||
|
||||
### Buffering Messages During Reconnect Attempts
|
||||
|
||||
There is another setting that comes in to play during reconnection. This setting controls how much memory the client library will hold in the form of outgoing messages while it is disconnected. During a short reconnect, the client will generally allow applications to publish messages but because the server is offline, will be cached in the client. The library will then send those messages on reconnect. When the maximum reconnect buffer is reached, messages will no longer be publishable by the client.
|
||||
|
||||
!INCLUDE "../_examples/reconnect_5mb.html"
|
||||
|
||||
> *As mentioned throughout this document, each client library may behave slightly differently. Please check the documentation for the library you are using.*
|
||||
12
developer/connecting/cluster.md
Normal file
12
developer/connecting/cluster.md
Normal file
@ -0,0 +1,12 @@
|
||||
# Connecting to a Cluster
|
||||
|
||||
When connecting to a cluster, there are a few things to think about.
|
||||
|
||||
* Passing a URL for each cluster member (semi-optional)
|
||||
* The connection algorithm
|
||||
* The reconnect algorithm (discussed later)
|
||||
* Server provided URLs
|
||||
|
||||
When a client connects to the server, the server may provide a list of URLs for additional known servers. This allows a client to connect to one server and still have other servers available during reconnect. However, the initial connection cannot depend on these additional servers. Rather, the additional connection will try to connect to each of the URLs provided in the connect call and will fail if it is unable to connect to any of them. *Note, failure behavior is library dependent, please check the documentation for your client library on information about what happens if the connect fails.*
|
||||
|
||||
!INCLUDE "../../_examples/connect_multiple.html"
|
||||
5
developer/connecting/connect_timeout.md
Normal file
5
developer/connecting/connect_timeout.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Setting a Connect Timeout
|
||||
|
||||
Each library has its own, language preferred way, to pass connection options. For example, to set the maximum time to connect to a server to 10 seconds:
|
||||
|
||||
!INCLUDE "../../_examples/connect_options.html"
|
||||
5
developer/connecting/default_server.md
Normal file
5
developer/connecting/default_server.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Connecting to the Default Server
|
||||
|
||||
Some libraries also provide a special way to connect to a *default* url, which is general `nats://localhost:4222`:
|
||||
|
||||
!INCLUDE "../../_examples/connect_default.html"
|
||||
5
developer/connecting/intro.md
Normal file
5
developer/connecting/intro.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Connecting to NATS
|
||||
|
||||
Most client libraries provide several ways to connect to the NATS server, gnatsd recently updated to 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](https://nats.io), at `nats://demo.nats.io:4222`, where `4222` is the default port for NATS.
|
||||
|
||||
There are numerous options for a NATS connections.
|
||||
5
developer/connecting/name.md
Normal file
5
developer/connecting/name.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Setting the Connection Name
|
||||
|
||||
Connections can be assigned a name which will appear in some of the server monitoring data. This name is not required but can help in debugging and testing.
|
||||
|
||||
!INCLUDE "../../_examples/connect_name.html"
|
||||
34
developer/connecting/noecho.md
Normal file
34
developer/connecting/noecho.md
Normal file
@ -0,0 +1,34 @@
|
||||
# Turning Off Echo'd Messages
|
||||
|
||||
By default the server will echo messages. This means that if a publisher on a connection sends a message to a subject any subscribers on that same connection may receive the message. Turning off echo is a fairly new feature for the NATS server, but some of the clients already support it.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
digraph {
|
||||
rankdir=LR;
|
||||
subgraph cluster_1 {
|
||||
shape=box;
|
||||
style="rounded";
|
||||
label = "Connection #1";
|
||||
|
||||
publisher [shape=box, style="rounded", label="Publisher"];
|
||||
subscriber_1 [shape=box, style="rounded", label="Subscriber"];
|
||||
}
|
||||
subgraph cluster_2 {
|
||||
shape=box;
|
||||
style="rounded";
|
||||
label = "Connection #2";
|
||||
|
||||
subscriber_2 [shape=box, style="rounded", label="Subscriber"];
|
||||
}
|
||||
|
||||
subject [shape=circle, label="Subject"];
|
||||
|
||||
publisher -> subject [label="msg"];
|
||||
subject -> subscriber_1 [label="echo'd msg", style="dashed"];
|
||||
subject -> subscriber_2 [label="msg"];
|
||||
}
|
||||
</code></div>
|
||||
|
||||
Keep in mind that each connection will have to turn off echo, and that it is per connection, not per application. Also, turning echo on and off can result in a major change to your applications communications protocol since messages will flow or stop flowing based on this setting and the subscribing code won't have any indication as to why.
|
||||
|
||||
!INCLUDE "../../_examples/no_echo.html"
|
||||
28
developer/connecting/pingpong.md
Normal file
28
developer/connecting/pingpong.md
Normal file
@ -0,0 +1,28 @@
|
||||
# Ping/Pong Protocol
|
||||
|
||||
The client and server use a simple PING/PONG protocol to check that they are both still connected. The client will ping the server on a regular, configured interval so that the server usually doesn't have to initiate the PING/PONG interaction.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
digraph g {
|
||||
rankdir=LR
|
||||
client [shape=box, style="rounded", label="NATS Client"];
|
||||
gnatsd [shape=circle, label="gnatsd"];
|
||||
|
||||
client -> gnatsd [label="PING"];
|
||||
gnatsd -> client [label="PONG"];
|
||||
}
|
||||
</code></div>
|
||||
|
||||
## Set the Ping Interval
|
||||
|
||||
If you have a connection that is going to be open a long time with few messages traveling on it, setting this PING interval can control how quickly the client will be notified of a problem. However on connections with a lot of traffic, the client will often figure out there is a problem between PINGS, and as a result the default PING interval is often on the order of minutes. To set the interval to 20s:
|
||||
|
||||
!INCLUDE "../../_examples/ping_20s.html"
|
||||
|
||||
## Limit Outgoing Pings
|
||||
|
||||
The PING/PONG interaction is also used by most of the clients as a way to flush the connection to the server. Clients that cache outgoing messages provide a flush call that will run a PING/PONG. The flush will wait for the PONG to return, telling it that all cached messages have been processed, including the PING. The number of cached PING requests can be limited in most clients to insure that traffic problems are identified early. This configuration for _max outgoing pings_ or similar will usually default to a small number and should only be increased if you are worried about fast flush traffic, perhaps in multiple threads.
|
||||
|
||||
For example, to set the maximum number of outgoing pings to 5:
|
||||
|
||||
!INCLUDE "../../_examples/ping_5.html"
|
||||
29
developer/connecting/protocol.md
Normal file
29
developer/connecting/protocol.md
Normal file
@ -0,0 +1,29 @@
|
||||
# Controlling the Client/Server Protocol
|
||||
|
||||
The protocol between the client and the server is fairly simple and relies on a control line and sometimes a body. The control line contains the operations being sent, like PING or PONG, followed by a carriage return and line feed, CRLF or "\r\n". The server has a setting that can limit the maximum size of a control line. For PING and PONG this doesn't come into play, but for messages that contain subject names, the control line length can be important. The server is also configured with a maximum payload size, which limits the size of a message body. The server sends the maximum payload size to the client at connect time but doesn't currently tell the client the maximum control line size.
|
||||
|
||||
## Set the Maximum Control Line Size
|
||||
|
||||
Some clients will try to limit the control line size on themselves to prevent an error from the server. These clients may or may not allow you to set the size being used, but if they do, the size should be set to match the server configuration.
|
||||
|
||||
For example, to set the maximum control line size to 2k:
|
||||
|
||||
!INCLUDE "../../_examples/control_2k.html"
|
||||
|
||||
## Get the Maximum Payload Size
|
||||
|
||||
While the client can't control the maximum payload size, clients may provide a way for applications to get the size after the connection is made. This will allow the application to chunk or limit data as needed to pass through the server.
|
||||
|
||||
!INCLUDE "../../_examples/max_payload.html"
|
||||
|
||||
## Turn On Pedantic Mode
|
||||
|
||||
The NATS server provides a _pedantic_ mode that does extra checks on the protocol. By default, this setting is off but you can turn it on:
|
||||
|
||||
!INCLUDE "../../_examples/connect_pedantic.html"
|
||||
|
||||
## Turn On/Off Verbose Mode
|
||||
|
||||
The NATS server also provide a _verbose_ mode. By default, verbose mode is enabled and the server will reply to every message from the client with either a +OK or a -ERR. Most clients turn off verbose mode, which disables all of the +OK traffic. Errors are rarely subject to verbose mode and client libraries handle them as documented. To turn on verbose mode, likely for testing:
|
||||
|
||||
!INCLUDE "../../_examples/connect_verbose.html"
|
||||
5
developer/connecting/specific_server.md
Normal file
5
developer/connecting/specific_server.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Connecting to a Specific Server
|
||||
|
||||
For example, to connect to the demo server with a URL:
|
||||
|
||||
!INCLUDE "../../_examples/connect_url.html"
|
||||
5
developer/receiving/async.md
Normal file
5
developer/receiving/async.md
Normal file
@ -0,0 +1,5 @@
|
||||
# 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 by the library. Check your libraries documentation for any resource usage associated with asynchronous subscriptions. The following example is the same as the previous one only with asynchronous code:
|
||||
|
||||
!INCLUDE "../../_examples/subscribe_async.html"
|
||||
26
developer/receiving/drain.md
Normal file
26
developer/receiving/drain.md
Normal file
@ -0,0 +1,26 @@
|
||||
# Draining Connections and Subscriptions
|
||||
|
||||
A new feature in 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. Which means the library will halt messages in any pending queue or cache for subscribers. When you drain a subscription or connection, it will process any cached/pending messages before closing.
|
||||
|
||||
For a connection the process is essentially:
|
||||
|
||||
1. Drain subscriptions
|
||||
2. Stop new messages from being published
|
||||
3. Flush any remaining messages
|
||||
4. Close
|
||||
|
||||
!INCLUDE "../../_examples/drain_conn.html"
|
||||
|
||||
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 queue timing.
|
||||
|
||||
The mechanics of drain for a subscription are simpler:
|
||||
|
||||
1. Unsubscribe at the server
|
||||
2. Process known 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.
|
||||
3
developer/receiving/intro.md
Normal file
3
developer/receiving/intro.md
Normal file
@ -0,0 +1,3 @@
|
||||
# Receiving Messages
|
||||
|
||||
Receiving messages with NATS can be very library dependent. Some languages, like Go or Java, can 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 server 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 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.
|
||||
25
developer/receiving/queues.md
Normal file
25
developer/receiving/queues.md
Normal file
@ -0,0 +1,25 @@
|
||||
# Queue Subscriptions
|
||||
|
||||
Using queues, from a subscription standpoint, is super easy. The application simply includes a queue name with the subscription.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
digraph g {
|
||||
rankdir=LR
|
||||
publisher [shape=box, style="rounded", label="PUB updates"];
|
||||
subject [shape=circle, label="gnatsd"];
|
||||
sub1 [shape=box, style="rounded", label="SUB updates workers"];
|
||||
sub2 [shape=box, style="rounded", label="SUB updates workers"];
|
||||
sub3 [shape=box, style="rounded", label="SUB updates workers"];
|
||||
|
||||
publisher -> subject [label="msgs 1,2,3"];
|
||||
subject -> sub1 [label="msg 2"];
|
||||
subject -> sub2 [label="msg 1"];
|
||||
subject -> sub3 [label="msg 3"];
|
||||
}
|
||||
</code></div>
|
||||
|
||||
For 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.
|
||||
5
developer/receiving/reply.md
Normal file
5
developer/receiving/reply.md
Normal file
@ -0,0 +1,5 @@
|
||||
# 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. In the publishing examples we sent a request for the current time. The following code will listen for that request and respond with the time.
|
||||
|
||||
!INCLUDE "../../_examples/subscribe_w_reply.html"
|
||||
5
developer/receiving/structure.md
Normal file
5
developer/receiving/structure.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Receiving Structured Data
|
||||
|
||||
In the publishing examples, we showed how to send JSON through NATS but you can receive encoded data as well. Each client library may provide tools to help with this encoding. The core traffic to the NATS server will always be byte arrays.
|
||||
|
||||
!INCLUDE "../../_examples/subscribe_json.html"
|
||||
6
developer/receiving/sync.md
Normal file
6
developer/receiving/sync.md
Normal file
@ -0,0 +1,6 @@
|
||||
|
||||
# Synchronous Subscriptions
|
||||
|
||||
Synchronous subscriptions require the application to poll 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 example, to subscribe to the subject `updates` and receive a single message you could do:
|
||||
|
||||
!INCLUDE "../../_examples/subscribe_sync.html"
|
||||
13
developer/receiving/unsub_after.md
Normal file
13
developer/receiving/unsub_after.md
Normal file
@ -0,0 +1,13 @@
|
||||
# Unsubscribing After a Specified Number of 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. There are a few important things to know about auto unsubscribe. First, 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. Or 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.
|
||||
|
||||
Second, 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"
|
||||
5
developer/receiving/unsubscribing.md
Normal file
5
developer/receiving/unsubscribing.md
Normal file
@ -0,0 +1,5 @@
|
||||
# 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"
|
||||
15
developer/receiving/wildcards.md
Normal file
15
developer/receiving/wildcards.md
Normal file
@ -0,0 +1,15 @@
|
||||
# Wildcards
|
||||
|
||||
There is no special code to subscribe with a wildcard subject. The main technique that may come in to play 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"
|
||||
7
developer/reconnect/buffer.md
Normal file
7
developer/reconnect/buffer.md
Normal file
@ -0,0 +1,7 @@
|
||||
# Buffering Messages During Reconnect Attempts
|
||||
|
||||
There is another setting that comes in to play during reconnection. This setting controls how much memory the client library will hold in the form of outgoing messages while it is disconnected. During a short reconnect, the client will generally allow applications to publish messages but because the server is offline, will be cached in the client. The library will then send those messages on reconnect. When the maximum reconnect buffer is reached, messages will no longer be publishable by the client.
|
||||
|
||||
!INCLUDE "../../_examples/reconnect_5mb.html"
|
||||
|
||||
> *As mentioned throughout this document, each client library may behave slightly differently. Please check the documentation for the library you are using.*
|
||||
5
developer/reconnect/disable.md
Normal file
5
developer/reconnect/disable.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Disable Reconnect
|
||||
|
||||
You can disable automatic reconnect with connection options:
|
||||
|
||||
!INCLUDE "../../_examples/reconnect_none.html"
|
||||
5
developer/reconnect/events.md
Normal file
5
developer/reconnect/events.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Listening for Reconnect Events
|
||||
|
||||
Because reconnect is primarily under the covers many libraries provide an event listener you can use to be notified of reconnect events. This event can be especially important for applications sending a lot of messages.
|
||||
|
||||
!INCLUDE "../../_examples/reconnect_event.html"
|
||||
3
developer/reconnect/intro.md
Normal file
3
developer/reconnect/intro.md
Normal file
@ -0,0 +1,3 @@
|
||||
# Reconnecting
|
||||
|
||||
Most, if not all, of the client libraries will reconnect to the server if they are disconnected due to a network problem. The reconnect logic can differ by library, so check your client libraries. In general, the client will try to connect to all of the servers it knows about, either through the URLs provided in `connect` or the URLs provided by its most recent server. The library may have several options to help control reconnect behavior.
|
||||
5
developer/reconnect/max.md
Normal file
5
developer/reconnect/max.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Set the Number of Reconnect Attempts
|
||||
|
||||
Applications can set the maximum reconnect attempts. Generally, this will limit the actual number of attempts total, but check your library documentation. For example, in Java, if the client knows about 3 servers and the maximum reconnects is set to 2, it will not try all of the servers. On the other hand, if the maximum is set to 6 it will try all of the servers twice before considering the reconnect a failure and closing.
|
||||
|
||||
!INCLUDE "../../_examples/reconnect_10x.html"
|
||||
5
developer/reconnect/random.md
Normal file
5
developer/reconnect/random.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Avoiding the Thundering Herd
|
||||
|
||||
When a server goes down, there is a possible anti-pattern called the *Thundering Herd* where all of the clients try to reconnect immediately creating a denial of service attack. In order to prevent this, most NATS client libraries randomize the servers they attempt to connect to. This setting has no effect if only a single server is used, but in the case of a cluster, randomization, or shuffling, will ensure that no one server bears the brunt of the client reconnect attempts.
|
||||
|
||||
!INCLUDE "../../_examples/reconnect_no_random.html"
|
||||
5
developer/reconnect/wait.md
Normal file
5
developer/reconnect/wait.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Pausing Between Reconnect Attempts
|
||||
|
||||
It doesn’t make much sense to try to connect to the same server over and over. To prevent this sort of thrashing, and wasted reconnect attempts, libraries provide a wait setting. This setting will pause the reconnect logic if the same server is being tried multiple times. In the previous example, if you have 3 servers and 6 attempts, the Java library would loop over the three servers. If none were connectable, it will then try all three again. However, the Java client doesn’t wait between each attempt, only when trying the same server again, so in that example the library may never wait. If on the other hand, you only provide a single server URL and 6 attempts, the library will wait between each attempt.
|
||||
|
||||
!INCLUDE "../../_examples/reconnect_10s.html"
|
||||
5
developer/security/intro.md
Normal file
5
developer/security/intro.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Securing Connections
|
||||
|
||||
NATS provides several forms of security for your messages. First, you can turn on authorization which limits access to the NATS server. Second, access to specific subjects can be controlled. Third, you can use TLS to encrypt traffic between clients and the server. Finally, TLS can be used to verify client identities using certificates. By combining all of these methods you can protect access to data and data in motion.
|
||||
|
||||
The client doesn't have control over access controls, but clients do provide the configurations required to authenticate with the server and to turn on TLS.
|
||||
23
developer/security/tls.md
Normal file
23
developer/security/tls.md
Normal file
@ -0,0 +1,23 @@
|
||||
# Encrypting Connections with TLS
|
||||
|
||||
While authentication limits which clients can connect, TLS can be used to check the server’s identity and the client’s identity and will encrypt the traffic between the two. The most secure version of TLS with NATS is to use verified client certificates. In this mode, the client can check that it trusts the certificate sent by `gnatsd` but the server will also check that it trusts the certificate sent by the client. From an applications perspective connecting to a server that does not verify client certificates may appear identical. Under the covers, disabling TLS verification removes the server side check on the client’s certificate. When started in TLS mode, `gnatsd` will require all clients to connect with TLS. Moreover, if configured to connect with TLS, client libraries will fail to connect to a server without TLS.
|
||||
|
||||
The [Java examples repository](https://github.com/nats-io/java-nats-examples/tree/master/src/main/resources) contains certificates for starting the server in TLS mode.
|
||||
|
||||
```sh
|
||||
> gnatsd -c /src/main/resources/tls.conf
|
||||
or
|
||||
> gnatsd -c /src/main/resources/tls_verify.conf
|
||||
```
|
||||
|
||||
## Connecting with TLS
|
||||
|
||||
Connecting to a server with TLS is primarily an exercise in setting up the certificate and trust managers. For example:
|
||||
|
||||
!INCLUDE "../../_examples/connect_tls.html"
|
||||
|
||||
## Connecting with the TLS Protocol
|
||||
|
||||
Some clients may support the `tls` protocol as well as a manual setting to turn on TLS. However, in that case there is likely some form of default or environmental settings to allow the TLS libraries to find certificate and trust stores.
|
||||
|
||||
!INCLUDE "../../_examples/connect_tls_url.html"
|
||||
26
developer/security/token.md
Normal file
26
developer/security/token.md
Normal file
@ -0,0 +1,26 @@
|
||||
|
||||
# Authenticating with a Token
|
||||
|
||||
Tokens are basically random strings, much like a password, and can provide a simple authentication mechanism in some situations. However, tokens are only as safe as they are secret so other authentication schemes can provide more security in large installations.
|
||||
|
||||
For this example, start the server using:
|
||||
|
||||
```sh
|
||||
> gnatsd --auth mytoken
|
||||
```
|
||||
|
||||
The code uses localhost:4222 so that you can start the server on your machine to try them out.
|
||||
|
||||
## Connecting with a Token
|
||||
|
||||
!INCLUDE "../../_examples/connect_token.html"
|
||||
|
||||
## Connecting with a Token in the URL
|
||||
|
||||
Some client libraries will allow you to pass the token as part of the server URL using the form:
|
||||
|
||||
> nats://_token_@server:port
|
||||
|
||||
Again, once you construct this URL you can connect as if this was a normal URL.
|
||||
|
||||
!INCLUDE "../../_examples/connect_token_url.html"
|
||||
35
developer/security/userpass.md
Normal file
35
developer/security/userpass.md
Normal file
@ -0,0 +1,35 @@
|
||||
# Authenticating with a User and Password
|
||||
|
||||
For this example, start the server using:
|
||||
|
||||
```sh
|
||||
> gnatsd --user myname --pass password
|
||||
```
|
||||
|
||||
You can encrypt passwords to pass to `gnatsd` using a simple tool provided by the server:
|
||||
|
||||
```sh
|
||||
> go run mkpasswd.go -p
|
||||
> password: password
|
||||
> bcrypt hash: $2a$11$1oJy/wZYNTxr9jNwMNwS3eUGhBpHT3On8CL9o7ey89mpgo88VG6ba
|
||||
```
|
||||
|
||||
and use the hashed password in the server config. The client still uses the plain text version.
|
||||
|
||||
The code uses localhost:4222 so that you can start the server on your machine to try them out.
|
||||
|
||||
## Connecting with a User/Password
|
||||
|
||||
When logging in with a password `gnatsd` will take either a plain text password or an encrypted password.
|
||||
|
||||
!INCLUDE "../../_examples/connect_userpass.html"
|
||||
|
||||
## Connecting with a User/Password in the URL
|
||||
|
||||
Most clients make it easy to pass the user name and password by accepting them in the URL for the server. This standard format is:
|
||||
|
||||
> nats://_user_:_password_@server:port
|
||||
|
||||
Using this format, you can connect to a server using authentication as easily as you connected with a URL:
|
||||
|
||||
!INCLUDE "../../_examples/connect_userpass_url.html"
|
||||
9
developer/sending/caches.md
Normal file
9
developer/sending/caches.md
Normal file
@ -0,0 +1,9 @@
|
||||
# Caches, Flush and Ping
|
||||
|
||||
For performance reasons, most if not all, of the client libraries will cache outgoing data so that bigger chunks can be written to the network at one time. This may be as simple as a byte buffer that stores up a few messages before being pushed to the network. It is the libraries job to make sure messages flow in a high performance manner. But there may be times when an application needs to know that a message has "hit the wire." In this case, applications can use a flush call to tell the library to move data through the system.
|
||||
|
||||
!INCLUDE "../../_examples/flush.html"
|
||||
|
||||
## Flush and Ping/Pong
|
||||
|
||||
Many of the client libraries use the PING/PONG interaction built into the NATS protocol to insure that flush pushed all of the cached messages to the server. When an application calls flush, in this case, the library will put a PING on the outgoing queue of messages, and wait for the server to send PONG before saying that the flush was successful.
|
||||
5
developer/sending/intro.md
Normal file
5
developer/sending/intro.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Sending Messages
|
||||
|
||||
NATS sends and receives messages using a protocol that includes a target subject, an optional reply subject and an array of bytes. Some libraries may provide helpers to convert other data formats to and from bytes, but the NATS server will treat all messages as opaque byte arrays. All of the NATS clients are designed to make sending a message simple. For example, to send the string “All is Well” to the “updates” subject as a UTF-8 string of bytes you would do:
|
||||
|
||||
!INCLUDE "../../_examples/publish_bytes.html"
|
||||
5
developer/sending/replyto.md
Normal file
5
developer/sending/replyto.md
Normal file
@ -0,0 +1,5 @@
|
||||
# Including a Reply Subject
|
||||
|
||||
The optional reply-to field when publishing a message can be used on the receiving side to respond. The reply-to subject is often called an _inbox_, and some libraries may provide a method for generating unique inbox subjects. For example to send a request to the subject `time`, with no content for the messages, you might:
|
||||
|
||||
!INCLUDE "../../_examples/publish_with_reply.html"
|
||||
9
developer/sending/request_reply.md
Normal file
9
developer/sending/request_reply.md
Normal file
@ -0,0 +1,9 @@
|
||||
# Request-Reply
|
||||
|
||||
The pattern of sending a message and receiving a response is encapsulated in most client libraries into a request method. Under the covers this method will publish a message with a unique reply-to subject and wait for the response before returning. In the older versions of some libraries a completely new reply-to subject is created each time. In newer versions, a subject hierarchy is used so that a single subscriber in the client library listens for a wildcard, and requests are sent with a unique child subject of a single subject.
|
||||
|
||||
The primary difference between the request method and publishing with a reply-to is that the library is only going to accept one response, and in most libraries the request will be treated as a synchronous action. The library may provide a way to set the timeout. For example, updating the previous publish example we may request `time` with a one second timeout:
|
||||
|
||||
!INCLUDE "../../_examples/request_reply.html"
|
||||
|
||||
You can also build your own request-reply using publish-subscribe if you need a different semantic or timing.
|
||||
7
developer/sending/structure.md
Normal file
7
developer/sending/structure.md
Normal file
@ -0,0 +1,7 @@
|
||||
# Sending Structured Data
|
||||
|
||||
Some client libraries provide helpers to send structured data while others depend on the application to perform any encoding and decoding and just take byte arrays for sending. The following example shows how to send JSON but this could easily be altered to send a protocol buffer, YAML or some other format. JSON is a text format so we also have to encode the string in most languages to bytes. We are using UTF-8, the JSON standard encoding.
|
||||
|
||||
Take a simple _stock ticker_ that sends the symbol and price of each stock:
|
||||
|
||||
!INCLUDE "../../_examples/publish_json.html"
|
||||
1
developer/tutorials/intro.md
Normal file
1
developer/tutorials/intro.md
Normal file
@ -0,0 +1 @@
|
||||
# Tutorials
|
||||
185
developer/tutorials/pubsub.md
Normal file
185
developer/tutorials/pubsub.md
Normal file
@ -0,0 +1,185 @@
|
||||
# Explore NATS Pub/Sub
|
||||
|
||||
NATS is a publish subscribe messaging system. Subscribers listening on a subject name receive messages on that subject. If the subscriber is not actively listening on the subject, the message is not received. Subscribers can use the wildcard subjects `*` to match a single token to match the tail of a subject.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
digraph nats_pub_sub {
|
||||
graph [splines=ortho, nodesep=1];
|
||||
|
||||
sub1 [shape="box", label="SUB\ncom.msg.one"];
|
||||
pub1 [shape="box", label="PUB\ncom.msg.one"];
|
||||
non_active [shape="box", label="Non-Active\nSubscriber"];
|
||||
|
||||
{
|
||||
rank=same
|
||||
pub1 sub1 non_active
|
||||
}
|
||||
|
||||
gnatsd [shape="box", label="NATS", width=8];
|
||||
|
||||
sub2 [shape="box", label="SUB\ncom.msg.one"];
|
||||
sub3 [shape="box", label="SUB\ncom.msg.two"];
|
||||
sub4 [shape="box", label="SUB\ncom.msg.*"];
|
||||
|
||||
{
|
||||
rank=same
|
||||
sub2 sub3 sub4
|
||||
}
|
||||
|
||||
pub1 -> gnatsd [penwidth=2];
|
||||
gnatsd -> sub1 [penwidth=2];
|
||||
gnatsd -> non_active [style=dashed color=red arrowhead="none"];
|
||||
|
||||
gnatsd -> sub2 [penwidth=2];
|
||||
gnatsd -> sub3 [style=dashed color=red arrowhead="none"];
|
||||
gnatsd -> sub4 [penwidth=2];
|
||||
}
|
||||
</code></div>
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Go and the NATS server should be installed.
|
||||
|
||||
## 1. Start the NATS server
|
||||
|
||||
```sh
|
||||
% nats-server
|
||||
```
|
||||
|
||||
When the server starts successfully, you will see the following messages:
|
||||
|
||||
```sh
|
||||
[1] 2015/08/12 15:18:22.301550 [INF] Starting gnatsd version 0.6.4
|
||||
[1] 2015/08/12 15:18:22.301762 [INF] Listening for client connections on 0.0.0.0:4222
|
||||
[1] 2015/08/12 15:18:22.301769 [INF] gnatsd is ready
|
||||
```
|
||||
|
||||
The NATS server listens for client connections on TCP Port 4222.
|
||||
|
||||
## 2. Start a shell or command prompt session
|
||||
|
||||
You will use this session to run an example NATS client subscriber program.
|
||||
|
||||
## 3. CD to the Go client examples directory
|
||||
|
||||
```sh
|
||||
% cd $GOPATH/src/github.com/nats-io/nats/examples
|
||||
```
|
||||
|
||||
## 4. Run the client subscriber program
|
||||
|
||||
```sh
|
||||
% go run nats-sub.go <subject>
|
||||
```
|
||||
|
||||
Where `<subject>` is a subject to listen on. A valid subject is a string that is unique in the system.
|
||||
|
||||
For example:
|
||||
|
||||
```sh
|
||||
% go run nats-sub.go msg.test
|
||||
```
|
||||
|
||||
You should see the message: *Listening on [msg.test]*
|
||||
|
||||
## 5. Start another shell or command prompt session
|
||||
|
||||
You will use this session to run a NATS publisher client.
|
||||
|
||||
## 6. CD to the examples directory
|
||||
|
||||
```sh
|
||||
% cd $GOPATH/src/github.com/nats-io/nats/examples
|
||||
```
|
||||
|
||||
## 7. Publish a NATS message
|
||||
|
||||
```sh
|
||||
% go run nats-pub.go <subject> <message>
|
||||
```
|
||||
|
||||
Where `<subject>` is the subject name and `<message>` is the text to publish.
|
||||
|
||||
For example:
|
||||
|
||||
```sh
|
||||
% go run nats-pub.go msg.test hello
|
||||
```
|
||||
|
||||
or
|
||||
|
||||
```sh
|
||||
% go run nats-pub.go msg.test "NATS MESSAGE"
|
||||
```
|
||||
|
||||
## 8. Verify message publication and receipt
|
||||
|
||||
You should see that the publisher sends the message: *Published [msg.test] : 'NATS MESSAGE'*
|
||||
|
||||
And that the subscriber receives the message: *[#1] Received on [msg.test]: 'NATS MESSAGE'*
|
||||
|
||||
Note that if the receiver does not get the message, check that you are using the same subject name for the publisher and the subscriber.
|
||||
|
||||
## 9. Publish another message
|
||||
|
||||
```sh
|
||||
% go run nats-pub.go msg.test "NATS MESSAGE 2"
|
||||
```
|
||||
|
||||
You should see that the subscriber receive message 2. Note that the message count is incremented each time your subscribing client receives a message on that subject:
|
||||
|
||||
## 10. Start another shell or command prompt session
|
||||
|
||||
You will use this session to run a second NATS subscriber.
|
||||
|
||||
## 11. CD to the examples directory
|
||||
|
||||
```sh
|
||||
% cd $GOPATH/src/github.com/nats-io/nats/examples
|
||||
```
|
||||
|
||||
## 12. Subscribe to the message
|
||||
|
||||
```sh
|
||||
% go run nats-sub.go msg.test
|
||||
```
|
||||
|
||||
## 13. Publish another message using the publisher client
|
||||
|
||||
```sh
|
||||
% go run nats-pub.go msg.test "NATS MESSAGE 3"
|
||||
```
|
||||
|
||||
Verify that both subscribing clients receive the message.
|
||||
|
||||
## 14. Start another shell or command prompt session
|
||||
|
||||
You will use this session to run a third NATS subscriber.
|
||||
|
||||
## 15. CD to the examples directory
|
||||
|
||||
```sh
|
||||
% cd $GOPATH/src/github.com/nats-io/nats/examples
|
||||
```
|
||||
|
||||
## 16. Subscribe to a different message
|
||||
|
||||
```sh
|
||||
% go run nats-sub.go msg.test.new
|
||||
```
|
||||
|
||||
All the but last subscriber receives the message. Why? Because that subscriber is not listening on the message subject used by the publisher.
|
||||
|
||||
## 17. Update the last subscriber to use a wildcard
|
||||
|
||||
NATS supports the use of wildcard characters for message subscribers. (You cannot publish a message using a wildcard subject.)
|
||||
|
||||
Change the last subscriber the listen on msg.* and run it:
|
||||
|
||||
```sh
|
||||
% go run nats-sub.go msg.*
|
||||
```
|
||||
|
||||
## 18. Publish another message
|
||||
|
||||
This time, all three subscribing clients should receive the message.
|
||||
71
developer/tutorials/queues.md
Normal file
71
developer/tutorials/queues.md
Normal file
@ -0,0 +1,71 @@
|
||||
# Explore NATS Queueing
|
||||
|
||||
NATS supports a form of load balancing using queue groups. Subscribers register a queue group name. A single subscriber in the group is randomly selected to receive the message.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Go and the NATS server should be installed.
|
||||
|
||||
## 1. Start the NATS server
|
||||
|
||||
```sh
|
||||
nats-server
|
||||
```
|
||||
|
||||
## 2. Clone the repositories for each client examples
|
||||
|
||||
```sh
|
||||
go get github.com/nats-io/go-nats
|
||||
git clone https://github.com/nats-io/node-nats.git
|
||||
git clone https://github.com/nats-io/ruby-nats.git
|
||||
```
|
||||
|
||||
## 3. Run the Go client subscriber with queue group name
|
||||
|
||||
```sh
|
||||
cd $GOPATH/src/github.com/nats-io/go-nats/examples
|
||||
go run nats-qsub.go foo my-queue
|
||||
```
|
||||
|
||||
## 4. Install and run the Node client subscriber with queue group name
|
||||
|
||||
```sh
|
||||
npm install nats
|
||||
cd node-nats/examples
|
||||
node node-sub foo my-queue
|
||||
```
|
||||
|
||||
## 5. Install and run the Ruby client subscriber with queue group name
|
||||
|
||||
```sh
|
||||
gem install nats
|
||||
nats-queue foo my-queue &
|
||||
```
|
||||
|
||||
**6. Run another Go client subscriber *without* the queue group.
|
||||
|
||||
```sh
|
||||
cd $GOPATH/src/github.com/nats-io/go-nats/examples
|
||||
go run nats-sub.go foo
|
||||
```
|
||||
|
||||
## 7. Publish a NATS message using the Go client
|
||||
|
||||
```sh
|
||||
cd $GOPATH/src/github.com/nats-io/go-nats/examples
|
||||
go run nats-pub.go foo "Hello NATS!"
|
||||
```
|
||||
|
||||
## 8. Verify message publication and receipt
|
||||
|
||||
You should see that the publisher sends the message: *Published [foo] : 'Hello NATS!'*
|
||||
|
||||
You should see that only one of the my-queue group subscribers receives the message. In addition, the Go client subscriber not in the my-queue group should also receive the message.
|
||||
|
||||
## 9. Publish another message
|
||||
|
||||
```sh
|
||||
go run nats-pub.go foo "Hello NATS Again!"
|
||||
```
|
||||
|
||||
You should see that a different queue group subscriber receives the message this time, chosen at random among the 3 queue group members.
|
||||
41
developer/tutorials/reqreply.md
Normal file
41
developer/tutorials/reqreply.md
Normal file
@ -0,0 +1,41 @@
|
||||
# Explore NATS Request/Reply
|
||||
|
||||
NATS supports request/reply messaging. In this tutorial you explore how to exchange point-to-point messages using NATS.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Go and the NATS server should be installed.
|
||||
|
||||
## 1. Start the NATS server
|
||||
|
||||
```sh
|
||||
% gnatsd
|
||||
```
|
||||
|
||||
## 2. Start two terminal sessions
|
||||
|
||||
You will use these sessions to run the NATS request and reply clients.
|
||||
|
||||
## 3. Change to the examples directory
|
||||
|
||||
```sh
|
||||
% cd $GOPATH/src/github.com/nats-io/nats/examples
|
||||
```
|
||||
|
||||
## 4. In one terminal, run the reply client listener
|
||||
|
||||
```sh
|
||||
% go run nats-rply.go foo "this is my response"
|
||||
```
|
||||
|
||||
You should see the message `Receiver is listening`, and that the NATS receiver client is listening on the "help.please" subject. The reply client acts as a receiver, listening for message requests. In NATS, the receiver is a subscriber.
|
||||
|
||||
## 5. In the other terminal, run the request client
|
||||
|
||||
```sh
|
||||
% go run nats-req.go foo "request payload"
|
||||
```
|
||||
|
||||
The NATS requestor client makes a request by sending the message "some message" on the “help.please” subject.
|
||||
|
||||
The NATS receiver client receives the message, formulates the reply ("OK, I CAN HELP!!!), and sends it to the inbox of the requester.
|
||||
Loading…
x
Reference in New Issue
Block a user