Skip to main content

Crate iroh_dpc_rpc

Crate iroh_dpc_rpc 

Source
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.
DpcRpcBuilder
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§

HelloOutcome
Determines the server’s next state after one hello handler returns.
RpcError
Error returned by complete RPC operations and user handlers.
RpcReadError
Failure while reading or decoding an RPC stream.
RpcWriteError
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§

RpcReadResult
Result returned by RpcRead operations.
RpcResult
Result returned by an RPC operation or handler.
RpcWriteResult
Result returned by RpcWrite operations.