Resume
Connections drop: networks change, laptops sleep and the gateway is redeployed. RESUME continues your session on a new connection and replays what you missed.
Treat any close that the close codes table lets you reconnect from as a cue to resume. That includes a close caused by a deploy.
How to resume
Connect, wait for HELLO, then send RESUME (op 6) in place of IDENTIFY:
- You send
| Field | Type | Description |
|---|---|---|
session_id | string | The session_id from READY. |
seq | number | Sequence number of the last event you processed. |
There is no token in RESUME.
{ "op": 6, "d": { "session_id": "<from READY>", "seq": 1234 }}The session id is 256 bits of random data and works as a secret, so store it the way you store a token. Keep sending heartbeats on the new connection.
What the server answers
| Case | Response |
|---|---|
The session is valid and events after seq are still kept | The missed events in order, then a RESUMED event |
| The session is unknown or has expired | INVALID_SESSION with resumable false. Identify afresh |
seq is older than the events the gateway still holds | INVALID_SESSION with resumable false. Identify afresh |
seq is below where this session started | INVALID_SESSION with resumable false. Identify afresh |
seq is greater than the newest event | Close 4007 |
| The session's token is revoked or its account deleted | Close 4012 |
Identifying afresh starts a new session at the current head, so anything added in between is not delivered.
A RESUME for a session that is unknown or has expired counts towards the limit of 10 failed IDENTIFY attempts a minute from one network, after which the connection closes with 4008. Do not loop on a RESUME that has already failed. Identify afresh.
Things to know
- The gateway keeps events for 24 hours, and a session can be resumed for 24 hours after it starts.
- If you have been offline for longer than 24 hours there is no way to catch up on what you missed. Identify afresh and treat the gap as lost.
- Every RESUME checks the token again. A resumed connection counts towards the two-connection limit for the token.
- Replay can be long. If you are far behind, you may receive more events after RESUMED until you catch up.
- Replayed events are the same events, with the same
d.id. Ignore any you have already handled.
RECONNECT
The server may send RECONNECT (op 7). Close the connection, reconnect and resume.