docs/generated/contracts.mdgenerated from code

Reference · 3 min read

grants

Contracts: grants.

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

ruston main
1/// Which bucket a token comes from (discussion:owner/146).2#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]3pub enum Bucket {4    /// Gossip messages a signer may have forwarded or published.5    Gossip,6    /// Changes the daemon signs for a peer key.7    Sign,8}910/// What a bucket refills at (discussion:owner/146): `per_sec` tokens11/// a second, holding at most `burst` (and always room for one, so a burst12/// of 0 still lets the rate through).13#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]14pub struct Rate {15    /// Tokens added a second.16    pub per_sec: u32,17    /// The most tokens the bucket holds.18    pub burst: u32,19}2021/// What a take is for, echoed by [`SignerOutput::Taken`].22#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]23pub enum TakeKey {24    /// The daemon's id of the request about to be committed.25    Sign(u64),26    /// A question an asker awaits (discussion:owner/439): the signer's executor27    /// answers it straight to the asker, by this id.28    Asked(u64),29}3031/// The limits in force (discussion:owner/146).32///33/// They are the limit constants in `docs/generated/vocabulary.md` by34/// default ([`Limits::DEFAULT`]), each replaced by its key in protected35/// `lvcs.toml` `[limits]` (the daemon's `LvcsToml`; a missing key keeps its36/// default), so a peer can't change them by editing the file. The37/// field names are the `[limits]` keys (the constants' names in lower38/// case). They are the defaults for every signer, the owner included: each39/// signer's [`Rate`] comes from them ([`Limits::sign_rate`],40/// [`Limits::gossip_rate`]), each per-second rate and the signing burst41/// replaced by the signer's grant terms where they name one (discussion:owner/146),42/// and the gossip machine sizes its memory and tolerance by `gossip_burst`. A43/// change quota is never a limit: a grant's terms carry it (discussion:owner/70).44/// Owner: `M3.grants`.45#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]46#[serde(default)]47pub struct Limits {48    /// `PEER_SIGN_PER_SEC` in force.49    pub peer_sign_per_sec: u32,50    /// `PEER_SIGN_BURST` in force.51    pub peer_sign_burst: u32,52    /// `PEER_GOSSIP_PER_SEC` in force.53    pub peer_gossip_per_sec: u32,54    /// `GOSSIP_BURST` in force.55    pub gossip_burst: u32,56}5758impl Limits {59    /// The protocol defaults.60    pub const DEFAULT: Self = Self {61        peer_sign_per_sec: PEER_SIGN_PER_SEC,62        peer_sign_burst: PEER_SIGN_BURST,63        peer_gossip_per_sec: PEER_GOSSIP_PER_SEC,64        gossip_burst: GOSSIP_BURST,65    };6667    /// The default signing rate: `peer_sign_per_sec`, holding68    /// `peer_sign_burst`.69    #[must_use]70    pub const fn sign_rate(&self) -> Rate {71        Rate {72            per_sec: self.peer_sign_per_sec,73            burst: self.peer_sign_burst,74        }75    }7677    /// The default gossip rate: `peer_gossip_per_sec`, holding78    /// `gossip_burst`.79    #[must_use]80    pub const fn gossip_rate(&self) -> Rate {81        Rate {82            per_sec: self.peer_gossip_per_sec,83            burst: self.gossip_burst,84        }85    }86}8788impl Default for Limits {89    fn default() -> Self {90        Self::DEFAULT91    }92}9394/// A signer machine's events, generated by its sml table: its dispatch95/// and journal type (discussion:owner/286 and discussion:owner/341). Owner: `M3.grants`.96///97/// Its events, each the payload type its variant is named for:98/// [`TakeToken`] and [`RefillToken`].99pub use machine::{MeteringEvents, RefillToken, TakeToken};100101/// Outputs of a signer machine. Owner: `M3.grants`.102#[derive(Debug, Clone, PartialEq, Eq)]103pub enum SignerOutput {104    /// The answer to a [`MeteringEvents::TakeToken`]. When `allowed` is false,105    /// `retry_after_ms` is how long until the bucket holds a token, at106    /// most one hour (3 600 000, for a bucket whose rate is 0 and so never107    /// refills; discussion:owner/109): for a gossip take the message is dropped (`rejection` = `rate_limited`),108    /// and for a sign take the daemon answers the request `rate_limited`109    /// with it, uncommitted. A waiting take is never refused: it is110    /// answered allowed, with `retry_after_ms` 0, once its bucket holds a111    /// token.112    Taken {113        /// The take answered.114        key: TakeKey,115        /// Whether a token was taken.116        allowed: bool,117        /// How long until the bucket holds a token, when refused.118        retry_after_ms: u64,119    },120    /// Send this machine [`MeteringEvents::RefillToken`] for the kept take121    /// `key` at `at_ms`, when its bucket should hold a token (at most one122    /// hour on, for a bucket whose rate is 0): the machine's own executor's123    /// timer.124    Wake {125        /// The kept take.126        key: TakeKey,127        /// When, by the daemon's clock.128        at_ms: i64,129    },130}