dig-rpc-types 0.2.1

//! The canonical DIG-node RPC error taxonomy.
//!
//! This module is the **single definition point** for every error code the DIG
//! node RPC surface emits, the canonical [`RpcError`] envelope
//! (`{code, message, data:{code, origin}}`), and the one constructor helper both
//! node implementations call so every error carries a machine-branchable
//! `data.code` and `data.origin`.
//!
//! # The code set
//!
//! Standard JSON-RPC 2.0 codes plus the DIG protocol-specific codes. The numeric
//! values are a **published wire contract** and never change once assigned.
//!
//! | Code | Variant | Origin | Meaning |
//! |---|---|---|---|
//! | `-32700` | [`ParseError`](ErrorCode::ParseError) | Node | request body is not valid JSON |
//! | `-32600` | [`InvalidRequest`](ErrorCode::InvalidRequest) | Node | not a valid Request object |
//! | `-32601` | [`MethodNotFound`](ErrorCode::MethodNotFound) | Node | method not implemented |
//! | `-32602` | [`InvalidParams`](ErrorCode::InvalidParams) | Node | missing/malformed params |
//! | `-32603` | [`InternalError`](ErrorCode::InternalError) | Node | well-formed call failed |
//! | `-32000` | [`ServerError`](ErrorCode::ServerError) | Node | generic server error |
//! | `-32004` | [`ResourceUnavailable`](ErrorCode::ResourceUnavailable) | Node | resource not available at the requested root (genuine infra miss) |
//! | `-32005` | [`RootNotAnchored`](ErrorCode::RootNotAnchored) | Node | requested/served root is not the chain-anchored root (fail-closed pin) |
//! | `-32006` | [`PeerUnreachable`](ErrorCode::PeerUnreachable) | Node | no NAT-traversal strategy reached the peer |
//! | `-32007` | [`RangeNotSatisfiable`](ErrorCode::RangeNotSatisfiable) | Node | byte range lies outside the resource |
//! | `-32008` | [`ContentRedirect`](ErrorCode::ContentRedirect) | Node | content held elsewhere — `data.redirect` names holders |
//! | `-32010` | [`UpstreamError`](ErrorCode::UpstreamError) | Upstream | an upstream/proxy fetch failed |
//! | `-32011` | [`StageInvalidInput`](ErrorCode::StageInvalidInput) | Node | `dig.stage`: dir unreadable / walk budget exceeded |
//! | `-32012` | [`StageNoFiles`](ErrorCode::StageNoFiles) | Node | `dig.stage`: no files to compile |
//! | `-32013` | [`StageOverCap`](ErrorCode::StageOverCap) | Node | `dig.stage`: input exceeds the store cap |
//! | `-32014` | [`StageCompileFailed`](ErrorCode::StageCompileFailed) | Node | `dig.stage`: compile / IO failure |
//! | `-32020` | [`OnionCircuitUnavailable`](ErrorCode::OnionCircuitUnavailable) | Onion | private read could not build/keep a circuit |
//! | `-32021` | [`PrivacyRequiresLocalNode`](ErrorCode::PrivacyRequiresLocalNode) | Onion | privacy mode requires the caller be a local originator |
//! | `-32022` | [`OnionHopsOutOfRange`](ErrorCode::OnionHopsOutOfRange) | Onion | requested hop count outside `[2, 5]` |
//! | `-32030` | [`Unauthorized`](ErrorCode::Unauthorized) | Control | control-plane call is not authorized |
//! | `-32031` | [`NotSupported`](ErrorCode::NotSupported) | Control | control-plane method not supported here |
//! | `-32032` | [`ControlError`](ErrorCode::ControlError) | Control | control-plane runtime error |
//!
//! ## The `-32020..-32022` collision, resolved
//!
//! The published normative protocol (docs.dig.net) assigns `-32020/-32021/-32022`
//! to the **onion** (private-retrieval) failures. Those keep their numbers. The
//! control-plane errors that previously squatted the same values are renumbered
//! to `-32030/-32031/-32032`.

use serde::{Deserialize, Serialize};
use serde_repr::{Deserialize_repr, Serialize_repr};

/// A canonical DIG-node RPC error code.
///
/// Serializes as a bare integer (via `serde_repr`), spec-compliant for
/// `error.code`. `#[non_exhaustive]` so adding a code in a minor release is
/// additive; downstream matches must use `_ => …`.
#[repr(i32)]
#[non_exhaustive]
#[derive(Debug, Clone, Copy, Serialize_repr, Deserialize_repr, PartialEq, Eq, Hash)]
pub enum ErrorCode {
    // ---- Standard JSON-RPC 2.0 ----
    /// Invalid JSON was received by the server.
    ParseError = -32700,
    /// The JSON sent is not a valid Request object.
    InvalidRequest = -32600,
    /// The method does not exist / is not available.
    MethodNotFound = -32601,
    /// Invalid method parameter(s).
    InvalidParams = -32602,
    /// The node failed to satisfy a well-formed call (network profile).
    InternalError = -32603,

    // ---- DIG protocol-specific (implementation-defined server range) ----
    /// Generic server error (config write failure, file I/O, chain read failure).
    ServerError = -32000,
    /// Resource not available at the requested root — a genuine infrastructure
    /// miss (absent module, bad magic, oversize, a trap, an undecodable
    /// envelope). Distinct from a content miss, which is an indistinguishable
    /// decoy and is never an error.
    ResourceUnavailable = -32004,
    /// The requested or served generation is not the store's current on-chain
    /// root. The read path pins to the CHIP-0035 singleton's on-chain root and
    /// fails closed rather than serving an unverified generation.
    RootNotAnchored = -32005,
    /// No connection to the named peer could be established — every
    /// NAT-traversal strategy failed, or the peer is not on this network.
    PeerUnreachable = -32006,
    /// The requested byte range lies outside the resource (`offset >=
    /// total_length`) or is otherwise unsatisfiable.
    RangeNotSatisfiable = -32007,
    /// This node does not hold the content but located peers that do.
    /// `data.redirect` names the holders + the redirect budget.
    ContentRedirect = -32008,
    /// An upstream/proxy fetch (e.g. `rpc.dig.net`) failed. Distinct from the
    /// generic [`ServerError`](ErrorCode::ServerError) so a client can tell an
    /// upstream fault from a local one.
    UpstreamError = -32010,
    /// `dig.stage`: the input directory is unreadable, or the bounded walk
    /// exceeded its byte / file-count / depth budget.
    StageInvalidInput = -32011,
    /// `dig.stage`: the input directory contained no files to compile.
    StageNoFiles = -32012,
    /// `dig.stage`: the input exceeds the per-store size cap.
    StageOverCap = -32013,
    /// `dig.stage`: compiling the capsule failed (CLVM/IO error).
    StageCompileFailed = -32014,

    // ---- Onion / private retrieval (published normative — KEEP) ----
    /// A `mode:"privacy"` read could not be served privately (no circuit could
    /// be built, or one died mid-fetch). The node fails closed rather than
    /// downgrading — a silent downgrade would deanonymize the reader.
    OnionCircuitUnavailable = -32020,
    /// `mode:"privacy"` was requested but the caller is not the node's own
    /// trusted local originator. Privacy requires a local DIG node.
    PrivacyRequiresLocalNode = -32021,
    /// The requested `privacy.hops` (circuit length) is outside `[2, 5]`.
    OnionHopsOutOfRange = -32022,

    // ---- Control plane (loopback-only; renumbered off the onion codes) ----
    /// The control-plane call is not authorized (loopback / token gate failed).
    Unauthorized = -32030,
    /// The control-plane method is recognized but not supported on this node.
    NotSupported = -32031,
    /// A control-plane runtime error (pin registry, sync trigger, config write).
    ControlError = -32032,
}

impl ErrorCode {
    /// The raw integer wire code.
    pub const fn code(self) -> i32 {
        self as i32
    }

    /// The stable `UPPER_SNAKE_CASE` machine identifier carried in `data.code`.
    ///
    /// This is the branch key an agent keys on; it never changes once assigned.
    pub const fn machine_code(self) -> &'static str {
        match self {
            ErrorCode::ParseError => "PARSE_ERROR",
            ErrorCode::InvalidRequest => "INVALID_REQUEST",
            ErrorCode::MethodNotFound => "METHOD_NOT_FOUND",
            ErrorCode::InvalidParams => "INVALID_PARAMS",
            ErrorCode::InternalError => "INTERNAL_ERROR",
            ErrorCode::ServerError => "SERVER_ERROR",
            ErrorCode::ResourceUnavailable => "RESOURCE_UNAVAILABLE",
            ErrorCode::RootNotAnchored => "ROOT_NOT_ANCHORED",
            ErrorCode::PeerUnreachable => "PEER_UNREACHABLE",
            ErrorCode::RangeNotSatisfiable => "RANGE_NOT_SATISFIABLE",
            ErrorCode::ContentRedirect => "CONTENT_REDIRECT",
            ErrorCode::UpstreamError => "UPSTREAM_ERROR",
            ErrorCode::StageInvalidInput => "STAGE_INVALID_INPUT",
            ErrorCode::StageNoFiles => "STAGE_NO_FILES",
            ErrorCode::StageOverCap => "STAGE_OVER_CAP",
            ErrorCode::StageCompileFailed => "STAGE_COMPILE_FAILED",
            ErrorCode::OnionCircuitUnavailable => "ONION_CIRCUIT_UNAVAILABLE",
            ErrorCode::PrivacyRequiresLocalNode => "PRIVACY_REQUIRES_LOCAL_NODE",
            ErrorCode::OnionHopsOutOfRange => "ONION_HOPS_OUT_OF_RANGE",
            ErrorCode::Unauthorized => "UNAUTHORIZED",
            ErrorCode::NotSupported => "NOT_SUPPORTED",
            ErrorCode::ControlError => "CONTROL_ERROR",
        }
    }

    /// The default human-readable summary for this code (used when a caller does
    /// not supply a more specific message).
    pub const fn default_message(self) -> &'static str {
        match self {
            ErrorCode::ParseError => "Parse error",
            ErrorCode::InvalidRequest => "Invalid request",
            ErrorCode::MethodNotFound => "Method not found",
            ErrorCode::InvalidParams => "Invalid params",
            ErrorCode::InternalError => "Internal error",
            ErrorCode::ServerError => "Server error",
            ErrorCode::ResourceUnavailable => "Resource not available at the requested root",
            ErrorCode::RootNotAnchored => "Root not chain-anchored",
            ErrorCode::PeerUnreachable => "Peer unreachable",
            ErrorCode::RangeNotSatisfiable => "Range not satisfiable",
            ErrorCode::ContentRedirect => "Content held elsewhere — redirect",
            ErrorCode::UpstreamError => "Upstream error",
            ErrorCode::StageInvalidInput => "Stage input directory not readable",
            ErrorCode::StageNoFiles => "Stage input contained no files",
            ErrorCode::StageOverCap => "Stage input over the store cap",
            ErrorCode::StageCompileFailed => "Stage compile failed",
            ErrorCode::OnionCircuitUnavailable => "Onion circuit unavailable",
            ErrorCode::PrivacyRequiresLocalNode => "Privacy requires a local node",
            ErrorCode::OnionHopsOutOfRange => "Onion hop count out of range",
            ErrorCode::Unauthorized => "Unauthorized",
            ErrorCode::NotSupported => "Not supported",
            ErrorCode::ControlError => "Control-plane error",
        }
    }

    /// The natural [`ErrorOrigin`] for this code (which subsystem the failure
    /// arose in). A caller may override it — a `ResourceUnavailable` bubbled up
    /// from an upstream proxy can be tagged [`ErrorOrigin::Upstream`].
    pub const fn default_origin(self) -> ErrorOrigin {
        match self {
            ErrorCode::UpstreamError => ErrorOrigin::Upstream,
            ErrorCode::OnionCircuitUnavailable
            | ErrorCode::PrivacyRequiresLocalNode
            | ErrorCode::OnionHopsOutOfRange => ErrorOrigin::Onion,
            ErrorCode::Unauthorized | ErrorCode::NotSupported | ErrorCode::ControlError => {
                ErrorOrigin::Control
            }
            ErrorCode::PeerUnreachable => ErrorOrigin::Peer,
            _ => ErrorOrigin::Node,
        }
    }

    /// Whether this variant is in the JSON-RPC-reserved range
    /// (`-32768..=-32000`).
    pub const fn is_jsonrpc_reserved(self) -> bool {
        let c = self.code();
        c >= -32768 && c <= -32000
    }

    /// Every code, in wire order. Drives the OpenRPC error catalogue and the
    /// exhaustiveness conformance test — a new variant must be added here.
    pub const ALL: &'static [ErrorCode] = &[
        ErrorCode::ParseError,
        ErrorCode::InvalidRequest,
        ErrorCode::MethodNotFound,
        ErrorCode::InvalidParams,
        ErrorCode::InternalError,
        ErrorCode::ServerError,
        ErrorCode::ResourceUnavailable,
        ErrorCode::RootNotAnchored,
        ErrorCode::PeerUnreachable,
        ErrorCode::RangeNotSatisfiable,
        ErrorCode::ContentRedirect,
        ErrorCode::UpstreamError,
        ErrorCode::StageInvalidInput,
        ErrorCode::StageNoFiles,
        ErrorCode::StageOverCap,
        ErrorCode::StageCompileFailed,
        ErrorCode::OnionCircuitUnavailable,
        ErrorCode::PrivacyRequiresLocalNode,
        ErrorCode::OnionHopsOutOfRange,
        ErrorCode::Unauthorized,
        ErrorCode::NotSupported,
        ErrorCode::ControlError,
    ];
}

/// The subsystem a failure arose in — carried in `data.origin` so a client can
/// route the error (retry upstream, rebuild a circuit, re-auth the control
/// plane) without parsing the message.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "lowercase")]
pub enum ErrorOrigin {
    /// The node's own read/serve path.
    Node,
    /// The peer-network layer (discovery / availability / range serving).
    Peer,
    /// An upstream fetch (`rpc.dig.net` proxy / whole-store sync).
    Upstream,
    /// The onion (private-retrieval) layer.
    Onion,
    /// The loopback control plane.
    Control,
}

/// Structured error context carried in `error.data`.
///
/// The canonical DIG envelope always carries `data.code` (the
/// [`UPPER_SNAKE_CASE`](ErrorCode::machine_code) machine identifier) and
/// `data.origin`. `redirect` is present only on
/// [`ContentRedirect`](ErrorCode::ContentRedirect); `extra` carries any
/// method-specific fields verbatim (flattened onto `data`).
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ErrorData {
    /// The stable `UPPER_SNAKE_CASE` machine code (mirrors the numeric `code`).
    pub code: String,
    /// The subsystem the failure arose in.
    pub origin: ErrorOrigin,
    /// The redirect payload — present only on `CONTENT_REDIRECT`.
    #[serde(skip_serializing_if = "Option::is_none", default)]
    pub redirect: Option<crate::types::RedirectInfo>,
    /// Any additional method-specific fields, flattened onto `data`.
    #[serde(flatten, default, skip_serializing_if = "serde_json::Map::is_empty")]
    pub extra: serde_json::Map<String, serde_json::Value>,
}

/// The canonical DIG-node RPC error object: `{code, message, data:{code, origin}}`.
///
/// Build one with [`RpcError::new`] (or the code-specific helpers) so the numeric
/// code, the `data.code` machine string, and the origin can never drift apart.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RpcError {
    /// The numeric wire code.
    pub code: ErrorCode,
    /// A human-readable message. May be refined over time; `data.code` is the
    /// stable branch key.
    pub message: String,
    /// Structured, machine-branchable context.
    pub data: ErrorData,
}

impl RpcError {
    /// The single constructor: mint the canonical envelope from a code, a
    /// message, and an origin. `data.code` is derived from `code` so the two
    /// can never disagree.
    pub fn new(code: ErrorCode, message: impl Into<String>, origin: ErrorOrigin) -> Self {
        Self {
            code,
            message: message.into(),
            data: ErrorData {
                code: code.machine_code().to_string(),
                origin,
                redirect: None,
                extra: serde_json::Map::new(),
            },
        }
    }

    /// Mint an error using the code's [default origin](ErrorCode::default_origin).
    pub fn of(code: ErrorCode, message: impl Into<String>) -> Self {
        Self::new(code, message, code.default_origin())
    }

    /// Mint an error using both the code's default origin and its
    /// [default message](ErrorCode::default_message).
    pub fn code_only(code: ErrorCode) -> Self {
        Self::new(code, code.default_message(), code.default_origin())
    }

    /// Attach a [`RedirectInfo`](crate::types::RedirectInfo) payload (for
    /// [`ContentRedirect`](ErrorCode::ContentRedirect)).
    pub fn with_redirect(mut self, redirect: crate::types::RedirectInfo) -> Self {
        self.data.redirect = Some(redirect);
        self
    }

    /// Attach one extra `data` field (flattened onto `data`).
    pub fn with_extra(mut self, key: impl Into<String>, value: serde_json::Value) -> Self {
        self.data.extra.insert(key.into(), value);
        self
    }
}

impl std::fmt::Display for RpcError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "[{}] {}", self.code.machine_code(), self.message)
    }
}

impl std::error::Error for RpcError {}

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

    /// **Proves:** every numeric code is pinned to its published wire value.
    /// **Catches:** a reorder/renumber, or a lost `#[repr(i32)]`.
    #[test]
    fn numeric_values_pinned() {
        assert_eq!(ErrorCode::ParseError.code(), -32700);
        assert_eq!(ErrorCode::InvalidRequest.code(), -32600);
        assert_eq!(ErrorCode::MethodNotFound.code(), -32601);
        assert_eq!(ErrorCode::InvalidParams.code(), -32602);
        assert_eq!(ErrorCode::InternalError.code(), -32603);
        assert_eq!(ErrorCode::ServerError.code(), -32000);
        assert_eq!(ErrorCode::ResourceUnavailable.code(), -32004);
        assert_eq!(ErrorCode::RootNotAnchored.code(), -32005);
        assert_eq!(ErrorCode::PeerUnreachable.code(), -32006);
        assert_eq!(ErrorCode::RangeNotSatisfiable.code(), -32007);
        assert_eq!(ErrorCode::ContentRedirect.code(), -32008);
        assert_eq!(ErrorCode::UpstreamError.code(), -32010);
        assert_eq!(ErrorCode::StageInvalidInput.code(), -32011);
        assert_eq!(ErrorCode::StageNoFiles.code(), -32012);
        assert_eq!(ErrorCode::StageOverCap.code(), -32013);
        assert_eq!(ErrorCode::StageCompileFailed.code(), -32014);
        assert_eq!(ErrorCode::OnionCircuitUnavailable.code(), -32020);
        assert_eq!(ErrorCode::PrivacyRequiresLocalNode.code(), -32021);
        assert_eq!(ErrorCode::OnionHopsOutOfRange.code(), -32022);
        assert_eq!(ErrorCode::Unauthorized.code(), -32030);
        assert_eq!(ErrorCode::NotSupported.code(), -32031);
        assert_eq!(ErrorCode::ControlError.code(), -32032);
    }

    /// **Proves:** the onion codes keep `-32020..-32022` and the control codes
    /// are renumbered clear of them.
    /// **Catches:** a regression that reintroduces the historical collision.
    #[test]
    fn onion_control_collision_resolved() {
        assert_eq!(ErrorCode::OnionCircuitUnavailable.code(), -32020);
        assert_eq!(ErrorCode::Unauthorized.code(), -32030);
        assert_ne!(
            ErrorCode::OnionCircuitUnavailable.code(),
            ErrorCode::Unauthorized.code()
        );
    }

    /// **Proves:** a code serializes as a bare integer, never a tagged object.
    /// **Catches:** a swap of `Serialize_repr` for plain `Serialize`.
    #[test]
    fn code_serialises_as_integer() {
        assert_eq!(
            serde_json::to_string(&ErrorCode::MethodNotFound).unwrap(),
            "-32601"
        );
        assert_eq!(
            serde_json::to_string(&ErrorCode::ContentRedirect).unwrap(),
            "-32008"
        );
    }

    /// **Proves:** `ALL` lists exactly the distinct codes, with unique numbers
    /// and unique machine strings.
    /// **Catches:** a new variant left out of `ALL`, or a duplicated
    /// code/machine string.
    #[test]
    fn all_codes_unique_and_complete() {
        use std::collections::HashSet;
        let nums: HashSet<i32> = ErrorCode::ALL.iter().map(|c| c.code()).collect();
        let strs: HashSet<&str> = ErrorCode::ALL.iter().map(|c| c.machine_code()).collect();
        assert_eq!(nums.len(), ErrorCode::ALL.len(), "duplicate numeric code");
        assert_eq!(strs.len(), ErrorCode::ALL.len(), "duplicate machine code");
        assert_eq!(ErrorCode::ALL.len(), 22);
    }

    /// **Proves:** the constructor mints the full `{code, message, data:{code,
    /// origin}}` envelope and `data.code` mirrors the numeric code.
    /// **Catches:** a drift between the numeric code and `data.code`.
    #[test]
    fn envelope_shape_and_data_code() {
        let e = RpcError::new(
            ErrorCode::ResourceUnavailable,
            "not here",
            ErrorOrigin::Node,
        );
        let v = serde_json::to_value(&e).unwrap();
        assert_eq!(v["code"], -32004);
        assert_eq!(v["message"], "not here");
        assert_eq!(v["data"]["code"], "RESOURCE_UNAVAILABLE");
        assert_eq!(v["data"]["origin"], "node");
        // Round-trips.
        let back: RpcError = serde_json::from_value(v).unwrap();
        assert_eq!(back, e);
    }

    /// **Proves:** `UpstreamError` defaults to the `upstream` origin.
    #[test]
    fn upstream_default_origin() {
        let e = RpcError::of(ErrorCode::UpstreamError, "upstream: boom");
        assert_eq!(e.data.origin, ErrorOrigin::Upstream);
        assert_eq!(
            serde_json::to_value(&e).unwrap()["data"]["origin"],
            "upstream"
        );
    }

    /// **Proves:** `code_only` uses the default message + origin.
    #[test]
    fn code_only_defaults() {
        let e = RpcError::code_only(ErrorCode::PeerUnreachable);
        assert_eq!(e.message, "Peer unreachable");
        assert_eq!(e.data.origin, ErrorOrigin::Peer);
    }
}