mirror of
https://github.com/taigrr/nats.docs
synced 2025-01-18 04:03:23 -08:00
Fix Typos
This PR fixes a number of typos and grammatical errors found within the NATS documentation. Note that it is not comprehensive and there are likely other errors to be found.
This commit is contained in:
Nick Calibey
parent
6ec19ef95f
commit
1fd055097b
@ -1,6 +1,6 @@
|
||||
# Acknowledgements
|
||||
|
||||
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.
|
||||
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 ensure 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 a [scatter-gather pattern](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.
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
# 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.
|
||||
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 use to find each other.
|
||||
|
||||
<div class="graphviz"><code data-viz="dot">
|
||||
digraph g {
|
||||
@ -16,7 +16,7 @@ digraph g {
|
||||
}
|
||||
</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.
|
||||
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 cannot contain whitespace. For safety across clients, ASCII characters should be used, although this is subject to change in the future.
|
||||
|
||||
## Subject Hierarchies
|
||||
|
||||
@ -30,8 +30,6 @@ time.eu.east
|
||||
time.eu.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.
|
||||
@ -76,4 +74,4 @@ digraph g {
|
||||
|
||||
### Monitoring and Wire Taps
|
||||
|
||||
Subject to your security configuration, wildcards can be used for monitoring by creating something sometimes called a *wire tap*. In the simplest case you can create a subscriber for `>`. This application will receive all messages, again subject to security settings, sent on your NATS cluster.
|
||||
Subject to your security configuration, wildcards can be used for monitoring by creating something sometimes called a *wire tap*. In the simplest case you can create a subscriber for `>`. This application will receive all messages -- again, subject to security settings -- sent on your NATS cluster.
|
||||
|
||||
@ -4,4 +4,4 @@ A NATS system is usually identified by a standard URL with the `nats` or `tls` p
|
||||
|
||||
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.
|
||||
There are numerous options for a NATS connection ranging from timeouts to reconnect settings.
|
||||
|
||||
@ -1,13 +1,13 @@
|
||||
# Buffering Messages During Reconnect Attempts
|
||||
|
||||
The NATS client libraries, try as much as possible to be fire and forget. One of the features that may be included in the library you are using is the ability to buffer outgoing messages when the connection is down.
|
||||
The NATS client libraries try as much as possible to be fire and forget. One of the features that may be included in the library you are using is the ability to buffer outgoing messages when the connection is down.
|
||||
|
||||
During a short reconnect, these client can allow applications to publish messages that, 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.
|
||||
|
||||
Be aware, while the message appears to be sent to the application it is possible that it is never sent because the connection is never remade. Your applications should use patterns like acknowledgements to insure delivery.
|
||||
Be aware, while the message appears to be sent to the application it is possible that it is never sent because the connection is never remade. Your applications should use patterns like acknowledgements to ensure delivery.
|
||||
|
||||
For clients that support this feature, you are able to configure the size of this buffer with bytes, messages or both.
|
||||
|
||||
!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.*
|
||||
> *As mentioned throughout this document, each client library may behave slightly differently. Please check the documentation for the library you are using.*
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
# 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.
|
||||
When a server goes down, there is a possible anti-pattern called the *Thundering Herd* where all of the clients try to reconnect immediately, thus 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.
|
||||
|
||||
However, if you want to disable the randomization process, so that servers are always checked in the same order, you can do that in most libraries with a connection options:
|
||||
|
||||
!INCLUDE "../../_examples/reconnect_no_random.html"
|
||||
!INCLUDE "../../_examples/reconnect_no_random.html"
|
||||
|
||||
@ -6,7 +6,7 @@ NATS Streaming is a service on top of NATS. To connect to the service you first
|
||||
|
||||
Connecting to a streaming server requires a cluster id, defined by the server configuration, and a client ID defined by the client.
|
||||
|
||||
_Client ID should contain only alphanumeric characters, `-` or `_`_
|
||||
*Client ID should contain only alphanumeric characters, `-` or `_`*
|
||||
|
||||
Connecting to a server running locally on the default port is as simple as this:
|
||||
|
||||
@ -23,4 +23,4 @@ Sometimes you may want to provide NATS settings that aren't available in the str
|
||||
|
||||
```go
|
||||
sc, err := stan.Connect(clusterID, clientID, stan.NatsConn(nc))
|
||||
```
|
||||
```
|
||||
|
||||
@ -54,7 +54,7 @@ A connection request is sent when a streaming client connects to the NATS Stream
|
||||
|
||||
More advanced libraries can set the protocol to 1 and send a connection ID which in combination with ping interval and ping max out allows the library to detect that the connection to the server is lost.
|
||||
|
||||
This request is published to a subject comprised of the `<discover-prefix>.cluster-id`, for example, if a NATS Streaming Server was started with a cluster-id of `mycluster`, and the default prefix was used, the client publishes to `_STAN.discover.mycluster`
|
||||
This request is published to a subject comprised of the `<discover-prefix>.cluster-id`. For example, if a NATS Streaming Server was started with a cluster-id of `mycluster`, and the default prefix was used, the client publishes to `_STAN.discover.mycluster`
|
||||
|
||||
##### Message Structure
|
||||
|
||||
@ -262,4 +262,4 @@ The `CloseResponse` is sent by the NATS Streaming Server on the reply subject of
|
||||
|
||||
- `error`: error string, empty/omitted if no error
|
||||
|
||||
[Back to table](#protocols)
|
||||
[Back to table](#protocols)
|
||||
|
||||
@ -11,7 +11,7 @@ Subscriptions come in several forms:
|
||||
|
||||
For more details on the various types, check the [concepts](/nats_streaming/channels/subscriptions/subscriptions.md) section.
|
||||
|
||||
***Note: message callbacks are invoked serially, one message at a time. If your application does not care about processing ordering and would prefer the messages to be dispatched concurrently, it is the application responsibility to move them to some internal queue to be picked up by threads/go routines.***
|
||||
***Note: message callbacks are invoked serially, one message at a time. If your application does not care about processing ordering and would prefer the messages to be dispatched concurrently, it is the application's responsibility to move them to some internal queue to be picked up by threads/go routines.***
|
||||
|
||||
Subscriptions set their starting position on creation using position or time. For example, in Go you can start at:
|
||||
|
||||
@ -49,7 +49,7 @@ sub, err := sc.Subscribe("foo",
|
||||
stan.StartAtTime(startTime))
|
||||
```
|
||||
|
||||
To set the delay after which the server should attempt to redeliver a message for which it has not receive an acknowledgment:
|
||||
To set the delay after which the server should attempt to redeliver a message for which it has not received an acknowledgment:
|
||||
|
||||
```go
|
||||
sub, err := sc.Subscribe("foo",
|
||||
@ -57,7 +57,7 @@ sub, err := sc.Subscribe("foo",
|
||||
stan.AckWait(20*time.Second))
|
||||
```
|
||||
|
||||
When an application wishes to stop receiving, but want to maintain the connection opened, the subscription should be closed. There are two ways to stop a subscription, either "close" it, or "unsubscribe" it. For non durable subscriptions, this is equivalent since the subscription will be completely removed. For durable subscriptions, close means that the server will stop delivering, but remember the durable subscription. Unsubscribe, however, means that the server will remove the state of this subscription.
|
||||
When an application wishes to stop receiving, but wants to maintain the connection opened, the subscription should be closed. There are two ways to stop a subscription, either "close" it, or "unsubscribe" it. For non durable subscriptions, this is equivalent since the subscription will be completely removed. For durable subscriptions, close means that the server will stop delivering, but remember the durable subscription. Unsubscribe, however, means that the server will remove the state of this subscription.
|
||||
|
||||
To simply close:
|
||||
```go
|
||||
|
||||
@ -1,9 +1,9 @@
|
||||
# Durable
|
||||
|
||||
If an application wishes to resume message consumption from where it previously stopped, it needs to create a durable subscription. It does so by providing a durable name, which is combined with the client ID provided when the client created its connection. The server then maintain the state for this subscription even after the client connection is closed.
|
||||
If an application wishes to resume message consumption from where it previously stopped, it needs to create a durable subscription. It does so by providing a durable name, which is combined with the client ID provided when the client created its connection. The server then maintains the state for this subscription even after the client connection is closed.
|
||||
|
||||
***Note: The starting position given by the client when restarting a durable subscription is ignored.***
|
||||
|
||||
When the application wants to stop receiving messages on a durable subscription, it should close - but *not unsubscribe*- this subscription. If a given client library does not have the option to close a subscription, the application should close the connection instead.
|
||||
When the application wants to stop receiving messages on a durable subscription, it should close - but *not unsubscribe* - this subscription. If a given client library does not have the option to close a subscription, the application should close the connection instead.
|
||||
|
||||
When the application wants to delete the subscription, it must unsubscribe it. Once unsubscribed, the state is removed and it is then possible to re-use the durable name, but it will be considered a brand new durable subscription, with the start position being the one given by the client when creating the durable subscription.
|
||||
When the application wants to delete the subscription, it must unsubscribe it. Once unsubscribed, the state is removed and it is then possible to re-use the durable name, but it will be considered a brand new durable subscription, with the start position being the one given by the client when creating the durable subscription.
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
When consumers want to consume from the same channel but each receive a different message, as opposed to all receiving the same messages, they need to create a queue subscription. When a queue group name is specified, the server will send each messages from the log to a single consumer in the group. The distribution of these messages is not specified, therefore applications should not rely on an expected delivery scheme.
|
||||
|
||||
After the first queue member is created, any other member joining the group will receive messages based on where the server is in the message log for that particular group. That means that starting position given by joining members is ignored by the server.
|
||||
After the first queue member is created, any other member joining the group will receive messages based on where the server is in the message log for that particular group. That means that the starting position given by joining members is ignored by the server.
|
||||
|
||||
When the last member of the group leaves (subscription unsubscribed/closed/or connection closed), the group is removed from the server. The next application creating a subscription with the same name will create a new group, starting at the start position given in the subscription request.
|
||||
|
||||
|
||||
@ -2,10 +2,10 @@
|
||||
|
||||
When the server sends a message to a consumer, it expects to receive an ACK from this consumer. The consumer is the one specifying how long the server should wait before resending all unacknowledged messages to the consumer.
|
||||
|
||||
When the server restarts and recovers unacknowledged messages for a subscription, it will first attempt to redelivery those messages before sending new messages. However, if during the initial redelivery some messages don't make it to the client, the server cannot know that and will enable delivery of new messages.
|
||||
When the server restarts and recovers unacknowledged messages for a subscription, it will first attempt to redeliver those messages before sending new messages. However, if during the initial redelivery some messages don't make it to the client, the server cannot know that and will enable delivery of new messages.
|
||||
|
||||
***So it is possible for an application to receive redelivered messages mixed with new messages. This is typically what happens outside of the server restart scenario.***
|
||||
|
||||
For queue subscriptions, if a member has unacknowledged messages, when this member `AckWait` (which is the duration given to the server before the server should attempt to redeliver unacknowledged messages) time elapses, the messages are redelivered to any other member in the group (including itself).
|
||||
For queue subscriptions, if a member has unacknowledged messages, when this member's `AckWait` (which is the duration given to the server before the server should attempt to redeliver unacknowledged messages) time elapses, the messages are redelivered to any other member in the group (including itself).
|
||||
|
||||
If a queue member leaves the group, its unacknowledged messages are redistributed to other queue members.
|
||||
If a queue member leaves the group, its unacknowledged messages are redistributed to other queue members.
|
||||
|
||||
@ -8,4 +8,4 @@ When receiving ACKs from the consumer, the server will then deliver more message
|
||||
|
||||
A subscription can be created to start at any point in the message log, either by message sequence, or by time.
|
||||
|
||||
Following pages describe all types of subscription.
|
||||
The following pages describe all the types of subscriptions.
|
||||
|
||||
@ -14,4 +14,4 @@ nats-streaming-server -store file -dir store-c -clustered -nats_server nats://lo
|
||||
|
||||
For a given cluster ID, if more than one server is started with `cluster_bootstrap` set to true, each server with this parameter will report the misconfiguration and exit.
|
||||
|
||||
The very first server that bootstrapped the cluster can be restarted, however, the operator **must remove the datastores** of the other servers that were incorrectly started with the bootstrap parameter before attempting to restart them. If they are restarted -even without the `-cluster_bootstrap` parameter- but with existing state, they will once again start as a leader.
|
||||
The very first server that bootstrapped the cluster can be restarted, however, the operator **must remove the datastores** of the other servers that were incorrectly started with the bootstrap parameter before attempting to restart them. If they are restarted with existing state, even without the `-cluster_bootstrap` parameter, they will once again start as a leader.
|
||||
|
||||
@ -1,3 +1,3 @@
|
||||
# Shared State
|
||||
|
||||
Actual file replication to multiple disks is not handled by the Streaming server. This - if required - needs to be handled by the user. For the FileStore implementation that we currently provide, the data store needs to be mounted by all servers in the FT group (e.g. an NFS Mount (Gluster in Google Cloud or EFS in Amazon).
|
||||
Actual file replication to multiple disks is not handled by the Streaming server. This - if required - needs to be handled by the user. For the FileStore implementation that we currently provide, the data store needs to be mounted by all servers in the FT group (e.g. an NFS Mount, Gluster in Google Cloud or EFS in Amazon).
|
||||
|
||||
@ -1,11 +1,12 @@
|
||||
# Relation to NATS
|
||||
|
||||
NATS Streaming Server by default embeds a [NATS](https://github.com/nats-io/nats-server) server. That is, the Streaming server is not a server per-se, but instead, a client to a NATS Server.<br>
|
||||
NATS Streaming Server by default embeds a [NATS](https://github.com/nats-io/nats-server) server. That is, the Streaming server is not a server per-se, but instead, a client to a NATS Server.
|
||||
|
||||
It means that Streaming clients are not directly connected to the streaming server, but instead communicate with the streaming server *through* NATS Server.
|
||||
|
||||
This detail is important when it comes to Streaming clients connections to the Streaming server. Indeed, since there is no direct connection, the server knows if a client is connected based on heartbeats.
|
||||
|
||||
***It is therefore strongly recommended for clients to close their connection when the application exit, otherwise the server will consider these clients connected (sending data, etc...) until it detects missing heartbeats.***
|
||||
***It is therefore strongly recommended for clients to close their connection when the application exits, otherwise the server will consider these clients connected (sending data, etc...) until it detects missing heartbeats.***
|
||||
|
||||
The streaming server creates internal subscriptions on specific subjects to communicate with its clients and/or other servers.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user