Gateway topic

Discord's Gateway API allows bots and applications to receive events from Discord over a websocket connection. This topic contains the classes used by nyxx to manage the lifecycle of this connection.

This topic does not contain models for the events received from the Gateway. For that, see the Events topic.

A client's overall connection to the Gateway is managed by the Gateway class. It is responsible for receiving GatewayEvents from Shards, before parsing them and forwarding them to Gateway.events (which is also accessible via the NyxxGateway.onXXXEvent streams). It is also responsible for creating and coordinating several Shard instances.

Each Shard maintains a single websocket connection to Discord's Gateway API. A client can run one or more shards for better resiliency and load balancing, and shards can even be split across several different clients running separately for very large bots. This can be configured using GatewayApiOptions.totalShards and GatewayApiOptions.shards.

The websocket connection for each Shard, as well as the connection lifecycle and reconnection logic, are run in a separate Isolate. Communication with the worker isolate is performed using ShardMessages and GatewayMessages. These messages can be used to listen for connection lifecycle events such as reconnects and heartbeats.

Decompression, JSON/ETF deserialization and some parsing happens in the worker isolate. Events are then sent to the main isolate where the Gateway will finish the rest of the parsing (notably parsing RawDispatchEvents into DispatchEvents that reference the client).

GatewayManager, like other Managers, provides Dart APIs for the HTTP endpoints relating to the gateway. In particular, it can be used to obtain a GatewayBot instance with the needed configuration to connect to the Gateway API. Hence, it is available on NyxxRest instances. NyxxGateway instances only have a Gateway instance that extends GatewayManager.

Classes

Disconnecting

A shard message sent when the shard is going to disconnect permanently.

DispatchEvent

The base class for all events sent by dispatch.

Dispose

A gateway message sent to instruct the shard to disconnect & stop handling any further messages.

ErrorReceived

A shard message sent when the shard encounters an error.

EventParser

An internal class which allows the shard runner to parse gateway events without having a reference to the client's GatewayManager.

EventReceived

A shard message sent when an event is received on the Gateway.

Gateway

Handles the connection to Discord's Gateway with shards, manages the client's cache based on Gateway events and provides an interface to the Gateway.

GatewayApiOptions

Options for connecting to the Discord API for making HTTP requests and connecting to the Gateway with a bot token.

GatewayBot

Information about how to connect to the Gateway, with client-specific information.

GatewayEvent

The base class for all events received from the Gateway.

GatewayManager

A Manager for gateway information.

GatewayMessage

The base class for all control messages sent from the client to the shard.

Identify

A gateway message sent as a response to RequestingIdentify to allow the shard to identify.

Reconnecting

A shard message sent when the shard needs to reconnect to the Gateway.

RequestingIdentify

A shard message sent when the shard is waiting to identify on the Gateway.

Send

A gateway message sent to instruct the shard to send data on its connection.

Sent

A shard message sent when the shard adds a payload to the connection.

Shard

A single connection to Discord's Gateway.

ShardMessage

The base class for all control messages sent from the shard to the client.

StartShard

A gateway message sent when the Gateway instance is ready for the shard to start.

Exceptions / Errors

ShardDisconnectedError

An error thrown when a shard disconnects unexpectedly.