Module gateway

The gateway module contains the pieces - primarily the Shard - responsible for maintaining a WebSocket connection with Discord.

A shard is an interface for the lower-level receiver and sender. It provides what can otherwise be thought of as “sugar methods”. A shard represents a single connection to Discord. You can make use of a method named “sharding” to have multiple shards, potentially offloading some server load to another server(s).

Sharding

Sharding is a method to split portions of bots into separate processes. This is an enforced strategy by Discord once a bot reaches a certain number of guilds (2500). Once this number is reached, a bot must be sharded in a way that only 2500 guilds maximum may be allocated per shard.

The “recommended” number of guilds per shard is around 1000. Sharding can be useful for splitting processes across separate servers. Often you may want some or all shards to be in the same process, allowing for a shared State. This is possible through this library.

See Discord’s documentation for more information.

If you do not require sharding - such as for a small bot - then use Client::start.

There are a few methods of sharding available:

• Client::start_autosharded: retrieves the number of shards Discord recommends using from the API, and then automatically starts that number of shards.
• Client::start_shard: starts a single shard for use in the instance, handled by the instance of the Client. Use this if you only want 1 shard handled by this instance.
• Client::start_shards: starts all shards in this instance. This is best for when you want a completely shared State.
• Client::start_shard_range: start a range of shards within this instance. This should be used when you, for example, want to split 10 shards across 3 instances.

Structs

ActivityData

Activity data of the current user.

CollectorCallback

Newtype around a callback that will be called on every incoming request. As long as this collector should still receive events, it should return true. Once it returns false, it is removed.

PresenceData

Presence data of the current user.

Shard

A Shard is a higher-level handler for a websocket connection to Discord’s gateway.

ShardManager

A manager for handling the status of shards by starting them, restarting them, and stopping them when required.

ShardManagerOptions

ShardMessenger

A handle to a ShardRunner.

ShardQueuer

The shard queuer is a simple loop that runs indefinitely to manage the startup of shards.

ShardRunner

A runner for managing a Shard and its respective WebSocket client.

ShardRunnerInfo

Information about a ShardRunner.

ShardRunnerOptions

Options to be passed to ShardRunner::new.

ShardStageUpdateEvent

An event denoting that a shard’s connection stage was changed.

WsClient

Enums

ChunkGuildFilter

Discord docs.

ConnectionStage

Indicates the current connection stage of a Shard.

GatewayError

An error that occurred while attempting to deal with the gateway.

ReconnectType

The type of reconnection that should be performed.

ShardAction

ShardQueuerMessage

A message to be sent to the ShardQueuer.

ShardRunnerMessage

A message to send from a shard over a WebSocket.