Crate dig_rpc 

dig-rpc

An axum-based JSON-RPC server framework for a DIG node. It serves the canonical dig-rpc-protocol interface over the three DIG transport surfaces and owns everything transport-shaped so a node doesn’t have to:

• mTLS peer surface, HTTPS public-read surface, loopback control surface — one RpcServer per surface, over the same handler;
• the JSON-RPC 2.0 envelope + the uniform error envelope;
• the surface/tier allowlist boundary (dispatch) — a control method is unreachable off loopback, a non-allowlisted method is unreachable over the peer surface;
• rpc.discover served from the generated OpenRPC document;
• per-(peer, tier) rate limiting;
• graceful shutdown driven by any future.

The node supplies the semantics through one small trait, RpcHandler — so this crate depends ONLY on dig_rpc_protocol, never on a node or service crate. (The previous design’s dig-service dependency is gone: the shutdown signal is a plain future and dispatch is a trait, not an external RpcApi.)

Architecture

  POST /  (one surface: Loopback | PublicRead | Peer)
     │
     ▼  axum handler
  ┌────────────────────────────────────────────────┐
  │ rate limit  — per (peer, tier) token bucket      │
  │ dispatch    — resolve method (dig-rpc-protocol)      │
  │             — surface/tier allowlist boundary     │
  │             — rpc.discover from OpenRPC generator │
  │             — RpcHandler::handle (node semantics) │
  │ envelope    — JsonRpcResponse { result | error }  │
  └────────────────────────────────────────────────┘

Minimal handler

use dig_rpc::{RpcHandler};
use dig_rpc_protocol::{Method, RpcError, ErrorCode};
use serde_json::{json, Value};

struct MyNode;

#[async_trait::async_trait]
impl RpcHandler for MyNode {
    async fn handle(&self, method: Method, _params: Value) -> Result<Value, RpcError> {
        match method {
            Method::Health => Ok(json!({ "status": "ok" })),
            other => Err(RpcError::of(
                ErrorCode::MethodNotFound,
                format!("{} not served", other.name()),
            )),
        }
    }
}

Re-exports

pub use dispatch::dispatch;

pub use dispatch::parse_error_response;

pub use dispatch::SharedHandler;

pub use dispatch::Surface;

pub use error::RpcServerError;

pub use handler::RpcHandler;

pub use middleware::RateLimitConfig;

pub use middleware::RateLimitState;

pub use server::RpcServer;

pub use server::RpcServerMode;

pub use tls::InternalCertPaths;

pub use tls::PublicCertPaths;

pub use tls::TlsConfig;

pub use dig_rpc_protocol;

Modules

dispatch

JSON-RPC envelope dispatch + the tier/allowlist boundary.

envelope

JSON-RPC 2.0 envelope types.

error

Server operational errors (bind / TLS / fatal).

handler

The RpcHandler trait — the seam a DIG node implements.

middleware

Request-boundary middleware for the RPC server.

server

The RpcServer — an axum JSON-RPC server bound to one transport surface.

tls

TLS / mTLS configuration loading.

Structs

JsonRpcRequest

A JSON-RPC 2.0 request envelope.

JsonRpcResponse

A JSON-RPC 2.0 response envelope.

RpcError

The canonical DIG-node RPC error object: {code, message, data:{code, origin}}.

Enums

ErrorCode

A canonical DIG-node RPC error code.

ErrorOrigin

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.

Method

A DIG-node RPC method.

Tier

A method’s primary access tier.