Struct ConfigBuilder

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

Builder to customize the operation of a shard.

Implementations

impl ConfigBuilder

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

Create a new builder to configure and construct a shard.

Refer to each method to learn their default values.

Panics

Panics if loading TLS certificates fails.

impl<Q> ConfigBuilder<Q>

pub fn build(self) -> Config<Q>

Consume the builder, constructing a shard.

pub fn identify_properties( self, identify_properties: IdentifyProperties, ) -> Self

Set the properties to identify with.

This may be used if you want to set a different operating system, for example.

Examples

Set the identify properties for a shard:

use std::env::{self, consts::OS};
use twilight_gateway::{ConfigBuilder, Intents, Shard};
use twilight_model::gateway::payload::outgoing::identify::IdentifyProperties;

let token = env::var("DISCORD_TOKEN")?;
let properties = IdentifyProperties::new("twilight.rs", "twilight.rs", OS);

let config = ConfigBuilder::new(token, Intents::empty())
    .identify_properties(properties)
    .build();

pub const fn large_threshold(self, large_threshold: u64) -> Self

Set the maximum number of members in a guild to load the member list.

Default value is 50. The minimum value is 50 and the maximum is 250.

Examples

If you pass 200, then if there are 250 members in a guild the member list won’t be sent. If there are 150 members, then the list will be sent.

Panics

Panics if the provided value is below 50 or above 250.

pub fn presence(self, presence: UpdatePresencePayload) -> Self

Set the presence to use automatically when starting a new session.

The active presence of a session is maintained across re-connections when a session can be successfully resumed, and when a new session has to be made shards will send the configured presence. Manually updating the presence after a disconnection isn’t necessary.

Default is no presence, which defaults to strictly being “online” with no special qualities.

Examples

Set the bot user’s presence to idle with the status “Not accepting commands”:

use std::env;
use twilight_gateway::{ConfigBuilder, Intents, Shard, ShardId};
use twilight_model::gateway::{
    payload::outgoing::update_presence::UpdatePresencePayload,
    presence::{ActivityType, MinimalActivity, Status},
};

let config = ConfigBuilder::new(env::var("DISCORD_TOKEN")?, Intents::empty())
    .presence(UpdatePresencePayload::new(
        vec![MinimalActivity {
            kind: ActivityType::Playing,
            name: "Not accepting commands".into(),
            url: None,
        }
        .into()],
        false,
        None,
        Status::Idle,
    )?)
    .build();

let shard = Shard::with_config(ShardId::ONE, config);

pub fn proxy_url(self, proxy_url: String) -> Self

Set the proxy URL for connecting to the gateway.

Resumes are always done to the URL specified in resume_gateway_url.

pub fn queue<NewQ>(self, queue: NewQ) -> ConfigBuilder<NewQ>

Set the queue to use for queueing shard sessions.

Defaults to InMemoryQueue with its default settings.

Note that InMemoryQueue with a max_concurrency of 0 effectively turns itself into a no-op.

pub const fn ratelimit_messages(self, ratelimit_messages: bool) -> Self

Set whether or not outgoing messages will be ratelimited.

Useful when running behind a proxy gateway. Running without a functional ratelimiter will get you ratelimited.

Defaults to being enabled.

pub fn resume_url(self, resume_url: String) -> Self

Set the resume URL to use when the initial shard connection resumes an old session.

This is only used if the initial shard connection resumes instead of identifying and only affects the first session.

This only has an effect if ConfigBuilder::session is also set.

pub fn session(self, session: Session) -> Self

Set the gateway session to use when connecting to the gateway.

In practice this will result in the shard attempting to send a Resume to the gateway instead of identifying and creating a new session. Refer to the documentation for Session for more information.

Trait Implementations

impl<Q: Debug> Debug for ConfigBuilder<Q>

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

Formats the value using the given formatter.

impl<Q> From<Config<Q>> for ConfigBuilder<Q>

fn from(value: Config<Q>) -> Self

Converts to this type from the input type.