//! Errors the subtitle crate can produce. use std::{path::PathBuf, time::Duration}; use crate::model::{CandidateId, ProviderId}; /// Result alias for every fallible operation in this crate. pub type Result = std::result::Result; /// Everything that can go wrong reaching a subtitle provider. /// /// Every variant names the provider, because two are configured at once /// (DESIGN.md §15) and "search failed" without a name is unactionable in the /// operator message §9.5 folds these into. #[derive(Debug, thiserror::Error)] #[non_exhaustive] pub enum Error { /// The provider could not be reached at all, or the connection died. #[error("{provider} is unreachable")] Transport { /// The provider that was called. provider: ProviderId, /// The underlying transport failure. #[source] source: Box, }, /// The provider refused the credentials it was given. /// /// Separate from [`Error::Transport`] because it never resolves by /// retrying: the configuration is wrong (DESIGN.md §10). #[error("{provider} rejected the configured credentials")] Unauthorized { /// The provider that was called. provider: ProviderId, }, /// The provider's rate limit or daily download cap was hit. /// /// Its own variant so the reconcile loop can show it as a queue state /// rather than a failure — being at the cap is expected (DESIGN.md §15). #[error("{provider} is at its cap")] RateLimited { /// The provider that was called. provider: ProviderId, /// How long the provider asked to be left alone, when it says. retry_after: Option, }, /// A candidate the provider offered is no longer downloadable. #[error("{provider} no longer has candidate {candidate}")] NotFound { /// The provider that was called. provider: ProviderId, /// The candidate that was asked for. candidate: CandidateId, }, /// The provider answered, but not with the shape its API documents. #[error("{provider} answered with something unexpected: {detail}")] Malformed { /// The provider that was called. provider: ProviderId, /// What was wrong, short enough to log. detail: String, }, /// Reading or writing a file on the way to or from a provider failed. #[error("could not read {path}")] Io { /// The file involved. path: PathBuf, /// The underlying IO failure. #[source] source: std::io::Error, }, } impl Error { /// Whether calling the same provider again later is worth doing. /// /// A cap lifts and a network recovers; bad credentials and a malformed /// response do not fix themselves, and retrying them only burns budget. #[must_use] pub const fn is_transient(&self) -> bool { matches!(self, Self::Transport { .. } | Self::RateLimited { .. }) } } #[cfg(test)] mod tests { use super::Error; use crate::model::ProviderId; #[test] fn a_cap_is_worth_retrying_and_a_bad_key_is_not() { let provider = ProviderId::new("opensubtitles"); assert!(Error::RateLimited { provider: provider.clone(), retry_after: None, } .is_transient()); assert!(!Error::Unauthorized { provider }.is_transient()); } }