dawn is an asynchronous, simple, and extensible set of libraries which can be used separately or in combination for the Discord API.

The ecosystem of first-class crates includes dawn-cache, dawn-command-parser, dawn-gateway, dawn-http, dawn-model, dawn-voice, and more. These are explained in detail below.

The main dawn crate is a "skeleton crate": it includes all of the non-vendor-specific crates in the dawn ecosystem.

Not included by default are crates like dawn-cache-redis for a redis-backed cache implementation, dawn-lavalink for lavalink voice support, and more. Read further down for a list of known first-party and third-party integration crates.

Most of Dawn requires at least 1.39+ (rust beta).

Add this to your Cargo.toml's [dependencies] section:

dawn = "0.1"

These are crates that can work together for a full application experience. You may not need all of these - such as dawn-cache - but they can be mixed together to accomplish just what you need.

dawn-model is a set of models defining structures, enums, and bitflags for the entirety of the Discord API. It is split into a number of sub-modules, such as gateway for containing the WebSocket gateway types, guild for containing types owned by guilds (servers), voice containing the types used by the Voice WebSocket API, and more.

These are all in a single crate so that you can use gateway models without depending on dawn-gateway. One use case is if you write your own WebSocket gateway implementation.

dawn-cache is based on a single trait which can be implemented to use custom third-party backends with a single ubiquitous interface. The Cache is responsible for holding information about things like guilds, channels, role information, voice states, and any other data that comes from Discord.

Included by default is an InMemoryCache backend, which caches within the process's memory. Also available as a first-class library is dawn-cache-redis which supports caching via Redis.

dawn-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.

It includes two primary types: the Shard and Cluster.

The Shard handles a single WebSocket connection and can manage up to 2500 guilds. If you manage a small bot in under about 2000 guilds, then this is what you use. See the Discord docs for more information on sharding.

The Cluster is an interface which manages the health of the shards it manages and proxies all of their events under one unified stream. This is useful to use if you have a large bot in over 1000 or 2000 guilds.

dawn-command-parser is a crate for parsing commands out of messages received over the gateway. It finds messages commanding your bot and parses the arguments out.

dawn-http is an HTTP client supporting all of the Discord REST API. It is based on hyper. It meets Discord's ratelimiting requirements and supports proxying.

dawn-voice is a WebSocket client supporting Discord's voice API. It exposes a powerful API supporting efficient managed voice connections, queueing, playback mutation, streaming, and audio controls.

use futures::StreamExt;
use dawn::{
    gateway::{Config, Event, Shard},
    http::Client as HttpClient,
};
use std::{
    env,
    error::Error,
};

let token = env::var("DISCORD_TOKEN")?;

let http = HttpClient::new(&token);

let config = Config::builder(&token).build();
let mut shard = Shard::new(config);
shard.connect().await?;
let mut events = shard.events();

while let Some(event) = events.next().await {
    runtime::spawn(handle_event(event));
}

async fn handle_event(event: Event) -> Result<(), Box<dyn Error>> {
    match event {
        Event::Connected(connected) => {
            println!("Connected on shard {}", connected.shard_id);
        },
        Event::Message(msg) => {
            if msg.content == "!ping" {
                http.send_message(msg.channel_id).content("Pong!").await?;
            }
        },
        _ => {},
    }

    Ok(())
}

Maintaining a cache of guilds, users, channels, and more sent by the gateway:

use futures::StreamExt;
use dawn::{
    cache::InMemoryCache,
    gateway::{Config, Event, Shard},
};
use std::{
    env,
    error::Error,
};

let token = env::var("DISCORD_TOKEN")?;

let config = Config::builder(&token).build();
let mut shard = Shard::new(config);
shard.connect().await?;
let mut events = shard.events();

let cache = InMemoryCache::new();

while let Some(event) = events.next().await {
    runtime::spawn(cache.update(&event));
}

Below is a list of crates which are either first-party or known unofficial third-party crates. These are not included by default.

dawn-cache-redis is an asynchronous caching implementation backed by Redis. It uses redis-async-rs.

dawn-lavalink is an implementation bridging dawn-gateway and Lavalink, offering a powerful interface for audio control.

N/A

All first-party crates are licensed under ISC