dig_rpc_types/
lib.rs

1//! # dig-rpc-types
2//!
3//! The **canonical DIG-node JSON-RPC interface**. This crate is the single
4//! source of truth both DIG node implementations (the digstore `dig-node` crate
5//! and the standalone `dig-node` binary) depend on instead of hand-rolling
6//! `json!({…})` shapes and ad-hoc error codes:
7//!
8//! - the JSON-RPC 2.0 [`envelope`] — [`JsonRpcRequest`],
9//!   [`JsonRpcResponse`], [`RequestId`], [`Version`];
10//! - the canonical [error taxonomy](error) — [`ErrorCode`], the
11//!   [`RpcError`] envelope (`{code, message, data:{code, origin}}`), and the one
12//!   constructor helper both nodes call;
13//! - the [method catalogue](method) — [`Method`] with stable wire names, the
14//!   per-method [`Tier`], and the mTLS peer allowlist;
15//! - the [wire types](types) for every method's params + results, field-for-field
16//!   with the canonical node (network-profile-only fields `Option` + doc-flagged);
17//! - the shape-dispatched [peer frame families](frames) — the DHT and PEX wires;
18//! - the [OpenRPC 1.2.6 generator](openrpc) — the single discovery document,
19//!   generated from the tables above so discovery can never drift.
20//!
21//! ## What does NOT live here
22//!
23//! - **No I/O, no async, no server logic.** No axum, no tokio, no transport. The
24//!   [`dig-rpc`](https://crates.io/crates/dig-rpc) server crate and the node
25//!   implementations build on these types. This crate MUST NOT depend on any
26//!   server or service crate.
27//! - **No crypto.** Hex identifiers are `String` on the wire; length/charset
28//!   validation is the consumer's boundary responsibility.
29//!
30//! ## Stability
31//!
32//! 1. [`ErrorCode`] and [`Method`] are `#[non_exhaustive]`; adding a code /
33//!    method is additive (match with `_ => …`).
34//! 2. [`ErrorCode`] numeric values and machine codes never change once assigned.
35//! 3. Method wire names are stable.
36//! 4. The tier map and the peer allowlist mirror the canonical node exactly.
37//!
38//! ## Example — build and inspect an error envelope
39//!
40//! ```
41//! use dig_rpc_types::{RpcError, ErrorCode, ErrorOrigin};
42//!
43//! let e = RpcError::of(ErrorCode::ResourceUnavailable, "not at this root");
44//! assert_eq!(e.code, ErrorCode::ResourceUnavailable);
45//! assert_eq!(e.data.code, "RESOURCE_UNAVAILABLE");
46//! assert_eq!(e.data.origin, ErrorOrigin::Node);
47//! ```
48
49#![forbid(unsafe_code)]
50#![warn(missing_docs)]
51
52pub mod envelope;
53pub mod error;
54pub mod frames;
55pub mod method;
56pub mod openrpc;
57pub mod tier;
58pub mod types;
59
60// Re-export the most-used items at the crate root.
61pub use envelope::{JsonRpcRequest, JsonRpcResponse, JsonRpcResponseBody, RequestId, Version};
62pub use error::{ErrorCode, ErrorData, ErrorOrigin, RpcError};
63pub use method::Method;
64pub use openrpc::{openrpc_document, OPENRPC_VERSION};
65pub use tier::Tier;
66
67/// The interface (wire-schema) version this crate defines. Bumped only on a
68/// wire-breaking change; additive changes leave it untouched.
69pub const INTERFACE_VERSION: &str = "1";
dig_rpc_types/lib.rs

dig_rpc_types/
lib.rs
