docs/generated/contracts.mdgenerated from code
Reference · 7 min read
sync
Contracts: sync.
Read as
Source: crates/lvcs-net/src/sync/mod.rs.
1/// The sync actor's events, generated by its sml table: its dispatch2/// and journal type (discussion:owner/286 and discussion:owner/341). Time enters only as event data. Owner:3/// `M3.sync`.4///5/// Its events, each the payload type its variant is named for: [`NodeOpened`],6/// [`NodeClosed`], [`DocKnown`], [`DocWoke`], [`DocPurged`], [`DocOutgoing`],7/// [`DocSettled`], [`FrameIn`], [`DocRejected`], [`DocTook`], [`NodeRoom`].8pub use machine::{9 Access, Admission, AskDigests, AskHeard, DigestsMoved, DocAnswered, DocKnown, DocOutgoing,10 DocPurged, DocRejected, DocRested, DocSettled, DocTook, DocWoke, FrameIn, HoldsResolved,11 NodeClosed, NodeExpired, NodeOpened, NodeRoom, NodesAdmitted, Stepped, SuspendTick,12 SyncingEvents, WindowTick, digests_fingerprint, digests_moved,13};1415/// An outgoing sync message's bytes, journaled as their content hash and16/// length only (row 452): replay never sends a message, and the sync17/// machine reads only its length (discussion:owner/111). A replayed one carries18/// no bytes.19#[derive(Clone)]20pub struct Payload {21 /// The bytes; empty when read back from the journal.22 bytes: std::sync::Arc<[u8]>,23 /// SHA-256 of the bytes.24 hash: [u8; 32],25 /// Their length.26 len: u64,27}2829impl Payload {30 /// `bytes`, hashed.31 #[must_use]32 pub fn new(bytes: Vec<u8>) -> Self {33 use sha2::Digest as _;34 let hash = sha2::Sha256::digest(&bytes).into();35 let len = u64::try_from(bytes.len()).unwrap_or(u64::MAX);36 Self {37 bytes: bytes.into(),38 hash,39 len,40 }41 }4243 /// The bytes (none when replayed).44 #[must_use]45 pub fn bytes(&self) -> &[u8] {46 &self.bytes47 }4849 /// Their length, also when replayed.50 #[must_use]51 pub fn len(&self) -> usize {52 usize::try_from(self.len).unwrap_or(usize::MAX)53 }5455 /// Whether it holds nothing.56 #[must_use]57 pub const fn is_empty(&self) -> bool {58 self.len == 059 }6061 /// The SHA-256 of its bytes, also when replayed.62 #[must_use]63 pub const fn digest(&self) -> [u8; 32] {64 self.hash65 }66}6768impl std::fmt::Debug for Payload {69 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {70 f.debug_struct("Payload")71 .field("len", &self.len)72 .finish_non_exhaustive()73 }74}7576impl PartialEq for Payload {77 fn eq(&self, other: &Self) -> bool {78 self.hash == other.hash && self.len == other.len79 }80}8182impl Eq for Payload {}8384/// What a [`Payload`] journals.85#[derive(Serialize, Deserialize)]86struct Journaled {87 #[serde(with = "crate::wire::cbor::fixed")]88 hash: [u8; 32],89 len: u64,90}9192impl Serialize for Payload {93 fn serialize<S: serde::Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {94 Journaled {95 hash: self.hash,96 len: self.len,97 }98 .serialize(serializer)99 }100}101102impl<'de> Deserialize<'de> for Payload {103 fn deserialize<D: serde::Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {104 let Journaled { hash, len } = Journaled::deserialize(deserializer)?;105 Ok(Self {106 bytes: std::sync::Arc::from(Vec::new()),107 hash,108 len,109 })110 }111}112113/// Outputs of the sync actor, which the daemon shell carries out.114/// Owner: `M3.sync`.115#[derive(Debug, Clone, PartialEq, Eq)]116pub enum SyncOutput {117 /// Signed reopened-stream incarnation compared with the value held before suspension.118 /// None means the prior or new incarnation was unavailable.119 IncarnationVerdict { node: Node, same: Option<bool> },120 /// Abort this sync stream and discard queued writer frames when access121 /// ends; the node's connection remains and may reopen caps-only.122 AbortSync { node: Node },123 /// Send `WindowTick { node, arm }` back `SYNC_JOIN_STALE_MS` from now124 /// (caps-transport/3): the node's join window holds slots, and the tick125 /// tells whether it moved since.126 ArmWindow { node: Node, arm: u64 },127 /// The link with `node` needs neither the start nor the stop of `doc`128 /// (`hushed`), or needs both again (daemon-memory/1): the shell sends a129 /// hushed document's `DocWoke` and `DocRested` to every machine but130 /// this one, whose step would change nothing and still be journaled.131 Hush {132 /// The node whose link it is.133 node: Node,134 /// The document's address.135 doc: String,136 /// Whether the link needs neither.137 hushed: bool,138 },139 /// The link with `node` opened afresh or closed: it hushes nothing.140 Unhushed { node: Node },141 /// Seal `frame` in an envelope of kind `sync` signed by this device's142 /// key and write it to the sync stream with `node`143 /// (`TransportCommand::SyncFrame`).144 Send {145 /// The node to send to.146 node: Node,147 /// The document the frame is for.148 doc: String,149 /// The frame's payload.150 payload: Payload,151 /// A control document's frame, written ahead of files' frames152 /// (`TransportCommand::SyncFrame::urgent`).153 urgent: bool,154 },155 /// Report when the sync stream with `node` has `room` bytes of room156 /// (`TransportCommand::AwaitRoom`, session-29a3231b/2): this side holds157 /// what it writes the node until it does ([`SyncingEvents::NodeRoom`]).158 /// `room` is what the writer's next frame needs within its share of159 /// the daemon's answers (r3-hsm's B1 on r3-memory/12).160 AwaitRoom {161 /// The node the stream is with.162 node: Node,163 /// The room the next held frame needs.164 room: u64,165 },166 /// Seal an `inventory` envelope ([`crate::wire::SyncInventory`]) counting `docs`,167 /// signed by this device's key, and write it to the sync stream with168 /// `node`: sent each time the node's caps round settles, after the169 /// round's held messages and joins, with every document then joined170 /// with the node, `.lvcs/caps` among them. `None` while the node's171 /// admission is undecided (orchestrator/26), sealed as172 /// [`crate::wire::INVENTORY_UNDECIDED`]; the decision sends it again173 /// with the count.174 Inventory {175 /// The node to send to.176 node: Node,177 /// How many documents sync with it, once its admission is decided.178 docs: Option<u64>,179 },180 /// Seal a [`crate::wire::SyncHeads`] of `docs` in an envelope of kind181 /// `heads` signed by this device's key, and write it to the sync182 /// stream with `node`: sent first as each stream opens183 /// (discussion:owner/637).184 Heads {185 /// The node to send to.186 node: Node,187 /// This side's heads digests.188 docs: Vec<crate::wire::DocHeads>,189 },190 /// `node` sent its `inventory`: it syncs `docs` documents with this191 /// daemon (`lvcs join` waits for them), its daemon holds `holders`,192 /// whose signatures the shell checks, and it is named `host`193 /// (discussion:owner/314).194 Inventoried {195 /// The node that sent it.196 node: Node,197 /// How many documents it syncs with this daemon, `None` while it198 /// hasn't decided this daemon's admission (orchestrator/26): no199 /// join ends on that.200 docs: Option<u64>,201 /// The peer keys its daemon holds, each signed.202 holders: Vec<crate::wire::Holder>,203 /// Its machine name.204 host: Option<String>,205 },206 /// Hand a received payload to the document at `doc`, spawning its actor207 /// if it isn't running (`DocEvent::SyncIn`, carrying `tag`). The shell208 /// refuses one whose address the path filter excludes (never-sync,209 /// discussion:owner/81) or that collides with an existing directory, before210 /// spawning any document (discussion:owner/110), and spawns no document for one211 /// while it holds `PROJECT_MAX_DOCUMENTS` documents, dropping it without212 /// penalty (discussion:owner/112).213 Deliver {214 /// The document's address.215 doc: String,216 /// The node the payload came from.217 node: Node,218 /// The sync message, opaque here, journaled as its hash and219 /// length: the bytes the frame was read into, never copied here.220 payload: Payload,221 /// The input's tag: the document reports it took it222 /// ([`SyncingEvents::DocTook`]), whatever came of it.223 tag: u64,224 /// The sender's trace context, carried as it is (discussion:owner/441).225 trace: Option<Traceparent>,226 /// A follow-up frame for a document this node's frames already227 /// charged and that hasn't settled with it (discussion:owner/762228 /// rule 4a): its permit is asked as held, within the budget's cap.229 held: bool,230 },231 /// Start syncing `doc` with `node` (`DocEvent::NodeJoined`, carrying232 /// `tag`). Every `Join` and `Deliver` takes the next value of a counter233 /// rising through the daemon run (discussion:owner/110); tags are never234 /// telemetry values.235 Join {236 /// The document's address.237 doc: String,238 /// The node to sync with.239 node: Node,240 /// The input's tag.241 tag: u64,242 },243 /// Stop reading the sync stream with `node` between frames244 /// (`TransportCommand::PauseSync`): `SYNC_IN_FLIGHT_MAX_BYTES` of its245 /// frames' payloads were delivered and not yet taken, so the stream's246 /// flow control pushes back to the node until its documents take them247 /// (session-29a3231b/2). The pause ends with the stream.248 Pause {249 /// The node whose stream to stop reading.250 node: Node,251 },252 /// Read the sync stream with `node` again253 /// (`TransportCommand::ResumeSync`): its documents took its delivered254 /// frames down to `SYNC_IN_FLIGHT_LOW_BYTES`.255 Resume {256 /// The node whose stream to read again.257 node: Node,258 },259 /// Stop syncing `doc` with `node` (`DocEvent::NodeLeft`).260 Leave {261 /// The document's address.262 doc: String,263 /// The node to stop syncing with.264 node: Node,265 },266 /// Close the stream and every connection to `node` and lower its score267 /// (`TransportCommand::Disconnect` and `Penalize`): a faulty frame, a268 /// document's rejection, or `over_limit` (discussion:owner/111 and discussion:owner/112).269 Disconnect {270 /// The faulty node.271 node: Node,272 /// Why it is disconnected.273 reason: Rejection,274 },275 /// Answer [`AskDigests`] `to`: the heads digests the machine holds of276 /// this side's documents, the base a reopen's [`DigestsMoved`] is277 /// against (request-flood/3).278 Digests {279 /// The ask.280 to: u64,281 /// Each document's digest.282 docs: std::collections::BTreeMap<String, [u8; 32]>,283 },284 /// Answer [`AskHeard`] `to`: the node's heads digests as its last285 /// `heads` frame named them, the base the next frame's move is against286 /// (caps-transport/10).287 Heard {288 /// The ask.289 to: u64,290 /// Each document's digest.291 docs: std::collections::BTreeMap<String, [u8; 32]>,292 },293}