# Streaming API

Elstat's Streaming API enables clients to receive realtime
updates from the server.

Clients can subscribe just to *certain* channels in the case
they don't want to have a lot of overhead, or they can just
not use the Streaming API at all. It is optional.


## Common payload format

Payloads can not exceed 256 bytes in size.
Payloads are JSON encoded.

```javascript
{
    "op": ANY_INTEGER
}
```

Extra fields are on each OP's description, instead of being in
some `d` field (like Discord's Gateway API).


## 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|


## 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`*


## Channel names

Channels are what clients subscribe to receive data about that channel.
Channels are specified as `<type>:<name>`

e.g `status:elixire` and `graph:elixire`

### 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.