/// Failures from a remote backend.
#[derive(Debug, thiserror::Error)]
pub enum RemoteError {
    #[error("not authenticated")]
    Unauthenticated,

    #[error("authentication rejected")]
    AuthFailed,

    /// Authenticated, but not permitted to do this.
    ///
    /// **Distinct from [`AuthFailed`](Self::AuthFailed) on purpose.** Folding
    /// 403 into 401 sends the user to re-check a credential that is working
    /// perfectly: reads succeed, only the write is refused. On Nextcloud the
    /// usual cause is an app password created without "Allow filesystem
    /// access", or a read-only share — neither of which signing in again will
    /// fix.
    #[error("permission denied — the account is authenticated but not allowed to write here")]
    PermissionDenied,

    #[error("not found: {0}")]
    NotFound(String),

    /// The backend does not support this operation. Expected, not a bug —
    /// callers check capabilities and adapt.
    #[error("operation unsupported by this backend: {0}")]
    Unsupported(&'static str),

    /// A conditional write failed: the remote changed underneath us. Triggers
    /// the sidecar merge path (ARCH §8.5).
    #[error("precondition failed — remote was modified")]
    PreconditionFailed,

    #[error("quota exceeded")]
    QuotaExceeded,

    #[error("network error: {0}")]
    Network(String),

    #[error("unexpected server response: {status} {detail}")]
    Server { status: u16, detail: String },

    #[error("malformed response: {0}")]
    Protocol(String),

    #[error("operation cancelled")]
    Cancelled,
}

impl RemoteError {
    /// Whether retrying might succeed.
    pub fn is_transient(&self) -> bool {
        match self {
            RemoteError::Network(_) => true,
            RemoteError::Server { status, .. } => {
                // 5xx and 429 are worth retrying; other 4xx are not.
                //
                // 423 Locked is the exception, and it is not hypothetical:
                // Nextcloud's file locking returns it on a plain *read* under
                // concurrency, and the same range re-read seconds later
                // succeeds. Treating it as permanent marks an image
                // permanently undated over a lock that lasted moments.
                *status >= 500 || *status == 429 || *status == 423
            }
            _ => false,
        }
    }

    /// Whether this failure means *the server could not be reached*, as
    /// opposed to the server answering and refusing.
    ///
    /// The distinction is the whole basis of offline mode (FR-CAT-9). A 403
    /// and a dead connection are both "the operation failed", but only one of
    /// them is fixed by waiting, and only one of them should put the whole app
    /// into a degraded mode. Signing the user out — or showing "you are
    /// offline" — because a single file was forbidden would be a much worse
    /// error than the one it reported.
    ///
    /// A 5xx is deliberately **not** offline: the server is up and talking, it
    /// is just failing, and a retry is the right response rather than a
    /// mode change. 429 and 423 likewise — those are the server working
    /// correctly under load.
    pub fn indicates_offline(&self) -> bool {
        matches!(self, RemoteError::Network(_))
    }
}

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

    #[test]
    fn transient_errors_are_retryable() {
        assert!(RemoteError::Network("timeout".into()).is_transient());
        assert!(RemoteError::Server {
            status: 503,
            detail: String::new()
        }
        .is_transient());
        assert!(RemoteError::Server {
            status: 429,
            detail: String::new()
        }
        .is_transient());
    }

    #[test]
    fn client_errors_are_not_retryable() {
        assert!(!RemoteError::Server {
            status: 404,
            detail: String::new()
        }
        .is_transient());
        assert!(!RemoteError::PreconditionFailed.is_transient());
        assert!(!RemoteError::AuthFailed.is_transient());
        // Neither is worth retrying, but they mean different things and a
        // caller may want to say so.
        assert!(!RemoteError::PermissionDenied.is_transient());
    }

    #[test]
    fn permission_denied_is_not_an_auth_failure() {
        // 403 folded into 401 sent a user to re-check a credential that was
        // working: reads succeeded and only the write was refused (observed
        // against a real server, 2026-08-09). The two must read differently.
        let denied = RemoteError::PermissionDenied.to_string();
        let rejected = RemoteError::AuthFailed.to_string();
        assert_ne!(denied, rejected);
        assert!(
            denied.contains("not allowed to write"),
            "the message must point at permissions, not the login: {denied}"
        );
    }

    #[test]
    fn a_lock_is_transient() {
        // Observed against a real server: 12 concurrent range reads produced
        // 423 on some files, and the identical request succeeded moments
        // later. Classing it with the permanent 4xx left those images
        // undated for good.
        assert!(RemoteError::Server {
            status: 423,
            detail: String::new()
        }
        .is_transient());

        // Still permanent, so the exception stays narrow.
        assert!(!RemoteError::Server {
            status: 404,
            detail: String::new()
        }
        .is_transient());
        assert!(!RemoteError::Server {
            status: 400,
            detail: String::new()
        }
        .is_transient());
    }
}