Module protocol 

Bidirectional requests over the transport, with pipelining and explicit sessions.

A reader receives messages from each connection. Each session also has a writer that sends queued messages and a deadline worker that times out operations. Incoming requests and unread responses stay encoded until recv() or wait(). Invalid payloads close their original session when decoded.

Each session limits accepted peer requests and buffered incoming bytes. Set both with Session::set_inbound_limits or Server::set_inbound_limits. Exceeding a limit closes the session. The reader never waits for the application to make room. These limits are local; no flow control is negotiated with the peer. The outgoing queue has no capacity limit.

The application opens a crate::transport::Stream; this layer constructs and owns its transport. connect establishes one client session. Server owns a persistent stream and accepts successive server sessions. Each Session owns its receive queue and closes when dropped. Its Requester and Responder handles always target that session, even after it closes and another session connects. Both sides use the same handle types. Sessions exchange Message, the union of every body in the schema. The schema::host_to_ark::Content and schema::ark_to_host::Content oneofs hold what each side may send. Convert a received Message into the peer’s oneof to dispatch on it exhaustively. Callers select response types when waiting on Promise<Message>. A request is refused with a schema::Error, an application’s own error type converting into one through CodedError. A request whose content this build does not know is refused as UNKNOWN by the session itself, so a newer peer learns what an older one serves. A response of unknown content is malformed, no request having asked for it.

Requests and replies return promises without waiting for I/O. Their deadlines include time in the outgoing queue; wait() does not restart the timeout. Transport write timeouts are independent: a request can still reach the peer after its promise expires. The reader and writer run independently of the application, but the application must keep receiving and answering requests while its own requests wait for replies. All waiting is blocking; no async runtime is required. Every request expects a reply, including notifications.

Closing a session fails its pending promises and discards queued messages. Completed promises keep their results. A write already in progress may still reach the peer.

Modules

schema

Protobuf bindings of the protocol, generated from proto/wire.proto and excluded from the lints of handwritten code. Every message implements prost::Message for raw encoding. Applications exchange the bodies through Message, converting to the host_to_ark and ark_to_host oneofs to dispatch on one direction. The HostToArk and ArkToHost envelopes are the wire form, handled by the session internally.

Structs

Closer

Clonable handle for closing the session or server that created it.

Promise

Result of a queued request or reply.

Requester

Clonable handle for sending requests through the session that created it. Does not keep the session open or follow a replacement session. Dropping a requester does not close the session or cancel operations it already submitted.

Responder

Handle for answering one incoming request through the session that received it. The handler selects the success content, without a static request/response map. This handle cannot keep its session open or address a replacement session.

Server

Owner of a persistent server stream, accepting successive sessions. Closing or dropping the server ends its active session and shuts down the physical stream. Closing an individual Session keeps this owner and its stream available for another handshake.

Session

Owner of one session and its incoming request queue.

Enums

Error

Failure of a protocol operation. A remote application’s error is carried by Error::Remote; it does not by itself end the session.

Message

A request or successful response body from either direction. Variants are named by their body type, so a request and its response stay apart. Request IDs and wire envelopes remain internal to the session API. The session checks whether it can send this message in its direction.

Constants

DEFAULT_AUTOREPLY_TIMEOUT

Default timeout for sending an automatic reply, UNANSWERED when a responder is dropped or UNKNOWN to a request this build does not know. Starts when the responder is dropped or the request arrives and includes time in the outgoing queue. Configure it with Session::set_autoreply_timeout or Server::set_autoreply_timeout. Transport write timeouts are independent.

DEFAULT_MAX_INBOUND_BYTES

Default limit of 16 MiB for queued requests and unread response promises. Counts their full encoded envelopes. Taking or dropping an envelope reduces the byte count. Decoded application data, outgoing messages and transport buffers are excluded. Configure it with Session::set_inbound_limits or Server::set_inbound_limits. Zero permits no retained envelope bytes.

DEFAULT_MAX_INBOUND_REQUESTS

Default limit of 1,024 accepted peer requests per session. A request counts while queued, held by a responder, or waiting to send its reply. The slot is freed when the writer takes the reply or the reply is discarded. Configure it with Session::set_inbound_limits or Server::set_inbound_limits. Zero admits no peer requests.

Traits

CodedError

An application failure a request is answered with. The peer dispatches on the code and may show the message. Codes below 0x100 are the protocol’s schema::ReservedErrors, an application assigns its own from 0x100 up.

Functions

connect

Establishes a client session, verifies the peer and returns the verifier’s info. Takes ownership of the stream and constructs the transport internally. Failure closes the client stream; the application can open another stream and reconnect. The verifier is only borrowed during this blocking call. Failure to start a required worker or an escaping worker panic aborts the process.