docs/generated/contracts.mdgenerated from code
Reference · 7 min read
namespace
Contracts: namespace.
Read as
Source: crates/lvcs-doc/src/kinds/namespace/mod.rs.
1/// A file, by its namespace node's id: stable across moves and renames.2/// Written like a [`ChangeId`]; its text document is `.lvcs/files/<id>`.3#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]4pub struct FileId(pub ChangeId);56/// The path a file is at now, and every path it held, for its document7/// (history row 457 and discussion:owner/616): a file document authorizes8/// a change it receives against the paths its file held at the change's9/// signed time ([`held_at`] over `held`), as the audit does, and holds10/// changes until it knows a path. The namespace document's own close11/// sends it to each file whose path or history a step changed, whoever's12/// change it was, and on every render to every file.13#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]14pub struct PathKnown {15 pub file: FileId,16 /// `None` once the file is removed.17 pub path: Option<String>,18 /// For a removed file, the path it had just before its newest removal19 /// (history row 458: its changes are authorized against it), judged20 /// at the version just before that removal; `None` for a live file, or21 /// one that never had a path.22 #[serde(default)]23 pub last: Option<String>,24 /// When told: every path a deleted node of the file was at just before25 /// the removal that took it (discussion:owner/790), sorted, the file's26 /// whole set as it stands, which replaces what was told before (a27 /// later delete of a node deleted already can become its removal, and28 /// move the path). Told by a step for each file a delete op of the29 /// step reaches, and by a listing for every file with a deleted node,30 /// a live file too. It is the value the namespace's own newest-removal31 /// answer compares ([`Namespace::removal_at`]), so the router can name32 /// the files removed from a path without loading the namespace.33 /// `None` when it tells nothing of them, as every entry written before34 /// it reads.35 #[serde(default, skip_serializing_if = "Option::is_none")]36 pub lasts: Option<Vec<String>>,37 /// Every path the file held, oldest first, as the namespace's ledger38 /// replayed in its order gives them (discussion:owner/616).39 #[serde(default, skip_serializing_if = "Vec::is_empty")]40 pub held: Vec<Held>,41 /// The device whose change created the file, when the namespace holds42 /// that change (discussion:owner/675): a file document with no change43 /// yet that another device created is waiting for that device's text.44 #[serde(default, skip_serializing_if = "Option::is_none")]45 pub creator: Option<crate::DeviceKey>,46}4748/// One [`PathKnown`]'s term of a [`listing_digest`]: the first 8 bytes of49/// the SHA-256 of its canonical encoding, never 0 (0 is no term). One that50/// doesn't encode still counts, as a term of its own, so a router never told51/// of it holds a different sum and the listing is told again. Eight bytes,52/// not 32, so a router entry stays within its bytes a file53/// (router_resident_memory; tree-render/8).54#[must_use]55pub(crate) fn known_term(known: &PathKnown) -> u64 {56 let digest = crate::cbor::digest(known).unwrap_or([0xff; 32]);57 let [a, b, c, d, e, f, g, h, ..] = digest;58 u64::from_be_bytes([a, b, c, d, e, f, g, h]).max(1)59}6061/// The digest a listing of [`PathKnown`]s is known by, whatever its order:62/// the sum, mod 2^64, of each one's [`known_term`], in the last 8 of 3263/// bytes. Additive, so a duplicated or re-added entry never cancels and two64/// stale ones never mask each other (the orchestrator's ruling on65/// tree-render's restart telling): the router keeps it of what it was told,66/// and the namespace tells every path again only when its own listing's67/// differs. Mod 2^64, not 2^256 (the orchestrator's ruling, 11-13): it is a68/// local recovery check, never a security boundary. A false "unchanged"69/// needs the daemon to stop between a namespace step and the router's70/// journal of it, and a 2^-64 collision besides; and an additive multiset71/// hash is weak to a k-sum search at any width, so 32 bytes would buy72/// nothing but 26 bytes a router entry.73#[must_use]74pub fn listing_digest<'a>(known: impl IntoIterator<Item = &'a PathKnown>) -> [u8; 32] {75 digest_of_sum(76 known77 .into_iter()78 .fold(0_u64, |sum, one| sum.wrapping_add(known_term(one))),79 )80}8182/// A sum of [`known_term`]s as a listing's 32-byte digest.83#[must_use]84pub(crate) fn digest_of_sum(sum: u64) -> [u8; 32] {85 let mut digest = [0; 32];86 if let Some(low) = digest.get_mut(24..) {87 low.copy_from_slice(&sum.to_be_bytes());88 }89 digest90}9192/// One path a file held: from the signed time `since` of the namespace93/// change that put it there until `until`, that of the change that took94/// it away (`None` while it still holds it), both inclusive at the second95/// (discussion:owner/463).96#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]97pub struct Held {98 pub path: String,99 pub since: i64,100 pub until: Option<i64>,101}102103/// How one file's path changed in a namespace step: created (`from` is104/// `None`), removed (`to` is `None`), or moved or renamed (both set), so105/// the tree renames a file on disk rather than deleting and creating it.106#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]107pub struct PathChange {108 pub file: FileId,109 pub from: Option<String>,110 pub to: Option<String>,111}112113/// Which file is at `path` (answered [`FilesAnswer::Resolved`]).114#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]115pub struct ResolvePath {116 pub req: RequestId,117 pub path: String,118}119120/// Every file and its path (answered [`FilesAnswer::Listed`]).121#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]122pub struct ListFiles {123 pub req: RequestId,124}125126/// Create the file at `path`, with any directories above it, as127/// `origin`'s writer (answered [`FilesAnswer::Created`], or the existing128/// file's id with the heads unchanged).129#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]130pub struct CreateFile {131 pub req: RequestId,132 pub origin: Origin,133 pub path: String,134}135136/// Move or rename the node at `from`, with everything below it, to `to`137/// (answered `DocOutput::Changed` naming `req`, or `Rejected`:138/// `InvalidRange` when nothing is at `from` or something is at `to`).139#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]140pub struct MovePath {141 pub req: RequestId,142 pub origin: Origin,143 pub from: String,144 pub to: String,145}146147/// Remove the node at `path`, with everything below it (answered as148/// [`MovePath`] is).149#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]150pub struct RemovePath {151 pub req: RequestId,152 pub origin: Origin,153 pub path: String,154}155156/// Bring back the file most recently removed from `path`, with its file157/// id, so its document and history serve the path again (history row158/// 458), as `origin`'s writer (answered [`FilesAnswer::Created`] with the159/// restored file's id, or `Rejected`: `InvalidRange` when `path` is taken160/// or no removed file was there).161#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]162pub struct RestorePath {163 pub req: RequestId,164 pub origin: Origin,165 pub path: String,166}167168/// The file the newest removal took from `path`, changing nothing, even169/// when a recreated file is at `path` now (answered170/// [`FilesAnswer::Resolved`]; `None` when no removed file was there or it171/// is live elsewhere): what [`RestorePath`] brings back when `path` is172/// free, and what a lagging edit's base may name when it isn't.173#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]174pub struct ResolveRemoved {175 pub req: RequestId,176 pub path: String,177}178179/// The file the newest removal took from `path` and the change that removed180/// it, changing nothing (answered [`FilesAnswer::Removal`]; `None` when no181/// removed file was there or it is live elsewhere): an approval at a182/// frontier whose namespace heads hold that change approves the removal183/// (discussion:owner/806).184#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]185pub struct ResolveRemoval {186 pub req: RequestId,187 pub path: String,188}189190/// The namespace document's answers to its own queries, each naming its191/// request.192#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]193pub enum FilesAnswer {194 Resolved {195 req: RequestId,196 file: Option<FileId>,197 },198 Listed {199 req: RequestId,200 files: Vec<(String, FileId)>,201 },202 /// [`ResolveRemoval`]'s answer: the removed file and its removal's203 /// change.204 Removal {205 req: RequestId,206 removed: Option<(FileId, ChangeId)>,207 },208 /// `heads` are those of what the store holds once the answer is good209 /// (f-perf/2 point 4): the signed changes, and the own changes the210 /// answer waits for with the own changes those are built on. Given211 /// when a create is stored, they are the stored heads, and name no212 /// later own change, which may yet be dropped.213 Created {214 req: RequestId,215 file: FileId,216 heads: crate::change::Heads,217 },218}