Driver: Automate (re)connection logic (#81)

This PR adds several enhancements to Driver connection logic:
* Driver (re)connection attempts now have a default timeout of around 10s.
* The driver will now attempt to retry full connection attempts using a user-provided strategy: currently, this defaults to 5 attempts under an exponential backoff strategy.
* The driver will now fire `DriverDisconnect` events at the end of any session -- this unifies (re)connection failure events with session expiry as seen in #76, which should provide users with enough detail to know *which* voice channel to reconnect to. Users still need to be careful to read the session/channel IDs to ensure that they aren't overwriting another join.

This has been tested using `cargo make ready`, and by setting low timeouts to force failures in the voice receive example (with some additional error handlers).

Closes #68.

src/events/context/data/connect.rs

@@ -1,7 +1,18 @@
+use crate::id::*;
+
 /// Voice connection details gathered at setup/reinstantiation.
 #[derive(Clone, Debug, Eq, Hash, PartialEq)]
 #[non_exhaustive]
 pub struct ConnectData<'a> {
+    /// ID of the voice channel being joined, if it is known.
+    ///
+    /// If this is available, then this can be used to reconnect/renew
+    /// a voice session via thew gateway.
+    pub channel_id: Option<ChannelId>,
+    /// ID of the target voice channel's parent guild.
+    pub guild_id: GuildId,
+    /// Unique string describing this session for validation/authentication purposes.
+    pub session_id: &'a str,
     /// The domain name of Discord's voice/TURN server.
     ///
     /// With the introduction of Discord's automatic voice server selection,

src/events/context/data/disconnect.rs

@@ -0,0 +1,119 @@
+use crate::{
+    error::ConnectionError,
+    id::*,
+    model::{CloseCode as VoiceCloseCode, FromPrimitive},
+    ws::Error as WsError,
+};
+#[cfg(not(feature = "tokio-02-marker"))]
+use async_tungstenite::tungstenite::protocol::frame::coding::CloseCode;
+#[cfg(feature = "tokio-02-marker")]
+use async_tungstenite_compat::tungstenite::protocol::frame::coding::CloseCode;
+
+/// Voice connection details gathered at termination or failure.
+///
+/// In the event of a failure, this event data is gathered after
+/// a reconnection strategy has exhausted all of its attempts.
+#[derive(Debug)]
+#[non_exhaustive]
+pub struct DisconnectData<'a> {
+    /// The location that a voice connection was terminated.
+    pub kind: DisconnectKind,
+    /// The cause of any connection failure.
+    ///
+    /// If `None`, then this disconnect was requested by the user in some way
+    /// (i.e., leaving or changing voice channels).
+    pub reason: Option<DisconnectReason>,
+    /// ID of the voice channel being joined, if it is known.
+    ///
+    /// If this is available, then this can be used to reconnect/renew
+    /// a voice session via thew gateway.
+    pub channel_id: Option<ChannelId>,
+    /// ID of the target voice channel's parent guild.
+    pub guild_id: GuildId,
+    /// Unique string describing this session for validation/authentication purposes.
+    pub session_id: &'a str,
+}
+
+/// The location that a voice connection was terminated.
+#[derive(Copy, Clone, Debug, Eq, Hash, PartialEq)]
+#[non_exhaustive]
+pub enum DisconnectKind {
+    /// The voice driver failed to connect to the server.
+    ///
+    /// This requires explicit handling at the gateway level
+    /// to either reconnect or fully disconnect.
+    Connect,
+    /// The voice driver failed to reconnect to the server.
+    ///
+    /// This requires explicit handling at the gateway level
+    /// to either reconnect or fully disconnect.
+    Reconnect,
+    /// The voice connection was terminated mid-session by either
+    /// the user or Discord.
+    ///
+    /// If `reason == None`, then this disconnection is either
+    /// a full disconnect or a user-requested channel change.
+    /// Otherwise, this is likely a session expiry (requiring user
+    /// handling to fully disconnect/reconnect).
+    Runtime,
+}
+
+/// The reason that a voice connection failed.
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+#[non_exhaustive]
+pub enum DisconnectReason {
+    /// This (re)connection attempt was dropped due to another request.
+    AttemptDiscarded,
+    /// Songbird had an internal error.
+    ///
+    /// This should never happen; if this is ever seen, raise an issue with logs.
+    Internal,
+    /// A host-specific I/O error caused the fault; this is likely transient, and
+    /// should be retried some time later.
+    Io,
+    /// Songbird and Discord disagreed on the protocol used to establish a
+    /// voice connection.
+    ///
+    /// This should never happen; if this is ever seen, raise an issue with logs.
+    ProtocolViolation,
+    /// A voice connection was not established in the specified time.
+    TimedOut,
+    /// The Websocket connection was closed by Discord.
+    ///
+    /// This typically indicates that the voice session has expired,
+    /// and a new one needs to be requested via the gateway.
+    WsClosed(Option<VoiceCloseCode>),
+}
+
+impl From<&ConnectionError> for DisconnectReason {
+    fn from(e: &ConnectionError) -> Self {
+        use ConnectionError::*;
+
+        match e {
+            AttemptDiscarded => Self::AttemptDiscarded,
+            CryptoModeInvalid
+            | CryptoModeUnavailable
+            | EndpointUrl
+            | ExpectedHandshake
+            | IllegalDiscoveryResponse
+            | IllegalIp
+            | Json(_) => Self::ProtocolViolation,
+            Io(_) => Self::Io,
+            Crypto(_) | InterconnectFailure(_) => Self::Internal,
+            Ws(ws) => ws.into(),
+            TimedOut => Self::TimedOut,
+        }
+    }
+}
+
+impl From<&WsError> for DisconnectReason {
+    fn from(e: &WsError) -> Self {
+        Self::WsClosed(match e {
+            WsError::WsClosed(Some(frame)) => match frame.code {
+                CloseCode::Library(l) => VoiceCloseCode::from_u16(l),
+                _ => None,
+            },
+            _ => None,
+        })
+    }
+}

src/events/context/data/mod.rs

@@ -2,10 +2,11 @@
 //!
 //! [`EventContext`]: super::EventContext
 mod connect;
+mod disconnect;
 mod rtcp;
 mod speaking;
 mod voice;
 
 use discortp::{rtcp::Rtcp, rtp::Rtp};
 
-pub use self::{connect::*, rtcp::*, speaking::*, voice::*};
+pub use self::{connect::*, disconnect::*, rtcp::*, speaking::*, voice::*};