serenity-rs/serenity v0.5.0 on GitHub

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:

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
(@UninterestinAcc) 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 (@UninterestinAcc)
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