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