gogrlx/nats-server
1
0
Fork 0
mirror of https://github.com/gogrlx/nats-server.git synced 2026-04-02 03:38:42 -07:00
Code Issues Packages Projects Releases Wiki Activity

adr documenting the idle_heartbeat feature for consumers (#2330)

Browse Source 
* adr documenting the idle_heartbeat feature for consumers
[ci skip]
This commit is contained in:
Alberto Ricart
2021-07-01 09:46:35 -05:00
committed by GitHub
parent a389e46efb
commit a2480f15b4
1 changed files with 52 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

52
doc/adr/0009-js-idle-heartbeat.md Normal file
View File

@@ -0,0 +1,52 @@
# 9. js-idle-heartbeat
Date: 2021-06-30
## Status
Accepted
## Context
The JetStream ConsumerConfig option `idle_heartbeat` enables server-side
heartbeats to be sent to the client. To enable the option on the consumer simply
specify it with a value representing the number of nanoseconds that the server
should use as notification interval.
The server will only notify after the specified interval has elapsed and no new
messages have been delivered to the consumer. Delivering a message to the
consumer resets the interval.
The idle heartbeats notifications are sent to the consumer's subscription as a
regular NATS message. The message will have a `code` of `100` with a
`description` of `Idle Heartbeat`. The message will contain additional headers
that the client can use to re-affirm that it has not lost any messages:
- `Nats-Last-Consumer` indicates the last consumer sequence delivered to the
client. If `0`, no messages have been delivered.
- `Nats-Last-Stream` indicates the sequence number of the newest message in the
stream.
Here's an example of a client creating a consumer with an idle_heartbeat of 10
seconds, followed by a server notification.
```
$JS.API.CONSUMER.CREATE.FRHZZ447RL7NR8TAICHCZ6 _INBOX.FRHZZ447RL7NR8TAICHCQ8.FRHZZ447RL7NR8TAICHDQ0 136␍␊
{"config":{"ack_policy":"explicit","deliver_subject":"my.messages","idle_heartbeat":10000000000},
"stream_name":"FRHZZ447RL7NR8TAICHCZ6"}␍␊
...
> HMSG my.messages 2 75 75␍␊NATS/1.0 100 Idle Heartbeat␍␊Nats-Last-Consumer: 0␍␊Nats-Last-Stream: 0␍␊␍␊␍␊
alive - last stream seq: 0 - last consumer seq: 0
```
This feature is intended as an aid to clients to detect when they have been
disconnected. Without it the consumer's subscription may sit idly waiting for
messages, without knowing that the server might have simply gone away and
recovered elsewhere.
## Consequences
Clients can use this information to set client-side timers that track how many
heartbeats have been missed and perhaps take some action such as re-create a
subscription to resume messages.