Module serenity::gateway

source ·
Available on crate feature gateway only.
Expand description

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 are not using a bot account or 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. The shard allows for sending and receiving messages over the websocket, such as setting the active activity, reconnecting, syncing guilds, and more.
  • 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§

Traits§