Rework the EventHandler trait to have a single dispatch function (#3324)

The primary motivation for this change is to allow for concurrent execution
of the event handler and the framework, but also brings other benefits:

- The trait becomes much simpler, only having three functions now.
- New fields to events will no longer be breaking changes.

Author: jamesbt365

README.md

@@ -16,11 +16,12 @@ Serenity supports bot login via the use of [`Client::builder`].
 You may also check your tokens prior to login via the use of
 [`validate_token`].
 
-Once logged in, you may add handlers to your client to dispatch [`Event`]s,
-by implementing the handlers in a trait, such as [`EventHandler::message`].
-This will cause your handler to be called when a [`Event::MessageCreate`] is
-received. Each handler is given a [`Context`], giving information about the
-event. See the [client's module-level documentation].
+Once logged in, you can add an event handler to your client to dispatch [`Event`]s.
+This will allow you to recieve and handle events as you see fit. For example, an
+[`Event::MessageCreate`] event will be dispatched to you when a message is sent.
+Every event will give you access to a [`Context`], giving information about the event.
+See the [client's module-level documentation].
+
 
 The [`Shard`] is transparently handled by the library, removing
 unnecessary complexity. Sharded connections are automatically handled for
@@ -215,7 +216,6 @@ a Rust-native cloud development platform that allows deploying Serenity bots for
 
 [`Cache`]: https://docs.rs/serenity/*/serenity/cache/struct.Cache.html
 [`Client::builder`]: https://docs.rs/serenity/*/serenity/client/struct.Client.html#method.builder
-[`EventHandler::message`]: https://docs.rs/serenity/*/serenity/client/trait.EventHandler.html#method.message
 [`Context`]: https://docs.rs/serenity/*/serenity/client/struct.Context.html
 [`Event`]: https://docs.rs/serenity/*/serenity/model/event/enum.Event.html
 [`Event::MessageCreate`]: https://docs.rs/serenity/*/serenity/model/event/enum.Event.html#variant.MessageCreate

examples/e01_basic_ping_bot/src/main.rs

@@ -1,34 +1,44 @@
 use serenity::async_trait;
-use serenity::model::channel::Message;
-use serenity::model::gateway::Ready;
+use serenity::gateway::client::FullEvent;
 use serenity::prelude::*;
 
 struct Handler;
 
 #[async_trait]
 impl EventHandler for Handler {
-    // Set a handler for the `message` event. This is called whenever a new message is received.
-    //
-    // Event handlers are dispatched through a threadpool, and so multiple events can be dispatched
-    // simultaneously.
-    async fn message(&self, ctx: Context, msg: Message) {
-        if msg.content == "!ping" {
-            // Sending a message can fail, due to a network error, an authentication error, or lack
-            // of permissions to post in the channel, so log to stdout when some error happens,
-            // with a description of it.
-            if let Err(why) = msg.channel_id.say(&ctx.http, "Pong!").await {
-                println!("Error sending message: {why:?}");
-            }
-        }
-    }
+    async fn dispatch(&self, ctx: &Context, event: &FullEvent) {
+        match event {
+            // Set a handler for the `message` event. This is called whenever a new message is
+            // received.
+            //
+            // Event handlers are dispatched through a threadpool, and so multiple events can be
+            // dispatched simultaneously.
+            FullEvent::Message {
+                new_message, ..
+            } => {
+                if new_message.content == "!ping" {
+                    // Sending a message can fail, due to a network error, an authentication error,
+                    // or lack of permissions to post in the channel, so log to
+                    // stdout when some error happens, with a description of it.
+                    if let Err(why) = new_message.channel_id.say(&ctx.http, "Pong!").await {
+                        println!("Error sending message: {why:?}");
+                    }
+                }
+            },
 
-    // Set a handler to be called on the `ready` event. This is called when a shard is booted, and
-    // a READY payload is sent by Discord. This payload contains data like the current user's guild
-    // Ids, current user data, private channels, and more.
-    //
-    // In this case, just print what the current user's username is.
-    async fn ready(&self, _: Context, ready: Ready) {
-        println!("{} is connected!", ready.user.name);
+            // Set a handler to be called on the `ready` event. This is called when a shard is
+            // booted, and a READY payload is sent by Discord. This payload contains
+            // data like the current user's guild Ids, current user data, private
+            // channels, and more.
+            //
+            // In this case, just print what the current user's username is.
+            FullEvent::Ready {
+                data_about_bot, ..
+            } => {
+                println!("{} is connected!", data_about_bot.user.name);
+            },
+            _ => {},
+        }
     }
 }
 

examples/e02_transparent_guild_sharding/src/main.rs

@@ -1,6 +1,5 @@
 use serenity::async_trait;
-use serenity::model::channel::Message;
-use serenity::model::gateway::Ready;
+use serenity::gateway::client::FullEvent;
 use serenity::prelude::*;
 
 // Serenity implements transparent sharding in a way that you do not need to handle separate
@@ -22,19 +21,25 @@ struct Handler;
 
 #[async_trait]
 impl EventHandler for Handler {
-    async fn message(&self, ctx: Context, msg: Message) {
-        if msg.content == "!ping" {
-            println!("Shard {}", ctx.shard_id);
-
-            if let Err(why) = msg.channel_id.say(&ctx.http, "Pong!").await {
-                println!("Error sending message: {why:?}");
-            }
+    async fn dispatch(&self, ctx: &Context, event: &FullEvent) {
+        match event {
+            FullEvent::Message {
+                new_message, ..
+            } => {
+                if new_message.content == "!ping" {
+                    if let Err(why) = new_message.channel_id.say(&ctx.http, "Pong!").await {
+                        println!("Error sending message: {why:?}");
+                    }
+                }
+            },
+            FullEvent::Ready {
+                data_about_bot, ..
+            } => {
+                println!("{} is connected!", data_about_bot.user.name);
+            },
+            _ => {},
         }
     }
-
-    async fn ready(&self, _: Context, ready: Ready) {
-        println!("{} is connected!", ready.user.name);
-    }
 }
 
 #[tokio::main]

examples/e03_struct_utilities/src/main.rs

@@ -1,32 +1,41 @@
 use serenity::async_trait;
 use serenity::builder::CreateMessage;
-use serenity::model::channel::Message;
-use serenity::model::gateway::Ready;
+use serenity::gateway::client::FullEvent;
 use serenity::prelude::*;
 
 struct Handler;
 
 #[async_trait]
 impl EventHandler for Handler {
-    async fn message(&self, context: Context, msg: Message) {
-        if msg.content == "!messageme" {
-            // If the `utils`-feature is enabled, then model structs will have a lot of useful
-            // methods implemented, to avoid using an often otherwise bulky Context, or even much
-            // lower-level `rest` method.
-            //
-            // In this case, you can direct message a User directly by simply calling a method on
-            // its instance, with the content of the message.
-            let builder = CreateMessage::new().content("Hello!");
-            let dm = msg.author.id.dm(&context.http, builder).await;
+    async fn dispatch(&self, ctx: &Context, event: &FullEvent) {
+        match event {
+            FullEvent::Message {
+                new_message, ..
+            } => {
+                if new_message.content == "!messageme" {
+                    // If the `utils`-feature is enabled, then model structs will have a lot of
+                    // useful methods implemented, to avoid using an often
+                    // otherwise bulky Context, or even much lower-level `rest`
+                    // method.
+                    //
+                    // In this case, you can direct message a User directly by simply calling a
+                    // method on its instance, with the content of the message.
+                    let builder = CreateMessage::new().content("Hello!");
+                    let dm = new_message.author.id.dm(&ctx.http, builder).await;
 
-            if let Err(why) = dm {
-                println!("Error when direct messaging user: {why:?}");
-            }
-        }
-    }
+                    if let Err(why) = dm {
+                        println!("Error when direct messaging user: {why:?}");
+                    }
+                }
+            },
 
-    async fn ready(&self, _: Context, ready: Ready) {
-        println!("{} is connected!", ready.user.name);
+            FullEvent::Ready {
+                data_about_bot, ..
+            } => {
+                println!("{} is connected!", data_about_bot.user.name);
+            },
+            _ => {},
+        }
     }
 }
 

examples/e04_message_builder/src/main.rs

@@ -1,44 +1,51 @@
 use serenity::async_trait;
-use serenity::model::channel::Message;
-use serenity::model::gateway::Ready;
+use serenity::gateway::client::FullEvent;
 use serenity::prelude::*;
 use serenity::utils::MessageBuilder;
 
 struct Handler;
 
 #[async_trait]
 impl EventHandler for Handler {
-    async fn message(&self, context: Context, msg: Message) {
-        if msg.content == "!ping" {
-            let channel = match msg.channel(&context).await {
-                Ok(channel) => channel,
-                Err(why) => {
-                    println!("Error getting channel: {why:?}");
+    async fn dispatch(&self, ctx: &Context, event: &FullEvent) {
+        match event {
+            FullEvent::Message {
+                new_message, ..
+            } => {
+                if new_message.content == "!ping" {
+                    let channel = match new_message.channel(ctx).await {
+                        Ok(channel) => channel,
+                        Err(why) => {
+                            println!("Error getting channel: {why:?}");
 
-                    return;
-                },
-            };
+                            return;
+                        },
+                    };
 
-            // The message builder allows for creating a message by mentioning users dynamically,
-            // pushing "safe" versions of content (such as bolding normalized content), displaying
-            // emojis, and more.
-            let response = MessageBuilder::new()
-                .push("User ")
-                .push_bold_safe(msg.author.name.as_str())
-                .push(" used the 'ping' command in the ")
-                .mention(&channel)
-                .push(" channel")
-                .build();
+                    // The message builder allows for creating a message by mentioning users
+                    // dynamically, pushing "safe" versions of content (such as
+                    // bolding normalized content), displaying emojis, and more.
+                    let response = MessageBuilder::new()
+                        .push("User ")
+                        .push_bold_safe(new_message.author.name.as_str())
+                        .push(" used the 'ping' command in the ")
+                        .mention(&channel)
+                        .push(" channel")
+                        .build();
 
-            if let Err(why) = msg.channel_id.say(&context.http, &response).await {
-                println!("Error sending message: {why:?}");
-            }
+                    if let Err(why) = new_message.channel_id.say(&ctx.http, &response).await {
+                        println!("Error sending message: {why:?}");
+                    }
+                }
+            },
+            FullEvent::Ready {
+                data_about_bot, ..
+            } => {
+                println!("{} is connected!", data_about_bot.user.name);
+            },
+            _ => {},
         }
     }
-
-    async fn ready(&self, _: Context, ready: Ready) {
-        println!("{} is connected!", ready.user.name);
-    }
 }
 
 #[tokio::main]