Skip to main content

iroh_dpc_rpc/
lib.rs

1//! RPC dispatch over bidirectional iroh streams.
2//!
3//! Registering at least one hello handler enables a per-connection negotiation
4//! phase. During that phase, the server accepts streams serially and dispatches
5//! only hello handlers. The client must perform application-level
6//! synchronization with a hello handler that returns [`HelloOutcome::Promote`]
7//! before it opens ordinary or concurrent RPC streams. Opening an ordinary
8//! stream early is unsupported: it cannot run before promotion, and if accepted
9//! as the next hello stream its ID is unknown and disconnects the connection.
10//!
11//! The framework never writes an acknowledgement or any other reply. Every
12//! handler owns its [`RpcWrite`] and [`RpcRead`] and is responsible for its
13//! application protocol, including writing and finishing any response. The
14//! [`HelloOutcome`] takes effect only after the handler future returns.
15//!
16//! # Wire format
17//!
18//! Each call occupies one iroh bidirectional stream. The initiator first writes
19//! the RPC ID as an unsigned 16-bit integer in big-endian order. Everything after
20//! the ID belongs to the handler. [`RpcWrite::write_message_raw`] and
21//! [`RpcRead::read_message_raw`] frame each ordinary message as a big-endian
22//! `u32` byte length followed by exactly that many bytes. The encoded payload is
23//! limited to [`MAX_MESSAGE_SIZE`] (16 MiB).
24//!
25//! The `bincode` feature uses bincode 2 with [`bincode::STD_BINCODE_CONFIG`];
26//! each value occupies one complete ordinary frame and trailing bytes are an
27//! error. The `bao` feature instead provides unframed, whole-payload convenience
28//! transfers. Applications must communicate and authenticate their length and
29//! root hash separately; see [`bao`] for the current allocation limitations.
30//!
31//! # Compatibility and responsibilities
32//!
33//! RPC IDs, handler-specific message order and types, hello exchanges, enabled
34//! codecs, and application error replies form the application protocol. Peers
35//! must agree on all of them. This crate does not negotiate versions, authorize
36//! authenticated iroh identities, impose request deadlines, retry calls, finish
37//! send streams, or define an error frame. A handler error ends dispatch for that
38//! stream and is logged by the server; callers observe only resulting
39//! application or transport behavior.
40
41#![warn(missing_docs)]
42
43#[cfg(target_pointer_width = "16")]
44compile_error!("iroh-dpc-rpc requires a target pointer width of at least 32 bits");
45
46mod dpc_rpc;
47mod dpc_rpc_builder;
48mod handler_lifecycle;
49mod handler_tasks;
50mod outcome;
51mod rpc_error;
52mod rpc_ext;
53mod rpc_id;
54mod rpc_read;
55mod rpc_write;
56#[cfg(test)]
57mod tests;
58mod util_error;
59
60#[cfg(feature = "bao")]
61/// Unframed, authenticated whole-payload BAO transfer helpers.
62pub mod bao;
63#[cfg(feature = "bincode")]
64/// Bincode 2 encoding helpers for ordinary framed messages.
65pub mod bincode;
66/// Internal catch-all error support retained as public API.
67pub mod error;
68
69pub use dpc_rpc::DpcRpc;
70pub use dpc_rpc_builder::DpcRpcBuilder;
71pub use outcome::HelloOutcome;
72pub use rpc_error::{RpcError, RpcResult};
73pub use rpc_ext::RpcExt;
74pub use rpc_id::RpcId;
75pub use rpc_read::{RpcRead, RpcReadError, RpcReadResult};
76pub use rpc_write::{RpcWrite, RpcWriteError, RpcWriteResult};
77
78use std::num::NonZeroUsize;
79use std::time::Duration;
80
81const LOG_TARGET: &str = "iroh-dpc-rpc";
82
83/// Default maximum number of ordinary request handlers running per connection.
84pub const DEFAULT_MAX_CONCURRENT_REQUESTS_PER_CONNECTION: NonZeroUsize =
85    NonZeroUsize::new(64).expect("default concurrency is nonzero");
86
87/// Default total time allowed for a connection's hello negotiation.
88pub const DEFAULT_HELLO_NEGOTIATION_TIMEOUT: Duration = Duration::from_secs(10);
89
90/// Maximum encoded size of an ordinary raw or bincode message: 16 MiB.
91///
92/// Messages use an unsigned 32-bit big-endian length prefix. BAO transfers use
93/// separate authenticated length and hash metadata and do not use this limit.
94pub const MAX_MESSAGE_SIZE: u32 = 16 * 1024 * 1024;