Skip to main content

Module rpc_session

Module rpc_session 

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

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.
RpcPublishStub
Stub publish sink for Transport::Pub. Errors on any send_frames call; the RPC plane is request-response only.
SessionRpcTransport
Wraps a [web_transport_trait::Session] as a Transport for RPC plane traffic. Generic over the session impl, so the same client logic rides iroh, quinn, or any future Session backend.

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_LIMIT does 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 (one Arc<HandlerInner>), not per-connection — so this bounds total in-flight streams for the whole server, capping memory to MAX_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_TIMEOUT bounding 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§

IrohRequestProcessor
Sealed trait used to wire actual request processing.

Functions§

build_error_envelope
Build a signed ResponseEnvelope (request_id = 0) carrying message as the payload. Used when the processor itself fails — guarantees the client sees a parseable envelope rather than EOF.
from_fn
Convenience: build an IrohRequestProcessor from a Send + Sync async 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 at cap bytes.
serve_rpc_connection
Serve one accepted [Session] until the peer closes it or shutdown is cancelled. Terminates hyprstream-rpc/1-style bidi streams, caps concurrent streams via the shared stream_limit, and (in concert with the caller’s drain on that same stream_limit) drains in-flight requests on shutdown.

Type Aliases§

RpcPendingStream
Stub stream type for Transport::Sub. Always pending — the RPC plane does not carry SUB-style topic streams; those live on the streaming plane.