Events: Deprecate ClientConnect (#112)

Discord no longer send these websocket payloads, users should instead rely on the main part of their bot for determining actual connection events, or `SpeakingUpdate`s for SSRC mapping.

Closes #104.

examples/serenity/voice_receive/src/main.rs

@@ -29,7 +29,7 @@ use serenity::{
 
 use songbird::{
     driver::DecodeMode,
-    model::payload::{ClientConnect, ClientDisconnect, Speaking},
+    model::payload::{ClientDisconnect, Speaking},
     Config,
     CoreEvent,
     Event,
@@ -86,7 +86,7 @@ impl VoiceEventHandler for Receiver {
             },
             Ctx::SpeakingUpdate(data) => {
                 // You can implement logic here which reacts to a user starting
-                // or stopping speaking.
+                // or stopping speaking, and to map their SSRC to User ID.
                 println!(
                     "Source {} has {} speaking.",
                     data.ssrc,
@@ -114,19 +114,6 @@ impl VoiceEventHandler for Receiver {
                 // containing the call statistics and reporting information.
                 println!("RTCP packet received: {:?}", data.packet);
             },
-            Ctx::ClientConnect(
-                ClientConnect {audio_ssrc, video_ssrc, user_id, ..}
-            ) => {
-                // You can implement your own logic here to handle a user who has joined the
-                // voice channel e.g., allocate structures, map their SSRC to User ID.
-
-                println!(
-                    "Client connected: user {:?} has audio SSRC {:?}, video SSRC {:?}",
-                    user_id,
-                    audio_ssrc,
-                    video_ssrc,
-                );
-            },
             Ctx::ClientDisconnect(
                 ClientDisconnect {user_id, ..}
             ) => {
@@ -224,11 +211,6 @@ async fn join(ctx: &Context, msg: &Message, mut args: Args) -> CommandResult {
             Receiver::new(),
         );
 
-        handler.add_global_event(
-            CoreEvent::ClientConnect.into(),
-            Receiver::new(),
-        );
-
         handler.add_global_event(
             CoreEvent::ClientDisconnect.into(),
             Receiver::new(),

src/events/context/mod.rs

@@ -38,8 +38,19 @@ pub enum EventContext<'a> {
     VoicePacket(VoiceData<'a>),
     /// Telemetry/statistics packet, received from another stream.
     RtcpPacket(RtcpData<'a>),
-    /// Fired whenever a client connects to a call for the first time, allowing SSRC/UserID
+    #[deprecated(
-    /// matching.
+        since = "0.2.2",
+        note = "ClientConnect events are no longer sent by Discord. Please use SpeakingUpdate or Discord gateway events."
+    )]
+    /// Formerly fired whenever a client connects to a call for the first time, allowing SSRC/UserID
+    /// matching. This event no longer fires.
+    ///
+    /// To detect when a user connects, you must correlate gateway (e.g., VoiceStateUpdate) events
+    /// from the main part of your bot.
+    ///
+    /// To obtain a user's SSRC, you must use [`SpeakingUpdate`] events.
+    ///
+    /// [`SpeakingUpdate`]: Self::SpeakingUpdate
     ClientConnect(ClientConnect),
     /// Fired whenever a client disconnects.
     ClientDisconnect(ClientDisconnect),
@@ -114,6 +125,7 @@ impl<'a> CoreContext {
             SpeakingUpdate(evt) => EventContext::SpeakingUpdate(SpeakingUpdateData::from(evt)),
             VoicePacket(evt) => EventContext::VoicePacket(VoiceData::from(evt)),
             RtcpPacket(evt) => EventContext::RtcpPacket(RtcpData::from(evt)),
+            #[allow(deprecated)]
             ClientConnect(evt) => EventContext::ClientConnect(*evt),
             ClientDisconnect(evt) => EventContext::ClientDisconnect(*evt),
             DriverConnect(evt) => EventContext::DriverConnect(ConnectData::from(evt)),
@@ -140,6 +152,7 @@ impl EventContext<'_> {
             SpeakingUpdate(_) => Some(CoreEvent::SpeakingUpdate),
             VoicePacket(_) => Some(CoreEvent::VoicePacket),
             RtcpPacket(_) => Some(CoreEvent::RtcpPacket),
+            #[allow(deprecated)]
             ClientConnect(_) => Some(CoreEvent::ClientConnect),
             ClientDisconnect(_) => Some(CoreEvent::ClientDisconnect),
             DriverConnect(_) => Some(CoreEvent::DriverConnect),

src/events/core.rs

@@ -25,7 +25,19 @@ pub enum CoreEvent {
     /// Fires on receipt of an RTCP packet, containing various call stats
     /// such as latency reports.
     RtcpPacket,
-    /// Fires whenever a user connects to the same stream as the bot.
+    #[deprecated(
+        since = "0.2.2",
+        note = "ClientConnect events are no longer sent by Discord. Please use SpeakingUpdate or Discord gateway events."
+    )]
+    /// Formerly fired whenever a client connects to a call for the first time, allowing SSRC/UserID
+    /// matching. This event no longer fires.
+    ///
+    /// To detect when a user connects, you must correlate gateway (e.g., VoiceStateUpdate) events
+    /// from the main part of your bot.
+    ///
+    /// To obtain a user's SSRC, you must use [`SpeakingUpdate`] events.
+    ///
+    /// [`SpeakingUpdate`]: Self::SpeakingUpdate
     ClientConnect,
     /// Fires whenever a user disconnects from the same stream as the bot.
     ClientDisconnect,