Manages a single shard's gateway connection.

Purpose

Discord's gateway sends us events over websocket. The shard session state machine concerns it self with parsing these events and dispatching them to clients as appropriate.

Internal module

This module is intended for exclusive usage inside of nostrum, and is documented for completeness and people curious to look behind the covers.

Inner workings

The session is implemented via :gen_statem and can be in one of the following states:

• disconnected: when no connection is up at all. On initial connection of the session (e.g. no seq field is available), this will block if we need to wait a moment to respect the session startup concurrency limits. Afterwards, it will transition to connecting_http.

• connecting_http: We are setting up a HTTP connection to the API. This means that no connection was available previously at all, and we need to open it from scratch. Used for gateway-initiated reconnect requests ("Cloudflare Websocket proxy restarting") and on :gun_down notifications for the connection in connected state. Once :gun notifies us that the connection is up, we transition to the connecting_ws state.

• connecting_ws: We are turning the HTTP connection into a WebSocket connection. If this succeeds, we head into the connected state.

• connected: The WebSocket connection is up. This state actively deals with new data from the gateway, and takes care of heartbeating. If Discord fails to respond to our heartbeats, we close down the full connection and attempt to re-establish and resume events.