docs/generated/contracts.mdgenerated from code

Reference · 7 min read

sync

Contracts: sync.

Source: crates/lvcs-net/src/sync/mod.rs.

ruston main
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}