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

28
developing-with-nats-streaming/acks.md Normal file
View File

@@ -0,0 +1,28 @@
# Acknowledgements
## Acknowledgements
Subscribers can use auto-ack or manual-ack. Auto-ack is the default for most clients and is sent by the library when the message callback returns. Manual ack provides more control. The subscription options provide flags to:
* Set manual acks to true
* Set the ack wait used by the server for messages to this subscription
The ack wait is the time the server will wait before resending a message.
```go
sub, err := sc.Subscribe("foo",
func(m *stan.Msg) {
m.Ack()
}, stan.SetManualAckMode(), stan.AckWait(aw))
```
## Max In Flight
Subscribers can set max in flight to rate limit incoming messages. The server will send at most “max in flight” messages before receiving an acknowledgement. Setting max in flight to 1 insures every message is processed in order.
```go
sc.Subscribe("foo", func(m *stan.Msg) {...},
stan.SetManualAckMode(),
stan.MaxInflight(25))
```

28
developing-with-nats-streaming/connecting.md Normal file
View File

@@ -0,0 +1,28 @@
# Connecting to NATS Streaming
First, it is recommended to understand the relation between Streaming and core NATS. You should familiarize yourself with the [concept](../nats-streaming-concepts/relation-to-nats.md).
NATS Streaming is a service on top of NATS. To connect to the service you first connect to NATS and then use the client library to communicate with the server over your NATS connection. Most of the libraries provide a convenience mechanism for connecting in a single step. These convenience methods will take some NATS options, like the cluster ID, and perform the NATS connection first, then run the protocol to connect to the streaming server.
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 `_`_
Connecting to a server running locally on the default port is as simple as this:
```go
sc, err := stan.Connect(clusterID, clientID)
```
If the server runs on port `1234`:
```go
sc, err := stan.Connect(clusterID, clientID, stan.NatsURL(“nats://localhost:1234))
```
Sometimes you may want to provide NATS settings that aren't available in the streaming libraries connect method. Or, you may want to reuse a NATS connection instead of creating a new one. In this case the libraries generally provide a way to connect to streaming with an existing NATS connection:
```go
sc, err := stan.Connect(clusterID, clientID, stan.NatsConn(nc))
```

14
developing-with-nats-streaming/durables.md Normal file
View File

@@ -0,0 +1,14 @@
# Durable Subscriptions
Regular subscriptions remember their position while the client is connected. If the client disconnects the position is lost. Durable subscriptions remember their position even if the client is disconnected.
Durable subscriptions identify themselves with a name. Connect and disconnect won’t affect the durable subscriptions position in the channel.
```go
sc.Subscribe("foo", func(m *stan.Msg) {...}, stan.DurableName("my-durable"))
```
Unsubscribe will cause the server to completely remove the durable subscription.
Check the [concepts](../nats-streaming-concepts/channels/subscriptions/durable.md) section for more information.

254
developing-with-nats-streaming/protocol.md Normal file
View File

@@ -0,0 +1,254 @@
# The Streaming Protocol
You can find a list of all supported client libraries [here](https://nats.io/download/). There are also links to community contributed clients.
In the event you would want to write your own NATS Streaming library, you could have a look at existing libraries to understand the flow. But you need to use [Google Protocol Buffers](https://developers.google.com/protocol-buffers/) to exchange protocols between the client and the server.
## NATS Streaming Protocol
The NATS streaming protocol sits atop the core NATS protocol and uses [Google's Protocol Buffers](https://developers.google.com/protocol-buffers/). Protocol buffer messages are marshaled into bytes and published as NATS messages on specific subjects described below. In communicating with the NATS Streaming Server, the NATS request/reply pattern is used for all protocol messages that have a corresponding reply.
### NATS streaming protocol conventions
**Subject names**: Subject names, including reply subject \(INBOX\) names, are case-sensitive and must be non-empty alphanumeric strings with no embedded whitespace, and optionally token-delimited using the dot character \(`.`\), e.g.:
`FOO`, `BAR`, `foo.bar`, `foo.BAR`, `FOO.BAR` and `FOO.BAR.BAZ` are all valid subject names
`FOO. BAR`, `foo. .bar` and`foo..bar` are \*not- valid subject names
**Wildcards**: NATS streaming does **not** support wildcards in subject subscriptions
**Protocol definition**: The fields of NATS streaming protocol messages are defined in the NATS streaming client [protocol file](https://github.com/nats-io/stan.go/blob/master/pb/protocol.proto).
### NATS streaming protocol messages
The following table briefly describes the NATS streaming protocol messages.
Click the name to see more detailed information, including usage:
#### Protocols
| Message Name | Sent By | Description |
| :--- | :--- | :--- |
| [`ConnectRequest`](protocol.md#connectrequest) | Client | Request to connect to the NATS Streaming Server |
| [`ConnectResponse`](protocol.md#connectresponse) | Server | Result of a connection request |
| [`SubscriptionRequest`](protocol.md#subscriptionrequest) | Client | Request sent to subscribe and retrieve data |
| [`SubscriptionResponse`](protocol.md#subscriptionresponse) | Server | Result of a subscription request |
| [`UnsubscribeRequest`](protocol.md#unsubscriberequest) | Client | Unsubscribe from a subject |
| [`PubMsg`](protocol.md#pubmsg) | Client | Publish a message to a subject |
| [`PubAck`](protocol.md#puback) | Server | An acknowledgement that a published message has been processed on the server |
| [`MsgProto`](protocol.md#msgproto) | Server | A message from the NATS Streaming Server to a subscribing client |
| [`Ack`](protocol.md#ack) | Client | Acknowledges that a message has been received |
| [`Ping`](protocol.md#ping) | Client | Ping sent to server to detect connection loss |
| [`PingResponse`](protocol.md#pingresponse) | Server | Result of a Ping |
| [`CloseRequest`](protocol.md#closerequest) | Client | Request sent to close the connection to the NATS Streaming Server |
| [`CloseResp`](protocol.md#closeresponse) | Server | Result of the close request |
The following sections explain each protocol message.
#### ConnectRequest
**Description**
A connection request is sent when a streaming client connects to the NATS Streaming Server. The connection request contains a unique identifier representing the client, and an inbox subject the client will listen on for incoming heartbeats. The identifier **must** be unique; a connection attempt with an identifier currently in use will fail. The inbox subject is the subject where the client receives incoming heartbeats, and responds by publishing an empty NATS message to the reply subject, indicating it is alive. The NATS Streaming Server will return a [ConnectResponse](protocol.md#connectresponse) message to the reply subject specified in the NATS request message.
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`
**Message Structure**
* `clientID`: A unique identifier for a client
* `heartbeatInbox`: An inbox to which the NATS Streaming Server will send heartbeats for the client to process
* `protocol`: Protocol the client is at
* `connID`: Connection ID, a way to uniquely identify a connection \(no connection should ever have the same\)
* `pingInterval`: Interval at which client wishes to send PINGs \(expressed in seconds\)
* `pingMaxOut`: Maximum number of PINGs without a response after which the connection can be considered lost
[Back to table](protocol.md#protocols)
#### ConnectResponse
**Description**
After a `ConnectRequest` is published, the NATS Streaming Server responds with this message on the reply subject of the underlying NATS request. The NATS Streaming Server requires the client to make requests and publish messages on certain subjects \(described above\), and when a connection is successful, the client saves the information returned to be used in sending other NATS streaming protocol messages. In the event the connection was not successful, an error is returned in the `error` field.
**Message Structure**
* `pubPrefix`: Prefix to use when publishing
* `subRequests`: Subject used for subscription requests
* `unsubRequests`: Subject used for unsubscribe requests
* `closeRequests`: Subject for closing a connection
* `error`: An error string, which will be empty/omitted upon success
* `subCloseRequests`: Subject to use for subscription close requests
* `pingRequests`: Subject to use for PING requests
* `pingInterval`: Interval at which client should send PINGs \(expressed in seconds\).
* `pingMaxOut`: Maximum number of PINGs without a response after which the connection can be considered lost
* `protocol`: Protocol version the server is at
* `publicKey`: Reserved for future use
[Back to table](protocol.md#protocols)
#### SubscriptionRequest
**Description**
A `SubscriptionRequest` is published on the subject returned in the `subRequests` field of a [ConnectResponse](protocol.md#connectresponse), and creates a subscription to a subject on the NATS Streaming Server. This will return a [SubscriptionResponse](protocol.md#subscriptionresponse) message to the reply subject specified in the NATS protocol request message.
**Message Structure**
* `clientID`: Client ID originally provided in the [ConnectRequest](protocol.md#connectrequest)
* `subject`: Formal subject to subscribe to, e.g. foo.bar
* `qGroup`: Optional queue group
* `inbox`: Inbox subject to deliver messages on
* `maxInFlight`: Maximum inflight messages without an acknowledgement allowed
* `ackWaitInSecs`: Timeout for receiving an acknowledgement from the client
* `durableName`: Optional durable name which survives client restarts
* `startPosition`: An enumerated type specifying the point in history to start replaying data
* `startSequence`: Optional start sequence number
* `startTimeDelta`: Optional start time
**StartPosition enumeration**
* `NewOnly`: Send only new messages
* `LastReceived`: Send only the last received message
* `TimeDeltaStart`: Send messages from duration specified in the `startTimeDelta` field.
* `SequenceStart`: Send messages starting from the sequence in the `startSequence` field.
* `First`: Send all available messages
[Back to table](protocol.md#protocols)
#### SubscriptionResponse
**Description**
The `SubscriptionResponse` message is the response from the `SubscriptionRequest`. After a client has processed an incoming [MsgProto](protocol.md#msgproto) message, it must send an acknowledgement to the `ackInbox` subject provided here.
**Message Structure**
* `ackInbox`: subject the client sends message acknowledgements to the NATS Streaming Server
* `error`: error string, empty/omitted if no error
[Back to table](protocol.md#protocols)
#### UnsubscribeRequest
**Description**
The `UnsubscribeRequest` closes or unsubcribes the subscription from the specified subject. The inbox specified is the `inbox` returned from the NATS Streaming Server in the `SubscriptionResponse`. Depending on which subject this request is sent, the action will result in close \(if sent to subject `subCloseRequests`\) or unsubscribe \(if sent to subject `unsubRequests`\)
**Message Structure**
* `clientID`: Client ID originally provided in the [ConnectRequest](protocol.md#connectrequest)
* `subject`: Subject for the subscription
* `inbox`: Inbox subject to identify subscription
* `durableName`: Optional durable name which survives client restarts
[Back to table](protocol.md#protocols)
#### PubMsg
**Description**
The `PubMsg` protocol message is published from a client to the NATS Streaming Server. The GUID must be unique, and is returned in the [PubAck](protocol.md#puback) message to correlate the success or failure of storing this particular message.
**Message Structure**
* `clientID`: Client ID originally provided in the [ConnectRequest](protocol.md#connectrequest)
* `guid`: a guid generated for this particular message
* `subject`: subject
* `data`: payload
* `connID`: Connection ID. For servers that know about this field, clientID can be omitted
[Back to table](protocol.md#protocols)
#### PubAck
**Description**
The `PubAck` message is an acknowledgement from the NATS Streaming Server that a message has been processed. The message arrives on the subject specified on the reply subject of the NATS message the `PubMsg` was published on. The GUID is the same GUID used in the `PubMsg` being acknowledged. If an error string is present, the message was not persisted by the NATS Streaming Server and no guarantees regarding persistence are honored. `PubAck` messages may be handled asynchronously from their corresponding `PubMsg` in the client.
**Message Structure**
* `guid`: GUID of the message being acknowledged by the NATS Streaming Server
* `error`: An error string, empty/omitted if no error
[Back to table](protocol.md#protocols)
#### MsgProto
**Description**
The `MsgProto` message is received by client from the NATS Streaming Server, containing the payload of messages sent by a publisher. A `MsgProto` message that is not acknowledged with an [Ack](protocol.md#ack) message within the duration specified by the `ackWaitInSecs` field of the subscription request will be redelivered.
**Message Structure**
* `sequence`: Globally ordered sequence number for the subject's channel
* `subject`: Subject
* `data`: Payload
* `timestamp`: Time the message was stored in the server.
* `redelivered`: Flag specifying if the message is being redelivered
[Back to table](protocol.md#protocols)
#### Ack
**Description**
An `Ack` message is an acknowledgement from the client that a [MsgProto](protocol.md#msgproto) message has been considered received. It is published to the `ackInbox` field of the [SubscriptionResponse](protocol.md#subscriptionresponse).
**Message Structure**
* `subject`: Subject of the message being acknowledged
* `sequence`: Sequence of the message being acknowledged
[Back to table](protocol.md#protocols)
#### Ping
**Description**
A `Ping` message is sent to the server at configured interval to check that the connection ID is still valid. This should be used only if client is at protocol 1, and has sent a `connID` in the [ConnectRequest](protocol.md#connectrequest) protocol.
**Message Structure**
* `connID`: The connection ID
[Back to table](protocol.md#protocols)
#### PingResponse
**Description**
This is a response from the server to a `Ping` from the client. If the content is not empty, it will be the error indicating to the client why the connection is no longer valid.
**Message Structure**
* `error`: Error string, empty/omitted if no error
[Back to table](protocol.md#protocols)
#### CloseRequest
**Description**
A `CloseRequest` message is published on the `closeRequests` subject from the [ConnectResponse](protocol.md#connectresponse), and notifies the NATS Streaming Server that the client connection is closing, allowing the server to free up resources. This message should **always** be sent when a client is finished using a connection.
**Message Structure**
* `clientID`: Client ID originally provided in the [ConnectRequest](protocol.md#connectrequest)
[Back to table](protocol.md#protocols)
#### CloseResponse
**Description**
The `CloseResponse` is sent by the NATS Streaming Server on the reply subject of the `CloseRequest` NATS message. This response contains any error that may have occurred with the corresponding close call.
**Message Structure**
* `error`: error string, empty/omitted if no error
[Back to table](protocol.md#protocols)

22
developing-with-nats-streaming/publishing.md Normal file
View File

@@ -0,0 +1,22 @@
# Publishing to a Channel
The streaming client library can provide a method for publishing synchronously. These publish methods block until the ACK is returned by the server. An error or exception is used to indicate a timeout or other error.
```go
err := sc.Publish("foo", []byte("Hello World"))
```
Streaming libraries can also provide a way to publish asynchronously. An ACK callback of some kind is required. The library will publish the message and notify the callback on ACK or timeout. The global id associated with the message being sent is returned from publish so that the application can identify it on callback.
```go
ackHandler := func(ackedNuid string, err error){ ... }
nuid, err := sc.PublishAsync("foo", []byte("Hello World"), ackHandler)
```
Even in this mode, the call will still block if the library has a number of published messages without having received an ACK from the server. The default can be changed when creating the connection.
```go
sc, err := sc.Connect(clusterID, clientName, stan.MaxPubAcksInflight(1000))
```

40
developing-with-nats-streaming/queues.md Normal file
View File

@@ -0,0 +1,40 @@
# Queue Subscriptions
Queue subscriptions are created like other subscriptions with the addition of a queue name.
```go
qsub1, _ := sc.QueueSubscribe(channelName,
queueName, func(m *stan.Msg) {...})
qsub2, _ := sc.QueueSubscribe(channelName,
queueName, func(m *stan.Msg) {...})
```
Multiple subscriptions using the same channel and queue name are members of the same queue group. That means that if a message is published on that channel, only one member of the group receives the message. Other subscriptions receive messages independently of the queue groups, that is, a message is delivered to all subscriptions and one member of each queue group.
To create a durable queue subscription, simply add a durable name:
```go
qsub, err := sc.QueueSubscribe(channelName,
queueName, func(m *stan.Msg) {...},
stan.DurableName("durable-name"))
```
Subscriptions options apply to each member independently, notably, the `AckWait` and `MaxInflight`. Those two members of the same queue group use different options for redelivery and max inflight.
```go
qsub1, _ := sc.QueueSubscribe(channelName,
queueName, func(m *stan.Msg) {...},
stan.AckWait(5*time.Second),
stan.MaxInflight(5))
qsub2, _ := sc.QueueSubscribe(channelName,
queueName, func(m *stan.Msg) {...},
stan.AckWait(20*time.Second),
stan.MaxInflight(10))
```
If the queue subscription is durable, only the last member calling `Unsubscribe()` will cause the durable queue group to be removed from the server.
Check the [concepts](../nats-streaming-concepts/channels/subscriptions/queue-group.md) section for more information.

75
developing-with-nats-streaming/receiving.md Normal file
View File

@@ -0,0 +1,75 @@
# Receiving Messages from a Channel
Clients subscribe to channels by name. Wildcards are not supported. Receiving messages is similar to core NATS. Messages in streaming use protocol buffers and will have a bit more structure than NATS opaque messages. Client messages are still presented and accepted as raw/opaque binary data. The use of protocol buffers is transparent.
Subscriptions come in several forms:
* Regular
* Durable
* Queue
* Queue/Durable
For more details on the various types, check the [concepts](../nats-streaming-concepts/channels/subscriptions/) 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'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:
* The last message received
```go
sub, err := sc.Subscribe("foo",
func(m *stan.Msg) {...},
stan.StartWithLastReceived())
```
* The beginning of the channel
```go
sub, err := sc.Subscribe("foo",
func(m *stan.Msg) {...},
stan.DeliverAllAvailable())
```
* A specific message, indexing starts at 1
```go
sub, err := sc.Subscribe("foo",
func(m *stan.Msg) {...},
stan.StartAtSequence(22))
```
* A specific time the message arrived in the channel
```go
var startTime time.Time
...
sub, err := sc.Subscribe("foo",
func(m *stan.Msg) {...},
stan.StartAtTime(startTime))
```
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",
func(m *stan.Msg) {...},
stan.AckWait(20*time.Second))
```
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
err := sub.Close()
```
To unsubscribe:
```go
err := sub.Unsubscribe()
```
_Note: If a connection is closed without explicitly closing the subscriptions, the subscriptions are implicitly closed, not unsubscribed._

129
developing-with-nats-streaming/streaming.md Normal file
View File

@@ -0,0 +1,129 @@
# Introduction
## Deciding to Use At-Least-Once Delivery
The decision to use the at least once delivery through NATS streaming is important. It will affect your deployment, usage, performance, and total cost of ownership.
In modern systems applications can expose services or produce and consume data streams. At a high level, if observability is required, applications need to consume messages in the future, need to come consume at their own pace, or need all messages, then at-least-once semantics \(NATS streaming\) makes sense. If observation needs to be realtime and the most recent message is the most important, the use _At-Most-Once_ delivery semantics with core NATS.
Just be aware that using an a least once guarantee is the facet of messaging with the highest cost in terms of compute and storage. The NATS Maintainers highly recommend a strategy of defaulting to core NATS using a service pattern \(request/reply\) to guarantee delivery at the application level and using streaming only when necessary. This ultimately results in a more stable distributed system. Entire systems such as Cloud Foundry have been built upon core NATS with no messaging persistence involved.
### When to use NATS Streaming
NATS streaming is ideal when:
* A historical record of a stream is required. This is when a replay of data
is required by a consumer.
* The last message produced on a stream is required for initialization and
the producer may be offline.
* A-priori knowledge of consumers is not available, but consumers must receive
messages. This is often a false assumption.
* Data producers and consumers are highly decoupled. They may be online at
different times and consumers must receive messages.
* The data in messages being sent have a lifespan beyond that of the
intended application lifespan.
* Applications need to consume data at their own pace.
Note that no assumptions should ever be made of who will receive and process data in the future, or for what purpose.
### When to use Core NATS
Using core NATS is ideal for the fast request path for scalable services where there is tolerance for message loss or when applications themselves handle message delivery guarantees.
These include:
* Service patterns where there is a tightly coupled request/reply
* A request is made, and the application handles error cases upon timeout
\(resends, errors, etc\). \_\_Relying on a messaging system to resend here is
considered an anti-pattern.\_\_
* Where only the last message received is important and new messages will
be received frequently enough for applications to tolerate a lost message.
This might be a stock ticker stream, frequent exchange of messages in a
service control plane, or device telemetry.
* Message TTL is low, where the value of the data being transmitted degrades
or expires quickly.
* The expected consumer set for a message is available a-priori and consumers
are expected to be live. The request/reply pattern works well here or
consumers can send an application level acknowledgement.
We've found that core NATS is sufficient for most use cases. Also note that nothing precludes the use of both core NATS and NATS streaming side by side, leveraging the strengths of each to build a highly resilient distributed system.
## NATS Streaming Overview
Where NATS provides at most once quality of service, streaming adds at least once. Streaming is implemented as a request-reply service on top of NATS. Streaming messages are encoded as protocol buffers, the streaming clients use NATS to talk to the streaming server. The streaming server organizes messages in channels and stores them in files and databases. ACKs are used to ensure delivery in both directions.
> Sometimes the maintainers will refer to NATS as "nats core" and streaming as "stan" or "streaming".
Messages to the streaming service are opaque byte arrays, just as they are with NATS. However, the streaming server protocol uses protocol buffers to wrap these byte arrays. So if you listen to the NATS traffic the messages will appear as protocol buffers, while the actual data sent and received will simply be byte arrays.
NATS streaming uses the concept of a channel to represent an ordered collection of messages. Clients send to and receive from channels instead of subjects. The subjects used by the streaming libraries and server are managed internally. Channels do not currently support wildcards. Channels aren’t raw subjects. Streaming isn’t raw NATS. The streaming libraries hide some of the differences.
Think of channels as a First In First Out \(FIFO\) queue. Messages are added until the configured limit is reached. Old messages can be set to expire based on configuration, making room for new messages. Subscriptions don’t affect channel content, that is, when a message is acknowledged, it is not removed from the channel.
Positions in the channel are specified in multiple ways:
* Sequence number - counting from 1
* Time
* Time delta \(converted to time on client\)
New subscriptions can also specify last received to indicate they only want new messages. Sequence numbers are persistent so when message \#1 goes away, the oldest message is then message \#2. If you try to go to a position before the oldest message, you will be moved to the oldest message.
## Subscription Types
NATS Streaming supports several types of subscriptions:
* Regular
* Durable
* Queue
* Durable/Queue
Regular subscriptions pick the location of their channel position on creation and it is stored while the subscriber is active. Durable subscriptions store their position in the streaming server. Queue subscriptions share a channel position. Durable/Queue subscriptions share a channel position stored in the server. All subscriptions can be configured with a starting position, but only new durable subscriptions and new regular subscriptions respect the request.
All subscriptions define their position on creation. Regular subscriptions lose their position if the application crashes, the app disconnects or they unsubscribe. Durable subscriptions maintain their position through disconnect, subscriber close, but not through unsubscribe. The position on reconnect comes from the server not the options in both cases. Queue subscriptions share a position. Regular queue subscriptions lose their position on the last disconnect/unsubscribe. Durable queue subscriptions maintain their position through disconnect, but not through the last unsubscribe. Positions provided in options are ignored after the position is set.
## Acknowledgements
In order to implement at least once delivery NATS streaming uses ACK messages for publishers and subscribers. Each message sent from the streaming server to the client must be acknowledged or it will be re-delivered. Developers must switch their mind set. The same message can arrive more than once. Messages should be idempotent. The client libraries can help with ACKs. Subscriptions can use manual or automatic ACKs. Manual ACKs are safer, since the program controls when they happen. An ACK wait setting is used to define the timeout before an ACK is considered missing.
> Ack wait = 10s means that the server won’t redeliver for at least 10s
Using ACKs for each message sent can be a performance hit - round trip per message. NATS streaming allows subscriptions to set a max in flight value. Max in flight determines how many unacknowledged messages can be sent to the client. Ack Wait is used to decide when the ACK for a message has failed and it needs to be redelivered. New and redelivered messages are sent upon availability, in order.
Messages are sent in order, when they are available:
* Max inflight = 2
* Send msg 1 and msg 2
* ACK 2
* Message 3 arrives at the server
* Send message 3 \(since it is available\)
* When Ack wait expires, msg 1 is available
* Send msg 1 \(1 and 3 are in flight\)
The streaming server sends available messages in order, but 1 isn’t available until its Ack wait expires. If max in flight = 1 then only 1 message is on the wire at a time, it will be re-sent until it is acknowledged. Re-delivered messages will not come out of order in this situation.
Setting max in flight to a number greater than 1 requires some thought and foresight to deal with redelivery scenarios.
Max in flight is a per-subscription setting. In the case of queue subscribers, each client can set the value. Normally, each client will use the same value but this is not a requirement.
NATS streaming uses acknowledgements on the sending side as well as the subscribing side. The streaming server acknowledges messages it receives and has persisted. A maximum in flight setting is used for publishers. No more than max in flight can be on their way to the server at one time. The library may provide various mechanisms to handle publisher ACKs. **The application must manage redelivery to the server**.