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