command_attr

Thanks to the following for their contributions:

• [@acdenisSK]
• [@FelixMcFelix]
• [@Lakelezz]
• [@zeyla]

Added

• [http] Take Date header into account when ratelimiting ([@zeyla]) [c:40db3c0]
• [general] Add new join messages ([@zeyla]) [c:36d7a54]

Fixed

• [voice] Send silence frames upon connection ([@FelixMcFelix]) [c:83a0c85]
• [general] Remove spurious import warning ([@acdenisSK]) [c:64dcced]
• [docs] Fix dead link ([@Lakelezz]) [c:42063a2]
• [model] Fix "Guild Member Chunk" deserializations ([@zeyla]) [c:fd77a91]
• [voice] Fix voice hang ([@FelixMcFelix]) [c:e546fa2]
• [client] Fix panics on some guild member updates in certain situations ([@zeyla]) [c:526c366]

Misc.

• [gateway] Clarify shard sequence-off log ([@zeyla]) [c:7f9c01e]
• [client] Log more information about failed deserializations ([@zeyla])
• [framework] Reword command macro docs ([@acdenisSK]) [c:a481df6]

This release contains the usual bugfixes and helper methods.

Thanks to the following for their contributions:

• [@acdenisSK]
• [@FelixMcFelix]
• [@ForsakenHarmony]
• [@jkcclemens]
• [@Lakelezz]
• [@megumisonoda]
• [@Roughsketch]
• [@Scetch]
• [@xentec]
• [@zeyla]

Added

• [builder] Generalize CreateEmbed method parameters ([@acdenisSK]) [c:f115c17]
• [http] Add 'Get Guild Vanity Url' endpoint ([@zeyla]) [c:dbfc06e]
• [framework] Add unrecognized_command method ([@Lakelezz]) [c:2937792]
• [client] Add documentation to EventHandler ([@acdenisSK]) [c:80dfcb0]
• [http] Support sending files with an embed ([@Scetch]) [c:7e0d908]

Fixed

• [voice] Add Drop impl for ffmpeg container ([@FelixMcFelix]) [c:3d67a4e]
• [model] Pad user discrims in content_safe ([@megumisonoda]) [c:2ab714f]
• [framework] Properly check if Args input is empty ([@acdenisSK]) [c:beebff5]
• [voice] Backport [c:7d162b9] (voice fixes) ([@FelixMcFelix]) [c:9baf167]
• [framework] Fix no-cache StandardFramework compilations ([@Lakelezz]) [c:02dc506]
• [builder] Make CreateEmbed and CreateMessage consistent ([@acdenisSK]) [c:77c399b]
• [framework] Fix help command precedence ([@acdenisSK]) [c:c6a5fe4]
• [gateway] Fix heartbeat checking ([@zeyla]) [c:21fe999]
• [framework] Fix Args::is_empty behaviour ([@acdenisSK]) [c:e5bcee7]
• [framework] Add Args::full_quotes ([@acdenisSK]) [c:24d2233]
• [http] Do not include Optional params if None for audit logs ([@jkcclemens]) [c:bd195de]
• [model] Handle deserializing AuditLogEntry::target_id ([@acdenisSK]) [c:0d779ba]
• [model] Fix AuditLogOptions to be correct types ([@acdenisSK], [@jkcclemens]) [c:217e1c6], [c:2791ed7]

Misc.

• [builder] DRY in CreateEmbed builder methods ([@xentec], [@acdenisSK], [@zeyla]) [c:2e1eb4c] [c:d8c9d89], [c:a4cc582], [c:ffc5ea1]
• [builder] Inline some CreateEmbed builder methods ([@acdenisSK]) [c:e814e9a]
• [framework] Add tests for empty messages ([@Lakelezz]) [c:d0ae9bb]
• [general] Remove useless clones ([@Roughsketch]) [c:b71d99f]
• [framework] Add no_run to doctests that instantiate a Client ([@Roughsketch]) [c:003dc2e]
• [general] Don't create enums and IDs via macros ([@ForsakenHarmony]) [c:fdcf44e]
• [framework] Short-circuit on errors ([@acdenisSK]) [c:82e21a6]
• [model, utils] Fix nsfw related docs ([@Lakelezz]) [c:7f09642]
• [framework] Improve docs for Args ([@acdenisSK]) [c:b9fa745]
• [general] Fix some documentatoin typos ([@Lakelezz]) [c:e506e9f]

This release contains a number of fixes, a few more model helper methods, and additional framework features.

Thanks to the following for their contributions:

• [@acdenisSK]
• [@ConcurrentMarxistGC]
• [@FelixMcFelix]
• [@indiv0]
• [@Lakelezz]
• [@perryprog]
• [@zeyla]

Added

• [framework] Add way to register middleware functions directly on CreateCommand ([@acdenisSK]) [c:d193975]
• [model] Add Message::member ([@zeyla]) [c:ce2952a]
• [http, model] Add functions to reorder a guild's channels ([@zeyla]) [c:ab1f11a]
• [voice] Add multiple audio stream playback, volume control, and pausing ([@FelixMcfelix]) [c:324a288]

Fixed

• [framework] Fix incorrect skipping for some prefixes ([@ConcurrentMarxistGC]) [c:76bcf7d]
• [framework] Trim content after prefix mentions ([@Lakelezz]) [c:27c83e8]
• [voice] Strip RTP header extensions if present ([@indiv0]) [c:e4612ac]
• [voice] Fix voice websocket loop termination ([@indiv0]) [c:55fa37a]
• [model] Account for guild owners in member hierarchy check ([@zeyla]) [c:03a7e3e]
• [model] Check message ID count in delete_messages ([@zeyla]) [c:92c91b8]
• [model] Correctly set newly created roles' positions on new roles ([@zeyla]) [c:5a0b8a6]
• [voice] Fix an odd-to-use Into<Option<Box<T>>> bound ([@zeyla]) [c:eee3168]
• [framework] Fix case insensitivity for aliases ([@Lakelezz]) [c:d240074]
• [docs] Fix broken docs links caused by model module changes ([@zeyla]) [c:8578d5f]

Changed

Misc.

• [general] Reduce number of clones in the library ([@zeyla]) [c:13b0de1]
• [example] Add voice receive example (example 10) ([@zeyla]) [c:b9a7e50]
• [examples, framework] Add docs for customised help functions ([@Lakelezz]) [c:7912f23]
• [example] Add another message embed builder example ([@perryprog]) [c:aba1ba6]

This release is a rewrite of the client and gateway internals with a minimal amount of breaking changes for userland code. These changes are mainly to prepare for Tokio and to reduce the number of atomic operations per received event, reducing the number of atomic operations by roughly 85%. The framework has also seen a rewrite, and is now centered around a trait-based design.

Thanks to the following for their contributions:

• [@acdenisSK]
• [@Caemor]
• [@ConcurrentMarxistGC]
• [@drklee3]
• [@fenhl]
• [@Flat]
• [@ftriquet]
• [@hsiW]
• [@indiv0]
• [@jhelwig]
• [@jkcclemens]
• [@Lakelezz]
• [@MOZGIII]
• [@nabijaczleweli]
• [@Roughsketch]
• [@tahahawa]
• [@thelearnerofcode]
• [@timotree3]
• [@zeyla]

Upgrade Path

Per [c:91c8ec4], the Guild::default_channel and Guild::default_channel_guarenteed methods now return Option<Arc<Mutex<GuildChannel>>> instead of Option<GuildChannel>. This avoids a clone. To access the channel, you just have to retrieve a read or write lock by doing guild.default_channel()?.read() or guild.default_channel()?.write().

Per [c:14b9222], there is a new Member::default_channel() function that returns the default channel for the user. This no longer returns the channel with the same ID as the guild itself, as this behaviour was changed by Discord. A member's "default channel" is now the top-most channel that it has permission to view. Accordingly, Guild::default_channel matches this behaviour.

Per [c:93e0a42], the library now uses the parking_lot crate's Mutex and RwLock implementations over the stdlib's. parking_lots implementations are more efficient, do not poison due to lock drops on unwinding, and implement eventual fairness.

To account for this, change all Mutex lock retrievals and RwLock read and write lock retrievals to not unwrap. parking_lot's Mutex::lock, RwLock::read, and RwLock::write don't return Results, unlike the stdlib's.

Per [c:78c6df9], the Guild::features structfield is no longer a Vec<Feature>. Discord adds guild features over time, which can cause guilds with those new features to fail in deserialization. Instead, we're future-proofing by making this a Vec<String>.

Per [c:65e3279], the CreateEmbed builder's field and fields functions no longer take a builder as the argument, and instead take 3 arguments. For example, code like this:

channel.send_message(|m| m
    .embed(|e| e
        .title("This is an embed")
        .field(|f| f
            .name("Test field")
            .value("Test value")
            .inline(true))));

Would now be this:

channel.send_message(|m| m
    .embed(|e| e
        .title("This is an embed")
        .field("Test field", "Test value", true)))

Per [c:ad0dcb3], shards can no longer have their afk property set, as this was a leftover from user account support. This removes the afk parameter of the Context::set_presence function, removal of the parameter from the Shard::set_presence function, and the Shard::set_afk function.

Per [c:b328b3e], the client::EventHandler no longer prefixes all trait methods with on_. An implementation that looks like this:

use serenity::client::{Context, EventHandler};
use serenity::model::Message;

struct Handler;

impl EventHandler for Handler {
    fn on_message(&self, _: Context, msg: Message) {
        // ...
    }
}

Now looks like this:

use serenity::client::{Context, EventHandler};
use serenity::model::channel::Message;

struct Handler;

impl EventHandler for Handler {
    fn message(&self, _: Context, msg: Message) {
        // ...
    }
}

(a note on the serenity::model::channel::Message import later.)

Per [c:b19b031], Client::new returns a Result, as it now creates some essential information on instantiation instead of deferring it to when a connection is started. You can probably just unwrap this Result.

Per [c:b8efeaf], [c:d5a9aa8], and [c:65233ad], the client and gateway internals have been rebuilt to significantly reduce the number of atomic operations (upwards of ~85%). This means that retrieval of shard information (like the shard latency to the Discord gateway or the current connection status) are retrieved via the encompassing ShardManager located on the client. This can be inserted into the client's data structfield if you need to access that information in event or framework command handlers. See this example for more information. Additionally, Context::quit to shutdown the shard no longer exists; go through the ShardManager instead.

Per [c:aad4744], the framework's Args::list function has been renamed to Args::multiple for consistency.

Per [c:f10b9d7], [c:1fd652b], [c:0aa55a2], the framework has been reworked to be trait-based; thus as per [c:f61816c], [c:4e20277], allowed more useful functionality to commands.

Per [c:05f6ed4], the client's close handle has been removed, in favour of doing so through the ShardManager.

Per [c:8c9baa7], the Guild::default_message_notifications, Guild::mfa_level, PartialGuild::default_message_notifications, and PartialGuild::mfa_level structfields are now enums to represent a stronger type, instead of u64s.

Per [c:bcd16dd], the model module has been broken up: instead of a giant root module full of imports, types have been moved to where they fit. For example, the Message, Reaction, and Channel structs are now in the model::channel module. The RichInvite, Member, Role, and MfaLevel types are now in model::guild. Refer to the commit message or the model module docs for more information.

Per [c:be43836], the http::HttpError enum's InvalidRequest variant no longer gives just the HTTP status code of the response. It now includes the full Response instance.

Per [c:2edba81], the builder re-export in the utils module no longer exists after being there in deprecation for a long time. Please import it like so:

// old
use serenity::utils::builder;

// new
use serenity::builder;

Added

• [framework] Make the framework error's internal String public ([@acdenisSK]) [c:3b9f0f8]
• [client, gateway] Improve shard and shard runner logging ([@zeyla]) [c:f0ee805]
• [gateway] Have ConnectionStage derive Copy ([@acdenisSK]) [c:551f166]
• [builder, framework, http, model] Replace Vec<T> parameter with more generic IntoIterator<Item=T> ([@ftriquet]) [c:b146501], [c:934eb3a]
• [builder, gateway, model, voice] Make more parameters generic with trait bounds of AsRef ([@acdenisSK]) [c:e0e7617], [c:b62dfd4]
• [framework, model] Add help command filtering, member prefix searching ([@Lakelezz]) [c:ee207b3]
• [model] Add guild member filtering functions ([@Lakelezz]) [c:f26dad8]
• [model] impl BanOptions for &str ([@acdenisSK]) [c:7c911d5]
• [model] Derive Default on IDs and CurrentUser ([@acdenisSK]) [c:0881e18]
• [client] Add a threadpool for event dispatches ([@zeyla]) [c:1fa83f7], [c:3e14067], [c:f2c21ef]
• [model] Fall back to str::parse if parse_username fails ([@acdenisSK]) [c:8c85664]
• [model] Add a parsing fallback for RoleId ([@acdenisSK]) [c:5d4301b]
• [http, model] Expand Audit Log support ([@acdenisSK]) [c:f491809]
• [framework] Make Command::aliases public ([@acdenisSK]) [c:8c83866]
• [model] impl FromStr for ReactionType ([@acdenisSK]) [c:2032a40], [c:84706f1]
• [builder] Make trait bounds more generic, from Into<String> to Display ([@acdenisSK]) [c:05dad71]
• [framework, internal, model, utils] Derive Debug on more public types ([@thelearnerofcode]) [c:e5a6f3a]
• [model] Change PrivateChannel::say to accept a more generic argument ([@fenhl]) [c:a359f77]
• [model] impl From<EmojiId, EmojiIdentifier> for ReactionType ([@fenhl]) [c:68156c9]
• [http] impl From<&Path> for AttachmentType ([@zeyla]) [c:7a5aa3c]
• [model] Add GameType::Listening ([@hsiW], [@zeyla]) [c:40c5c12], [c:a17fea7]
• [framework] Add cmd function to CreateCommand and CreateGroup ([@acdenisSK]) [c:e748d1f]
• [model] Add Reaction::message function ([@Roughsketch]) [c:fd19446]
• [model] Add Reaction::channel function ([@zeyla]) [c:e02a842]
• [model] Add Reaction::user function ([@zeyla]) [c:82b87f1]
• [model] Implement Deserialize for {,Gateway,Voice}Event ([@zeyla]) [c:c3aa63f]
• [framework] Add help() to CreateGroup ([@Lakelezz]) [c:39a1435]
• [framework] Add a way to execute code when a command is registered ([@acdenisSK]) [c:f61816c]
• [framework] Add before/after middleware to Command ([@acdenisSK]) [c:4e20277]
• [general] Switch from try_opt! macro to using ? operator ([@hsiW]) [c:2d23d8b]
• [framework] Make help commands customizable ([@Lakelezz]) [c:031fc92]
• [model] Add VIEW_AUDIT_LOG permission ([@Lakelezz]) [c:612e973]
• [model] Fallback to str::parse on ChannelId FromStr impl ([@acdenisSK]) [c:0525ede]
• [model] Add missing fields to Guild ([@zeyla]) [c:3d24033], [c:99d17d2], [c:2abeea5]
• [framework] Add Args::len ([@acdenisSK]) [c:2c9b682], [c:b60d037], [c:143fddd]
• [model] Add variant adapters to Channel ([@timotree3]) [c:f0a56f4]
• [model] Add animated field to Emoji and ReactionType ([@zeyla]) [c:f2fa349]
• [framework] Better support for multiple delimiters on Args ([@Lakelezz]) [c:62647f5]
• [model] Update Region to include new voice regions ([@Flat]) [c:d264cc3]
• [framework] Add Args::iter_quoted ([@acdenisSK]) [c:032c5a7]
• [model] Add missing num implementations on models ([@zeyla]) [c:0b1f684]
• [client] Add an event for shard connection changes ([@zeyla]) [c:7e46d8f]
• [model] Implement or derive serde::Serialize on all models ([@zeyla]) [c:25dddb6]
• [model] Further generic-ify reaction_users' after parameter ([@zeyla]) [c:85d7d5f]
• [model] Add Member::highest_role ([@zeyla]) [c:b7542f4]
• [model] Add Guild::greater_member_hierarchy ([@zeyla]) [c:84ff27b]
• [model] Allow channels to be moved in and out of a category ([@jkcclemens]) [c:6587655]
• [cache, model] Create partial member instances for users without a Member instance ([@zeyla]) [c:d1113c0]

Fixed

• [gateway] Improve shard reconnection logic ([@zeyla]) [c:45c1f27]
• [gateway] Reset shard heartbeat state on resume ([@zeyla]) [c:ae50886]
• [http] Make webhook_id a majour parameter in ratelimiting ([@zeyla]) [c:1735e57]
• [gateway] Resume on resumable session invalidations ([@zeyla]) [c:eb9e8df]
• [client] Fix setting of framework ([@zeyla]) [c:12317b9]
• [framework] Fix help commands to list all eligible commands in DMs ([@Lakelezz]) [c:114e43a]
• [framework] Fix command parsing behaviour when prefix has spaces ([@ConcurrentMarxistGC]) [c:10c56a9]
• [client] Attempt to restart failed shard boots ([@zeyla]) [c:8d68503]
• [client, gateway] Fix shards attempting to re-identify on their own ([@zeyla]) [c:e678883]
• [framework] Fix multiple char delimiters ([@zeyla]) [c:08febb0]
• [framework] Fix multiple_quoted ([@Lakelezz]) [c:9aad1aa]
• [model] Fix # finding in Guild::member_named ([@tahahawa]) [c:a7b67df]
• [builder] Convert embed footers for impl Form<Embed> for CreateEmbed ([@drklee3]) [c:9aaa555]
• [framework] Fix plain help command ([@Lakelezz]) [c:4bd223a]
• [model] Correctly iterate over channel permission overwrites in permission building ([@zeyla]) [c:7566f32]
• [model] Compare instants in Shard::latency, avoiding panics ([@zeyla]) [c:08db9fa]
• [model] Add some role hierarchy position checks ([@zeyla]) [c:222382c]
• [framework] Add missing correct roles checks in help commands ([@Lakelezz]) [c:470f366]
• [framework] Fix multibyte character-based prefixes ([@ConcurrentMarxistGC]) [c:e611776]

Changed

• [framework] Change the way users' command handlers are stored ([@acdenisSK]) [c:d90b90c]
• [model] Guild::{default_channel, default_channel_guarenteed} now return an Arc<Mutex<GuildChannel>> instead of a clone of the channel ([@acdenisSK]) [c:91c8ec4]
• [framework] Don't default command argument delimiter to " " ([@jhelwig]) [c:3a4cb18]
• [model] Change behaviour of default_channel to match Discord's new behaviour ([@hsiW]) [c:14b9222]
• [utils] Disallow Message Builder I from being user-implemented ([@acdenisSK]) [c:7cf1e52]
• [general] Switch to parking_lot::{Mutex, RwLock} ([@zeyla]) [c:93e0a42]
• [model] Make {Guild, PartialGuild}::features a Vec<String> ([@zeyla]) [c:78c6df9]
• [builder] Slightly change performance of builders by using &'static strs and a VecMap ([@acdenisSK], [@zeyla]) [c:9908999], [c:3a0c890], [c:26fe139]
• [builder] Change CreateEmbed::field{,s} to not take builders ([@zeyla]) [c:65e3279]
• [client, gateway] Remove setting of a shard's afk field ([@zeyla]) [c:ad0dcb3]
• [client] Remove on_ prefix to EventHandler tymethods ([@zeyla]) [c:b328b3e]
• [client] Make the Client return a result [c:b19b031]
• [client, gateway] Redo client+gateway internals to reduce atomic operations ([@zeyla]) [c:b8efeaf], [c:d5a9aa8], [c:65233ad]
• [framework] Rename Args::list -> Args::multiple ([@acdenisSK]) [c:aad4744]
• [framework] Make framework use trait-based commands ([@acdenisSK]) [c:f10b9d7], [c:1fd652b], [c:0aa55a2]
• [client] Remove client close handle ([@zeyla]) [c:05f6ed4]
• [model] Change types of some Guild and PartialGuild structfields ([@zeyla]) [c:8c9baa7]
• [model] Break up the model module ([@zeyla]) [c:bcd16dd]
• [http] Give the full hyper Response in HTTP errors ([@zeyla]) [c:be43836]
• [utils] Remove builder module re-export ([@zeyla]) [c:2edba81]
• [framework] Remove is_bot state boolean ([@zeyla]) [c:524b8f8]
• [client, framework, gateway, voice] Use an encompassing InterMessage enum to communicate over the gateway ([@zeyla]) [c:9232b8f]

Misc.

• [general] Simplify Error's Display impl ([@zeyla]) [c:ee2bbca]
• [framework] Document that application owners bypass checks ([@fenhl]) [c:b215457]
• [general] Compile all features for docs.rs ([@zeyla]) [c:a96be90]
• [model] Document that Reaction::{message, users} methods hit the API ([@zeyla]) [c:141bbfc]
• [builder] Use ToString blanket impl for Displays ([@acdenisSK]) [c:3ca7e15]
• [framework] Avoid an unwrap in Args::parse_quotes ([@zeyla]) [c:60613ef]
• [client] Trim token given in Client::new ([@zeyla]) [c:25d79ac]
• [model] Fix a doc typo on User ([@Lakelezz]) [c:9da642a]
• [model] Fix docs for User::has_role ([@zeyla]) [c:b52eb9f]

This release contains the regular bugfixes, new features and slight behaviour changes.

Thanks to the following people for their contributions:

• [@acdenisSK]
• [@efyang]
• [@Caemor]
• [@Flat]
• [@hsiW]
• [@Lakelezz]
• [@ConcurrentMarxistGC]
• [@zeyla]

Added

• [general] Add a way to change a role's position ([@Flat]) [c:f47a0c8]
• [general] Add logging and dotenv to example 07 ([@zeyla]) [c:d50b129]
• [general] Add owner + quit function to example 07 ([@zeyla]) [c:41f26b3]
• [framework] Add PartialEq impls and doc-tests to Args ([@acdenisSK]) [c:f9e5e76]
• [framework] Add "zero-copy" parsing to Args ([@acdenisSK]) [c:9428787]
• [framework] Add a debug impl to DispatchError ([@acdenisSK]) [c:a58de97]

Fixed

• [general] Fix clippy warnings ([@hsiW]) [c:fbd6258]
• [model] Fall back to str::parse if utils::parse_username fails ([@acdenisSK]) [c:292ceda]
• [model] Fix User::has_role ([@zeyla]) [c:d3015a0ff]
• [gateway] Fix shard connection ([@zeyla]) [c:585ac6e]
• [gateway] Fix shard shutdown via Context ([@zeyla]) [c:3616585]
• [framework] Fix allow_whitespace ([@ConcurrentMarxistGC]) [c:e694766]
• [framework, gateway, cache] Properly update emojis in the cache, fix shard re-tries and do some cleanup to help_commands.rs ([@Lakelezz]) [c:e02d5fb]

Changed

• [model] Do equality and hashing on just the user's id ([@acdenisSK]) [c:b7cdf15]
• [model] defer to delete_message if there's just one message to delete ([@acdenisSK]) [c:c7aa27d]
• [model] Use the underlaying integer value of ChannelType ([@acdenisSK]) [c:e57b510]

Misc.

• [general] Update dependencies ([@zeyla]) [c:2219bb3]
• [general] Re-export parking_lot's Mutex and RwLock from the prelude ([@zeyla]) [c:74ec713]
• [general] Update the version in Cargo.toml to actually be v0.4.2 ([@Caemor]) [c:5829c67]
• [general] Cleanup gitignore to have comments ([@hsiW]) [c:ce4f8c2]
• [gateway] Use update syntax for Shard ([@efyang]) [c:fcc4e2c]
• [model] Deprecate some methods on Channel ([@zeyla]) [c:23ff6f]

This release contains bugfixes and some newly added or newly exposed functionality.

Thanks to the following for their contributions this release:

• [@acdenisSK]
• [@ftriquet]
• [@hsiW]
• [@Lakelezz]
• [@lolzballs]
• [@Roughsketch]
• [@zeyla]

Added

• [general] Replace Vec parameters by IntoIterator ([@ftriquet])[c:55167c3]
• [general] Replace slice parameters by IntoIterator ([@ftriquet]) [c:022e35d]
• [model] Add Guild::members_starting_with ([@Lakelezz]) [c:b3aa441]
• [model] Add Guild::members_containing ([@Lakelezz]) [c:1b167b5]
• [model] impl<'a> BanOptions for &'a str ([@acdenisSK]) [c:cf40386]
• [model] Derive Default on CurrentUser and IDs ([@acdenisSK]) [c:09a8a44]
• [client] Add a configurable, shard-shared threadpool ([@zeyla]) [c:d7621aa], [c:8109619]
• [model] Add Guild::members_username_containing, members_nick_containing ([@Lakelezz]) [c:002ce3a]
• [framework] Add an iterator for Args ([@acdenisSK]) [c:0ed1972]
• [framework] Make has_all_requirements public ([@Lakelezz]) [c:08d390c]
• [framework] Make default help messages list help for aliases ([@Lakelezz]) [c:0d1c0f1]

Fixed

• [model] Use request_client! for attachment downloading ([@lolzballs]) [c:71f709d]
• [client] Fix client no-framework compilation ([@zeyla]) [c:1d4ecb2]
• [client] Fix client shards not filling ([@zeyla]) [c:86d8bdd]
• [model] Fix User::tag and CurrentUser::tag discrim output ([@zeyla]) [c:6b9dcf5]
• [framework] Modify initialized method purpose ([@acdenisSK]) [c:05f158f]
• [framework] Make command Error string public ([@acdenisSK]) [c:917dd30]
• [client, gateway] Improve shard logic ([@acdenisSK], [@zeyla]) [c:683691f], [c:7befcd5]
• [gateway] Reset shard heartbeat state on resume ([@zeyla]) [c:c98cae4]
• [general] Fix font-height and soften the logo ([@Lakelezz]) [c:3b2c246]

Misc.

• [client, gateway] Improve shard and shard runner logging ([@zeyla]) [c:21e194b]
• to_owned -> to_string ([@acdenisSK]) [c:1bf4d9c]
• [general] Fix most clippy warnings ([@Roughsketch]) [c:7945094]
• [framework] Add some docs to Args ([@acdenisSK]) [c:8572943]
• [examples] Add env_logger bot example [c:0df77b9]
• [general] Fix clippy lints ([@zeyla]) [c:483b069]
• [model] Optimize Member::roles ([@hsiW]) [c:8565fa2]
• [general] Internally use a try_opt! macro ([@hsiW]) [c:9b0c053]
• [general] Feature-flag extern crates behind their name ([@zeyla]) [c:11b85ca]

This release contains a lot of added functionality, minor-scale rewrites, bugfixes, documentation work, and the beginning of a rewrite to use the tokio ecosystem.

The release was delayed due to a [fairly majour bug][rust-websocket:issue:137] in rust-websocket that we have forked over to temporarily fix.

This release was lead in development by [@acdenisSK].

Thanks to the following for their contributions this release:

• [@acdenisSK]
• [@Arcterus]
• [@Bond-009]
• [@blaenk]
• [@hsiW]
• [@imnotbad]
• [@joek13]
• [@Lakelezz]
• [@Roughsketch]
• [@xentec]
• [@zeyla]

Upgrade Path

Per commits [c:af1061b], [c:cdedf36], and [c:aa307b1], Direct Messaging other bot users is now disallowed by the API. To fix this, simply don't do it.

Per commit [c:ebc4e51], deprecated functions were finally removed. The following can simply have their usage renamed:

• Cache::get_channel --> Cache::channel
• Cache::get_guild --> Cache::guild
• Cache::get_guild_channel --> Cache::guild_channel
• Cache::get_member --> Cache::member
• Cache::get_private_channel --> Cache::private_channel
• Cache::get_role --> Cache::role
• Cache::get_user --> Cache::user
• ChannelId::get_invites --> ChannelId::invites
• ChannelId::get_message --> ChannelId::message
• ChannelId::get_messages --> ChannelId::messages
• ChannelId::get_reaction_users --> ChannelId::get_reaction_users
• ChannelId::get_webhooks --> ChannelId::webhooks
• Channel::get_message --> Channel::message
• Channel::get_messages --> Channel::messages
• Channel::get_reaction_users --> Channel::reaction_users
• Client::login_bot --> Client::new
• Client::login --> Client::new
• Colour::get_b --> Colour::b
• Colour::get_g --> Colour::g
• Colour::get_r --> Colour::r
• Colour::get_tuple --> Colour::tuple
• CurrentUser::distinct --> CurrentUser::tag
• Group::get_message --> Group::message
• Group::get_messages --> Group::messages
• Group::get_reaction_users --> Group::reaction_users
• Guild::get_bans --> Guild::bans
• Guild::get_channels --> Guild::channels
• Guild::get_emoji --> Guild::emoji
• Guild::get_emojis --> Guild::emojis
• Guild::get_integrations --> Guild::integrations
• Guild::get_invites --> Guild::invites
• Guild::get_member --> Guild::member
• Guild::get_members --> Guild::members
• Guild::get_member_named --> Guild::member_named
• Guild::get_prune_count --> Guild::prune_count
• Guild::get_webhooks --> Guild::webhooks
• GuildId::get_bans --> GuildId::bans
• GuildId::get_channels --> GuildId::channels
• GuildId::get_emoji --> GuildId::emoji
• GuildId::get_emojis --> GuildId::emojis
• GuildId::get_integrations --> GuildId::integrations
• GuildId::get_invites --> GuildId::invites
• GuildId::get_member --> GuildId::member
• GuildId::get_members --> GuildId::members
• GuildId::get_prune_count --> GuildId::prune_count
• GuildId::get_webhooks --> GuildId::webhooks
• Message::get_reaction_users --> Message::reaction_users
• PartialGuild::get_bans --> PartialGuild::bans
• PartialGuild::get_channels --> PartialGuild::channels
• PartialGuild::get_emoji --> PartialGuild::emoji
• PartialGuild::get_emojis --> PartialGuild::emojis
• PartialGuild::get_integrations --> PartialGuild::integrations
• PartialGuild::get_invites --> PartialGuild::invites
• PartialGuild::get_member --> PartialGuild::member
• PartialGuild::get_members --> PartialGuild::members
• PartialGuild::get_prune_count --> PartialGuild::prune_count
• PartialGuild::get_webhooks --> PartialGuild::webhooks
• PrivateChannel::get_message --> PrivateChannel::message
• PrivateChannel::get_messages --> PrivateChannel::messages
• PrivateChannel::get_reaction_users --> PrivateChannel::reaction_users
• Role::edit_role --> Role::edit
• User::distinct --> User::tag

http::send_file has been replaced by http::send_files. Instead of using http::send_file like so:

use serde_json::Map;
use serenity::http;
use serenity::model::ChannelId;
use std::fs::File;

let channel_id = ChannelId(253635665344987136);
let filename = "mr-sakamoto.png";
let file = File::open(&format!("./img/{}", filename))?;
let map = Map::<String, Value>::new();

http::send_file(channel_id, file, filename, map)?;

Instead send an attachment of files, such as:

use serde_json::Map;
use serenity::http;
use serenity::model::ChannelId;
use std::fs::File;

let channel_id = ChannelId(253635665344987136);
let files = vec![
    (File::open(&format!("./img/{}", filename))?, filename),
];
let map = Map::<String, Value>::new();

http::send_files(channel_id, files, map)?;

Similar logic can be applied to shortcut methods which have been removed, namely:

• Channel::send_file (instead use Channel::send_files)
• ChannelId::send_file (instead use ChannelId::send_files)
• Group::send_file (instead use Group::send_files)
• GuildChannel::send_file (instead use GuildChannel::send_files)
• PrivateChannel::send_file (instead use PrivateChannel::send_files)

Instead of using the now-removed Channel::delete_messages and Channel::delete_permission, use the inner channel's method:

use serenity::model::{Channel, ChannelId};

let channel = ChannelId(253635665344987136).get()?;
let message_ids = vec![
    MessageId(359845483356749825),
    MessageId(359854838403694592),
];

if let Channel::Guild(c) = channel {
    c.delete_messages(&message_ids)?;
}

Similar logic can be applied to Channel::delete_permission.

Member::find_guild ended up being only a shortcut to the Member::guild_id structfield. Instead of calling the find_guild method like member.find_guild(), instead access the structfield directly via member.guild_id.

The model::permissions::{general, text, voice} methods have been removed, as they ended up being shortcuts to the model::permissions::PRESET_GENERAL, model::permissions::PRESET_TEXT, and model::permissions::PRESET_VOICE constants, respectively.

Per commit [c:ea432af], event handling is now done via implementing a trait. Instead of passing functions to the client directly like:

use serenity::Client;
use std::env;

let mut client = Client::new(env::var("DISCORD_TOKEN")?);

client.on_message(|ctx, msg| {
    // code
});

Instead implement the new EventHandler trait:

use serenity::client::{Client, Context, EventHandler};
use serenity::model::Message;

struct Handler;

impl EventHandler for Handler {
    fn on_message(&self, ctx: Context, msg: Message) {
        // code
    }
}

let client = Client::new(env::var("DISCORD_TOKEN")?);

Per commit [c:4f2e47f], the deprecated ext module (which has recently only been a series of re-exports for the cache, framework, and voice modules) was removed. Instead of using serenity::ext::cache for example, use serenity::cache.

Per commit [c:878684f], due to the concept of default channels being changed, GuildId::as_channel_id has been deprecated due to the fact that the ID of the default channel of a guild will no longer necessarily be the same as the guild's ID.

If you require this same exact functionality (the GuildId as a ChannelId), rewrite your code from:

use serenity::model::GuildId;

let channel_id = GuildId(81384788765712384).as_channel_id();

to:

use serenity::model::{ChannelId, GuildId};

let guild_id = GuildId(81384788765712384);
let channel_id = ChannelId(guild_id.0);

Per commits [c:2b053ea], [c:8cc2300], [c:8e29694], and [c:948b27c], custom frameworks can now be implemented, meaning that a built implementation is now passed instead of a base framework being provided and mutated. To use the old framework, modify code from:

use serenity::Client;
use std::env;

let mut client = Client::new(&env::var("DISCORD_TOKEN")?);

client.with_framework(|f| f
    // method calls to mutate framework here
);

to the new style:

use serenity::client::{Client, EventHandler};
use serenity::framework::standard::StandardFramework;
use std::env;

struct Handler;

impl EventHandler for Handler { }

let mut client = Client::new(&env::var("DISCORD_TOKEN")?, Handler);

client.with_framework(StandardFramework::new()
    // method calls here to mutate framework here
);

Per commit [c:fc9eba3d], if you were pattern matching on the serenity::framework::DispatchError::CheckFailed variant, instead either use or ignore the matched data by rewriting code from:

use serenity::framework::DispatchError;

// Code to begin dispatch error handling here.

match dispatch_error {
    DispatchError::CheckFailed => {
        // Handle operation here.
    },
    // Other variants.
}

to:

// The standard implementation is now in a "standard" framework module, but
// that's unrelated.
use serenity::framework::standard::DispatchError;

match dispatch_error {
    DispatchError::CheckFailed(_) => {
        // Handle operation here.
    },
    // Other variants.
}

Per commits [c:45d72ef], [c:03b6d78], and [c:d35d719], the framework's command! macro no longer parses arguments' types for you. You are now given an Args struct that you can retrieve arguments from and parse from to a requested type that implements FromStr.

For example, a simple sum function that looked like:

#[macro_use] extern crate serenity;

command!(sum(_ctx, msg, _args, x: i64, y: i64) {
    let _ = msg.reply(&format!("Result: {}", x + y));
});

Now looks like:

use serenity::client::Context;
use serenity::framework::standard::Args;
use serenity::model::Message;

fn sum(_: &mut Context, msg: &Message, args: Args) -> Result<(), String> {
    let x = match args.single::<i64>() {
        Ok(x) => x,
        Err(_) => return Ok(()),
    };
    let y = match args.single::<i64>() {
        Ok(y) => y,
        Err(_) => return Ok(()),
    };

    let _ = msg.reply(&format!("Result: {}", x + y));
}

Per commit [c:562ce49], serenity::model::User's FromStr implementation can now hit the REST API. No code changes required, but do note the possibility.

Per commit [c:40031d9], the following routes have been removed for being userbot routes, which are leftovers from when serenity supported them and had them removed:

• http::get_application_info
• http::get_applications
• http::get_emoji
• http::get_emojis
• model::Guild::emoji
• model::Guild::emojis
• model::GuildId::emoji
• model::GuildId::emojis
• model::PartialGuild::emoji
• model::PartialGuild::emojis

Per commit [c:092f288], bitflags has been upgraded, which introduces a minor change in how to use permissions.

Update code from:

use serenity::model::permissions::{ADD_REACTIONS, MANAGE_MESSAGES};

foo(vec![ADD_REACTIONS, MANAGE_MESSAGES]);

to:

use serenity::model::Permissions;

foo(vec![Permissions::ADD_REACTIONS, Permissions::MANAGE_MESSAGES]);

Added

• [framework] Make CommandOrAlias and CommandGroup.commands public ([@joek13]) [c:3db42c9]
• [builder] Add support for sending attachments in embeds ([@acdenisSK]) [c:c68d4d5]
• [client] Add an on_cached event ([@acdenisSK]) [c:6d6063f]
• [framework] Add reaction actions
• [client] Add shard shutdown shortcut to the context ([@acdenisSK]) [c:561b0e3]
• [client] Add is_new paramenter to the guild_create handler ([@acdenisSK]) [c:3017f6d]
• [http, model] Add ban reasons ([@acdenisSK]) [c:420f9bd], [c:8a33329], [c:710fa02], [c:421c709]
• [model] Add Guild::members_with_status ([@acdenisSK]) [c:a7a0945], [c:29ee627]
• [model] Make Ban and User impl Eq, Hash, and PartialEq ([@acdenisSK]) [c:64bfc54]
• [model] Return error if user exceeds reason limit ([@acdenisSK]) [c:60c33db], [c:25d4931]
• [builder] Add method to add multiple embed fields ([@acdenisSK]) [c:dbd6727]
• [model] Make BanOptions take and return an &str ([@acdenisSK]) [c:1ab8b31]
• [framework] Provide the command to checks ([@acdenisSK]) [c:eb47559]
• [model] Add {ChannelId, GuildChannel, PrivateChannel}::name functions ([@acdenisSK]) [c:ca0f113]
• [client] Switch to tokio for events ([@Arcterus]) [c:88765d0]
• [client] Add method to close all shards explicitly ([@acdenisSK]) [c:4d4e9dc], [c:c2cf691], [c:c7b8ab8], [c:9900b20], [c:d8027d7], [c:051d23d]
• [framework] Implement adding checks to buckets ([@acdenisSK]) [c:dc3a4df]
• [client] Handle the closing of shards ([@blaenk]) [c:5fd3509]
• [client] Make CloseHandle derive Copy ([@blaenk]) [c:b249c82]
• [model] Add nsfw property to channels ([@acdenisSK], [@Bond-009]) [c:b602805], [c:fd89d09], [c:fd47b86]
• [http, model] Add audit log support ([@acdenisSK]) [c:6a101c4], [c:4532e4a], [c:9ccf388], [c:1fad3dd], [c:e2053dd]
• [model] Add Message::is_own ([@acdenisSK], [@zeyla]) [c:5a96724], [c:fdbfbe0], [c:6572580]
• [utils] Implement From<(u8, u8, u8)> for Colour ([@acdenisSK]) [c:6f147e1]
• [builder, model] Make some functions accept a Display bound instead of &str ([@acdenisSK]) [c:7e913b6], [c:05162aa], [c:0810ab7]
• [model] Add simulated default channel methods ([@acdenisSK]) [c:878684f]
• [framework] Add support for custom delimiters ([@acdenisSK]) [c:125c1b8], [c:fdfb184]
• [framework] Provide Args to checks ([@acdenisSK], [@Roughsketch]) [c:005437f], [c:68c5be8], [c:26919cf], [c:25e91da], [c:ab67c1d], [c:caf69d6]
• [model] Use cache when possible in UserId::get ([@Roughsketch]) [c:bfdb57c]
• [utils] Add with_config{,_mut} ([@acdenisSK]) [c:1a08904]
• [voice] Add ability to play DCA and Opus ([@Roughsketch]) [c:3e0b103], [c:e1a8fe3]
• [model] Add `{Guild,PartialGuild}::role_by_name ([@Lakelezz]) [c:f6fcf32]
• [framework] Add CreateCommand::num_args ([@Roughsketch]) [c:aace5fd]
• [framework] Add case insensitive command name support ([@acdenisSK]) [c:deee38d]
• [framework] Allow commands to be limited to roles ([@Lakelezz]) [c:d925f92]
• [client] Add a way for users to get shards ([@zeyla]) [c:619a91d]
• [cache, client, model] Add channel category support ([@acdenisSK], [@zeyla]) [c:4be6b9d], [c:870a2a5], [c:192ac8a], [c:485ad29], [c:52b8e29]
• [client] Add Context::handle ([@acdenisSK]) [c:97e84fe]
• [framework] Copy some functionality from Command to Group ([@Roughsketch]) [c:8e1435f]

Fixed

• [client] Return websocket pings with a pong ([@acdenisSK]) [c:824f8cb], [c:e218ce0], [c:e72e25c], [c:bd05bda]
• [utils] Fix MessageBuilder::push_mono_safe
• [framework] Fix args when use_quotes is active ([@acdenisSK]) [c:e7a5ba3]
• [model] Make Reaction::name optional ([@acdenisSK]) [c:8f37f78]
• [gateway] Fix presence updates due to API change ([@Roughsketch]) [c:16a5828]
• [model] Fix permissions::PRESET_GENERAL bits ([@zeyla]) [c:9f02720]
• [http] Update deprecated bulk delete endpoint ([@zeyla]) [c:dbcb351]
• [client] Fix subtraction overflow on guild cached dispatch ([@Roughsketch]) [c:f830f31]
• [framework] Fix admin permission check ([@Lakelezz]) [c:2fb12e2]
• [general] Fix compiles of a variety of feature combinations ([@zeyla]) [c:8e3b4d6]
• [client] Fix spawning of multiple events (non-v0.3 bug) ([@zeyla]) [c:7c4b052]
• [framework] Add Send/Sync to framework items (non-v0.3 bug) ([@zeyla]) [c:50d7f00]

Changed

• [model] Prevent Direct Messaging other bot users ([@zeyla]) [c:af1061b], [c:266411c]
• [cache, client] Apply API changes for bot DMs ([@acdenisSK]) [c:cdedf36], [c:aa307b1]
• [client] Switch to a trait-based event handler ([@acdenisSK]) [c:ea432af]
• [cache, client, http, model, utils] Remove deprecated functions ([@acdenisSK]) [c:ebc4e51]
• [framework] Allow custom framework implementations ([@acdenisSK], [@zeyla]) [c:2b053ea], [c:8cc2300], [c:8e29694], [c:948b27c]
• [general] Remove the BC-purposed ext module ([@acdenisSK]) [c:4f2e47f]
• [model] Deprecate GuildId::as_channel_id ([@acdenisSK]) [c:878684f]
• [utils] Remove I bound for MessageBuilder language params ([@acdenisSK]) [c:f16af97]
• [cache] Split event handling to a trait ([@acdenisSK]) [c:eee857a], [c:32de2cb], [c:bc3491c]
• [framework] Provide command to DispatchError::CheckFailed ([@Lakelezz]) [c:fc9eba3]
• [framework] Provide arguments as an iterable struct ([@acdenisSK], [@Roughsketch]) [c:106a4d5], [c:428cbb9], [c:45d72ef], [c:03b6d78], [c:d35d719]
• [model] Provide useful user/role/channel id FromStr parsing errors ([@acdenisSK]) [c:8bf77fa], [c:8d51ead]
• [model] Allow User's FromStr impl to hit REST ([@Roughsketch]) [c:562ce49]
• [http] Remove remaining userbot endpoints ([@zeyla]) [c:40031d9]
• [general] Update bitflags, other dependencies ([@zeyla]) [c:092f288]

Misc.

• [model] Fix a ModelError doctest ([@zeyla]) [c:bd9fcf7]
• [docs] Various docs fixes ([@hsiW]) [c:f05efce]
• [docs] Update links to docs ([@zeyla]) [c:78e7b1b]
• [general] Fix clippy warnings ([@imnotbad]) [c:e1912c2]
• [docs] Update to add EventHandler ([@acdenisSK]) [c:fdfd5bc]
• [examples] Update examples ([@acdenisSK], [@Roughsketch]) [c:3582691], [c:4e360cf]
• [docs] Fix doctests from EventHandler changes ([@acdenisSK]) [c:511ec87]
• [docs] Update readme to use correct docs link ([@acdenisSK]) [c:0240717]
• [client] Add a macro for reaction dispatching ([@acdenisSK]) [c:4efe1d1]
• [framework] Simplify an iterator usage ([@acdenisSK]) [c:fbc1ac7]
• [general] Fix clippy warnings ([@imnotbad]) [c:b6af867]
• [docs] Fix the doc on PrivateChannel::name ([@acdenisSK]) [c:14fd41b]
• [model, voice] Use stabilized loop-with-break-value ([@acdenisSK]) [c:f5a97d4]
• [model] Change a match to an and_then ([@acdenisSK]) [c:5e5f161]
• [framework] Make bucket checks less cache dependent ([@acdenisSK]) [c:ea1eba8]
• [framework] Remove unnecessary Send + Sync bounds ([@acdenisSK]) [c:3c2716b]
• [client, framework, http, utils] Remove some clones ([@acdenisSK]) [c:0d6965f]
• [cache] Remove an unnecessary map ([@acdenisSK]) [c:924c447]
• [general] Make Travis test on osx ([@Arcterus]) [c:fb2a1a9]
• [cache] Ignore private channels on create if already cached ([@acdenisSK], [@Lakelezz]) [c:7e8da0c], [c:e5889ed], [c:069df4f]
• [examples] Document example 05 more heavily ([@Lakelezz]) [c:0186754]
• [examples] Fix listed feature requirements in examples ([@zeyla]) [c:078947e]
• [http] Document and un-hide http::set_token ([@zeyla]) [c:cb18d42]
• [model] Refactor Display impl for Ids ([@acdenisSK]) [c:47ea8f7]
• [client] Add a sharding manager base ([@zeyla]) [c:6c43fed]

This release contains a number of added methods, fixes, deprecations, and documentation improvements. It brings a module restructure and an upgrade to rust-websocket v0.20, hyper v0.10, and switching to native-tls, meaning using an up-to-date rust-openssl v0.9 on Linux, schannel on Windows, and Secure Transport on Mac. The long-standing issue [#56][issue:56] was closed.

Thanks to the following for their contributions this release:

• [@acdenisSK]
• [@barzamin]
• [@eLunate]
• [@Flat]
• [@fwrs]
• [@hsiW]
• [@Roughsketch]

Upgrade Path

Invite retrieval functions now accept a stats argument. If you don't need stats, just pass false.

ChannelId::create_permission and GuildChannel::create_permission now accept a reference, as they do not need to own the overwrite.

The deprecated GuildChannel methods (get_invites, get_message, get_messages, get_reaction_users, get_webhooks) have been removed. Use their equivalents without the get_ prefix.

The send_file functions have been deprecated. Use send_files instead by passing a Vec.

CurrentUser::distinct and User::distinct have been deprecated. Instead use CurrentUser::tag and User::tag.

User::get has been deprecated. Instead, use UserId::get.

Role::edit_role has been deprecated, renaming it to Role::edit.

time has been removed as a direct dependency, moving to chrono. Public-facing fields that return time::Timespec or were a String in ISO-3339 format are now chrono::DateTime<UTC>s. Instead use its methods for what was being done with the Timespecs or strings.

User::direct_message and User::dm now accept a builder to allow for more complete, yet simple use out of the methods. Instead of passing a &str, use the provided builder:

// old
user.dm("hello")?;

// new
user.dm(|m| m.content("hello"))?;

Client::login has been deprecated. Instead use Client::new:

use serenity::Client;
use std::env;

// old
let client = Client::login(&env::var("DISCORD_TOKEN")?);

// new
let client = Client::new(&env::var("DISCORD_TOKEN")?);

Member::guild_id is now no longer an Option<GuildId> -- just a GuildId. Since this is now always present, Member::find_guild has been deprecated since the cache now never searches the cache for the guild ID.

The deprecated GuildChannel methods get_invites, get_message, get_messages, get_reaction_users, and get_webhooks have been removed. Use their alternatives, such as GuildChannel::invites, instead.

Added

• Add support for retrieving invites with counts ([@hsiW]) [c:302d771]
• Handle message type 7 ([@fwrs]) [c:8f88c6b]
• Add GuildChannel::permissions_for [c:6502ded]
• Add Invite::url(), RichInvite::url() [c:3062981]
• Reasonable derive Debug on all items [c:9dae9e6]
• Add more examples and improve others [c:8c0aeac]
• Support adding reactions when creating message ([@acdenisSK]) [c:77b5b48]
• Add VerificationLevel::Higher [c:7dbae6b]
• Add CurrentUser::invite_url ([@Roughsketch], [@Flat]) [c:e033ff3], [c:0b95db9]
• impl From<char> for ReactionType [c:2afab7c]
• Implement multiple attachments ([@Flat]) [c:46b79dd]
• Add _line + _line_safe methods to MessageBuilder ([@Roughsketch]) [c:543b604]
• Add docs for CurrentUser ([@Roughsketch]) [c:921f7f4]
• Add cache docs ([@Roughsketch]) [c:d367a70]
• Add docs and tests for framework ([@Roughsketch]) [c:4267bdb]
• Add Content for MessageBuilder ([@eLunate]) [c:060b06e]
• Include more info on ratelimiting debugs [c:d37461b]
• Add User::refresh [c:8c04d31]
• Add some model docs ([@Roughsketch]) [c:c00f349]
• Add Message::channel() [c:063a52f]
• Add CurrentUser::default_avatar_url [c:2d09152]
• Add CurrentUser::face(), User::face() [c:d033909]
• Deserialize embed footers [c:e92b667]
• Add Member::permissions [c:39a28d3] ([@acdenisSK])
• Add wait parameter to http::execute_webhook [c:dc73d1a]

Fixed

• Don't skip @everyone role when checking channel overwrites ([@Roughsketch]) [c:b468cbf]
• Allow unreachable_code lint in command! macro ([@Flat]) [c:eb43b9c]
• Fix incorrect attempted send_file deserialization [c:0102706]
• Fix ratelimits causing 429s in certain situations [c:f695174]
• Check last heartbeat acknowledged in heartbeater [c:ec9b1c7]
• Make client join shards and return [c:175d3a3]
• Make client starts return an error [c:858bbf2]
• Ws read/write timeout after 90s to avoid infinite blocking [c:1700a4a]
• Fix negative nonces failing to deserialize [c:d0b64cd]
• Use HTTPS Connector with remaining HTTP functions [c:0d218e0] ([@Roughsketch])

Changed

• Restructure modules [c:9969be6]
• Change create_permission to take a reference [c:aea9885]
• Remove deprecated GuildChannel methods [c:ab7f113]
• Guild::create_channel doesn't require mutability [c:494cc50]
• Deprecate *User::distinct, add *User::tag [c:6579b1f]
• Deprecate User::get [c:afc571f]
• Deprecate Role::edit_role, add Role::edit [c:c00f349]
• Switch to chrono [c:990e611]
• Make User::direct_message/User::dm accept a builder [c:11a02db]
• Deprecate Client::login, add Client::new [c:7990381]
• Make Member::guild_id non-optional [c:b4bd771]
• Remove Context::channel_id and Context::queue [c:8b504ad]
• Make the framework's dynamic_prefix accept an &Message [c:2845681]
• Deprecate Channel::delete_messages, Channel::delete_permission [c:7fc49d8]
• Make Message::nonce a serde_json::Value [c:c832009]

Misc.

• Remove deprecated login_bot usage from docs ([@hsiW]) [c:ae395f4]
• Fix call to VoiceManager::join in example 06 ([@barzamin]) [c:6853daf]
• Sort default help by group/command names ([@Roughsketch]) [c:93416cd]
• Move CreateGroup docs to the struct [c:71f3dbb]
• Don't create group in help if no commands to show ([@Roughsketch]) [c:4f5fbb5]
• Move user avatar method logic out [c:8360f32]
• Upgrade rust-websocket and hyper, switch to native-tls [c:8f8a059]
• Fix broken links in README [c:51c15d0]
• Remove unused cookie dependency [c:92f4ec2]
• Switch from #[doc(hidden)] to pub(crate) [c:32e07e4] ([@acdenisSK])
• Re-export all errors from the prelude [c:db0f025]
• Rework shard logic and shard handling [c:601704a]

This is a very large release with a number of rewritten components. The cache has been rewritten to make use of memory more efficiently, the models directory has been re-organized, structures are now deserialized via serde and serde_derive - instead of the custom decoding build script we had - with a number of bugfixes and other various changes and additions.

Thanks to the following for their contributions this release:

• [@acdenisSK]
• [@Flat]
• [@fwrs]
• [@hsiW]
• [@Roughsketch]
• [@sschroe]

Upgrade Path

Replace uses of ext::cache::ChannelRef with model::Channel.

The following ext::cache::Cache method signatures are now encased in Arc<RwLock>s and should be handled appropriately:

• call
• channel
• guild
• guild_channel
• group
• member
• role
• user

Additionally, GuildId::find and UserId::find now return Option<Arc<RwLock>>s.

Member::display_name now returns a Cow<String> instead of a &str.

client::Context has had most of its methods removed. The methods were mostly a copy of those on ChannelId. Upgrade by instead calling methods on ChannelId:

command!(foo(ctx) {
    let _ = ctx.say("hello");
});

// is now written as:

command!(bar(_ctx, msg) {
    let _ = msg.channel_id.say("hello");
});

CreateMessage::nonce has been removed. Instead, simply do not provide a nonce.

ChannelId::edit_message now has an argument signature of:

&self, message_id: M, f: F
where F: FnOnce(CreateMessage) -> CreateMessage, M: Into<MessageId>

instead of

&self, message_id: M, text: &str, f: F
where F: FnOnce(CreateEmbed) -> CreateEmbed, M: Into<MessageId>

To account for this change, modify code like so:

channel_id.edit_message(message_id, "new content", |e| e);

// now:

channel_id.edit_message(message_id, |m| m.content("new content"));

Message::edit has also had an argument signature updated to:

&mut self, f: F where F: FnOnce(CreateMessage) -> CreateMessage

from:

&mut self, new_content: &str, embed: F where F: FnOnce(CreateEmbed) -> CreateEmbed

To account for this change, modify code like so:

message.edit("new content", |e| e.description("test"));

// now:

message.edit(|m| m.content("new content").embed(|e| e.description("test")));

client::rest::accept_invite, Invite::accept, and RichInvite::accept have been removed. Instead, do not attempt this, as they were userbot functions.

Selfbot support has been completely removed. Review the [commit message][c:d9118c0] for the long list of details.

Group calls and guild sync have [also been removed][c:c74cc15]. Read the commit message for all the details.

Instead of defining multiple separate error messages for command framework message dispatches, match the dispatch error in a single method:

// old code:
client.with_framework(|f| f
    .configure(|c| c
        .command_disabled_message("The command `%command%` was disabled")
        .blocked_guild_message("The owner of this guild has been blocked")
        .invalid_permission_message("You don't have permission to use this command")));

// new code:
client.with_framework(|f| f.on_dispatch_error(|_, msg, err| {
    match err {
        DispatchError::CommandDisabled(command_name) => {
            let _ = msg.channel_id.say(&format!("The command `{}` was disabled", command_name));
        },
        DispatchError::BlockedGuild => {
            // this change also allows for more intelligent error messages:
            if let Some(guild) = msg.guild() {
                let owner_id = guild.read().unwrap().owner_id;

                if let Some(user) = CACHE.read().unwrap().user(owner_id) {
                    let c = format!("The owner - {} - has been blocked", user.name);
                    let _ = msg.channel_id.say(&c);

                    return;
                }
            }

            let _ = msg.channel_id.say("The owner of this guild has been blocked");
        },
        DispatchError::LackOfPermissions(_) => {
            let _ = msg.channel_id.say("You don't have permission to use this command");
        },
    }
}));

All functions prefixed with get_ have had the prefix removed. For example, Guild::get_webhooks() is now Guild::webhooks().

Instead of using model::permissions::general(), model::permissions::text(), and model::permissions::voice(), use model::permissions::{PRESET_GENERAL, PRESET_TEXT, PRESET_VOICE}.

Added

• Add say method to Group, GuildChannel, PrivateChannel [c:a0bb306]
• Add missing send_file/send_message impls [c:bad9ac3]
• Add Message::guild [c:9ef5522]
• Add Shard Id helpers [c:1561f9e]
• Implement From<&str> for ReactionType [c:e7110ad]
• Check for embed lengths on message sends [c:e1079e9]
• Add is_nsfw check to channels [c:9268f9c]
• Add missing Member::kick helper [c:83b1d96]
• Derive Eq, Hash, PartialEq on ReactionType [c:86a4e00] ([@acdenisSK])

Fixed

• Handle unsuccessful responses before decoding [c:7e254c5]
• Uniquely ratelimit message deletions [c:01f6872]
• Fix Member methods due to variant joined_at values [c:cd914f5]
• Fix deadlock on channel create event for DMs [c:6b0b9b2] ([@sschroe])
• Default to using [0, 1] shards [c:f0d1157]
• Fix ratelimiting for Route::None routes [c:5bf6c2d]
• Fix guild leaving result [c:ae352ea]
• Fix permissions when sending to DMs or groups [c:404a089] ([@acdenisSK])
• Check if message starts with dynamic_prefix result [c:9ec05e7] ([@Roughsketch])
• Trim content before parsing framework args [c:e6712c9] ([@Roughsketch])

Changed

• Optimize caching [c:0c9ec37]
• Remove most Context methods [c:585af23]
• Remove sending message nonces [c:9c04a19]
• Standardize message editing methods [c:3c7c575]
• Remove invite accepting [c:e4b484f]
• Remove selfbot support [c:d9118c0] [c:c74cc15]
• Switch to using serde for deserialization [c:f6b27eb]
• Update the ways errors are handled in dispatch [c:31aae7d] ([@fwrs])
• Deprecate methods prefixed with get_ [c:3f03f9a]
• Framework help commands now accept a slice of args [c:ff4437a]
• Make User.discriminator a u16 [c:0f41ffc]
• Use constants for preset permissions [c:70d4e75]

Misc.

• Make logo more better [c:6e11a10] ([@Flat])
• Fix incorrect cache example [c:b96f85c]
• Rework the models directory [c:9114963]
• Change permission values to byte literals [c:c8536c1]
• Fix example in README [c:d4fc8b6]

This is a release to fix broken nightly builds, due to a change in how rustc handles lifetimes, with a few performance optimizations and other fixes.

Upgrade Path

For Group::send_message, PrivateChannel::send_message, and GuildChannel::send_message, instead of passing in only a &str of content, use a CreateMessage builder:

// assuming a `channel` is bound

// old signature:
channel.send_message("hello");

// new signature:
channel.send_message(|m| m.content("hello"));

Instead of calling message_id.get_reaction_users and passing in a ChannelId, call channel_id.get_reaction_users and pass in the MessageId. Note that the latter already existed.

// assuming `channel_id`, `message_id`, and `reaction_type` are bound

// removed method:
message_id.get_reaction_users(channel_id, reaction_type, Some(10), None);

// alternative method:
channel_id.get_reaction_users(message_id, reaction_type, Some(10), None);

Added

• Register the status user setting for user accounts (e.g. online, invisible) [c:0b9bf91]
• Expose and document ratelimiting structures [c:eb09f2d]
• Add method to EditGuild to transfer ownership [c:f00e165]

Fixed

• Fix potential unreachable pattern warning in command! macro [c:97f9bd1]
• Fix value of 'browser' in shard identify [c:4cf8338]
• Remove lifetime on Search builder [c:6f33a35]

Changed

• Standardize methods for creating messages [c:c8c6b83]
• Remove MessageId::get_reaction_users [c:268f356]

Misc.

• Avoid re-requesting the gateway URL when autosharding (optimization) [c:e891ebe]
• Avoid cloning on non-framework message create events (opt.) [c:b7cbf75]
• Avoid cloning the context on event dispatches (opt.) [c:5ee5fef]
• Optimize presence update for current user in cache (opt.) [c:9392f61]
• Make GLOBAL ratelimit mutex a unit (opt.) [c:55ccaca]
• Resume when restarting WS sender/receiver [c:04cfaa9]

This is a general release for pretty much everything, from new features to bugfixes to a switch to a more OOP style. The current minimum supported version is rustc 1.13+.

The next release will be v0.2.0, which will feature serde codegen support along with a rewrite of the framework. It will be a more modularized version of the library. v0.2.0 will require rustc 1.15+, due to the stabilization of Macros 1.1.

Thanks to the following for contributions this release:

• [@acdenisSK]
• [@bippum]
• [@DeltaEvo]
• [@emoticon]
• [@foxbot]
• [@fwrs]
• [@hsiW]
• [@indiv0]
• [@SunDwarf]

Two of the major highlights of this release are that the broken pipe issue has been fixed, and the library is more OOP now and therefore no longer relies on the Context to get stuff done. The methods feature flag has been removed.

Upgrade Path

When formatting using Display for ChannelIds, RoleIds, and UserId, instead of formatting use their Mentionable equivilants:

use serenity::model::{ChannelId, RoleId, UserId};

// old
assert_eq!(format!("{}", ChannelId(1)), "<#1>");
assert_eq!(format!("{}", RoleId(2)), "<@&2>");
assert_eq!(format!("{}", UserId(3)), "<@3>");

// new
assert_eq!(format!("{}", ChannelId(1).mention()), "<#1>");
assert_eq!(format!("{}", RoleId(2)).mention()), "<@&2>");
assert_eq!(format!("{}", UserId(3).mention()), "<@3>");

When using EmbedBuilder::{image, thumbnail}, instead of calling another builder, provide urls directly:

use serenity::model::Embed;

// old
Embed::fake(|e| e
    .image(|i| i.url("https://not.zey.moe/me.png"))
    .thumbnail(|t| t.url("https://not.zey.moe/me2.png")));

// new
Embed::fake(|e| e
    .image("https://not.zey.moe/me.png")
    .thumbnail("https://not.zey.moe/me2.png"));

When specifying a sharding method, instead of passing a u8 for sharding info, pass a u64:

use serenity::Client;

let client = Client::login_bot(&env::var("DISCORD_TOKEN").unwrap());

// old
client.start_shard(1u8, 5u8); // or
client.start_shards(5u8); // or
client.start_shard_range([1u8, 3u8], 8u8);

// new
client.start_shard(1u64, 5u64); // or
client.start_shards(5u64); // or
client.start_shard_range([1u64, 3u64], 8u64);

Client.shards is now private. Instead of accessing it, don't.

When creating a Colour struct yourself, instead of specifying a single value field, pass a single tuple value:

use serenity::utils::Colour;

// old
Colour {
    value: 0,
}

// new
Colour(0);

Instead of using Attachment::download_to_directory to download an attachment to a directory, do it yourself:

use std::fs::File;
use std::io::Write;

// assuming an `attachment` has already been bound

// old
attachment.download_to_directory("./attachments");

// new
let bytes = attachment.download().unwrap();
let filepath: PathBuf = path.as_ref().join(&attachment.filename);
let mut f = File::create(&filepath);
let _ = f.write(&bytes);

Instead of calling Message::is_webhook():

// assuming a `message` has already been bound

// old
let _ = message.is_webhook();

// new
let _ = message.webhook_id.is_some();

Instead of PartialGuild::find_role(role_id):

use serenity::model::RoleId;

// assuming a `guild` has already been bound

// old
let _ = guild.find_role(RoleId(1));

// new
let _ = guild.roles.get(RoleId(1));

Instead of Guild::{get_channel, get_member}, call:

use serenity::model::{ChannelId, UserId};

// assuming a `guild` has already been bound

// old
let _ = guild.get_channel(ChannelId(1));
let _ = guild.get_member(UserId(2));

// new
let _ = guild.channels.get(ChannelId(1));
let _ = guild.members.get(UserId(2));

Instead of using Context methods, use their Id or other struct equivalents.

Added

• the voice feature no longer requires the cache feature to be enabled [c:7b45f16]
• the framework feature no longer requires the cache feature to be enabled [c:86cd00f]
• Guild, InviteGuild, and PartialGuild now have splash_url methods [c:d58c544]
• Expose Message::webhook_id for messages sent via webhooks ([@fwrs]) [c:a2cbeb6]
• Framework: add option to ignore webhooks or DMs ([@fwrs]) [c:8e2c052]
• Added documentation for creating embed timestamps ([@foxbot]) [c:66546d3]
• Allow time::Tm to be passed into the embed timestamp field, in addition to a direct string [c:b001234]
• Add Client::on_message() example ([@indiv0]) [c:bcb70e8]
• Support webp/gif avatars/icons in URL methods [c:ab778f8]
• Update current user presence in cache on set [c:5b275fc]
• Add CurrentUser/User::static_avatar_url() methods to generate webp URLs [c:c36841d]
• Command (batch) alias support ([@fwrs]) [c:f96b6cc]
• Command example field for help command ([@fwrs]) [c:f96b6cc]
• Added "Meibi Pink" to the Colour struct ([@hsiW]) [c:2cb607d]
• Register support for 4011 code (too many shards) ([@SunDwarf]) [c:93f3c60]
• Added "Rohrkatze Blue" to the Colour struct ([@bippum]) [c:345e140]
• Add User::default_avatar_url() [c:e85e901]
• Add Message::content_safe() to avoid @everyone/@heres ([@fwrs]) [c:e5a83dd]
• Add Member::distinct(), User::distinct() ([@fwrs]) [c:e5a83dd]
• Document that messages can't be older than 14 days when bulk deleting ([@fwrs]) [c:0a2f5ab]
• Add shard latency tracking (stolen borrowed from brayzure/Eris) [c:096b0f5]
• Add guild chunking [c:3ca7ad9]

Fixed

• User::avatar_url no longer mentions the user in the generated URL [c:0708ccf]
• Framework: owners_only check now functions only if the author of a message is an owner ([@fwrs]) [c:6355288]
• Framework: fix command cooldown timer (would always say to wait i64::MAX seconds) [c:fafa363]
• Framework: the before closure is now properly run when a message is sent by the owner [c:760a47a]
• CurrentApplicationInfo now properly decodes due to flags no longer being sent [c:2a743ce]
• Fix Message::delete() permission check [c:4229034]
• Framework: properly split messages on character boundary limits; aka thanks Unicode [c:c01f238]
• Remove need to import Context/Message in command macros ([@acdenisSK]) [c:abd22d2]
• Fix a ton of gateway stuff [c:94fc85b], [c:f894cfd], [c:f894cfd]
• Specify command! macro signature as returning std::result::Result [c:e9aae9c]
• Fix dependency description in example 06 ([@DeltaEvo]) [c:92309b2]
• Return a User from rest::get_user -- not a CurrentUser [c:f57a187]
• Fix shards always booting at index 0 [c:83b29d5]
• Wait 5 seconds between shard boots to avoid session invalidations [c:fb4d411]
• Use CDN for default avatars [c:69ec62a]
• Fix Resumed event payload decoding [c:c2e8b69]
• Fix CurrentApplicationInfo decoding without rpc_origins [c:38db32e]
• Reboot shard on broken pipe; fixes a lot of gateway problems [c:76f9095]
• Make rest::execute_webhook be a POST [c:c050c59]

Changed

• Framework: argument number is now displayed on parsing error ([@fwrs]) [c:fb07751]
• Id display formatters use the direct u64 instead of mentioning; format!("{}", UserId(7)) will format into "7" instead of "<@7>" [c:933ee89]
• Default the framework's use_quotes for quote parsing to false (was true) [c:38a484d]
• The CreateEmbed builder now has direct image and thumbnail methods instead of one-method builders [c:68c473d]
• Accept u64 shard counts to allow using more than 255 shards (instead of u8s) [c:ada07fa]
• Remove user logout endpoint [c:70bf22a]
• Don't abuse unicode for message content sanitization ([@fwrs]) [c:2b237e7]
• Change Colour struct to be a tuplestruct [c:a8acd61]
• Make a single POST on guild role create [c:147cf01]
• Switch to a mostly-fully OOP approach [c:651c618]
• Rename webhooks methods to get_webhooks (eg: GuildChannel::webhooks() --> GuildChannel::get_webhooks()) [c:e8a9086]
• Make Guild::create_channel and related functions return a GuildChannel [c:5918d01]

Misc.

• Cleaned up YAML definition layouts [c:00fb61b]
• Gateway identify compression code is now simplified [c:2416813]
• Gateway Event decoders are now abstracted to individual struct implementations [c:5fe6a39]
• Simplify Role's' Ord impl ([@emoticon]) [c:6a887b2]
• Slightly simplify Shard::set_presence [c:5c40e85]
• Rename repo references from serenity.rs to serenity ([@fwrs]) [c:3348178]
• Simplify Reaction::delete() [c:1594961]
• Abstract large threshold number to a constant [c:f3f74ce]
• Avoid a needless string clone on login [c:d3389be]
• Avoid a lot of Arc/Message/RwLock clones [c:8c5ee70]

This is a hotfix for applying a PR and fixing a major bug in the plain help command.

Thanks to the following for contributions this release:

• [@fwrs]

Upgrade Path

None.

Added

• Blocking individual users and guilds in commands, add blocking commands, and configuring owners of bots ([@fwrs]) [c:a39647d]

Fixed

• The plain help command now properly sends a message when requesting information about a command [c:7b4b154]

Misc.

• Groups are now on their own lines in the plain help command [c:16bd765]

This release focuses on revamping the framework, adding a large amount of configuration and overall features. v0.1.3 will be focused on performance optimizations and code cleanup.

Thanks to the following for contributions this release:

• [@acdenisSK]
• [@fwrs]

v0.1.2 can now be retrieved from the [crates.io listing].

Upgrade Path

When using EmbedBuilder::{image, thumbnail}, instead of calling another builder, provide urls directly:

use serenity::model::Embed;

// old
Embed::fake(|e| e
    .image(|i| i.url("https://not.zey.moe/me.png"))
    .thumbnail(|t| t.url("https://not.zey.moe/me2.png")));

// new
Embed::fake(|e| e
    .image("https://not.zey.moe/me.png")
    .thumbnail("https://not.zey.moe/me2.png"));

Added

• Allow mentionable structs to be used as command arguments ([@fwrs]) [c:626ffb2]
• Implemented From<Embed> for CreateEmbed [c:7914274]
• Framework command builder, quoted arguments, multi-prefixes ([@fwrs]) [c:8f24aa3]
• {Emoji,EmojiIdentifier}::url [c:ef6eba3]
• Command groups and buckets [c:daf92ed]

Fixed

• Fix mentioning in the MessageBuilder ([@fwrs]) [c:13de5c2]
• Don't mutate token for bots on profile change [c:8effc91]

Changed

• Deprecate CreateEmbedImage::{height, width} and CreateEmbedThumbnail::{height, width}

Misc.

• All internal try!s have been converted to use ? syntax ([@acdenisSK]) [c:f69512b]

v0.1.1 is a "features that v0.1.0 should have had" and "miscellaneous work" release. v0.1.2 will be focused on the framework, while v0.1.3 will be focused on performance optimizations.

Thanks to the following for contributions this release:

• [@abalabahaha]
• [@Flat]
• [@fwrs]
• [@GetRektByMe]
• [@iCrawl]
• [@indiv0]
• [@khazhyk]
• [@SunDwarf]

v0.1.1 can now be retrieved from the [crates.io listing].

Upgrade Path

When calling rest::get_guilds, instead of passing no parameters, pass a GuildPagination variant and a limit:

use serenity::client::rest::{self, GuildPagination};
use serenity::model::GuildId;

// before
rest::get_guilds();

// after
rest::get_guilds(GuildPagination::After(GuildId(777)), 50);

Added

• The following colours to the Colour struct:
  • "Kerbal" ([@indiv0]) [c:c032fbe]
  • "Blurple" ([@GetRektByMe]) [c:e9282d3]
  • "Blitz Blue" ([@iCrawl]) [c:f53124e]
  • "Fabled Pink" ([@Flat]) [c:9aa357f]
  • "Fooyoo" ([@SunDwarf]) [c:49a6841]
  • "Rosewater" ([@fwrs]) [c:2eaa415]
• Message::guild_id as a quick method for retrieving the Id of a message's guild [c:bceb049]
• CurrentUser::guilds() to get the current user's guilds. Meant for use with selfbots [c:57c060f]
• CurrentUser::edit() to edit the current user's profile settings [c:16d1b3c]
• User::distinct to format a string with the username#discriminator combination ([@fwrs]) [c:31becb1]
• Member::colour to retrieve the member's colour ([@fwrs]) [c:43a5c5d]
• Roles can now be directly compared (role1 < role2) for hierarchy [c:143337a]
• Documentation:
  • EditMember and EditProfile ([@Kiseii]) [c:e2557ac]
  • Documentation for 19 model definitions ([@fwrs]) [c:2844ae1]
  • Context + permission requirements [c:d144136]
• A custom shared state (not the Cache) can now be accessed and mutated across commands/contexts, through the use of Context.data's ShareMap. See example 06 for an example

Fixed

• rest::start_integration_sync/Context::start_integration_sync now properly work ([@abalabahaha]) [c:7f04179]
• Role positions can now be negative; fixes issues where a guild's @everyone role (and other roles) are negative [c:f847638]
• Context::move_member's signature is now correct [c:4de39da]
• The command! macro now publicly exports functions. This allows commands created via this macro to be separated into different modules or crates [c:62ed564]

Changed

• rest::get_guilds now supports pagination of guilds, as the output is now limited to 100 [c:57c060f]

Misc.

• Colour::dark_green is now sorted alphabetically ([@khazhyk]) [c:4a14b92]
• Simplify the colour macro [c:bb97211]
• Capitalize the hex value for Colour::blitz_blue ([@Kiseii]) [c:daa24ec]

Initial commit.

<!-- COMPARISONS -->

<!-- AUTHORS -->

<!-- COMMITS -->