Struct twilight_gateway::Shard

pub struct Shard<Q = InMemoryQueue> { /* private fields */ }

Gateway API client responsible for up to 2500 guilds.

Shards are responsible for maintaining the gateway connection by processing events relevant to the operation of shards—such as requests from the gateway to re-connect or invalidate a session—and then to pass them on to the user.

Shards start out disconnected, but will on the first successful call to poll_next try to reconnect to the gateway. poll_next must then be repeatedly called in order for the shard to maintain its connection and update its internal state.

Shards go through an identify queue that rate limits concurrent Identify events (across all shards) per 5 seconds. Exceeding this limit invalidates the shard’s session and it is therefore very important to reuse the same queue for all shards.

Sharding

A shard may not be connected to more than 2500 guilds, so large bots must split themselves across multiple shards. See the Discord Docs/Sharding and ShardId documentation for more info.

Examples

Create and start a shard and print new and deleted messages:

use std::env;
use twilight_gateway::{Event, EventTypeFlags, Intents, Shard, ShardId, StreamExt as _};

// Use the value of the "DISCORD_TOKEN" environment variable as the bot's
// token. Of course, this value may be passed into the program however is
// preferred.
let token = env::var("DISCORD_TOKEN")?;
let wanted_event_types = EventTypeFlags::MESSAGE_CREATE | EventTypeFlags::MESSAGE_DELETE;

let mut shard = Shard::new(ShardId::ONE, token, Intents::GUILD_MESSAGES);

while let Some(item) = shard.next_event(EventTypeFlags::all()).await {
    let Ok(event) = item else {
        tracing::warn!(source = ?item.unwrap_err(), "error receiving event");

        continue;
    };

    match event {
        Event::MessageCreate(message) => {
            println!("message received with content: {}", message.content);
        }
        Event::MessageDelete(message) => {
            println!("message with ID {} deleted", message.id);
        }
        _ => {}
    }
}

Implementations

impl Shard

pub fn new(id: ShardId, token: String, intents: Intents) -> Self

Create a new shard with the default configuration.

impl<Q> Shard<Q>

pub fn with_config(shard_id: ShardId, config: Config<Q>) -> Self

Create a new shard with the provided configuration.

pub const fn config(&self) -> &Config<Q>

Immutable reference to the configuration used to instantiate this shard.

pub const fn id(&self) -> ShardId

ID of the shard.

pub const fn inflater(&self) -> &Inflater

Available on crate features zlib-stock or zlib-simd only.

Zlib decompressor statistics.

Reset when reconnecting to the gateway.

pub const fn state(&self) -> ShardState

State of the shard.

pub const fn latency(&self) -> &Latency

Shard latency statistics, including average latency and recent heartbeat latency times.

Reset when reconnecting to the gateway.

pub const fn ratelimiter(&self) -> Option<&CommandRatelimiter>

Statistics about the number of available commands and when the command ratelimiter will refresh.

This won’t be present if ratelimiting was disabled via ConfigBuilder::ratelimit_messages or if the shard is disconnected.

pub fn resume_url(&self) -> Option<&str>

Immutable reference to the gateways current resume URL.

A resume URL might not be present if the shard had its session invalidated and has not yet reconnected.

pub const fn session(&self) -> Option<&Session>

Immutable reference to the active gateway session.

An active session may not be present if the shard had its session invalidated and has not yet reconnected.

pub fn command(&self, command: &impl Command)

Queue a command to be sent to the gateway.

Serializes the command and then calls send.

pub fn send(&self, json: String)

Queue a JSON encoded gateway event to be sent to the gateway.

pub fn close(&self, close_frame: CloseFrame<'static>)

Queue a websocket close frame.

Invalidates the session and shows the application’s bot as offline if the close frame code is 1000 or 1001. Otherwise Discord will continue showing the bot as online until its presence times out.

To read all remaining messages, continue calling poll_next until it returns Message::Close or a ReceiveMessageErrorType::WebSocket error type.

Example

Close the shard and process remaining messages:

use tokio_stream::StreamExt;
use twilight_gateway::{error::ReceiveMessageErrorType, CloseFrame, Message};

shard.close(CloseFrame::NORMAL);

while let Some(item) = shard.next().await {
    match item {
        Ok(Message::Close(_)) => break,
        Ok(Message::Text(_)) => unimplemented!(),
        Err(source) if matches!(source.kind(), ReceiveMessageErrorType::WebSocket) => break,
        Err(source) => unimplemented!(),
    }
}

pub fn sender(&self) -> MessageSender

Retrieve a channel to send messages over the shard to the gateway.

This is primarily useful for sending to other tasks and threads where the shard won’t be available.

Example

Queue a command in another process:

use tokio_stream::StreamExt;

while let Some(item) = shard.next().await {
    match item {
        Ok(message) => {
            let sender = shard.sender();
            tokio::spawn(async move {
                let command = unimplemented!();
                sender.send(command);
            });
        }
        Err(source) => unimplemented!(),
    }
}

Trait Implementations

impl<Q: Debug> Debug for Shard<Q>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Q: Queue + Unpin> Stream for Shard<Q>

type Item = Result<Message, ReceiveMessageError>

Values yielded by the stream.

fn poll_next( self: Pin<&mut Self>, cx: &mut Context<'_> ) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.