dig-rpc-protocol

The canonical DIG-node JSON-RPC protocol (formerly dig-rpc-types) — the single source of truth both DIG node implementations (the digstore dig-node crate and the standalone dig-node binary) depend on instead of hand-rolling json!({…}) shapes and ad-hoc error codes.

Pure types: no I/O, no async, no server logic, no crypto. The dig-rpc server crate and the node implementations build on these types.

What's here

The full contract is in SPEC.md.

Full Protocol Interface (at-a-glance LLM reference)

All Methods (34 total)

Access Tiers: PublicRead = anonymous content reads (HTTPS / mTLS). Peer = mTLS peer surface (node↔node). Control = loopback / in-process only.

Peer-Reachable Methods (10 total): dig.getContent, dig.getNetworkInfo, dig.getPeers, dig.announce, dig.getAvailability, dig.listInventory, dig.fetchRange, dig.getAnchoredRoot, dig.getCollection, dig.listCollectionItems. All Control and non-peer PublicRead methods are never peer-reachable.

Error Codes (22 total)

Error Origins: Node = node's own read/serve path. Peer = peer-network layer. Upstream = upstream fetch (proxy/whole-store sync). Onion = private-retrieval layer. Control = loopback control plane.

Request/Response Envelope

JSON-RPC 2.0 strict:

Request: {"jsonrpc":"2.0","id":<num|str>,"method":"<wire_name>","params":<object|null>}
Response: {"jsonrpc":"2.0","id":<num|str>,"result":<any>} | {"jsonrpc":"2.0","id":<num|str>,"error":{"code":<int>,"message":"<str>","data":{"code":"<UPPER_SNAKE>","origin":"<str>",...}}}

Error Envelope Structure:

{
  code: i32,                    // numeric wire code (e.g., -32004)
  message: String,              // human-readable summary
  data: {
    code: String,              // stable machine code (e.g., "RESOURCE_UNAVAILABLE")
    origin: String,            // subsystem (node/peer/upstream/onion/control)
    redirect?: RedirectInfo,   // present only on CONTENT_REDIRECT
    <extra fields>             // method-specific fields flattened
  }
}

Interface Version

INTERFACE_VERSION is not yet versioned in the wire (future work). The protocol evolves via additive Method variants and ErrorCode assignments; both are #[non_exhaustive] so a client match-arm default (_ => …) handles future extensions.

Error taxonomy at a glance

Standard JSON-RPC codes plus the DIG protocol codes. The onion codes -32020/-32021/-32022 are the published normative contract and keep their numbers; the control-plane codes are -32030/-32031/-32032.

use dig_rpc_protocol::{RpcError, ErrorCode, ErrorOrigin};

let e = RpcError::of(ErrorCode::ResourceUnavailable, "not at this root");
assert_eq!(e.code, ErrorCode::ResourceUnavailable);       // -32004
assert_eq!(e.data.code, "RESOURCE_UNAVAILABLE");          // stable branch key
assert_eq!(e.data.origin, ErrorOrigin::Node);

Method catalogue + discovery

use dig_rpc_protocol::{Method, Tier, openrpc_document};

assert_eq!(Method::GetContent.name(), "dig.getContent");
assert_eq!(Method::GetContent.tier(), Tier::PublicRead);
assert!(Method::GetContent.is_peer_reachable());
assert!(!Method::CacheClear.is_peer_reachable());          // control tier

let doc = openrpc_document(env!("CARGO_PKG_VERSION"));      // OpenRPC 1.2.6

Features

Testing

cargo test --all-features        # unit + conformance vectors
cargo llvm-cov --all-features    # coverage (CI-gated ≥80%)

Licensed under Apache-2.0 OR MIT.