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

GitBook: [master] 326 pages and 16 assets modified

Browse Source
This commit is contained in:
Ginger Collison
2019-10-04 17:48:52 +00:00
committed by gitbook-bot
parent 8b7ba5c3bb
commit fb0d5c8355
203 changed files with 4640 additions and 3107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

20
developer/connecting/cluster.md
View File

@@ -1,20 +0,0 @@
# 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 library first tries to connect it will use the list of URLs provided to the connection options or function. These URLs are checked, usually in order, and the first successful connection is used.
After 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.
To insure the initial connection, your code should include a list of reasonable _front line_ servers. Those servers may know about other members of the cluster, and may tell the client about those members. But you don't have to configure the client to pass every valid member of the cluster in the connect method.
By providing the ability to pass multiple connect options NATS can handle the possibility of a machine going down or being unavailable to a client. By adding the ability of the server to feed clients a list of known servers as part of the client-server protocol the mesh created by a cluster can grow and change organically while the clients are running.
*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
View File

@@ -1,5 +0,0 @@
# Setting a Connect Timeout
Each library has its own, language preferred way, to pass connection options. One of the most common options is a connection timeout. To set the maximum time to connect to a server to 10 seconds:
!INCLUDE "../../_examples/connect_options.html"

5
developer/connecting/default_server.md
View File

@@ -1,5 +0,0 @@
# Connecting to the Default Server
Some libraries also provide a special way to connect to a *default* url, which is generally `nats://localhost:4222`:
!INCLUDE "../../_examples/connect_default.html"

7
developer/connecting/intro.md
View File

@@ -1,7 +0,0 @@
# Connecting to 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 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 connection ranging from timeouts to reconnect settings.

11
developer/connecting/noecho.md
View File

@@ -1,11 +0,0 @@
# Turning Off Echo'd Messages
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 subscribe and publish to the same subject. Usually a publish represents a state change that the application already knows about, so in the case where the application publishes an update it does not need to process the update itself.
![](/assets/images/noecho.svg)
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"

19
developer/connecting/pingpong.md
View File

@@ -1,19 +0,0 @@
# 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.
![](/assets/images/pingpong.svg)
## 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
View File

@@ -1,29 +0,0 @@
# 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 internally 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"

9
developer/connecting/specific_server.md
View File

@@ -1,9 +0,0 @@
# Connecting to a Specific Server
The NATS client libraries can take a full URL, `nats://demo.nats.io:4222`, to specify a specific server host and port to connect to.
Libraries are removing the requirement for an explicit protocol and may allow `nats://demo.nats.io:4222` or just `demo.nats.io:4222`. Check with your specific client library's documentation to see what URL formats are supported.
For example, to connect to the demo server with a URL you can use:
!INCLUDE "../../_examples/connect_url.html"