67 releases
0.15.4 | Sep 10, 2023 |
---|---|
0.15.2 | Apr 27, 2023 |
0.15.1 | Feb 26, 2023 |
0.14.0 | Nov 14, 2022 |
0.2.5 | Nov 29, 2020 |
#68 in Web programming
3,451 downloads per month
Used in 8 crates
(7 directly)
2.5MB
55K
SLoC
twilight-gateway
twilight-gateway
is an implementation of Discord's sharding gateway sessions.
This is responsible for receiving stateful events in real-time from Discord and
sending some stateful information.
The primary type is the Shard
, a stateful interface to maintain a Websocket
connection to Discord's gateway. Much of its functionality can be configured,
and it's used to receive gateway events or raw Websocket messages, useful for
load balancing and microservices.
Using the stream
module, shards can be easily managed in groups.
Features
simd-json
: usesimd-json
instead ofserde_json
for deserializing events- TLS (mutually exclusive)
native
: platform's native TLS implementation vianative-tls
rustls-native-roots
(default):rustls
using native root certificatesrustls-webpki-roots
:rustls
usingwebpki-roots
for root certificates, useful forscratch
containers
twilight-http
(default): enable thestream::create_recommended
function- Zlib (mutually exclusive)
Examples
Create a shard and loop over guild and voice state events:
use std::env;
use twilight_gateway::{Intents, Shard, ShardId};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
// Initialize the tracing subscriber.
tracing_subscriber::fmt::init();
let token = env::var("DISCORD_TOKEN")?;
let intents = Intents::GUILDS | Intents::GUILD_VOICE_STATES;
// Initialize the first and only shard in use by a bot.
let mut shard = Shard::new(ShardId::ONE, token, intents);
tracing::info!("started shard");
loop {
let event = match shard.next_event().await {
Ok(event) => event,
Err(source) => {
tracing::warn!(?source, "error receiving event");
// If the error is fatal, as may be the case for invalid
// authentication or intents, then break out of the loop to
// avoid constantly attempting to reconnect.
if source.is_fatal() {
break;
}
continue;
},
};
// You'd normally want to spawn a new tokio task for each event and
// handle the event there to not block the shard.
tracing::debug!(?event, "received event");
}
Ok(())
}
Create the recommended number of shards and run them concurrently through
ShardEventStream
:
use futures::StreamExt;
use std::env;
use twilight_gateway::{
stream::{self, ShardEventStream},
Config, Intents,
};
use twilight_http::Client;
#[tokio::main]
async fn main() -> anyhow::Result<()> {
tracing_subscriber::fmt::init();
let token = env::var("DISCORD_TOKEN")?;
let client = Client::new(token.clone());
let config = Config::new(token, Intents::GUILDS);
let mut shards = stream::create_recommended(&client, config, |_, builder| builder.build())
.await?
.collect::<Vec<_>>();
// Create an infinite stream over the shards' events.
let mut stream = ShardEventStream::new(shards.iter_mut());
while let Some((shard, event)) = stream.next().await {
let event = match event {
Ok(event) => event,
Err(source) => {
tracing::warn!(?source, "error receiving event");
if source.is_fatal() {
break;
}
continue;
}
};
// You'd normally want to spawn a new tokio task for each event and
// handle the event there to not block the shards.
tracing::debug!(?event, shard = ?shard.id(), "received event");
}
Ok(())
}
There are a few additional examples located in the repository.
Dependencies
~9–25MB
~375K SLoC