dig-rpc-protocol 0.9.0

//! Band invariants for [`ErrorCode`]: a new code must not collide with a numeric
//! range this ecosystem has already published.
//!
//! An error code is a permanent, published branch key — a consumer switches on it
//! to decide whether to retry a holder or abandon it. A new variant landing inside
//! a band another subsystem already published is therefore not a cosmetic defect:
//! it makes two different failures indistinguishable at exactly the moment the
//! client must tell them apart.
//!
//! Plain numeric uniqueness across the whole enum is already asserted by
//! `error::tests::all_codes_unique_and_complete` in the crate itself; this file
//! covers what that test cannot see — the published BAND a number falls in.

use dig_rpc_protocol::error::ErrorCode;

/// The onion / private-retrieval band, published normative in `SYSTEM.md` →
/// "Canonical DIG-node RPC interface". `-32021` in particular is
/// `PRIVACY_REQUIRES_LOCAL_NODE` and MUST NOT be reused.
const ONION_BAND: std::ops::RangeInclusive<i32> = -32022..=-32020;

/// **Proves:** `RANGE_METADATA_UNREPRESENTABLE` exists, sits outside the onion
/// band, and is not `-32021`.
///
/// It is load-bearing rather than decorative: dig-nat's encoder directs a holder
/// to answer this code when a resource's metadata alone cannot fit a frame — a
/// permanent property of that holder's view of the resource. A client that cannot
/// tell it from an ordinary transport failure will retry a holder that can never
/// succeed, which is why it needs its own number rather than a shared one.
#[test]
fn range_metadata_unrepresentable_is_outside_the_onion_band() {
    let code = ErrorCode::RangeMetadataUnrepresentable.code();

    assert_ne!(code, -32021, "-32021 is PRIVACY_REQUIRES_LOCAL_NODE");
    assert!(
        !ONION_BAND.contains(&code),
        "code {code} falls inside the published onion band {ONION_BAND:?}"
    );
    assert_eq!(
        ErrorCode::RangeMetadataUnrepresentable.machine_code(),
        "RANGE_METADATA_UNREPRESENTABLE"
    );
    assert!(
        ErrorCode::RangeMetadataUnrepresentable.is_jsonrpc_reserved(),
        "the code must live in the JSON-RPC implementation-defined server band"
    );
}

/// **Proves:** the module-level rustdoc taxonomy table lists EVERY code in
/// [`ErrorCode::ALL`], with the same number and variant name.
///
/// That table is the taxonomy published on docs.rs, and it is where a reimplementer
/// builds its branch table from — so a code missing there is a code that
/// reimplementation treats as a generic server error, which for
/// `RANGE_METADATA_UNREPRESENTABLE` means retrying a holder that can never serve the
/// range. The table was hand-maintained beside the enum and had already drifted once
/// by exactly one row, so the agreement is asserted mechanically rather than trusted.
#[test]
fn the_rustdoc_taxonomy_table_lists_every_code() {
    // The source of the module whose doc comment IS the published table. Read at
    // compile time so this test cannot go stale against a moved file.
    const ERROR_MODULE_SOURCE: &str = include_str!("../src/error.rs");

    let table: String = ERROR_MODULE_SOURCE
        .lines()
        .take_while(|line| line.starts_with("//!"))
        .collect::<Vec<_>>()
        .join("\n");

    for code in ErrorCode::ALL {
        let row = format!("| `{}` | [`{:?}`]", code.code(), code);
        assert!(
            table.contains(&row),
            "the rustdoc taxonomy table is missing a row for {} ({}); expected to find {row:?}",
            code.machine_code(),
            code.code()
        );
    }
}

/// **Proves:** the new code is reachable through the OpenRPC error catalogue, so a
/// peer that discovers the surface learns it can be answered with this code.
///
/// dig-node's serve leg answers it and dig-download's client branches on it; both
/// discover the taxonomy from this document rather than from Rust.
#[test]
fn range_metadata_unrepresentable_is_published_in_openrpc() {
    let doc = dig_rpc_protocol::openrpc::openrpc_document("0.0.0-test");
    let catalogue = doc["components"]["x-dig-errors"]
        .as_array()
        .expect("error catalogue is an array");

    let entry = catalogue
        .iter()
        .find(|e| e["machineCode"] == "RANGE_METADATA_UNREPRESENTABLE")
        .expect("RANGE_METADATA_UNREPRESENTABLE is absent from the OpenRPC catalogue");

    assert_eq!(
        entry["code"],
        ErrorCode::RangeMetadataUnrepresentable.code(),
        "the published number must match the enum"
    );
}

/// **Proves:** every published code lies inside the JSON-RPC server-error range
/// this crate advertises, and every variant in `ALL` contributes a distinct number.
///
/// # What actually guards against a duplicate, measured
///
/// `rustc` rejects two variants sharing a discriminant outright — setting
/// `ContentMissInconclusive` to `-32009` (the value it was first written as, already
/// owned by `RangeMetadataUnrepresentable`) does not fail this test, it fails to
/// COMPILE with `E0081: discriminant value -32009 assigned more than once`. So the
/// uniqueness half below is a restatement of a compiler guarantee, kept because it
/// also covers what `E0081` cannot see: a variant silently missing from
/// [`ErrorCode::ALL`], which is the hand-maintained list that drives the OpenRPC
/// catalogue and this crate's published taxonomy.
///
/// The RANGE half is the load-bearing assertion and is independently falsifiable:
/// `-31999` compiles perfectly, serializes perfectly, and is outside the band, so a
/// consumer's JSON-RPC layer may legitimately refuse it as a non-server error.
///
/// The collision this taxonomy is actually exposed to is a consumer HAND-WRITING an
/// integer it believes is free — which is what dig-node did with `-32009`, and
/// which no test in this crate can reach. That risk is addressed by publishing the
/// number in the rustdoc table and the OpenRPC catalogue (asserted by the sibling
/// tests here) so a consumer never has to guess.
#[test]
fn every_published_code_is_unique_and_in_the_jsonrpc_server_range() {
    use std::collections::HashMap;

    let mut seen: HashMap<i32, ErrorCode> = HashMap::new();
    for &code in ErrorCode::ALL {
        let n = code.code();

        if let Some(&prior) = seen.get(&n) {
            panic!(
                "error code {n} is claimed by BOTH {} and {} — a client cannot \
                 branch on it, so one of them must be renumbered to a free value",
                prior.machine_code(),
                code.machine_code()
            );
        }
        seen.insert(n, code);

        assert!(
            code.is_jsonrpc_reserved(),
            "{} = {n} lies outside the JSON-RPC implementation-defined server range \
             (-32768..=-32000) this crate publishes",
            code.machine_code()
        );
    }

    assert_eq!(
        seen.len(),
        ErrorCode::ALL.len(),
        "every variant in ALL must contribute a distinct number"
    );
}

/// **Proves:** `CONTENT_MISS_INCONCLUSIVE` did not land on any number already in
/// use, and specifically not on `-32009`.
///
/// A targeted companion to the general uniqueness test above: it names the ONE
/// wrong number that was actually written, so a revert to it fails with the reason
/// rather than with an arithmetic mismatch.
#[test]
fn content_miss_inconclusive_does_not_squat_range_metadata_unrepresentable() {
    let inconclusive = ErrorCode::ContentMissInconclusive;

    assert_eq!(inconclusive.code(), -32015);
    assert_ne!(
        inconclusive.code(),
        ErrorCode::RangeMetadataUnrepresentable.code(),
        "-32009 is RANGE_METADATA_UNREPRESENTABLE, which is holder-FATAL; this code \
         means the opposite (keep looking, this holder is still eligible)"
    );
    assert!(
        !ONION_BAND.contains(&inconclusive.code()),
        "must not fall inside the published onion band"
    );
    assert_eq!(inconclusive.machine_code(), "CONTENT_MISS_INCONCLUSIVE");
}