From 34220c41145de0b121cf35fc6051250e9335d636 Mon Sep 17 00:00:00 2001 From: Matthias Hanel Date: Sun, 9 Feb 2020 15:07:03 -0500 Subject: [PATCH] Incorporating comments from PR Signed-off-by: Matthias Hanel --- SUMMARY.md | 3 ++- developing-with-nats/connecting/name.md | 2 +- developing-with-nats/connecting/pingpong.md | 8 ++++++-- developing-with-nats/events/slow.md | 2 +- developing-with-nats/receiving/README.md | 2 +- developing-with-nats/reconnect/events.md | 1 - developing-with-nats/reconnect/wait.md | 4 +++- developing-with-nats/security/nkey.md | 2 +- developing-with-nats/security/token.md | 2 +- developing-with-nats/tutorials/reqreply.md | 4 ++-- 10 files changed, 18 insertions(+), 12 deletions(-) diff --git a/SUMMARY.md b/SUMMARY.md index 8851cd9..09d8cba 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -22,6 +22,7 @@ * [Connecting to the Default Server](developing-with-nats/connecting/default_server.md) * [Connecting to a Specific Server](developing-with-nats/connecting/specific_server.md) * [Connecting to a Cluster](developing-with-nats/connecting/cluster.md) + * [Connection Name](developing-with-nats/connecting/name.md) * [Setting a Connect Timeout](developing-with-nats/connecting/connect_timeout.md) * [Ping/Pong Protocol](developing-with-nats/connecting/pingpong.md) * [Controlling the Client/Server Protocol](developing-with-nats/connecting/protocol.md) @@ -29,8 +30,8 @@ * [Automatic Reconnections](developing-with-nats/reconnect/README.md) * [Disabling Reconnect](developing-with-nats/reconnect/disable.md) * [Set the Number of Reconnect Attempts](developing-with-nats/reconnect/max.md) - * [Pausing Between Reconnect Attempts](developing-with-nats/reconnect/wait.md) * [Avoiding the Thundering Herd](developing-with-nats/reconnect/random.md) + * [Pausing Between Reconnect Attempts](developing-with-nats/reconnect/wait.md) * [Listening for Reconnect Events](developing-with-nats/reconnect/events.md) * [Buffering Messages During Reconnect Attempts](developing-with-nats/reconnect/buffer.md) * [Securing Connections](developing-with-nats/security/README.md) diff --git a/developing-with-nats/connecting/name.md b/developing-with-nats/connecting/name.md index 7b83f4c..e41ce42 100644 --- a/developing-with-nats/connecting/name.md +++ b/developing-with-nats/connecting/name.md @@ -1,6 +1,6 @@ # 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. +Connections can be assigned a name which will appear in some of the server monitoring data. This name is not required, but is **highly recommended** as a friendly connection name will help in monitoring, error reporting, debugging, and testing. {% tabs %} {% tab title="Go" %} diff --git a/developing-with-nats/connecting/pingpong.md b/developing-with-nats/connecting/pingpong.md index e4a16d4..04ea312 100644 --- a/developing-with-nats/connecting/pingpong.md +++ b/developing-with-nats/connecting/pingpong.md @@ -1,10 +1,14 @@ # Ping/Pong Protocol -The client and server use a simple PING/PONG protocol to check that either of them are still connected to the other. On a regular interval the client will ping the server, which responds with a pong. Once a configurable maximum of outstanding pings without a single pong reply is hit, the connection is closed as stale. Together these two values define a timeout for the connection. In the presence of traffic, such as messages or client side pings, the server will not initiate the PING/PONG interaction. +The client and server use a simple PING/PONG protocol to check that either of them are still connected to the other. On a regular interval the client will ping the server, which responds with a pong. ![](../../.gitbook/assets/pingpong.svg) -If you have a connection that is going to be open a long time with few messages traveling on it, setting the PING interval and/or limit how many are outstanding, 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 and limit outstanding pings to 5, thus force a closed connection after 100s of inactivity: +Once a configurable maximum of outstanding pings without a single pong reply is hit, the connection is closed as stale. Together these two values define a timeout for the connection which specifies how quickly the client will be notified of a problem. This will also help when there is a remote network partition where the operating system does not detect a socket error. Upon connection close the client will attempt to reconnect. When it knows about other server, these will be tried next. + +In the presence of traffic, such as messages or client side pings, the server will not initiate the PING/PONG interaction. + +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 and limit outstanding pings to 5, thus force a closed connection after 100s of inactivity: {% tabs %} {% tab title="Go" %} diff --git a/developing-with-nats/events/slow.md b/developing-with-nats/events/slow.md index cf291cb..7dd837a 100644 --- a/developing-with-nats/events/slow.md +++ b/developing-with-nats/events/slow.md @@ -101,7 +101,7 @@ await nc.subscribe("updates", cb=cb, pending_bytes_limit=5*1024*1024, pending_ms {% tab title="Ruby" %} ```ruby -# The Ruby NATS client currently does not have option to customize specify a subscribers pending limits. +# The Ruby NATS client currently does not have option to specify a subscribers pending limits. ``` {% endtab %} diff --git a/developing-with-nats/receiving/README.md b/developing-with-nats/receiving/README.md index 6fbe358..5bad6b4 100644 --- a/developing-with-nats/receiving/README.md +++ b/developing-with-nats/receiving/README.md @@ -6,4 +6,4 @@ Some languages, like Go or Java, provide synchronous and asynchronous APIs, whil 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. When an application is done with a subscription it unsubscribes telling the server to stop sending messages. -If a connection has multiple subscriptions using identical or overlapping subjects (say `foo` and `>`), the same message will be sent to the client multiple times. +A client will receive a message for each matching subscription ,so if a connection has multiple subscriptions using identical or overlapping subjects (say `foo` and `>`) the same message will be sent to the client multiple times. diff --git a/developing-with-nats/reconnect/events.md b/developing-with-nats/reconnect/events.md index 1671e3e..8ea3bef 100644 --- a/developing-with-nats/reconnect/events.md +++ b/developing-with-nats/reconnect/events.md @@ -1,7 +1,6 @@ # 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. -- [ ] what do clients commonly do if reconnect is in progress and say a message is published? Block or error? {% tabs %} {% tab title="Go" %} diff --git a/developing-with-nats/reconnect/wait.md b/developing-with-nats/reconnect/wait.md index 0d59475..50d84dd 100644 --- a/developing-with-nats/reconnect/wait.md +++ b/developing-with-nats/reconnect/wait.md @@ -1,6 +1,8 @@ # 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. Generally clients make sure that between two reconnect attempts to the **same** server at least a certain amount of time has passed. The concrete implementation depends on the library used. +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, especially when using TLS, libraries provide a wait setting. Generally clients make sure that between two reconnect attempts to the **same** server at least a certain amount of time has passed. The concrete implementation depends on the library used. + +This setting not only prevents wasting client resources, it also alleviates a [_thundering herd_](random.md) situation when additional servers are not available. {% tabs %} {% tab title="Go" %} diff --git a/developing-with-nats/security/nkey.md b/developing-with-nats/security/nkey.md index 54dd975..ac8393c 100644 --- a/developing-with-nats/security/nkey.md +++ b/developing-with-nats/security/nkey.md @@ -1,6 +1,6 @@ # Authenticating with an NKey -The 2.0 version of NATS server introduces a new challenge response authentication option. This challenge response is based on a wrapper we call [NKeys](../../nats-server/configuration/securing_nats/auth_intro/nkey_auth.md). The server can use these keys in several ways for authentication. The simplest is for the server to be configured with a list of known public keys and for the clients to respond to the challenge by signing it with its private key. (A printable private NKey is referred to as seed). This challenge-response ensures security by ensuring that the client has the private key, but also protects the private key from the server which never has to actually see it. +The 2.0 version of NATS server introduces a new challenge response authentication option. This challenge response is based on a wrapper we call [NKeys](../../nats-server/configuration/securing_nats/auth_intro/nkey_auth.md). The server can use these keys in several ways for authentication. The simplest is for the server to be configured with a list of known public keys and for the clients to respond to the challenge by signing it with its private key. (A printable private NKey is referred to as seed). This challenge-response ensures security by ensuring that the client has the private key, but also protects the private key from the server, which never has access to it! Handling challenge response may require more than just a setting in the connection options, depending on the client library. diff --git a/developing-with-nats/security/token.md b/developing-with-nats/security/token.md index 850c141..f7fe283 100644 --- a/developing-with-nats/security/token.md +++ b/developing-with-nats/security/token.md @@ -1,6 +1,6 @@ # 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. +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. It is highly recommended to use one of the other NATS authentication mechanisms. For this example, start the server using: diff --git a/developing-with-nats/tutorials/reqreply.md b/developing-with-nats/tutorials/reqreply.md index 6c387e0..285128b 100644 --- a/developing-with-nats/tutorials/reqreply.md +++ b/developing-with-nats/tutorials/reqreply.md @@ -35,9 +35,9 @@ This means that the NATS receiver client is listening for requests messages on t ### 5. In the other terminal, run the request client ```bash -% go run nats-req/main.go help.please "some message" +% go run nats-req/main.go help.please "I need help!" ``` -The NATS requestor client makes a request by sending the message "some message" on the “help.please” subject. +The NATS requestor client makes a request by sending the message "I need help!" 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.