Expand description
RPC dispatch over bidirectional iroh streams.
Registering at least one hello handler enables a per-connection negotiation
phase. During that phase, the server accepts streams serially and dispatches
only hello handlers. The client must perform application-level
synchronization with a hello handler that returns HelloOutcome::Promote
before it opens ordinary or concurrent RPC streams. Opening an ordinary
stream early is unsupported: it cannot run before promotion, and if accepted
as the next hello stream its ID is unknown and disconnects the connection.
The framework never writes an acknowledgement or any other reply. Every
handler owns its RpcWrite and RpcRead and is responsible for its
application protocol, including writing and finishing any response. The
HelloOutcome takes effect only after the handler future returns.
§Wire format
Each call occupies one iroh bidirectional stream. The initiator first writes
the RPC ID as an unsigned 16-bit integer in big-endian order. Everything after
the ID belongs to the handler. RpcWrite::write_message_raw and
RpcRead::read_message_raw frame each ordinary message as a big-endian
u32 byte length followed by exactly that many bytes. The encoded payload is
limited to MAX_MESSAGE_SIZE (16 MiB).
The bincode feature uses bincode 2 with bincode::STD_BINCODE_CONFIG;
each value occupies one complete ordinary frame and trailing bytes are an
error. The bao feature instead provides unframed, whole-payload convenience
transfers. Applications must communicate and authenticate their length and
root hash separately; see bao for the current allocation limitations.
§Compatibility and responsibilities
RPC IDs, handler-specific message order and types, hello exchanges, enabled codecs, and application error replies form the application protocol. Peers must agree on all of them. This crate does not negotiate versions, authorize authenticated iroh identities, impose request deadlines, retry calls, finish send streams, or define an error frame. A handler error ends dispatch for that stream and is logged by the server; callers observe only resulting application or transport behavior.
Modules§
- bao
- Unframed, authenticated whole-payload BAO transfer helpers.
- bincode
- Bincode 2 encoding helpers for ordinary framed messages.
- error
- Internal catch-all error support retained as public API.
Structs§
- DpcRpc
- An iroh protocol handler that dispatches RPC streams with bounded concurrency.
- DpcRpc
Builder - Configures and builds a
DpcRpc. - RpcId
- Application-assigned 16-bit RPC method identifier.
- RpcRead
- Receiving half of an RPC stream.
- RpcWrite
- Sending half of an RPC stream.
Enums§
- Hello
Outcome - Determines the server’s next state after one hello handler returns.
- RpcError
- Error returned by complete RPC operations and user handlers.
- RpcRead
Error - Failure while reading or decoding an RPC stream.
- RpcWrite
Error - Failure while encoding or writing an RPC stream.
Constants§
- DEFAULT_
HELLO_ NEGOTIATION_ TIMEOUT - Default total time allowed for a connection’s hello negotiation.
- DEFAULT_
MAX_ CONCURRENT_ REQUESTS_ PER_ CONNECTION - Default maximum number of ordinary request handlers running per connection.
- MAX_
MESSAGE_ SIZE - Maximum encoded size of an ordinary raw or bincode message: 16 MiB.
Traits§
- RpcExt
- Extension trait adding rpc functionality to
iroh::endpoint::Connection
Type Aliases§
- RpcRead
Result - Result returned by
RpcReadoperations. - RpcResult
- Result returned by an RPC operation or handler.
- RpcWrite
Result - Result returned by
RpcWriteoperations.