docs/generated/contracts.mdgenerated from code

Reference · 6 min read

gossip

Contracts: gossip.

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

ruston main
1/// What the gossip actor knows of a signer that holds a live `Message`2/// grant, a live grant to attest a channel, or a live grant to3/// attest an action channel (discussion:owner/111, discussion:owner/146,4/// 203, and 206).5///6/// It is `gossip`, the rate its gossip bucket refills at, and the windows7/// of the three kinds of grant that admit gossip: `message`, from its8/// `Message` grants, admits every kind but `action_failed` and9/// `action_succeeded`; `attest`, from its grants to attest a channel,10/// admits those two only (discussion:owner/203); and `channels`, from its grants11/// to attest a gated action's channel, one window per such channel's document12/// address, each admitting `presence` only, and only when the presence's13/// `doc` is that address (discussion:owner/206). `message` and `attest` are `None`14/// and `channels` empty when the signer holds no such grant. The daemon15/// shell derives it from the `.lvcs/caps` document's render16/// (`lvcs_doc::CapsRendered`): every signer that holds any of them there,17/// the owner included with `message` and `attest`, so `lvcs-net` never18/// names a grant (chosen at the M3 freeze). Every signer's `gossip` is the19/// limits in force's ([`Limits::gossip_rate`]), its per-second rate20/// replaced by the signer's grant terms where they name one (21/// discussion:owner/146), so its `burst` is always `gossip_burst`, the capacity the gossip22/// actor sizes its memory and tolerance by. The gossip actor drops a23/// message whose signer is not in the table, whose kind its windows don't24/// admit, or whose kind's window has ended by the shell's clock, before25/// forwarding it; whether a grant's paths cover the message's document is26/// checked only before delivery ([`GossipOutput::Deliver`]). Owner:27/// `M3.gossip`.28#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]29pub struct SignerCap {30    /// The rate the signer's gossip bucket refills at.31    pub gossip: Rate,32    /// The window of its `Message` grants, which admits every kind but33    /// the action notifications; `None` when it holds none.34    pub message: Option<Window>,35    /// The window of its grants to attest a channel, which admits36    /// `action_failed` and `action_succeeded` only; `None` when it holds none.37    pub attest: Option<Window>,38    /// The window of its grants to attest each action channel, by39    /// that channel document's address, each admitting `presence` about40    /// that document only; empty when it holds none.41    pub channels: BTreeMap<String, Window>,42    /// The window of any live grant of its, which admits an `event`43    /// (discussion:owner/515); `None` when it holds none.44    #[serde(default)]45    pub any: Option<Window>,46}4748/// How long a kind of grant admits a signer's gossip ([`SignerCap`]).49#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]50pub struct Window {51    /// The end of the latest window among those grants, in Unix seconds;52    /// `None` for a grant with no expiry.53    pub until_s: Option<i64>,54}5556/// The gossip actor's events, generated by its sml table: its dispatch57/// and journal type (discussion:owner/286 and discussion:owner/341). Time enters only as event data. Owner:58/// `M3.gossip`.59///60/// Its events, each the payload type its variant is named for: [`JoinTopic`],61/// [`LeaveTopic`], [`PublishEnvelope`], [`ReceiveMessage`],62/// [`AdmissionAnswer`], [`ReplaceSigners`], [`NodeUp`], [`NodeGone`],63/// [`RemoteSubscribed`],64/// [`SyncFault`], [`SetLimits`].65pub use machine::{66    AdmissionAnswer, GossipingEvents, HoldDelivery, JoinTopic, LeaveTopic, NodeGone, NodeUp,67    PublishEnvelope, ReceiveMessage, RemoteSubscribed, ReplaceSigners, SetLimits, SyncFault,68};6970/// The answer to the take of [`GossipOutput::Admit`]. Owner: `M3.gossip`.71#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]72pub enum Admission {73    /// The signer's bucket had a token (`GrantsOutput::Taken` with74    /// `allowed`): accepted.75    Admitted,76    /// The signer's bucket was empty: ignored `rate_limited`.77    RateLimited,78}7980/// Outputs of the gossip actor, which the daemon shell carries out.81/// Owner: `M3.gossip`.82#[derive(Debug, Clone, PartialEq, Eq)]83pub enum GossipOutput {84    /// Join a topic (`TransportCommand::Subscribe`).85    Subscribe {86        /// The topic to join.87        topic: String,88    },89    /// Leave a topic (`TransportCommand::Unsubscribe`).90    Unsubscribe {91        /// The topic to leave.92        topic: String,93    },94    /// Publish `data` on `topic` (`TransportCommand::Publish`).95    Publish {96        /// The topic to publish on.97        topic: String,98        /// The encoded envelope.99        data: Vec<u8>,100    },101    /// Admit the message `id`, which passed every other check (102    /// discussion:owner/111 and discussion:owner/439): its executor asks `signer`'s machine for a token from its103    /// gossip bucket at `rate`, the signer table's, at `now_ms`, and104    /// answers with exactly one [`GossipingEvents::AdmissionAnswer`].105    Admit {106        /// The message's id.107        id: Vec<u8>,108        /// Its signer.109        signer: Signer,110        /// The signer's gossip rate, from the signer table.111        rate: Rate,112        /// The shell's clock when the message was received, in Unix113        /// milliseconds.114        now_ms: i64,115    },116    /// Report the validation of the message `id`117    /// (`TransportCommand::Validate`); `reason` is set for a rejected or118    /// ignored message, for the span's `rejection` attribute.119    Validate {120        /// The message's id.121        id: Vec<u8>,122        /// The node that forwarded it.123        propagation: Node,124        /// The verdict.125        acceptance: Acceptance,126        /// Why it was rejected or ignored; `None` when accepted.127        reason: Option<Rejection>,128    },129    /// An accepted message for this daemon (discussion:owner/111). `address` is the130    /// path of the document the message is about: a notification's or131    /// presence's `doc`, without its `#pointer`; `None` for presence on no132    /// document and for a check notice. Before it delivers the message to133    /// local clients, the shell checks its scope (discussion:owner/111): the134    /// subject document is `address`; `lvcs_doc::authorize`, with the caps135    /// render's grants, must accept `signer` doing the `message` verb on136    /// the subject document at the shell's clock in whole Unix seconds137    /// (rounded down) under one of its grants. An envelope names no grant,138    /// so the shell tries the owner's `GrantId::OWNER` and every grant whose139    /// grantee is `signer`. Out of scope, the message is dropped140    /// with `rejection` = `out_of_scope`; presence on no document has no141    /// subject document and needs no scope. In scope, the shell routes it by142    /// `kind`: `notification` and `presence` go to coordination, a check143    /// notice to the inbox, and a run notice to the runs. `payload` is the144    /// envelope's payload.145    Deliver {146        /// The topic it came on.147        topic: String,148        /// The envelope's kind.149        kind: WireKind,150        /// Its signer.151        signer: Signer,152        /// The path of the document it is about, if any.153        address: Option<String>,154        /// The envelope's payload.155        payload: Vec<u8>,156        /// The sender's trace context, carried as it is (discussion:owner/441).157        trace: Option<Traceparent>,158        /// The caps renders the machine had taken when it sent this, which159        /// [`GossipingEvents::HoldDelivery`] gives back.160        renders: u64,161        /// When it was first held, in Unix milliseconds, if it was.162        held_since: Option<i64>,163    },164    /// These messages, held for a caps render, pass the checks under the165    /// render just taken: each goes back on the machine's own queue166    /// (discussion:owner/653, rule 2).167    Recheck {168        /// The messages, oldest first.169        messages: Vec<ReceiveMessage>,170    },171    /// A delivery of `kind` held for a caps render is given up: too many172    /// were held, or no render admitted it in time. Reported `out_of_scope`.173    Dropped {174        /// Its kind.175        kind: WireKind,176    },177    /// Lower the forwarding device's score after a repeat offense (178    /// discussion:owner/111; `TransportCommand::Penalize`).179    Penalize {180        /// The forwarding node.181        node: Node,182        /// The offense.183        reason: Rejection,184    },185    /// The last connection of a node penalized since its first closed:186    /// reset its score (`TransportCommand::Pardon`, fleetroll/1).187    Pardon {188        /// The node.189        node: Node,190    },191}