docs/generated/contracts.mdgenerated from code

Reference · 10 min read

wire-payloads

Contracts: wire-payloads.

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

ruston main
1/// A peer that signs gossip messages, by its Ed25519 public key (the2/// bytes of an `lvcs_doc::PeerKey`; `Sender::Peer`).3///4/// The net actors' per-signer state (capabilities, token buckets) keys on5/// it. Journaled as a byte string. Owner: `M3.envelope`.6#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]7pub struct Signer(#[serde(with = "cbor::fixed")] pub [u8; 32]);89/// Payload of kind `sync` (discussion:owner/30 and discussion:owner/68; lane `M3.sync`).10///11/// It is one document's sync message on the one sync stream of a node pair.12/// `doc` is the document address the message is tagged with; `payload` is13/// what that document's actor emitted (`DocOutput::SyncOut`), handed14/// unchanged to the receiving node's actor for `doc` (`DocEvent::SyncIn`).15/// The envelope's sender is the sending device.16#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]17pub struct SyncFrame {18    /// The document address the message is tagged with.19    pub doc: String,20    /// What that document's actor emitted (`DocOutput::SyncOut`), opaque21    /// here.22    #[serde(with = "cbor::bytes")]23    pub payload: Vec<u8>,24}2526/// Payload of kind `inventory` (wire minor 1; refines discussion:owner/215).27///28/// Sent on the sync stream each time the sender's caps round with the29/// receiver settles: how many documents the sender syncs with the receiver30/// then, the caps document among them, which are every document it joined31/// with the receiver. A count, not a list, so it stays far under32/// `WIRE_MAX_BYTES` at any project size. A join waits until that many33/// distinct documents arrived from one connected node. The envelope's34/// sender is the sending device.35///36/// It also names the peer keys the sender's daemon holds for the37/// project (discussion:owner/314), at most `INVENTORY_HOLDERS_MAX`, each with its38/// signature over [`holder_input`], and the sender's machine name, at most39/// `HOST_NAME_MAX_BYTES`, so `node.list` names who and what each node is.40/// The receiver checks each signature; the name is the sender's own say.41#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]42pub struct SyncInventory {43    /// How many documents the sender syncs with the receiver, or44    /// [`INVENTORY_UNDECIDED`] while the sender hasn't decided the45    /// receiver's admission (orchestrator/26). A count is never 0, since46    /// `.lvcs/caps` always syncs, and an older receiver reads 0 as a node47    /// that owes nothing, as it read the caps-only count before.48    pub docs: u64,49    /// The peer keys the sender's daemon holds, each signed.50    pub holders: Vec<Holder>,51    /// The sender's machine name, if it has one.52    pub host: Option<String>,53}5455/// The [`SyncInventory::docs`] of a sender that hasn't decided the56/// receiver's admission yet (orchestrator/26): it needs the receiver's57/// holders, which only the receiver's own inventory names, so the count58/// follows in its next inventory, once decided.59pub const INVENTORY_UNDECIDED: u64 = 0;6061impl SyncInventory {62    /// How many documents the sender syncs with the receiver, `None`63    /// while it hasn't decided the receiver's admission.64    #[must_use]65    pub const fn count(&self) -> Option<u64> {66        if self.docs == INVENTORY_UNDECIDED {67            None68        } else {69            Some(self.docs)70        }71    }72}7374/// Payload of kind `incarnation` (discussion:owner/576): the sender's daemon75/// run, the same across its streams with the receiver until it restarts,76/// sent on the sync stream just before each inventory. Older nodes ignore77/// the kind.78#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]79pub struct SyncIncarnation {80    /// The run, its start time by the sender's clock.81    pub incarnation: u64,82}8384/// Payload of kind `heads` (discussion:owner/637): every document the85/// sender holds, each with the digest of its stored heads86/// ([`heads_digest`]), sent once as each sync stream opens. A receiver87/// holding a document under the same digest joins it only when it runs.88/// Older nodes ignore the kind.89#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]90pub struct SyncHeads {91    /// The documents, each with its heads digest.92    pub docs: Vec<DocHeads>,93}9495/// One document of a [`SyncHeads`].96#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]97pub struct DocHeads {98    /// The document's address.99    pub doc: String,100    /// The digest of its stored heads ([`heads_digest`]).101    #[serde(with = "cbor::fixed")]102    pub digest: [u8; 32],103}104105/// The digest a [`SyncHeads`] names a document's heads by106/// (discussion:owner/637): SHA-256 over the heads, each as its peer (u64)107/// then its counter (i32), big-endian, sorted by (peer, counter).108#[must_use]109pub fn heads_digest(heads: &[(u64, i32)]) -> [u8; 32] {110    use sha2::Digest as _;111    let mut sorted = heads.to_vec();112    sorted.sort_unstable();113    let mut hasher = sha2::Sha256::new();114    for (peer, counter) in sorted {115        hasher.update(peer.to_be_bytes());116        hasher.update(counter.to_be_bytes());117    }118    hasher.finalize().into()119}120121/// A peer key a daemon holds, with the peer's signature122/// over [`holder_input`] of the project and the daemon's device key123/// (discussion:owner/314).124#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]125pub struct Holder {126    /// The peer's public key.127    #[serde(with = "cbor::fixed")]128    pub key: [u8; 32],129    /// Its Ed25519 signature over [`holder_input`].130    #[serde(with = "cbor::fixed")]131    pub sig: [u8; 64],132}133134/// What a [`Holder`]'s signature covers: a domain tag, the project id, and135/// the holding daemon's device key, so a holder line is bound to one136/// project and one device.137#[must_use]138pub fn holder_input(project: &[u8; 32], device: &[u8; 32]) -> Vec<u8> {139    let mut input = b"lvcs holder v1\0".to_vec();140    input.extend_from_slice(project);141    input.extend_from_slice(device);142    input143}144145/// What a notification says the sender will do to its range (discussion:owner/165).146/// Encoded as `adding`, `changing`, or `removing`.147#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Serialize, Deserialize)]148#[serde(rename_all = "snake_case")]149pub enum NotifyOp {150    /// The sender will add to the range.151    Adding,152    /// The sender will change the range.153    Changing,154    /// The sender will remove the range.155    Removing,156}157158/// Payload of kind `notification` (discussion:owner/20 and discussion:owner/51; lane159/// `M3.coord`).160///161/// It is `{ doc, range, op, what, ref?, by, ts, auto }`,162/// published on the document's topic and every ancestor directory's topic.163/// `range` is the canonical CBOR encoding of the `lvcs_doc::RangeAnchor`164/// cursor pair the notifier's document anchored (`DocEvent::Anchor`),165/// opaque here: the receiving daemon resolves it against its own copy of166/// `doc` (the coord actor sees only resolved spans). An empty `range` is a whole-document167/// notification (`AnchorOutcome::Whole`: an empty document has no character168/// to anchor on), whose span is `coord::Span::WHOLE` (chosen at the M3169/// freeze). `ref` optionally names more detail (`kad://<key>` or170/// `lvcs://<doc>#<pointer>`). `by` is the notifying peer's key bytes171/// and must equal the envelope's `Sender::Peer`; `ts` is its Unix172/// time in milliseconds, which orders notifications: by `ts`, then `by`,173/// then the notification id (see `coord`). `auto` is true for a notification the daemon made from its author's174/// save through a tree (discussion:owner/155 and discussion:owner/165), false for one a client175/// sent (`announce`, `intent`). A notification's id is the `HASH` of this176/// payload's canonical CBOR encoding (`coord::NotificationId::of`), so the177/// id and the signature cover `auto`.178#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]179pub struct Notification {180    /// The document notified about.181    pub doc: String,182    /// The canonical CBOR encoding of the anchored `lvcs_doc::RangeAnchor`183    /// cursor pair; empty for the whole document.184    #[serde(with = "cbor::bytes")]185    pub range: Vec<u8>,186    /// What the sender will do to the range.187    pub op: NotifyOp,188    /// What the change is, in the sender's words.189    pub what: String,190    /// Where more detail is (`kad://<key>` or `lvcs://<doc>#<pointer>`),191    /// under the key `ref`.192    #[serde(rename = "ref")]193    pub reference: Option<String>,194    /// The notifying peer's key bytes.195    #[serde(with = "cbor::fixed")]196    pub by: [u8; 32],197    /// The notifier's Unix time in milliseconds.198    pub ts: i64,199    /// Whether the daemon made it from its author's save through a tree,200    /// not a client.201    pub auto: bool,202}203204/// Payload of kind `event` (discussion:owner/515): an ephemeral event, never205/// stored. `by` signs it: the author, or the key of the plugin `via` names206/// when it publishes for the user `author`. `doc` is the event's `about`207/// address, whose topics it is published on; `ts` its signed time in Unix208/// milliseconds. `event` is the event itself (`lvcs_api::events::Event`)209/// as JSON, opaque here: the receiving daemon checks it as it checks one210/// published to it.211#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]212pub struct EventNotice {213    /// The signing peer's key bytes.214    #[serde(with = "cbor::fixed")]215    pub by: [u8; 32],216    /// The event's author's key bytes.217    #[serde(with = "cbor::fixed")]218    pub author: [u8; 32],219    /// The plugin it came through, when `by` is a plugin's key.220    pub via: Option<String>,221    /// The event's `about` address.222    pub doc: String,223    /// The signed time, in Unix milliseconds.224    pub ts: i64,225    /// The event, as JSON.226    #[serde(with = "cbor::bytes")]227    pub event: Vec<u8>,228}229230/// Payload of kind `presence` (discussion:owner/513; lane `M3.coord`).231///232/// It says `by` is on the document `doc`, as of `ts` (Unix milliseconds), and counts as present there until233/// `PRESENCE_TTL_SECS` after it. Never stored.234#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]235pub struct Presence {236    /// The document `by` is on, if any.237    pub doc: Option<String>,238    /// The present peer's key bytes.239    #[serde(with = "cbor::fixed")]240    pub by: [u8; 32],241    /// The Unix time in milliseconds `by` is present as of.242    pub ts: i64,243}244245/// Payload of kind `run` (discussion:owner/303): runner `by`'s run of action246/// `action` of the channel whose document is `doc`, on the frontier247/// `frontier`, is in state `state` (a `run_state` value) as of `ts`. It248/// was taken at `started` and ended at `ended` (Unix milliseconds by the249/// runner's clock). Published on the channel document's topics and250/// accepted only under `Attest` of that channel, as a runner's presence251/// is (discussion:owner/206). Never stored but in the receiver's runs actor.252#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]253pub struct RunNotice {254    /// The channel document's address.255    pub doc: String,256    /// The action's name.257    pub action: String,258    /// The action's id, which a receiver checks is one of the channel's259    /// actions under its approved `lvcs.toml`.260    #[serde(with = "cbor::fixed")]261    pub id: [u8; 32],262    /// The frontier's id.263    #[serde(with = "cbor::fixed")]264    pub frontier: [u8; 32],265    /// A `run_state` value.266    pub state: String,267    /// When the runner took the run.268    pub started: i64,269    /// When it ended, for an ended state.270    pub ended: Option<i64>,271    /// The runner's peer key bytes.272    #[serde(with = "cbor::fixed")]273    pub by: [u8; 32],274    /// The Unix time in milliseconds the notice is as of.275    pub ts: i64,276}277278/// Payload of kinds `action_failed` and `action_succeeded` (discussion:owner/193).279///280/// A runner `by` tells `to`, an author of the failing window, that the281/// action `check` failed at the frontier `failed_at` after it last passed at282/// `passed_at` (absent when it never passed on the channel, so the window283/// starts at its genesis), or, as `action_succeeded`, that it passes again,284/// which ends that failing streak. It is published on `to`'s inbox topic.285/// `paths` are the documents the action's `paths` or `uses` match that `to`286/// changed in the window, each with the line runs of its changes at287/// `failed_at`; `others` are the window's other authors. `tail` is the288/// failing output's last `CHECK_OUTPUT_TAIL_BYTES` and `tests` the failing289/// test names read from it, both empty for `action_succeeded`; `log` names290/// the action's log document for `action_failed`, and `unmatched` says291/// nothing under `paths` moved in the window (discussion:owner/500). `by` must292/// equal the envelope's `Sender::Peer`, which must hold `attest`293/// on a channel; `ts` is its Unix time in milliseconds. Owner:294/// discussion:owner/193.295#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]296pub struct CheckNotice {297    /// The check's id.298    #[serde(with = "cbor::fixed")]299    pub check: [u8; 32],300    /// The id of the frontier where it last passed, if it ever did.301    #[serde(with = "cbor::opt_fixed")]302    pub passed_at: Option<[u8; 32]>,303    /// The id of the frontier where it failed.304    #[serde(with = "cbor::fixed")]305    pub failed_at: [u8; 32],306    /// The author told.307    #[serde(with = "cbor::fixed")]308    pub to: [u8; 32],309    /// What `to` changed in the window that the check reads.310    pub paths: Vec<CheckPath>,311    /// The window's other authors.312    pub others: Vec<Signer>,313    /// The failing output's tail.314    pub tail: String,315    /// The failing test names read from the tail.316    pub tests: Vec<String>,317    /// The address of the action's log document (`LOG_PREFIX` and its318    /// channel, discussion:owner/500) for an `action_failed`; `None` for an319    /// `action_succeeded`.320    pub log: Option<String>,321    /// Whether `to` is told because nothing under the action's `paths` or322    /// `uses` moved in the window: it changed some other file there, or,323    /// with no author in the window at all, it is the owner (discussion:owner/500).324    pub unmatched: bool,325    /// The runner's peer key bytes.326    #[serde(with = "cbor::fixed")]327    pub by: [u8; 32],328    /// The runner's Unix time in milliseconds.329    pub ts: i64,330}331332/// One document a [`CheckNotice`]'s recipient changed in the window: its333/// path and the line runs of its changes, 1-based and inclusive, at the334/// failing frontier (none for a binary or deleted file).335#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]336pub struct CheckPath {337    /// The document's path.338    pub path: String,339    /// The line runs.340    pub lines: Vec<CheckLines>,341}342343/// One run of lines of a [`CheckPath`]: `first` to `last`, 1-based and344/// inclusive.345#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]346pub struct CheckLines {347    /// The run's first line.348    pub first: u64,349    /// Its last line.350    pub last: u64,351}