dig_rpc/lib.rs
1//! # dig-rpc
2//!
3//! Axum-based JSON-RPC server for the DIG Network fullnode / validator /
4//! future wallet. Couples [`dig-service`](https://crates.io/crates/dig-service)
5//! lifecycle hooks with the [`dig-rpc-types`](https://crates.io/crates/dig-rpc-types)
6//! wire contract, adding:
7//!
8//! - mTLS transport (rustls) with server certs on either a private CA (internal
9//! admin port) or a public CA (read-only public port).
10//! - Cert-CN / SAN → [`Role`](role::Role) mapping via [`RoleMap`](role::RoleMap).
11//! - Per-method metadata ([`MethodMeta`](method::MethodMeta)) governing
12//! `min_role`, rate-limit bucket, and whether the method is exposed on
13//! the public port.
14//! - Tower middleware stack: request-id, panic-catch, audit, rate-limit,
15//! allow-list.
16//! - Graceful shutdown integrated with [`dig_service::ShutdownToken`].
17//!
18//! ## Scope — v0.1
19//!
20//! v0.1 focuses on the JSON-RPC wire layer and the Tower-layered middleware
21//! stack, with TLS server-auth. **Full mTLS client-cert verification is
22//! wired in via `rustls::server::WebPkiClientVerifier` but the
23//! authenticated-cert → Role resolution uses a pluggable trait so binaries
24//! can substitute dev-mode stubs.** Production binaries plug in the full
25//! cert parsing path (provided) or their own overrides.
26//!
27//! ## Architecture
28//!
29//! ```text
30//! HTTP request
31//! │
32//! ▼
33//! ┌──────────────────────────────────────────────────────┐
34//! │ tower::Service<Request> (Axum router) │
35//! │ ↓ RequestIdLayer │
36//! │ ↓ PanicCatchLayer │
37//! │ ↓ AuthLayer — TLS peer → Role │
38//! │ ↓ RateLimitLayer — (peer_key, method) bucket │
39//! │ ↓ AllowListLayer — role >= method.min_role? │
40//! │ ↓ Body parse — JsonRpcRequest<serde_json::Value>│
41//! │ ↓ RpcApi::dispatch (from dig-service) │
42//! │ ↓ Envelope response │
43//! │ ↓ AuditLayer │
44//! └──────────────────────────────────────────────────────┘
45//! ```
46
47#![deny(unsafe_code)]
48#![warn(missing_docs)]
49
50pub mod dispatch;
51pub mod error;
52pub mod method;
53pub mod middleware;
54pub mod role;
55pub mod server;
56pub mod tls;
57
58pub use dispatch::dispatch_envelope;
59pub use error::RpcServerError;
60pub use method::{MethodClass, MethodMeta, MethodRegistry, RateBucket};
61pub use role::{CertMatcher, Role, RoleMap};
62pub use server::{RpcServer, RpcServerMode};
63pub use tls::{InternalCertPaths, PublicCertPaths, TlsConfig};
64
65// Re-exports for ergonomic downstream use.
66pub use dig_rpc_types::{
67 envelope::{JsonRpcError, JsonRpcRequest, JsonRpcResponse, JsonRpcResponseBody},
68 errors::ErrorCode,
69};
70pub use dig_service::{RpcApi, ShutdownToken};