sapphire_framework_session/lib.rs
1//! The replication session two sapphire-framework replicas run over a byte stream.
2//!
3//! One `Replica` per side, one bidirectional stream, and a framed exchange of version
4//! vectors, path updates and content. This crate is the only place that knows the wire
5//! format; it neither knows nor cares what carries the bytes.
6//!
7//! Two shapes of session are built on that exchange:
8//!
9//! - [`run_session`] — a one-shot catch-up. It returns once both sides are caught up.
10//! - [`open_live_session`] — the same catch-up, then a stream that stays open: each side
11//! pushes what it commits and applies what arrives.
12//!
13//! See `docs/superpowers/specs/2026-09-15-p2p-sync-iroh-design.md` §3.7 and §4.2.
14
15#![warn(missing_docs)]
16
17mod error;
18mod frame;
19mod incoming;
20mod live;
21mod message;
22mod progress;
23mod session;
24mod writer;
25
26pub use error::{Error, Result};
27pub use frame::{
28 Frame, read_frame, read_framed, write_blob_chunk, write_blob_end, write_blob_start,
29 write_control, write_framed,
30};
31pub use live::{LiveSession, open_live_session};
32pub use message::Message;
33pub use session::{HELLO_TIMEOUT, SessionOutcome, run_session};
34
35use std::time::Duration;
36
37/// The session format this build speaks. Sent in the first message and checked.
38///
39/// 2 carries content as `BLOB_START`, chunks and `BLOB_END`; a format 1 peer is refused.
40pub const SESSION_FORMAT_VERSION: u32 = 2;
41
42/// Largest payload carried inline in an `Updates` page, in bytes. Anything larger is
43/// fetched by hash within the same session.
44pub const INLINE_LIMIT: usize = 64 * 1024;
45
46/// Longest control frame payload accepted, in bytes. Bounds the memory one peer can make
47/// the other allocate for one message.
48///
49/// Not tied to the largest file: content travels in chunks of at most [`CHUNK`], and a
50/// whole blob is bounded by the receiver's `max_file_size` instead.
51pub const MAX_FRAME_LEN: usize = 16 * 1024 * 1024;
52
53/// Most content one `BLOB_CHUNK` frame carries, in bytes. The sender reads, and the
54/// receiver holds, at most this much of a file at a time.
55pub const CHUNK: usize = 256 * 1024;
56
57/// How long the initial exchange goes without progress before it gives up on the peer.
58///
59/// Progress is a frame read from the peer or a frame written to it, and both directions
60/// count: a side sending a 1 GiB file hears nothing from the peer for as long as that
61/// takes, and must not give up on it for that. A bound on silence rather than on total
62/// time is what lets one large file take minutes while a peer that has stopped altogether
63/// is still let go of.
64///
65/// Progress counts whole frames, so a peer draining slower than about one [`CHUNK`] per
66/// `IDLE_TIMEOUT` (some 4 KiB/s) is given up on even though bytes are still moving.
67///
68/// The `Hello` wait has its own bound, [`HELLO_TIMEOUT`], and the live phase after the
69/// exchange has none.
70pub const IDLE_TIMEOUT: Duration = Duration::from_secs(60);