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 live;
20mod message;
21mod session;
22
23pub use error::{Error, Result};
24pub use frame::{Frame, read_frame, read_framed, write_blob, write_control, write_framed};
25pub use live::{LiveSession, open_live_session};
26pub use message::Message;
27pub use session::{HELLO_TIMEOUT, SessionOutcome, run_session};
28
29/// The session format this build speaks. Sent in the first message and checked.
30pub const SESSION_FORMAT_VERSION: u32 = 1;
31
32/// Largest payload carried inline in an `Updates` page, in bytes. Anything larger is
33/// fetched by hash within the same session.
34pub const INLINE_LIMIT: usize = 64 * 1024;
35
36/// Longest frame payload accepted, in bytes. Matches the replication core's
37/// `DEFAULT_MAX_FILE_SIZE`, and bounds the memory one peer can make the other allocate.
38pub const MAX_FRAME_LEN: usize = 64 * 1024 * 1024;