Expand description
Transport-generic RPC plane core — Epic #131 / moq M1 (#151).
This module generalises the iroh-specific RPC server/client (originally in
super::iroh_rpc and super::iroh_transport) over the
[web_transport_trait::Session] abstraction, so the RPC plane is
transport-pluggable: any Session impl (iroh’s web-transport-iroh,
quinn’s web-transport-quinn, or a future WASM web-transport-web) can
carry the exact same Cap’n Proto bidi wire protocol with identical DoS
bounds, graceful-drain, and error-envelope semantics.
serve_rpc_connection— the generic server accept loop. TerminatesSignedEnvelopebidi streams on a [Session], dispatches each through anIrohRequestProcessor, caps concurrent streams per connection (DoS bound) and drains in-flight requests onshutdown.SessionRpcTransport— the generic client transport implementingcrate::transport_traits::Transportover a [Session]. Eachsend()opens a fresh bidi stream.IrohRequestProcessor— the pluggable request-processing trait (retained under its original name to avoid churn in callers).build_error_envelope— signed error-envelope synthesis.
Wire framing: each request/response is the opaque bytes of a
Cap’n Proto-encoded envelope written to a freshly-opened bidi stream. The
length is delimited by stream FIN (no explicit length prefix); reads are
bounded by MAX_FRAME_BYTES via read_to_cap.
Structs§
- RpcConfig
- Unified RPC transport tunables for server builders.
- RpcPublish
Stub - Stub publish sink for
Transport::Pub. Errors on anysend_framescall; the RPC plane is request-response only. - Session
RpcTransport - Wraps a [
web_transport_trait::Session] as aTransportfor RPC plane traffic. Generic over the session impl, so the same client logic rides iroh, quinn, or any futureSessionbackend.
Constants§
- DEFAULT_
CONNECTION_ LIMIT - Default cap on concurrent accepted connections per server (#162). Bounds
fd/memory from a peer that opens many connections that each sit idle (no
streams) — the per-stream
DEFAULT_STREAM_LIMITdoes not cover that. Connections beyond the cap are rejected (dropped) rather than queued, so a flood can’t build unbounded backpressure. - DEFAULT_
STREAM_ LIMIT - Default concurrent-stream cap. NOTE: the
Arc<Semaphore>this sizes is shared server-wide across all connections (oneArc<HandlerInner>), not per-connection — so this bounds total in-flight streams for the whole server, capping memory toMAX_FRAME_BYTES × DEFAULT_STREAM_LIMIT= 256 MiB. - DRAIN_
TIMEOUT - Upper bound on how long graceful shutdown waits for in-flight streams to
drain before forcing teardown. With
REQUEST_READ_TIMEOUTbounding each read, well-behaved drains finish quickly; this is a backstop so a wedged processor or transport can’t hang shutdown forever (#159). - HANDSHAKE_
TIMEOUT - Maximum time the server waits for a peer’s WebTransport/QUIC handshake to complete before abandoning it (#162). Bounds a peer that completes the QUIC handshake then stalls the WebTransport CONNECT. Resolved inside the per-connection task so a slow handshake never blocks the accept loop.
- MAX_
FRAME_ BYTES - Hard cap on per-frame size (request or response) for the RPC control plane.
- REQUEST_
READ_ TIMEOUT - Maximum wall-clock time the server will spend reading a single request frame before abandoning the stream and releasing its semaphore permit.
- STOPPED_
GRACE - Grace period for [
SendStream::closed] after writing the response — if the peer crashes without acking the FIN, we don’t leak a task forever.
Traits§
- Iroh
Request Processor - Sealed trait used to wire actual request processing.
Functions§
- build_
error_ envelope - Build a signed
ResponseEnvelope(request_id = 0) carryingmessageas the payload. Used when the processor itself fails — guarantees the client sees a parseable envelope rather than EOF. - from_fn
- Convenience: build an
IrohRequestProcessorfrom aSend + Syncasync closure. Useful for tests. The closure is carrier-agnostic and is therefore restricted to trusted inproc/UDS carriers. It cannot receive bytes from an untrusted carrier. - read_
to_ cap - Read an entire stream into [
Bytes], capping the total atcapbytes. - serve_
rpc_ connection - Serve one accepted [
Session] until the peer closes it orshutdownis cancelled. Terminateshyprstream-rpc/1-style bidi streams, caps concurrent streams via the sharedstream_limit, and (in concert with the caller’s drain on that samestream_limit) drains in-flight requests on shutdown.
Type Aliases§
- RpcPending
Stream - Stub stream type for
Transport::Sub. Always pending — the RPC plane does not carry SUB-style topic streams; those live on the streaming plane.