serenity/gateway/bridge/
mod.rs

1//! The client gateway bridge is support essential for the [`client`] module.
2//!
3//! This is made available for user use if one wishes to be lower-level or avoid the higher
4//! functionality of the [`Client`].
5//!
6//! Of interest are three pieces:
7//!
8//! ### [`ShardManager`]
9//!
10//! The shard manager is responsible for being a clean interface between the user and the shard
11//! runners, providing essential functions such as [`ShardManager::shutdown`] to shutdown a shard
12//! and [`ShardManager::restart`] to restart a shard.
13//!
14//! If you are using the `Client`, this is likely the only piece of interest to you. Refer to [its
15//! documentation][`ShardManager`] for more information.
16//!
17//! ### [`ShardQueuer`]
18//!
19//! The shard queuer is a light wrapper around an mpsc receiver that receives
20//! [`ShardQueuerMessage`]s. It should be run in its own thread so it can receive messages to
21//! start shards in a queue.
22//!
23//! Refer to [its documentation][`ShardQueuer`] for more information.
24//!
25//! ### [`ShardRunner`]
26//!
27//! The shard runner is responsible for actually running a shard and communicating with its
28//! respective WebSocket client.
29//!
30//! It is performs all actions such as sending a presence update over the client and, with the help
31//! of the [`Shard`], will be able to determine what to do. This is, for example, whether to
32//! reconnect, resume, or identify with the gateway.
33//!
34//! ### In Conclusion
35//!
36//! For almost every - if not every - use case, you only need to _possibly_ be concerned about the
37//! [`ShardManager`] in this module.
38//!
39//! [`client`]: crate::client
40//! [`Client`]: crate::Client
41//! [`Shard`]: crate::gateway::Shard
42
43mod event;
44mod shard_manager;
45mod shard_messenger;
46mod shard_queuer;
47mod shard_runner;
48mod shard_runner_message;
49#[cfg(feature = "voice")]
50mod voice;
51
52use std::fmt;
53use std::time::Duration as StdDuration;
54
55pub use self::event::ShardStageUpdateEvent;
56pub use self::shard_manager::{ShardManager, ShardManagerOptions};
57pub use self::shard_messenger::ShardMessenger;
58pub use self::shard_queuer::ShardQueuer;
59pub use self::shard_runner::{ShardRunner, ShardRunnerOptions};
60pub use self::shard_runner_message::ShardRunnerMessage;
61#[cfg(feature = "voice")]
62pub use self::voice::VoiceGatewayManager;
63use super::ChunkGuildFilter;
64use crate::gateway::ConnectionStage;
65use crate::model::event::Event;
66use crate::model::id::ShardId;
67
68/// A message to be sent to the [`ShardQueuer`].
69#[derive(Clone, Debug)]
70pub enum ShardQueuerMessage {
71    /// Message to start a shard, where the 0-index element is the ID of the Shard to start and the
72    /// 1-index element is the total shards in use.
73    Start(ShardId, ShardId),
74    /// Message to shutdown the shard queuer.
75    Shutdown,
76    /// Message to dequeue/shutdown a shard.
77    ShutdownShard(ShardId, u16),
78}
79
80/// Information about a [`ShardRunner`].
81///
82/// The [`ShardId`] is not included because, as it stands, you probably already know the Id if you
83/// obtained this.
84#[derive(Debug)]
85pub struct ShardRunnerInfo {
86    /// The latency between when a heartbeat was sent and when the acknowledgement was received.
87    pub latency: Option<StdDuration>,
88    /// The channel used to communicate with the shard runner, telling it what to do with regards
89    /// to its status.
90    pub runner_tx: ShardMessenger,
91    /// The current connection stage of the shard.
92    pub stage: ConnectionStage,
93}
94
95impl AsRef<ShardMessenger> for ShardRunnerInfo {
96    fn as_ref(&self) -> &ShardMessenger {
97        &self.runner_tx
98    }
99}
100
101/// Newtype around a callback that will be called on every incoming request. As long as this
102/// collector should still receive events, it should return `true`. Once it returns `false`, it is
103/// removed.
104pub struct CollectorCallback(pub Box<dyn Fn(&Event) -> bool + Send + Sync>);
105impl std::fmt::Debug for CollectorCallback {
106    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
107        f.debug_tuple("CollectorCallback").finish()
108    }
109}
serenity/gateway/bridge/mod.rs

serenity/gateway/bridge/
mod.rs
