docs/generated/contracts.mdgenerated from code

Reference · 8 min read

router

Contracts: router.

Source: crates/lvcs-doc/src/router.rs.

ruston main
1/// A subscription, minted by the router, unique per project.2#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord, Serialize, Deserialize)]3pub struct SubId(pub u64);45/// Who a subscription delivers to: the connection that made it and the6/// peer it said hello as.7#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]8pub struct Subscriber {9    pub sub: SubId,10    pub conn: u64,11    pub peer: PeerKey,12}1314/// Outputs of the router.15#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]16pub enum RouterOutput {17    /// Push the taken event `id` to one event subscription's connection (18    /// discussion:owner/515), as `event.read` answers it: `record`, the19    /// record its [`Taken`] carried, which the journal never holds20    /// (f-perf/14).21    DeliverEvent {22        to: Subscriber,23        id: String,24        record: TakenRecord,25    },26    /// Push a change to one subscription's connection. A change produces27    /// one `Deliver` per matching subscription, in `SubId` order.28    Deliver {29        to: Subscriber,30        address: String,31        #[serde(with = "crate::cbor::heads")]32        heads: Vec<ChangeId>,33        splices: Vec<Splice>,34    },35    /// The subscription id a [`MintSub`] asked for: unused by any36    /// subscription or watch this router minted or took before; `None`37    /// when its connection already holds `SUBSCRIPTIONS_PER_CONN_MAX`38    /// subscriptions (discussion:owner/561).39    Minted { reply: u64, sub: Option<SubId> },40    /// The answer to a [`HeldAsked`]: the document's heads when it has41    /// saves, else `None`.42    Held {43        reply: u64,44        #[serde(with = "crate::cbor::opt_heads")]45        heads: Option<Vec<ChangeId>>,46    },47    /// The answer to a [`HeldListAsked`]: every document with saves, by48    /// address, and every live path the namespace named whose file has49    /// saves; `listed` when the index holds the namespace's whole listing,50    /// so a path not in `paths` has no held file (discussion:owner/505).51    HeldList {52        reply: u64,53        addresses: BTreeSet<String>,54        paths: BTreeSet<String>,55        listed: bool,56        /// Each held document's heads, sorted: what a sync stream's57        /// `heads` frame digests (discussion:owner/637).58        heads: BTreeMap<String, Vec<ChangeId>>,59        /// Each held document's heads with their digests, sorted60        /// (discussion:owner/820): equal lists are equal histories, which61        /// the ids alone are not ([`HeadDigest`]), so a reader that kept62        /// what it read of a document knows whether it changed without63        /// starting it.64        digests: BTreeMap<String, Vec<HeadDigest>>,65        /// Each held file document's live path, by address: what the66        /// opening compares with the tree's rendered heads (orchestrator/18).67        files: BTreeMap<String, String>,68        /// The held documents whose ledger keeps a refusal that drops a69        /// stored change, proven or not ([`Stored::kept`], with70        /// [`Stored::refusals`]): a sync stream's machine leaves each out71        /// of the heads it sends and matches until its sync with that node72        /// settled once in the link's life, so a document that rests73        /// unloaded carries its refusal to its author (r3-join/17) instead74        /// of being matched away, and joins once per node, not on every75        /// stream.76        refusing: BTreeSet<String>,77    },78    /// The answer to a [`HeldAtAsked`]: the address of the document at79    /// its path when it has saves, else `None`; `known` when the index80    /// can tell (a control document's address, a path the namespace81    /// named, or any path once the index holds its whole listing), so82    /// `None` with `known` false means only the namespace can resolve it.83    HeldAt {84        reply: u64,85        address: Option<String>,86        known: bool,87    },88    /// The answer to a [`FilesAsked`]: the paths of the files under its89    /// prefix not removed, sorted; `listed` when the index holds the90    /// namespace's whole listing, so these are all of them.91    Files {92        reply: u64,93        files: Vec<String>,94        listed: bool,95    },96    /// The answer to a [`FrontierAsked`]: main's visible frontier.97    Frontier { reply: u64, frontier: Frontier },98    /// The refusal of a [`FrontierAsked`] while main isn't whole on this99    /// node (r3-join/2): `count` files the namespace places have no text100    /// here yet, the first few of them `missing`, in path order. Not said101    /// in 0.3.0: the rule had no bound (a placed file whose text never102    /// came held main short for good), so its rows are out until it is103    /// scoped to text a reachable peer offers (r3-join/5).104    FrontierShort {105        reply: u64,106        missing: Vec<String>,107        count: usize,108    },109    /// The answer to a [`MainAtAsked`]: main's id, and its entries at the110    /// paths asked only (`None` id when main can't be hashed).111    MainAt {112        reply: u64,113        id: Option<crate::frontier::FrontierId>,114        at: Frontier,115    },116    /// The answer to a [`VersionsAsked`]: main's newest versions it keeps117    /// that match, newest first (discussion:owner/687).118    Versions {119        reply: u64,120        versions: Vec<MainVersion>,121    },122    /// Main's visible frontier moved to the frontier `id`: a `file`123    /// document it holds was shown at other heads, renamed or removed, or124    /// held for the first time (discussion:owner/518's `frontier_moved`).125    FrontierMoved { id: crate::frontier::FrontierId },126    /// The answer to a [`SubscribersAsked`]: every subscription matching127    /// its addresses, each once, in `SubId` order.128    Subscribers { reply: u64, to: Vec<Subscriber> },129    /// The answer to a [`FileAsked`]: the file the namespace last named130    /// at the path, `None` when it named none there; `listed` when the131    /// index holds the namespace's whole listing, so `None` means no file132    /// is there.133    FileAt {134        reply: u64,135        file: Option<FileId>,136        listed: bool,137    },138    /// The answer to a [`ListingAsked`]: the digest of what the namespace139    /// told since the last one, as `kinds::namespace::listing_digest` sums140    /// a listing (tree-render/8).141    Listing { reply: u64, digest: [u8; 32] },142    /// The answer to a [`PathAsked`]: the file's path as the namespace143    /// last named it (`Some(None)` once removed), `None` while it named144    /// none; `revived` when the file came back from a removal its document145    /// hasn't rendered since, so it gives its text back to the path's146    /// views as it starts.147    Path {148        reply: u64,149        path: Option<Option<String>>,150        revived: bool,151        /// A removed file's last path, for its document's authorization.152        last: Option<String>,153        /// Every path the file held, for its document's authorization154        /// (discussion:owner/616).155        #[serde(default)]156        held: Vec<crate::Held>,157        /// The device that created the file (discussion:owner/675).158        #[serde(default)]159        creator: Option<crate::DeviceKey>,160        /// The owner purged the file (discussion:owner/614): its document161        /// never loads again.162        #[serde(default)]163        purged: bool,164    },165    /// The answer to a [`RemovedAsked`]: every removed file the namespace166    /// named and the owner hasn't purged, with the path it was last at,167    /// by file; `listed` as for [`RouterOutput::Files`].168    Removed {169        reply: u64,170        files: Vec<(FileId, Option<String>)>,171        listed: bool,172    },173    /// The answer to a [`RemovedAtAsked`]: for each path asked that a174    /// deleted node of some file was last at, each such file and what it175    /// is now; `listed` as for [`RouterOutput::Files`].176    RemovedAt {177        reply: u64,178        at: BTreeMap<String, Vec<(FileId, RemovedNow)>>,179        listed: bool,180    },181    /// The answer to an [`AuthorsAsked`]: each Loro peer a document's182    /// verified changes named, with its record.183    Authors {184        reply: u64,185        authors: BTreeMap<u64, Record>,186    },187    /// The document at `address` is stuck as `doc` says, or, with `None`,188    /// no longer stuck: sent to the stuck lister (`crate::stuck`,189    /// o-decouple/8), whose list `status` reads, whenever what it set190    /// aside, the refusals its ledger keeps, its path, or its writers'191    /// signers change its [`StuckDoc`] (discussion:owner/671 rule 6).192    StuckChanged {193        address: String,194        doc: Option<StuckDoc>,195    },196    /// The router restarted, which forgets what was set aside (kept in197    /// memory only, discussion:owner/671 rule 2): the stuck lister forgets198    /// every document, and the stored refusals come again with `Stored`.199    StuckForgotten,200    /// Send the router a [`Settle`] `wait_ms` from now: main moved, and its201    /// id is computed once every step in that wait is in (o-decouple/8),202    /// not once per step. The wait grows with the paths main holds, so203    /// hashing main stays a fixed share of the router's time.204    Settling { wait_ms: u64 },205}206207/// A document holding changes it can't take in (discussion:owner/671 rule208/// 6), as the stuck lister ([`crate::stuck`]) answers it.209#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]210pub struct StuckDoc {211    /// The file's path when the document has one, else its address.212    pub address: String,213    /// How many changes it set aside or refuses.214    pub changes: u32,215    /// The writers they are from, by Loro peer.216    pub writers: u32,217    /// Who signed the first writer's, when the document knows.218    pub signer: Option<PeerKey>,219    /// Whether every one is a kept refusal, none set aside unreadable.220    pub refused: bool,221    /// A sender of what it set aside judged by rules newer than this222    /// binary's (discussion:owner/671 rule 6).223    #[serde(default, skip_serializing_if = "core::ops::Not::not")]224    pub newer_rules: bool,225    /// A file document stored at an address no file id prints (its id in226    /// capitals): main shows no file for it ([`file_at`]), so it is listed227    /// here rather than missing from main unsaid (owner/790).228    #[serde(default, skip_serializing_if = "core::ops::Not::not")]229    pub noncanonical: bool,230}231232/// One peer's changes a stored refusal keeps out, which no evidence proves233/// and the audit's own checks admit (discussion:owner/671 rule 6).234#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]235pub struct StoredRefusal {236    pub peer: u64,237    pub signer: PeerKey,238    pub changes: u32,239}240241/// The refusals `refused` keeps out of `changes` with no proof: those of a242/// peer `evidence` holds no equivocation of, by peer, with how many243/// stored changes each drops. A refusal with no change stored holds244/// nothing back and is left out.245#[must_use]246pub fn unproven_refusals(247    changes: &[crate::change::SignedChange],248    refused: &BTreeMap<u64, i32>,249    evidence: &[crate::change::Evidence],250) -> Vec<StoredRefusal> {251    let mut found: BTreeMap<u64, StoredRefusal> = BTreeMap::new();252    for signed in changes {253        let change = &signed.change;254        if !refused255            .get(&change.peer)256            .is_some_and(|first| change.end > *first)257            || evidence258                .iter()259                .any(|proof| proof.refused.change.peer == change.peer)260        {261            continue;262        }263        let refusal = found.entry(change.peer).or_insert(StoredRefusal {264            peer: change.peer,265            signer: change.record.signer,266            changes: 0,267        });268        refusal.changes = refusal.changes.saturating_add(1);269    }270    found.into_values().collect()271}272273/// A taken event's record as `event.read` answers it, riding with its274/// [`Taken`] and never journaled: `None` once decoded from the journal.275pub type TakenRecord = Transient<Option<Arc<serde_json::Value>>>;276277/// One taken event as the router decides on it (f-perf/14): its record's278/// id and its kind, which the journal holds, and the record itself, which279/// rides along to the deliveries and is never journaled, since no guard or280/// action reads it.281#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]282pub struct Taken {283    pub id: String,284    pub kind: String,285    pub record: TakenRecord,286}