docs/generated/contracts.mdgenerated from code

Reference · 4 min read

doc-read-at

Contracts: doc-read-at.

Source: crates/lvcs-doc/src/document/output.rs.

ruston main
1/// Read this document's body at `heads` (discussion:owner/434), with who changed it,2/// or a range of it (`within`), since. `req` is chosen by the daemon.3/// File documents take it. Answered with exactly one [`ReadAtDone`].4#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]5pub struct ReadAt {6    pub req: RequestId,7    #[serde(with = "crate::cbor::heads")]8    pub heads: Vec<ChangeId>,9    /// Limit the answer's `authors` to changes inside this range.10    pub within: Option<RangeAnchor>,11    /// Name the window from these heads to `heads` in the answer's12    /// `window` (discussion:owner/193): the changes in `heads`' history and not in13    /// these heads' history, an empty set naming every change up to14    /// `heads`. `None` for no window.15    #[serde(with = "crate::cbor::opt_heads")]16    pub since: Option<Vec<ChangeId>>,17    /// List the saves the answer's `saves` names (discussion:owner/399). `None`18    /// for none.19    #[serde(default)]20    pub saves: Option<SavesAsked>,21    /// Read the body, executable bit, and derived flag at `heads`'22    /// history less these cuts' changes ([`Cut`]), naming the heads read23    /// at in the answer's `cut`. Empty reads at `heads`.24    #[serde(default)]25    pub cuts: Vec<Cut>,26}2728/// The saves a [`ReadAt`] lists: at most `limit` of those in its `heads`'29/// history and not in `since`'s (discussion:owner/500's failing window), every30/// one up to `heads` when `since` is empty.31#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]32pub struct SavesAsked {33    pub limit: u32,34    #[serde(with = "crate::cbor::heads")]35    pub since: Vec<ChangeId>,36}3738/// Changes left out of a read (stophook/2): those `authors` made with a39/// signed commit time in `from_ms..=to_ms` (Unix milliseconds, whole40/// seconds), and every change that descends from one, whoever made it.41/// The time-0 imports are never left out.42#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]43pub struct Cut {44    pub authors: BTreeSet<PeerKey>,45    pub from_ms: i64,46    pub to_ms: i64,47}4849/// What a [`ReadAt`]'s cuts did: the heads `body`, `executable`, and50/// `derived` were read at, the greatest of `heads`' history less the51/// cuts' changes, and the authors of the changes left out.52#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]53pub struct CutDone {54    #[serde(with = "crate::cbor::heads")]55    pub heads: Vec<ChangeId>,56    pub authors: BTreeSet<PeerKey>,57}5859/// The earliest and latest signed commit times (Unix milliseconds, whole60/// seconds) of one author's changes.61#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]62pub struct TimeSpan {63    pub first_ms: i64,64    pub last_ms: i64,65}6667/// The answer to a [`ReadAt`].68#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]69pub struct ReadAtDone {70    pub req: RequestId,71    pub outcome: ReadAtOutcome,72}7374/// One save of a file document (discussion:owner/399): a change in its history75/// that touched `content` (named by its last op, the version right after76/// it), its record's signer, its signed commit time in Unix milliseconds77/// (whole seconds), and the lines of the file as it was right after it78/// that it touched, named as `window` names them.79#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]80pub struct SaveMeta {81    #[serde(with = "crate::cbor::hash")]82    pub hash: ChangeId,83    pub author: Option<PeerKey>,84    pub time_ms: i64,85    pub lines: Vec<LineName>,86}8788/// What a [`ReadAt`] found.89#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]90pub enum ReadAtOutcome {91    /// The file at `heads`, and the signers (each change's record's) of92    /// the changes the document holds beyond `heads`, its own unsigned93    /// changes included; with `within`, only those that inserted a94    /// character inside its range or deleted one of its characters (a95    /// character is inside when it lies between the anchor's first and last96    /// characters, discussion:owner/83; the range's characters are those visible97    /// inside it at the anchor's heads and those inserted inside it since).98    /// `window`, with `since`, maps the signer of each change in the window99    /// to the lines of `body` it touched (discussion:owner/193): those holding a100    /// character it inserted that is visible at `heads`, and the line where101    /// a character it deleted was, as `lines::names` names them, without102    /// `near`; a binary body names no lines. It is empty without `since`.103    /// `derived` is `meta.derived` at `heads` (row 180). `head_authors` are104    /// the signers of the document's head changes beyond `heads`, those no105    /// later change depends on (discussion:owner/314). `saves`, with106    /// `ReadAt::saves`, are the newest saves in `heads`' history, newest107    /// first ([`SaveMeta`], discussion:owner/399); empty without it. `spans` are108    /// each signer's earliest and latest signed times among every change109    /// beyond `heads`, `within` or not, the time-0 imports left out, for110    /// the gate's windows (stophook/2). `cut`, with `ReadAt::cuts`, is what111    /// the cuts did ([`CutDone`]).112    Read {113        body: FileBody,114        executable: bool,115        derived: bool,116        authors: BTreeSet<PeerKey>,117        window: BTreeMap<PeerKey, Vec<LineName>>,118        head_authors: BTreeSet<PeerKey>,119        #[serde(default)]120        saves: Vec<SaveMeta>,121        #[serde(default)]122        spans: BTreeMap<PeerKey, TimeSpan>,123        #[serde(default)]124        cut: Option<Box<CutDone>>,125    },126    /// `UnknownBase` when the document lacks `heads`, `since`, or127    /// `within`'s heads;128    /// `Failed` when `within` names characters not visible, in order, at129    /// its heads, or the document faulted answering or was closed.130    Refused(RejectReason),131}