diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/boot.md | 2 | ||||
| -rw-r--r-- | docs/api/events.md | 25 |
2 files changed, 22 insertions, 5 deletions
diff --git a/docs/api/boot.md b/docs/api/boot.md index 0c2dc08..46b972f 100644 --- a/docs/api/boot.md +++ b/docs/api/boot.md @@ -42,6 +42,7 @@ This endpoint will respond with a status of "id": "U1234abcd" }, "resume_point": 1312, + "heartbeat": 30, "users": [ { "id": "U1234abcd", @@ -72,6 +73,7 @@ The response will include the following fields: |:---------------|:----------------|:-------------------------------------------------------------------------------------------------------------------------| | `user` | object | The details of the caller's identity. | | `resume_point` | integer | A resume point for [events](./events.md), such that the event stream will begin immediately after the included snapshot. | +| `heartbeat` | integer | The [heartbeat timeout](./events.md#heartbeat-events), in seconds, for events. | | `users` | array of object | A snapshot of the users present in the service. | | `channels` | array of object | A snapshot of the channels present in the service. | | `messages` | array of object | A snapshot of the messages present in the service. | diff --git a/docs/api/events.md b/docs/api/events.md index 3347a26..7fc7d78 100644 --- a/docs/api/events.md +++ b/docs/api/events.md @@ -86,12 +86,27 @@ The service may terminate the connection at any time. Clients should reconnect a Each event's `data` consists of a JSON object describing one event. Every event includes the following fields: -| Field | Type | Description | -|:--------|:-------|:-------------------------------------------------------------------------------------------------------------| -| `type` | string | The type of entity the event describes. Will be one of the types listed in the next section. | -| `event` | string | The specific kind of event. Will be one of the events listed with the associated `type` in the next section. | +| Field | Type | Description | +|:--------|:-----------------|:-------------------------------------------------------------------------------------------------------------| +| `type` | string | The type of entity the event describes. Will be one of the types listed in the next section. | +| `event` | string, optional | The specific kind of event. Will be one of the events listed with the associated `type` in the next section. | -The remaining fields depend on the `type` and `event` field. +The remaining fields depend on the `type` and (if present) the `event` field. + + +## Heartbeat events + +```json +{ + "type": "heartbeat" +} +``` + +To help clients detect network interruptions, the service guarantees that it will deliver an event after a fixed interval called the "heartbeat interval." The specific interval length is given in seconds as part of the [boot response](./boot.md). If the service determines that the heartbeat interval is close to expiring, it will synthesize and deliver a heartbeat event. + +Clients should treat any period of time without events, longer than the heartbeat interval, as an indication that the event stream may have been interrupted. Clients may also use other techniques, such as [browser APIs](https://developer.mozilla.org/en-US/docs/Web/API/EventSource/error_event), to detect this condition and restart the connection. + +These events have the `type` field set to `"heartbeat"`. The `event` field is absent. ## User events |