docs/generated/contracts.mdgenerated from code
Reference · 10 min read
wire-payloads
Contracts: wire-payloads.
Read as
Source: crates/lvcs-net/src/wire/mod.rs.
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}