docs/generated/contracts.mdgenerated from code
Reference · 8 min read
router
Contracts: router.
Read as
Source: crates/lvcs-doc/src/router.rs.
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}