yamuse 0.2.0

typed async client for the yandex music api: catalogue, likes, playlists, radio, lossless downloads and ynison realtime
Documentation
//! error type raised by every fallible operation in the crate.
//!
//! all failures funnel into one [`Error`] enum, so a single `match` covers the
//! whole surface. the http-status variants mirror what the api reports:
//! `unauthorized` for 401/403, `bad_request` for 400, and so on.

use std::io;

/// convenience alias for results returned by this crate.
pub type Result<T> = std::result::Result<T, Error>;

/// every failure this crate can produce.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
    /// authentication or authorization failed (http 401/403, invalid token).
    #[error("unauthorized: {0}")]
    Unauthorized(String),

    /// the server rejected the request as malformed (http 400).
    #[error("bad request: {0}")]
    BadRequest(String),

    /// the requested resource does not exist (http 404).
    #[error("not found: {0}")]
    NotFound(String),

    /// the request conflicts with the resource's current state (http 409).
    ///
    /// deterministic — retrying an identical request fails the same way.
    #[error("conflict: {0}")]
    Conflict(String),

    /// the request payload exceeds the server's size limit (http 413).
    ///
    /// deterministic — retrying an identical request fails the same way.
    #[error("payload too large: {0}")]
    PayloadTooLarge(String),

    /// any other non-success http status.
    #[error("http {status}: {message}")]
    Http {
        /// the status code returned by the server.
        status: u16,
        /// the message extracted from the response body.
        message: String,
    },

    /// the transport failed (connection reset, dns, tls, ...).
    #[error("network: {0}")]
    Network(String),

    /// the request exceeded its timeout.
    #[error("timed out")]
    TimedOut,

    /// the response body was not the json this crate expected.
    #[error("invalid server response: {0}")]
    InvalidResponse(String),

    /// an operation needed an identifier that was not supplied.
    #[error("id missing: {0}")]
    IdMissing(&'static str),

    /// a track was requested with a bitrate or codec that is not available.
    #[error("invalid bitrate: {0}")]
    InvalidBitrate(String),

    /// the oauth device flow failed (excluding the expected pending state).
    #[error("device auth: {0}")]
    DeviceAuth(String),

    /// the ynison realtime protocol failed.
    #[error("ynison: {message}")]
    Ynison {
        /// what went wrong.
        message: String,
        /// how long the server asked us to wait before reconnecting, when it
        /// sent a "go away" frame.
        retry_after: Option<std::time::Duration>,
    },

    /// a filesystem operation failed while streaming a download to disk.
    #[error("io: {0}")]
    Io(#[from] io::Error),
}

impl Error {
    /// map an http status and the message extracted from its body to a variant.
    pub(crate) fn from_status(status: u16, message: String) -> Self {
        match status {
            401 | 403 => Self::Unauthorized(message),
            400 => Self::BadRequest(message),
            404 => Self::NotFound(message),
            409 => Self::Conflict(message),
            413 => Self::PayloadTooLarge(message),
            502 => Self::Network("bad gateway".into()),
            _ => Self::Http { status, message },
        }
    }

    /// build a ynison error without a server-requested delay.
    #[cfg(feature = "realtime")]
    pub(crate) fn ynison(message: impl Into<String>) -> Self {
        Self::Ynison {
            message: message.into(),
            retry_after: None,
        }
    }

    /// whether retrying an identical request could plausibly succeed.
    ///
    /// only transport-level failures qualify. deterministic api rejections
    /// (4xx) always fail the same way, so retrying them just burns quota.
    #[must_use]
    pub fn is_retryable(&self) -> bool {
        match self {
            Self::TimedOut | Self::Network(_) => true,
            Self::Http { status, .. } => *status >= 500,
            _ => false,
        }
    }

    /// how long the server asked us to wait before reconnecting, if it did.
    #[must_use]
    pub fn retry_after(&self) -> Option<std::time::Duration> {
        match self {
            Self::Ynison { retry_after, .. } => *retry_after,
            _ => None,
        }
    }
}

impl From<reqwest::Error> for Error {
    fn from(err: reqwest::Error) -> Self {
        if err.is_timeout() {
            return Self::TimedOut;
        }
        if err.is_decode() {
            return Self::InvalidResponse(err.to_string());
        }
        Self::Network(err.to_string())
    }
}

impl From<serde_json::Error> for Error {
    fn from(err: serde_json::Error) -> Self {
        Self::InvalidResponse(err.to_string())
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn status_maps_to_the_matching_variant() {
        assert!(matches!(
            Error::from_status(401, String::new()),
            Error::Unauthorized(_)
        ));
        assert!(matches!(
            Error::from_status(403, String::new()),
            Error::Unauthorized(_)
        ));
        assert!(matches!(
            Error::from_status(400, String::new()),
            Error::BadRequest(_)
        ));
        assert!(matches!(
            Error::from_status(404, String::new()),
            Error::NotFound(_)
        ));
        assert!(matches!(
            Error::from_status(409, String::new()),
            Error::Conflict(_)
        ));
        assert!(matches!(
            Error::from_status(413, String::new()),
            Error::PayloadTooLarge(_)
        ));
        assert!(matches!(
            Error::from_status(502, String::new()),
            Error::Network(_)
        ));
        assert!(matches!(
            Error::from_status(418, String::new()),
            Error::Http { status: 418, .. }
        ));
    }

    #[test]
    fn only_transport_failures_are_retryable() {
        assert!(Error::TimedOut.is_retryable());
        assert!(Error::Network("reset".into()).is_retryable());
        assert!(
            Error::Http {
                status: 503,
                message: String::new()
            }
            .is_retryable()
        );

        assert!(!Error::BadRequest(String::new()).is_retryable());
        assert!(!Error::NotFound(String::new()).is_retryable());
        assert!(!Error::Conflict(String::new()).is_retryable());
        assert!(!Error::PayloadTooLarge(String::new()).is_retryable());
        assert!(!Error::Unauthorized(String::new()).is_retryable());
        assert!(
            !Error::Http {
                status: 418,
                message: String::new()
            }
            .is_retryable()
        );
    }

    #[test]
    fn retry_after_is_carried_only_by_ynison_go_away() {
        let go_away = Error::Ynison {
            message: "temporary unavailable".into(),
            retry_after: Some(std::time::Duration::from_secs(30)),
        };
        assert_eq!(
            go_away.retry_after(),
            Some(std::time::Duration::from_secs(30))
        );

        let plain = Error::Ynison {
            message: "boom".into(),
            retry_after: None,
        };
        assert_eq!(plain.retry_after(), None);
        assert_eq!(Error::TimedOut.retry_after(), None);
    }
}