Struct twitch_irc::ClientConfig

pub struct ClientConfig<L: LoginCredentials> {
    pub login_credentials: L,
    pub max_channels_per_connection: usize,
    pub max_waiting_messages_per_connection: usize,
    pub time_per_message: Duration,
    pub connection_rate_limiter: Arc<Semaphore>,
    pub new_connection_every: Duration,
    pub connect_timeout: Duration,
    pub metrics_config: MetricsConfig,
    pub tracing_identifier: Option<Cow<'static, str>>,
}

Configures settings for a TwitchIRCClient.

Fields

login_credentials: L

Gets a set of credentials every time the client needs to log in on a new connection. See LoginCredentials for details.

max_channels_per_connection: usize

A new connection will automatically be created if a channel is joined and all currently established connections have joined at least this many channels.

max_waiting_messages_per_connection: usize

A new connection will automatically be created if any message is to be sent and all currently established connections have recently sent more than this many messages (time interval is defined by max_waiting_messages_duration_window)

time_per_message: Duration

We assume messages to be “waiting” for this amount of time after sending them out, e.g. typically 100 or 150 milliseconds (purely a value that has been measured/observed, not documented or fixed in any way)

connection_rate_limiter: Arc<Semaphore>

rate-limits the opening of new connections. By default this is constructed with 1 permit only, which means connections cannot be opened in parallel. If this is set to more than 1 permit, then that many connections can be opened in parallel.

This is designed to be wrapped in an Arc to allow it to be shared between multiple TwitchIRCClient instances.

new_connection_every: Duration

Allow a new connection to be made after this period has elapsed. By default this is set to 2 seconds, and combined with the permits=1 of the semaphore, allows one connection to be made every 2 seconds.

More specifically, after taking the permit from the semaphore, the permit will be put back after this period has elapsed.

connect_timeout: Duration

Imposes a general timeout for new connections. This is in place in addition to possible operating system timeouts (E.g. for new TCP connections), since additional “connect” work takes place after the TCP connection is opened, e.g. to set up TLS or perform a WebSocket handshake. Default value: 20 seconds.

metrics_config: MetricsConfig

Disable or enable and configure the collection of metrics on this TwitchIRCClient using the prometheus crate. See more information about the possible options on the MetricsConfig enum.

This crate is currently capable of exporting the following prometheus metrics:

• twitchirc_messages_received with label command counts all incoming messages. (Counter)

• twitchirc_messages_sent counts messages sent out, with a command label. (Counter)

• twitchirc_channels with type=allocated/confirmed counts how many channels you are joined to (Gauge). Allocated channels are joins that passed through the TwitchIRCClient but may be waiting e.g. for the connection to finish connecting. Once a confirmation response is received by Twitch that the channel was joined successfully, that channel is additionally confirmed.

• twitchirc_connections counts how many connections this client has in use (Gauge). The label state=initializing/open identifies how many connections are in the process of connecting (initializing) vs how many connections are already established (open).

• twitchirc_connections_failed counts every time a connection fails (Counter). Note however, depending on conditions e.g. how many channels were joined on that channel, there can be cases where a connection failing would not mandate the creation of a new connection (e.g. if you have parted channels on other connections, making it so all the channels the failed connection was joined to can be re-joined on those already existing connections).

• twitchirc_connections_created on the other hand tracks how many times, since the creation of the client, a new connection has been made.

tracing_identifier: Option<Cow<'static, str>>

Allows you to differentiate between multiple clients with the tracing crate.

This library logs a variety of trace, debug, info, warning and error messages using the tracing crate. An example log line using the default tracing_subscriber output format might look like this:

2022-02-07T10:44:23.297571Z  INFO client_loop: twitch_irc::client::event_loop: Making a new pool connection, new ID is 0

You may optionally set this configuration variable to some string, which will then modify all log messages by giving the client_loop span the name attribute:

use std::borrow::Cow;
use twitch_irc::ClientConfig;

let mut config = ClientConfig::default();
config.tracing_identifier = Some(Cow::Borrowed("bot_one"));

All log output will then look like this (note the additional {name=bot_one}:

2022-02-07T10:48:34.769272Z  INFO client_loop{name=bot_one}: twitch_irc::client::event_loop: Making a new pool connection, new ID is 0

Essentially, this library makes use of tracing Spans to differentiate between different async tasks and to also differentiate log messages coming from different connections.

Specifying this option will further allow you to differentiate between multiple clients if your application is running multiple of them. It will add the name=your_value attribute to the client_loop span, which is root for all further deeper spans in the client. This means that all log output from a single client will all be under that span, with that name.

Implementations

impl<L: LoginCredentials> ClientConfig<L>

pub fn new_simple(login_credentials: L) -> ClientConfig<L>

Create a new configuration from the given login credentials, with all other configuration options being default.

Trait Implementations

impl<L: Debug + LoginCredentials> Debug for ClientConfig<L>

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

Formats the value using the given formatter.

impl Default for ClientConfig<StaticLoginCredentials>

fn default() -> ClientConfig<StaticLoginCredentials>

Returns the “default value” for a type.