darkbio_wire/protocol/
mod.rs

1// wire-rs: encrypted protocol between Ark and host
2// Copyright 2026 Dark Bio AG. All rights reserved.
3
4//! Bidirectional requests over the transport, with pipelining and explicit sessions.
5//!
6//! A reader receives messages from each connection. Each session also has a writer
7//! that sends queued messages and a deadline worker that times out operations.
8//! Incoming requests and unread responses stay encoded until `recv()` or `wait()`.
9//! Invalid payloads close their original session when decoded.
10//!
11//! Each session limits accepted peer requests and buffered incoming bytes. Set
12//! both with [`Session::set_inbound_limits`] or [`Server::set_inbound_limits`].
13//! Exceeding a limit closes the session. The reader never waits for the application
14//! to make room. These limits are local; no flow control is negotiated with the
15//! peer. The outgoing queue has no capacity limit.
16//!
17//! The application opens a [`crate::transport::Stream`]; this layer constructs and
18//! owns its transport. [`connect`] establishes one client session. [`Server`] owns
19//! a persistent stream and accepts successive server sessions. Each [`Session`]
20//! owns its receive queue and closes when dropped. Its [`Requester`] and
21//! [`Responder`] handles always target that session, even after it closes and
22//! another session connects.
23//! Both sides use the same handle types. Sessions exchange [`Message`], the union
24//! of every body in the [`schema`]. The [`schema::host_to_ark::Content`] and
25//! [`schema::ark_to_host::Content`] oneofs hold what each side may send. Convert
26//! a received [`Message`] into the peer's oneof to dispatch on it exhaustively.
27//! Callers select response types when waiting on [`Promise<Message>`]. A request
28//! is refused with a [`schema::Error`], an application's own error type converting
29//! into one through [`CodedError`]. A request whose content this build does not
30//! know is refused as `UNKNOWN` by the session itself, so a newer peer learns what
31//! an older one serves. A response of unknown content is malformed, no request
32//! having asked for it.
33//!
34//! Requests and replies return promises without waiting for I/O. Their deadlines
35//! include time in the outgoing queue; `wait()` does not restart the timeout.
36//! Transport write timeouts are independent: a request can still reach the peer
37//! after its promise expires. The reader and writer run independently of the
38//! application, but the application must keep receiving and answering requests
39//! while its own requests wait for replies. All waiting is blocking; no async
40//! runtime is required. Every request expects a reply, including notifications.
41//!
42//! Closing a session fails its pending promises and discards queued messages.
43//! Completed promises keep their results. A write already in progress may still
44//! reach the peer.
45
46mod closer;
47mod envelope;
48mod error;
49mod message;
50mod operation;
51mod promise;
52mod requester;
53mod responder;
54mod server;
55mod session;
56mod worker;
57
58#[cfg(any(test, feature = "fuzz"))]
59#[cfg_attr(coverage_nightly, coverage(off))]
60#[doc(hidden)]
61pub mod mock;
62
63pub use closer::Closer;
64pub use error::{CodedError, Error};
65pub use message::Message;
66pub use promise::Promise;
67pub use requester::Requester;
68pub use responder::Responder;
69pub use server::Server;
70pub use session::{Session, connect};
71
72use std::time::Duration;
73
74/// Default timeout for sending an automatic reply, `UNANSWERED` when a responder
75/// is dropped or `UNKNOWN` to a request this build does not know. Starts when
76/// the responder is dropped or the request arrives and includes time in the
77/// outgoing queue. Configure it with [`Session::set_autoreply_timeout`] or
78/// [`Server::set_autoreply_timeout`]. Transport write timeouts are independent.
79pub const DEFAULT_AUTOREPLY_TIMEOUT: Duration = Duration::from_secs(5);
80
81/// Default limit of 1,024 accepted peer requests per session. A request counts
82/// while queued, held by a responder, or waiting to send its reply. The slot is
83/// freed when the writer takes the reply or the reply is discarded.
84/// Configure it with [`Session::set_inbound_limits`] or
85/// [`Server::set_inbound_limits`]. Zero admits no peer requests.
86pub const DEFAULT_MAX_INBOUND_REQUESTS: usize = 1024;
87
88/// Default limit of 16 MiB for queued requests and unread response promises.
89/// Counts their full encoded envelopes. Taking or dropping an envelope reduces
90/// the byte count.
91/// Decoded application data, outgoing messages and transport buffers are excluded.
92/// Configure it with [`Session::set_inbound_limits`] or
93/// [`Server::set_inbound_limits`]. Zero permits no retained envelope bytes.
94pub const DEFAULT_MAX_INBOUND_BYTES: usize = 16 * 1024 * 1024;
95
96/// Protobuf bindings of the protocol, generated from `proto/wire.proto` and
97/// excluded from the lints of handwritten code. Every message implements
98/// `prost::Message` for raw encoding. Applications exchange the bodies through
99/// [`Message`], converting to the `host_to_ark` and `ark_to_host` oneofs to
100/// dispatch on one direction. The `HostToArk` and `ArkToHost` envelopes are the
101/// wire form, handled by the session internally.
102#[allow(clippy::all)]
103#[allow(rustdoc::broken_intra_doc_links)]
104pub mod schema {
105    include!(concat!(env!("OUT_DIR"), "/darkbio.wire.rs"));
106}
darkbio_wire/protocol/mod.rs

darkbio_wire/protocol/
mod.rs
