Plan: retry observability contract (#462 narrowed)

// SPDX-License-Identifier: AGPL-3.0-or-later

//! Bounded exponential-backoff retry for outbound reqwest calls.
//!
//! Coordinates with the server-side idempotency middleware
//! (`canopy_api::idempotency_middleware`) so retried POSTs replay
//! safely. Emits `tracing::info!(target: "retry", ...)` before each
//! retry attempt — operators grep this target in canopy_logs to
//! correlate transient downstream blips with the runbook.

use std::time::Duration;

const BACKOFF_INITIAL_MS: u64 = 100;
const BACKOFF_MAX_MS: u64 = 30_000;

/// Tunables for retry behavior. Fields are private; construct via
/// [`RetryPolicy::default_http`] and refine via the `with_*` setters,
/// which assert invariants (no zero `max_attempts`, no NaN/negative
/// `jitter`).
#[derive(Debug, Clone)]
pub struct RetryPolicy {
    max_attempts: u32,
    initial_backoff: Duration,
    max_backoff: Duration,
    overall_timeout: Option<Duration>,
    jitter: f64,
}

impl RetryPolicy {
    /// HTTP-typical defaults: 3 attempts, 100ms → 30s backoff, ±25%
    /// jitter, no overall_timeout.
    pub const fn default_http() -> Self {
        Self {
            max_attempts: 3,
            initial_backoff: Duration::from_millis(BACKOFF_INITIAL_MS),
            max_backoff: Duration::from_millis(BACKOFF_MAX_MS),
            overall_timeout: None,
            jitter: 0.25,
        }
    }

    /// Override the attempt cap. **Panics** if `n == 0`.
    pub fn with_max_attempts(mut self, n: u32) -> Self {
        assert!(n > 0, "RetryPolicy::with_max_attempts: n must be > 0; got 0");
        self.max_attempts = n;
        self
    }

    /// Bound total wall-clock across all attempts.
    pub fn with_overall_timeout(mut self, d: Duration) -> Self {
        self.overall_timeout = Some(d);
        self
    }

    /// Override backoff jitter as a fraction (e.g. 0.25 = ±25%).
    /// **Panics** if `j` is NaN, negative, or >= 1.0.
    pub fn with_jitter(mut self, j: f64) -> Self {
        assert!(
            j.is_finite() && j >= 0.0 && j < 1.0,
            "RetryPolicy::with_jitter: j must be finite, in [0.0, 1.0); got {j}"
        );
        self.jitter = j;
        self
    }

    /// Read-only access to `max_attempts` for tests / metrics.
    pub fn max_attempts(&self) -> u32 { self.max_attempts }
}

/// Description of the request being retried. Fields are private so
/// callers cannot construct an unsafe descriptor (e.g., POST without an
/// idempotency key). Use the typed constructors.
#[derive(Debug, Clone)]
pub struct RetryRequest {
    method: reqwest::Method,
    has_idempotency_key: bool,
}

/// Reason a `RetryRequest` cannot be constructed for the requested
/// method/key combination.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum RetryRejection {
    /// POST requires an idempotency key so the server-side cache can
    /// replay the first response on retry.
    #[error("POST without an Idempotency-Key is not retryable")]
    PostWithoutKey,
    /// PATCH/PUT are not retryable in this iteration — server-side
    /// idempotency middleware caches POST only.
    #[error("{0} is not retryable in this iteration (server-side idempotency cache covers POST only)")]
    MethodUnsupported(reqwest::Method),
}

impl RetryRequest {
    pub fn get() -> Self { Self { method: reqwest::Method::GET, has_idempotency_key: false } }
    pub fn head() -> Self { Self { method: reqwest::Method::HEAD, has_idempotency_key: false } }
    pub fn delete() -> Self { Self { method: reqwest::Method::DELETE, has_idempotency_key: false } }
    pub fn post_with_idempotency_key() -> Self {
        Self { method: reqwest::Method::POST, has_idempotency_key: true }
    }
    pub fn try_new(method: reqwest::Method, has_idempotency_key: bool) -> Result<Self, RetryRejection> {
        match method {
            reqwest::Method::GET | reqwest::Method::HEAD | reqwest::Method::DELETE => {
                Ok(Self { method, has_idempotency_key })
            }
            reqwest::Method::POST if has_idempotency_key => Ok(Self { method, has_idempotency_key }),
            reqwest::Method::POST => Err(RetryRejection::PostWithoutKey),
            other => Err(RetryRejection::MethodUnsupported(other)),
        }
    }
    pub fn method(&self) -> &reqwest::Method { &self.method }
    pub fn has_idempotency_key(&self) -> bool { self.has_idempotency_key }
}

/// Decision returned by [`classify`].
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RetryDecision {
    /// Outcome is retryable (transient failure).
    Retry,
    /// Outcome is terminal — return immediately.
    Stop,
}

/// Classify an attempt outcome from the typed `reqwest` shape.
pub fn classify(
    status: Option<reqwest::StatusCode>,
    err: Option<&reqwest::Error>,
) -> RetryDecision {
    if let Some(e) = err {
        if e.is_connect() || e.is_timeout() { return RetryDecision::Retry; }
        return RetryDecision::Stop;
    }
    let Some(status) = status else { return RetryDecision::Stop; };
    if status.is_server_error()
        || status == reqwest::StatusCode::REQUEST_TIMEOUT
        || status == reqwest::StatusCode::TOO_MANY_REQUESTS
    {
        RetryDecision::Retry
    } else {
        RetryDecision::Stop
    }
}

/// Strongly-typed retry error.
#[derive(Debug, thiserror::Error)]
pub enum RetryError {
    /// Hit `max_attempts` with the last attempt also failing.
    #[error("retry exhausted after {attempts} attempts (last status={last_status:?})")]
    Exhausted {
        attempts: u32,
        last_status: Option<reqwest::StatusCode>,
        last_error: Option<String>,
    },
    /// `overall_timeout` elapsed before the loop completed.
    #[error("retry overall timeout after {elapsed:?}")]
    OverallTimeout { elapsed: Duration },
    /// Per-attempt budget exceeded AND no further retry was possible.
    #[error("retry per-attempt timeout after {elapsed:?}")]
    AttemptTimeout { elapsed: Duration },
    /// Non-retryable transport error wrapping the typed reqwest::Error.
    #[error("network error: {0}")]
    Network(#[source] reqwest::Error),
}

/// Run a request with bounded retry. See module docs.
pub async fn retry_request<F, Fut>(
    policy: &RetryPolicy,
    request: &RetryRequest,
    make_req: F,
) -> Result<reqwest::Response, RetryError>
where
    F: Fn() -> Fut,
    Fut: std::future::Future<Output = Result<reqwest::Response, reqwest::Error>>,
{
    // ... full implementation per the design ...
    unimplemented!() // filled in during Step 3
}