docs/generated/contracts.mdgenerated from code

Reference · 7 min read

namespace

Contracts: namespace.

Source: crates/lvcs-doc/src/kinds/namespace/mod.rs.

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