94 lines
2.7 KiB
Markdown
94 lines
2.7 KiB
Markdown
# Streaming API
|
|
|
|
Elstat's Streaming API enables clients to receive realtime
|
|
updates from the server.
|
|
|
|
Clients can optionally subscribe to certain channels using the
|
|
Streaming API if they don't want to have a lot of overhead.
|
|
|
|
## Common payload format
|
|
|
|
Payloads can not exceed 256 bytes in size.
|
|
Payloads are JSON encoded.
|
|
|
|
```javascript
|
|
{
|
|
"op": ANY_INTEGER
|
|
}
|
|
```
|
|
|
|
Data in packets are stored in specific fields, which are described
|
|
for each OP below. They are not stored inside of a `d` object, like Discord's gateway.
|
|
|
|
|
|
## Error codes
|
|
|
|
| Error code | Name |
|
|
|---:|:---|
|
|
|4200|`INVALID_PAYLOAD`|
|
|
|4420|`TOO_MUCH`|
|
|
|
|
|
|
## OP Codes
|
|
|
|
| OP Int | OP Name | Sent/Received by client |
|
|
|--:|:--|:--:|
|
|
|-1|`UNSUBSCRIBE`|Sent|
|
|
|0|`SUBSCRIBE`|Sent|
|
|
|1|`SUBSCRIBED`|Received|
|
|
|2|`UNSUBSCRIBED`|Received|
|
|
|3|`DATA`|Received|
|
|
|4|`INCIDENT_NEW`|Received|
|
|
|5|`INCIDENT_UPDATE`|Received|
|
|
|6|`INCIDENT_CLOSE`|Received|
|
|
|
|
## OP Payloads
|
|
|
|
- `SUBSCRIBE`
|
|
- field: `channels` (`list[str]`), array of channels you want to subscribe to.
|
|
- reply: `SUBSCRIBED` payload.
|
|
- `UNSUBSCRIBE`
|
|
- field: `channels` (`list[str]`), array of channels you want to **un**subscribe from.
|
|
- reply: `UNSUBSCRIBED` payload.
|
|
- `SUBSCRIBED`
|
|
- field: `channels` (`list[str]`), array of channels you *succesfully* subscribed to.
|
|
- `UNSUBSCRIBED`
|
|
- field: `channels` (`list[str]`), array of channels you *succesfully* **un**subscribed from.
|
|
- `DATA`
|
|
- field: `c` (`str`), the channel the data is coming from.
|
|
- data: `d` (`list[any]`), the data coming in from the channel.
|
|
- The first element of `d` is an integer, encoding an UNIX timestamp with millisecond precision.
|
|
- The second element of `d` is described on *`Channel types`*
|
|
|
|
- `INCIDENT_NEW`
|
|
- data: `d` (`dict`), an incident payload
|
|
- `INCIDENT_UPDATE`
|
|
- data: `d` (`dict`), an incident payload.
|
|
- `INCIDENT_CLOSE`
|
|
- data: `d` (`dict`), an incident payload, containing at least the `id` field.
|
|
|
|
|
|
## Channel names
|
|
|
|
Clients subscribe to channels to receive specific data. Channel names
|
|
are formatted like: `<type>:<name>`
|
|
|
|
e.g `status:elixire` and `graph:elixire`
|
|
|
|
**There is a special channel for incident reporting(OP codes 4, 5 and 6): `incidents`**
|
|
|
|
***TODO: incident types, stage types, etc.***
|
|
|
|
### Channel types
|
|
- `status` channel
|
|
- Returns a boolean, representing the status of the service
|
|
- `latency` channel
|
|
- Returns an integer, representing the latency of the service, in *milliseconds*.
|
|
|
|
|
|
## Connection logic
|
|
|
|
- Connect a websocket to `/api/streaming`.
|
|
- Send a `SUBSCRIBE` payload, receive `SUBSCRIBED` back
|
|
- Listen to `DATA` payloads and update local state as needed.
|
|
- Optionally: listen to `INCIDENT_{NEW|UPDATE|CLOSE}`
|