docs/generated/contracts.mdgenerated from code

Reference · 4 min read

coord

Contracts: coord.

Source: crates/lvcs-net/src/coord/mod.rs.

ruston main
1/// A notification's id.2///3/// It is the `HASH` of its [`Notification`] payload's canonical CBOR4/// encoding ([`NotificationId::of`]), written in `ID_ENCODING` on the API;5/// the last key of a notification's [`Order`]. Owner: `M3.coord`.6#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]7pub struct NotificationId(#[serde(with = "crate::wire::cbor::fixed")] pub [u8; 32]);89/// A notification's range resolved by this daemon's document actor10/// (`DocEvent::Resolve`) to code points of the document's text at its11/// current heads.12///13/// The cursor pair itself is opaque to `lvcs-net`. A whole-document14/// notification (an empty `Notification::range`) has the span15/// [`Span::WHOLE`], `0..usize::MAX`, which meets every span, so it needs16/// no resolution. A span meets another when they overlap or touch (one17/// ends where the other starts): a save is announced again only when no18/// current notification of its author meets its span. Owner: `M3.coord`.19#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]20pub struct Span {21    /// Where the span starts, in code points (inclusive).22    pub start: usize,23    /// Where the span ends, in code points (exclusive).24    pub end: usize,25}2627/// One head of a document: a Loro change id (its peer and counter),28/// opaque to `lvcs-net` (history row 457). Owner: `M3.coord`.29#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]30pub struct Head {31    /// The change's Loro peer.32    pub peer: u64,33    /// Its counter.34    pub counter: i32,35}3637/// A committed save of a document through a main tree, by the tree's38/// author, which holds the message capability on it (discussion:owner/165).39///40/// `range` is the canonical CBOR encoding of the anchor the save's touched41/// lines were anchored to at `heads` (empty for a whole document, a42/// removal, or a binary save, whose span is [`Span::WHOLE`]), opaque here43/// like [`Notification::range`]; `span` is that range resolved at `heads`.44/// `op` and `what` are what the notification says. Owner: `M3.coord`.45#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]46pub struct Saved {47    /// The document saved.48    pub doc: String,49    /// The saving peer's key bytes: the tree's author.50    #[serde(with = "crate::wire::cbor::fixed")]51    pub by: [u8; 32],52    /// The canonical CBOR encoding of the touched lines' anchor; empty for53    /// the whole document.54    #[serde(with = "crate::wire::cbor::bytes")]55    pub range: Vec<u8>,56    /// The touched lines resolved at `heads`.57    pub span: Span,58    /// The document's heads after the save.59    pub heads: Vec<Head>,60    /// What the save did to the range.61    pub op: NotifyOp,62    /// What the save is, in generated plain text.63    pub what: String,64    /// The lines its render named, opaque here (the daemon's encoding);65    /// `None` when it has no range.66    pub lines: Option<Vec<u8>>,67}6869/// A notification's place in the order notifications are kept in (discussion:owner/107): `ts`, then70/// `by`, then the id, all taken from the signed payload, so every node71/// orders a pair alike. Owner: `M3.coord`.72#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]73pub struct Order {74    /// The notification's signed `ts`.75    pub ts: i64,76    /// Its notifier.77    pub by: Signer,78    /// Its id.79    pub id: NotificationId,80}8182/// The effects of the board machine that the daemon carries83/// out. Owner: `M3.coord`.84#[derive(Debug, Clone, PartialEq, Eq)]85pub enum CoordOutput {86    /// Seal `notification` with its peer's key and publish it on87    /// the document's topic and every ancestor directory's topic.88    Publish(Notification),89    /// Publish a local peer's presence on its document's topic and90    /// every ancestor directory's topic, with a token from the91    /// peer's gossip bucket: its first local presence on the92    /// document while its board keeps it, then one at least a third of93    /// `PRESENCE_TTL_SECS` after the last one published, so other daemons94    /// count it present without a gap.95    PublishPresence(Presence),96    /// Push a received notification to this daemon's clients.97    Announce {98        /// The notification's id.99        id: NotificationId,100        /// The notification.101        notification: Notification,102    },103    /// Seal `notification`, an automatic announcement of a local save104    /// (`auto` true), with its peer's key and publish it like105    /// [`CoordOutput::Publish`], with a token from the peer's gossip106    /// bucket, since no request took one. `span` is its range resolved at107    /// `heads`, the save's heads.108    AutoPublish {109        /// The automatic notification.110        notification: Notification,111        /// Its range resolved at `heads`.112        span: Span,113        /// The document's heads after the save.114        heads: Vec<Head>,115        /// The save's lines, opaque, when its span is not the whole116        /// document.117        lines: Option<Vec<u8>>,118    },119}