taigrr/nats.docs
1
0
Fork 0
mirror of https://github.com/taigrr/nats.docs synced 2025-01-18 04:03:23 -08:00
Code Issues Projects Releases Wiki Activity

Updates

Browse Source 
Signed-off-by: Derek Collison <derek@nats.io>
This commit is contained in:
Derek Collison
2019-06-06 15:42:25 -07:00
parent d7c6b1ebcf
commit 99da6d13d0
20 changed files with 180 additions and 271 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
developer/concepts/acks.md
View File

@@ -1,6 +1,6 @@
# Acknowledgements
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.
In a system with at-most-once semantics, there are times when messages can be lost. If your application is doing request-reply it should use timeouts to handle any network or application failures. It is always a good idea to place a timeout on a requests and have code that deals with timeouts. When you are publishing an event or data stream, one way to 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 payload.
<div class="graphviz"><code data-viz="dot">
digraph nats_request_reply {
@@ -28,4 +28,4 @@ digraph nats_request_reply {
}
</code></div>
Because the ACK can be empty it can take up very little network bandwidth, but the idea of the ACK turns a simple fire-and-forget into a fire-and-know world where the sender can be sure that the message was received by the other side, or with [scatter-gather](reqreply.md), several other sides.
Because the ACK can be empty it can take up very little network bandwidth, but the idea of the ACK turns a simple fire-and-forget into a fire-and-know world where the sender can be sure that the message was received by the other side, or with a [scatter-gather pattern](reqreply.md), several other sides.

14
developer/concepts/intro.md
View File

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

11
developer/concepts/queue.md
View File

@@ -1,12 +1,13 @@
# Queue Subscribers & Sharing Work
# Queue Subscribers & Scalability
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.
NATS provides a builtin load balancing feature called distributed queues. Using queue subscribers will balance message delivery across a group of subscribers which can be used to provide application fault tolerance and scale workload processing.
To create a queue subscription, subscribers register a queue name. All subscribers with the same queue name form the queue group. 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.
To create a queue subscription, subscribers register a queue name. All subscribers with the same queue name form the queue group. This requires no configuration. As messages on the registered subject are published, one member of the group is chosen randomly to receive the message. Although queue groups have multiple subscribers, each message is consumed by only one.
One of the great features of NATS is that queue groups are defined by the subscribers, not on the server. Applications can create new queue groups without any server change.
One of the great features of NATS is that queue groups are defined by the application and their queue subscribers, not on the server configuration.
Queue subscribers are ideal for auto scaling as you can add or remove them anytime, without any configuration changes or restarting the server or clients.
Queue subscribers are ideal for scaling services. Scale up is as simple as running another application, scale down is terminating the application with a signal that drains the in flight requests.
This flexibility and lack of any configuration changes makes NATS an excellent service communication technology that can work with all platform technologies.
<div class="graphviz"><code data-viz="dot">
digraph nats_queues {

13
developer/concepts/reqreply.md
View File

@@ -1,10 +1,15 @@
# Request-Reply and Scatter-Gather
# 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 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*.
Request-Reply is a common pattern in modern distributed systems. A request is sent and the application either waits on the response with a certain timeout or receives a response asynchronously.
The increased complexity of modern systems requires features such as location transparency, scale up and scale down, observability and more. Many technologies need additional components, sidecars and proxies to accomplish the complete feature set.
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.
NATS supports this pattern with its core communication mechanism, publish and subscribe. A request is published on a given subject with a reply subject, and responders listen on that subject and send responses to the reply subject. Reply subjects
are usually a subject called and _INBOX that will be directed back to the requestor dynamically, regardless of location of either party.
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.
NATS allows multiple responders to run and form dynamic queue groups for transparent scale up. The ability for NATS applications to drain before exiting allows scale down with no requests being dropped. And since NATS is based on publish-subscribe,
observability is as simple as running another application that can view requests and responses to measure latency, watch for anomalies, direct scalability and more.
The power of NATS even allows multiple responses where the first response is utilized and the system efficiently discards the additional ones. This allows for a sophisticated pattern to have multiple responders reduce response latency and jitter.
<div class="graphviz"><code data-viz="dot">
digraph nats_request_reply {

6
developer/concepts/seq_num.md
View File

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

6
developer/connecting/intro.md
View File

@@ -1,9 +1,7 @@
# Connecting to NATS
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](https://nats.io), at `nats://demo.nats.io:4222`, where `4222` is the default port for NATS.
A NATS system is usually identified by a standard URL with the `nats` or `tls` protocol, e.g. nats://demo.nats.io. A NATS system can be a single server, a small cluster or a global super cluster. Throughout these examples we will rely on a single test server, provided by [nats.io](https://nats.io), at `nats://demo.nats.io`, 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.
NATS also supports secure connectivity using TLS via the `tls` protocol. Most clients support auto-detection of a secure connection using the URL protocol `tls`. There is also a demo server running TLS at `tls://demo.nats.io:4443`. The protocol requirement is being made optional for many client 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.
There are numerous options for a NATS connections ranging from timeouts to reconnect settings.

4
developer/connecting/noecho.md
View File

@@ -1,6 +1,8 @@
# 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 will receive the message. Turning off echo is a fairly new feature for the NATS server, but some of the clients already support it.
By default a NATS connection will echo messages if the connection also has interest in the published subject. This means that if a publisher on a connection sends a message to a subject any subscribers on that same connection will receive the message. Clients can opt to turn off this behavior, such that regardless of interest the message will not be delivered to subscribers on the same connection.
The NoEcho option can be useful in BUS patterns where all applications subsribe and publish to the same subject. Usually a publish represents a state change that the application already knows about, so in the case that the application opublishes an updated it does not need to process the update itself.
<div class="graphviz"><code data-viz="dot">
digraph {

14
developer/receiving/drain.md
View File

@@ -1,26 +1,28 @@
# Draining Connections and Subscriptions
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 cached/pending messages before closing.
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 queue timing.
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 subscriptions
1. Drain all subscriptions
2. Stop new messages from being published
3. Flush any remaining messages
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 at the server
2. Process known messages
1. Unsubscribe
2. Process all cached or inflight messages
3. Clean up
The API for drain can generally be used instead of unsubscribe:

6
developer/receiving/intro.md
View File

@@ -1,9 +1,9 @@
# Receiving Messages
Receiving messages with NATS can be very library dependent.
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 server that an application is interested in a particular subject.
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 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.
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.

2
developer/receiving/structure.md
View File

@@ -1,6 +1,6 @@
# Receiving Structured Data
Client libraries may provide tools to help receive structured data, like JSON. The core traffic to the NATS server will always be byte arrays. For libraries that don't provide helpers, you can always encode and decode data before sending the associated bytes to the NATS client.
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:

2
developer/receiving/sync.md
View File

@@ -1,7 +1,7 @@
# 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 situations where a single message is expected, synchronous subscriptions are sometimes easier to manage, depending on the language.
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:

8
developer/reconnect/intro.md
View File

@@ -1,9 +1,7 @@
# 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 library's documentation.
Most, if not all, of the client libraries will reconnect to the NATS system if they are disconnected for any reason. The reconnect logic can differ by library, so check your client library's documentation.
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.
In general, the client will try to connect to all of the servers it knows about, either through the URLs provided in the `connect` call or the URLs provided by the NATS system itself. The NATS system will inform clients of new endpoints that can be used to reconnect. The library may have several options to help control reconnect behavior.
The list of servers used during reconnect is library dependent, but generally is constructed from the list of servers passed to the connect function/options and the list of servers provided by the most recent connected server.
One, sometimes important, detail is that the server URLs provided to clients by servers will use addresses, while the URLs provided to the connect function will usually be host names. As a result, it is possible, on reconnect, for the same server to be tried multiple times without the client knowing about the match.
The list of servers used during reconnect is library dependent, but generally is constructed from connect function/options and the list of servers provided by the NATS system itself. This feature allows NATS applications and the NATS system itself to self heal and reconfigure itself with no additional configuration or intervention.

4
developer/security/intro.md
View File

@@ -1,5 +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.
NATS provides several forms of security, authentication, authorization and isolation. You can turn on authentication which limits access to the NATS system. Accounts allow for isolation of a subject space and groups of applications. Authorization can be used to limit individual users access to specific subjects for publish and subscribe operations. TLS can be used to encrypt all traffic between clients and the NATS system. Finally, TLS can be used to verify client identities using client certificates. By combining all of these methods you can protect access the system and to all message flows.
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.
The client doesn't have control over access controls, but clients do provide the configurations required to authenticate with the system, bind to an account, and to require TLS.

5
developer/security/tls.md
View File

@@ -1,6 +1,6 @@
# 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 `nats-server` but the server will also check that it trusts the certificate sent by the client. From an application's 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, `nats-server` 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.
While authentication limits which clients can connect, TLS can be used to check the server’s identity and optionally the client’s identity and will encrypt all 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 NATS system but the individual server will also check that it trusts the certificate sent by the client. From an application's 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, a `nats-server` 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.
@@ -12,7 +12,8 @@ The [Java examples repository](https://github.com/nats-io/java-nats-examples/tre
## Connecting with TLS
Connecting to a server with TLS is primarily an exercise in setting up the certificate and trust managers. For example:
Connecting to a server with TLS is straightforward. Most clients will automatically use TLS when connected to a NATS system using TLS. Setting up a NATS system to use TLS is primarily an exercise in setting up the certificate and trust managers.
Clients may also need additional information, for example:
!INCLUDE "../../_examples/connect_tls.html"

2
developer/sending/replyto.md
View File

@@ -1,5 +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:
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 most libraries may provide a method for generating unique inbox subjects. Most libraries also provide for the request-reply pattern with a single call. For example to send a request to the subject `time`, with no content for the messages, you might:
!INCLUDE "../../_examples/publish_with_reply.html"

20
developer/tutorials/pubsub.md
View File

@@ -1,6 +1,6 @@
# 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.
NATS is a publish subscribe messaging system. Subscribers listening on a subject 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 tokens such as `*` and `>` to match a single token or to match the tail of a subject.
<div class="graphviz"><code data-viz="dot">
digraph nats_pub_sub {
@@ -9,13 +9,13 @@ digraph nats_pub_sub {
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];
nats-server [shape="box", label="NATS", width=8];
sub2 [shape="box", label="SUB\ncom.msg.one"];
sub3 [shape="box", label="SUB\ncom.msg.two"];
@@ -26,19 +26,19 @@ digraph nats_pub_sub {
sub2 sub3 sub4
}
pub1 -> gnatsd [penwidth=2];
gnatsd -> sub1 [penwidth=2];
gnatsd -> non_active [style=dashed color=red arrowhead="none"];
pub1 -> nats-server [penwidth=2];
nats-server -> sub1 [penwidth=2];
nats-server -> non_active [style=dashed color=red arrowhead="none"];
gnatsd -> sub2 [penwidth=2];
gnatsd -> sub3 [style=dashed color=red arrowhead="none"];
gnatsd -> sub4 [penwidth=2];
nats-server -> sub2 [penwidth=2];
nats-server -> sub3 [style=dashed color=red arrowhead="none"];
nats-server -> sub4 [penwidth=2];
}
</code></div>
## Prerequisites
Go and the NATS server should be installed.
Go and the NATS server should be installed. optionally you can use the demo server located at `nats://demo.nats.io`
### 1. Start the NATS server