docs/generated/contracts.mdgenerated from code

Reference · 13 min read

api-files

Contracts: api-files.

Source: crates/lvcs-api/src/files.rs.

ruston main
1/// `open`: start (or find) the document actor for `address`.2#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]3pub struct OpenParams {4    pub address: String,5}67/// `open` result.8#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]9pub struct OpenResult {10    pub kind: String,11    pub heads: Vec<String>,12}1314/// `read`: the rendered body, or the value at `pointer`. With `heads`15/// (discussion:owner/303), the file as it was at those heads (change ids,16/// `<peer:016x><counter:08x>`, as a `read` or a frontier's document17/// returned them), with no18/// `pointer`; heads the document lacks are refused19/// `unknown_base`. With `frontier` (discussion:owner/385), the file at the heads20/// that frontier holds for it: a frontier id (`ID_ENCODING`) or a unique21/// start of one a channel names, with no `heads` or `pointer`; a frontier no channel names, or a file it lacks, is22/// refused `unknown_base`.23#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]24pub struct ReadParams {25    pub address: String,26    #[serde(default, skip_serializing_if = "Option::is_none")]27    pub pointer: Option<String>,28    #[serde(default, skip_serializing_if = "Option::is_none")]29    pub heads: Option<Vec<String>>,30    #[serde(default, skip_serializing_if = "Option::is_none")]31    pub frontier: Option<String>,32}3334/// `read` result: exactly one of `text`, `bytes_base64`, or `json` is35/// present; `deleted` is true when the file is deleted.36#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]37pub struct ReadResult {38    pub heads: Vec<String>,39    #[serde(default, skip_serializing_if = "Option::is_none")]40    pub text: Option<String>,41    #[serde(default, skip_serializing_if = "Option::is_none")]42    pub bytes_base64: Option<String>,43    #[serde(default, skip_serializing_if = "Option::is_none")]44    pub json: Option<String>,45    pub deleted: bool,46}4748/// One splice against the text at `base`.49#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]50pub struct SpliceParams {51    pub pos: usize,52    pub delete: usize,53    pub insert: String,54}5556/// `edit`: splices against the text at `base`, sorted by `pos`, disjoint.57#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]58pub struct EditParams {59    pub address: String,60    pub base: Vec<String>,61    pub splices: Vec<SpliceParams>,62}6364/// `write` (discussion:owner/518): a whole-file save of `bytes_base64` (standard65/// base64) at `address` from `base`, the heads it read there (empty for a66/// file not there yet), under the caller's `write` grant: as text, an67/// `edit` of the lines that differ from the text at `base`, scanned and68/// refused like one; as bytes that aren't UTF-8, a binary save, as the69/// tree's. With `executable`, the file's executable bit is set after.70/// With `derived`, the save marks the document derived (`true`, a71/// generator's output) or not (`false`); without it, the path's72/// classification decides, as for `edit`.73#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]74pub struct WriteParams {75    pub address: String,76    pub base: Vec<String>,77    pub bytes_base64: String,78    #[serde(default, skip_serializing_if = "Option::is_none")]79    pub executable: Option<bool>,80    #[serde(default, skip_serializing_if = "Option::is_none")]81    pub derived: Option<bool>,82}8384/// `write` result: the file's heads after it. For a text save they are85/// `edit`'s, the heads of the stored version holding it, a durable base86/// (discussion:owner/720). A binary save, and one that sets the87/// executable bit, still answers the file's live heads as a read right88/// after the save names them, which may name a change not yet stored.89#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]90pub struct WriteResult {91    pub heads: Vec<String>,92}9394/// `edit` result: the heads of the stored version holding the edit95/// (discussion:owner/720), a durable base. They name no change of another96/// writer that isn't stored yet, so the file's live heads, which `read`97/// and a `changed` push name, may be ahead of them.98#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]99pub struct EditResult {100    pub heads: Vec<String>,101}102103/// `add` (discussion:owner/513): save the file at `path`, a104/// path below the project root, as it is on disk. The tree's refused save105/// of it, held while its cause lasts, goes through intake again, checked106/// and signed like any save (`resent`); with none held, nothing is sent107/// (`resent` false): the tree reports a file that changed by itself. Either108/// way the answer comes once main holds the file as it is on disk, or109/// merged with lines changed since (a stale save), with its `heads`110/// (discussion:owner/653, o-decouple/1), so a read right after it gives111/// main's version: a save refused again is refused `rejected` (the save112/// held for its author), one taken as dropped or not landed within113/// `ADD_WAIT_MS` is answered `recover=wait`. A save the secret scan refused114/// (`secret_detected`) goes again only with `force`, which records a115/// signed allowlist entry for each flagged string's hash, with `reason`116/// when given (cut to `GRANT_TERM_MAX_BYTES`), so the string is never flagged again for any author.117/// Refused `not_author` unless the caller is the save's author, and118/// `out_of_scope` or `grant_ended` while no grant lets it write the path;119/// an allowlist entry counts against its grant's change quota first120/// (discussion:owner/178). A refused `add` leaves the save held.121#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]122pub struct AddParams {123    pub path: String,124    #[serde(default, skip_serializing_if = "std::ops::Not::not")]125    pub force: bool,126    #[serde(default, skip_serializing_if = "Option::is_none")]127    pub reason: Option<String>,128}129130/// `add` result: whether a held save went through intake again, and the131/// heads of main's version holding the file as it is on disk (none for a132/// file that isn't on disk).133#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]134pub struct AddResult {135    #[serde(default)]136    pub resent: bool,137    #[serde(default, skip_serializing_if = "Option::is_none")]138    pub heads: Option<Vec<String>>,139}140141/// `move` (discussion:owner/434 and discussion:owner/457): one change to the project's namespace142/// moves the file at `from` to `to`, or the directory `from` with every143/// file under it to the same place under `to`, keeping each file's144/// history, blame, and anchors, since a file's text145/// document never changes; every tree renders it as a rename. It commits146/// at the namespace's live version, so it names no base: a move touches147/// no text, and so overlaps no edit. The grant must cover both paths. A148/// `from` naming nothing is refused `invalid_params`, and a `to` naming a149/// live file `path_collision`.150#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]151pub struct MoveParams {152    pub from: String,153    pub to: String,154}155156/// `move` result: the namespace's heads after it, stored when the answer157/// comes (discussion:owner/720).158#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]159pub struct MoveResult {160    pub heads: Vec<String>,161}162163/// `remove` (discussion:owner/434 and discussion:owner/457): delete the file, or the directory and164/// every file under it, at `address`, one change to the project's165/// namespace at its live version, as `move` is. The grant must cover the166/// path. Every tree removes the file.167#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]168pub struct RemoveParams {169    pub address: String,170}171172/// `remove` result: the namespace's heads after it, stored when the173/// answer comes (discussion:owner/720).174#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]175pub struct RemoveResult {176    pub heads: Vec<String>,177}178179/// `subscribe`: an exact address or a `**` prefix pattern.180#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]181pub struct SubscribeParams {182    pub pattern: String,183}184185/// `subscribe` result; pushes carry the same id. A subscription to one186/// file or document is answered with its current heads (`heads`, sorted;187/// discussion:owner/661: subscribe, then snapshot), absent for a pattern and188/// for a file not held yet. They are a read's heads, live189/// (discussion:owner/720): they may name a change not yet stored, which190/// is gone if its signature fails; only a write's answer (`edit`, `write`,191/// `move`, `remove`) names heads that are a durable base.192#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]193pub struct SubscribeResult {194    pub sub: u64,195    #[serde(default, skip_serializing_if = "Vec::is_empty")]196    pub heads: Vec<String>,197}198199/// Server push, JSON-RPC notification method `changed`. A protected path200/// (`lvcs.toml`, `.github/**`) also gets one, heads alone, once the working201/// tree wrote or removed the file on disk (discussion:owner/661). A read202/// and a push aren't ordered: a push waits for its change to be durable203/// (discussion:owner/669), so it can follow a `read` that already holds the204/// change. A client that applies `splices` to a read ignores a push whose205/// `heads` that read already holds; one that re-reads on a push needs206/// nothing.207#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]208pub struct ChangedPush {209    pub sub: u64,210    pub address: String,211    pub heads: Vec<String>,212    pub splices: Vec<SpliceParams>,213}214215/// Server push, JSON-RPC notification method `stale_save`: a tree save216/// was applied against an older disk base (discussion:owner/447), or, with217/// `refused`, refused (discussion:owner/777). Sent to every client218/// connected as the tree's author; clients show it until dismissed.219#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]220pub struct StaleSavePush {221    pub address: String,222    pub chosen_base: Vec<String>,223    pub newest_base: Vec<String>,224    pub heads: Vec<String>,225    /// The lines the save would have deleted, which its writer can't be226    /// shown to have seen and which stay in the file (discussion:owner/668).227    #[serde(default, skip_serializing_if = "Vec::is_empty")]228    pub kept: Vec<crate::lines::LineName>,229    /// The save was refused, not applied: the file keeps its bytes until230    /// they land (discussion:owner/777).231    #[serde(default, skip_serializing_if = "std::ops::Not::not")]232    pub refused: bool,233    /// The saver's own lines an applied save replaced or deleted, named as234    /// `replaced_at` showed them (ruling (A) on discussion:owner/782): `lvcs235    /// read --base <replaced_at> <address>` shows them.236    #[serde(default, skip_serializing_if = "Vec::is_empty")]237    pub replaced: Vec<crate::lines::LineName>,238    /// Main's heads before the save, where `replaced` is named.239    #[serde(default, skip_serializing_if = "Vec::is_empty")]240    pub replaced_at: Vec<String>,241}242243/// Server push, JSON-RPC notification method `write_held`: the tree244/// stopped writing a file because another program held it open past245/// `HELD_DEADLINE_MS` (Windows, the held-rename row refining246/// discussion:owner/252). Sent to every client connected as the tree's author, with the247/// `write_held` notification in its inbox.248#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]249pub struct WriteHeldPush {250    pub address: String,251    /// The heads of the version the tree could not write.252    pub heads: Vec<String>,253    /// Why, and how to recover: as [`StatusHeld`]'s.254    pub error: ErrorData,255}256257/// `snapshot`: main's visible frontier.258#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]259pub struct SnapshotParams {}260261/// `snapshot` result: the frontier id and its documents, as a JSON array of262/// `[address, heads]` pairs sorted by address.263#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]264pub struct SnapshotResult {265    pub frontier: String,266    pub docs: Vec<(String, Vec<String>)>,267}268269/// `frontier.read` (discussion:owner/518): the `file` documents of a frontier270/// and their heads, by path: main's visible frontier when `at` is omitted271/// or `main`, else the frontier a channel holds with that id (as `read`'s272/// `frontier` names one, or its unique start). `id` is the frontier's id273/// as discussion:owner/586 hashes it, the one channels and runs name. With274/// `entries`, the result's `entries` give each path's whole frontier275/// entry, which the id is the hash of. Local only.276#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]277pub struct FrontierReadParams {278    #[serde(default, skip_serializing_if = "Option::is_none")]279    pub at: Option<String>,280    #[serde(default, skip_serializing_if = "std::ops::Not::not")]281    pub entries: bool,282}283284/// `frontier.read` result.285#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]286pub struct FrontierReadResult {287    pub id: String,288    pub docs: std::collections::BTreeMap<String, Vec<String>>,289    #[serde(default, skip_serializing_if = "Option::is_none")]290    pub entries: Option<std::collections::BTreeMap<String, FrontierDoc>>,291}292293/// One path of a frontier, whole: the file there (its namespace node, a294/// change id) and its document's heads, each a change id with the Merkle295/// digest (`ID_ENCODING`) of the span it ends.296#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]297pub struct FrontierDoc {298    pub file: String,299    pub heads: Vec<FrontierHead>,300}301302/// A head with its digest.303#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]304pub struct FrontierHead {305    pub id: String,306    pub digest: String,307}308309/// `tree.materialize` (discussion:owner/518): write each `file` document of the310/// frontier `frontier` (named as `frontier.read`'s `at` is) whose path one311/// of `paths` matches (gitignore patterns), as it is at the frontier's312/// heads and with its executable bit, below `dir`, an absolute directory313/// under the project's `.lvcs/tmp/`, which it creates; a file already314/// there is replaced. A removed file is skipped. With `entries` (the315/// `frontier.read {entries}` shape), the frontier is the one they give,316/// whose id must be `frontier`, so a frontier main moved past and no317/// channel holds still materializes. Refused `invalid_params` for a `dir`318/// elsewhere, a pattern that doesn't parse, or entries of another id.319/// Local only.320#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]321pub struct TreeMaterializeParams {322    pub frontier: String,323    pub paths: Vec<String>,324    pub dir: String,325    #[serde(default, skip_serializing_if = "Option::is_none")]326    pub entries: Option<std::collections::BTreeMap<String, FrontierDoc>>,327}328329/// `protected.read` (discussion:owner/120, discussion:owner/479, and discussion:owner/518): each protected path330/// core's protected-path machines hold, with its approved heads (absent331/// before any approval) and its baseline (the heads it had when it became332/// protected, once known), change ids sorted; only those of `paths` when333/// named. With `at` (path to heads, discussion:owner/622), each named path334/// that a machine guards also answers `approved_at`: whether those heads335/// are an approved version of it (its approved heads, its baseline, heads336/// a gating approval named, or approved heads it held before; never an337/// ancestor alone). Local only.338#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]339pub struct ProtectedReadParams {340    #[serde(default, skip_serializing_if = "Vec::is_empty")]341    pub paths: Vec<String>,342    #[serde(default, skip_serializing_if = "std::collections::BTreeMap::is_empty")]343    pub at: std::collections::BTreeMap<String, Vec<String>>,344}345346/// `protected.read` result, by path.347#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]348pub struct ProtectedReadResult {349    pub paths: std::collections::BTreeMap<String, ProtectedHeads>,350}351352/// One protected path's approved heads and baseline.353#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]354pub struct ProtectedHeads {355    #[serde(default, skip_serializing_if = "Option::is_none")]356    pub approved: Option<Vec<String>>,357    #[serde(default, skip_serializing_if = "Option::is_none")]358    pub baseline: Option<Vec<String>>,359    #[serde(default, skip_serializing_if = "Option::is_none")]360    pub approved_at: Option<bool>,361}362363/// `doc.descends` (discussion:owner/518): whether the document at `address` (a364/// path or a document address) holds `from` in the history of `heads`:365/// `yes`, `no`, or `unknown` when either set is empty, names a change it366/// doesn't hold, or no document is there. Local only.367#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]368pub struct DocDescendsParams {369    pub address: String,370    pub heads: Vec<String>,371    pub from: Vec<String>,372    /// Wait for a document this node holds to bring either side's heads373    /// (discussion:owner/660), answering `unknown` only if none came374    /// within the wait.375    #[serde(default, skip_serializing_if = "std::ops::Not::not")]376    pub wait: bool,377}378379/// `doc.descends` result.380#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]381pub struct DocDescendsResult {382    pub outcome: DescendsOutcome,383}384385/// A `doc.descends` answer, a JSON string.386#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]387#[serde(rename_all = "snake_case")]388pub enum DescendsOutcome {389    Yes,390    No,391    Unknown,392}393394/// `tree.materialize` result: how many files it wrote, and their bytes.395#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]396pub struct TreeMaterializeResult {397    pub files: u64,398    pub bytes: u64,399}400401/// `files.list` (discussion:owner/312): main's `file` documents, under `prefix`402/// when named, sorted,403/// each with how many peers are present on it now. With `frontier` (discussion:owner/385), the404/// `file` documents that frontier holds instead, each with its heads405/// there; named as `read`'s `frontier` is.406#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]407pub struct FilesListParams {408    #[serde(default, skip_serializing_if = "Option::is_none")]409    pub prefix: Option<String>,410    #[serde(default, skip_serializing_if = "Option::is_none")]411    pub frontier: Option<String>,412}413414/// `files.list` result.415#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]416pub struct FilesListResult {417    #[serde(default)]418    pub files: Vec<FileEntry>,419}420421/// One file.422#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]423pub struct FileEntry {424    pub path: String,425    /// The peers present on it now.426    #[serde(default)]427    pub presence: u32,428    /// Its heads at the `frontier` the list named (change ids,429    /// `<peer:016x><counter:08x>`, as `read { heads }` takes them); absent430    /// without one.431    #[serde(default, skip_serializing_if = "Option::is_none")]432    pub heads: Option<Vec<String>>,433}434435/// `file.purge` (discussion:owner/614), the project owner's alone: purge436/// the documents of deleted files, each `targets` entry a path or a file437/// id. A path names every removed file whose last path is that path or438/// under it (a directory); a file id names one file. One signed caps439/// change records each file id with the purge's time, final: every honest440/// node that holds it drops the document's content and never serves,441/// syncs, or accepts it again, and refuses every read of it `rejected`442/// `purged`. Copies already made elsewhere are not recalled. Refused443/// `REJECTED` `out_of_scope` for any caller but the owner,444/// `INVALID_PARAMS` with `next: lvcs rm <path>` for a file still in the445/// tree, and `INVALID_PARAMS` for a target that names no removed file.446/// With `unplaced` (secfix/34), each target is the file id of a document447/// this node holds that the namespace never placed (one a set-aside448/// namespace change took its place from, which `lvcs audit` reports as449/// not placed); one that has or had a path is refused `INVALID_PARAMS`.450#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]451pub struct PurgeParams {452    pub targets: Vec<String>,453    #[serde(default, skip_serializing_if = "core::ops::Not::not")]454    pub unplaced: bool,455}456457/// `file.purge` result: each file this call purged, sorted by file id;458/// empty when every one named was purged already.459#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]460pub struct PurgeResult {461    #[serde(default)]462    pub purged: Vec<PurgedFile>,463}464465/// One purged file: its id (`<peer:016x><counter:08x>`) and the path it466/// had just before its newest removal, when the namespace knows one.467#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]468pub struct PurgedFile {469    pub file: String,470    #[serde(default, skip_serializing_if = "Option::is_none")]471    pub last_path: Option<String>,472}