docs/generated/contracts.mdgenerated from code

Reference · 5 min read

api-nodes

Contracts: api-nodes.

Source: crates/lvcs-api/src/nodes.rs.

ruston main
1/// `node.list` (discussion:owner/303): the nodes this project's swarm is2/// connected to now.3#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]4pub struct NodeListParams {}56/// `node.list` result, sorted by node.7#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]8pub struct NodeListResult {9    #[serde(default)]10    pub nodes: Vec<NodeEntry>,11    /// The answering daemon's own node (discussion:owner/487), which `nodes` leaves12    /// out: `node.load` takes its id. Absent where the daemon doesn't tell,13    /// and to an anonymous reader unless `public_machines`.14    #[serde(default, skip_serializing_if = "Option::is_none")]15    pub own: Option<NodeEntry>,16    /// Whether `lvcs.toml`'s `[public] machines` lets an anonymous reader17    /// read `node.load` here (discussion:owner/487), and this node's operator18    /// allows it.19    #[serde(default)]20    pub public_machines: bool,21}2223/// One connected node.24#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]25pub struct NodeEntry {26    /// Its node id. An API value only, never a telemetry value.27    pub node: String,28    /// When its first connection of this daemon's run came up, in Unix29    /// milliseconds by this daemon's clock.30    pub since_ms: i64,31    /// Its machine name, as its own inventory says (discussion:owner/314).32    #[serde(default, skip_serializing_if = "Option::is_none")]33    pub host: Option<String>,34    /// The peers this daemon saw sign from the node's device, and35    /// those its daemon holds, each signature checked (discussion:owner/314), by36    /// name (`Named`), sorted.37    #[serde(default)]38    pub peers: Vec<String>,39    /// Its roles, sorted: `runner` when one of its peers carries40    /// runs this daemon heard of.41    #[serde(default)]42    pub roles: Vec<NodeRole>,43    /// How this daemon reaches it, a `node_link` value (discussion:owner/400):44    /// `relayed` while every connection to it goes through a circuit45    /// relay, `hole_punched` once a direct connection came up through46    /// DCUtR after a relayed one, else `direct`. Absent where the daemon47    /// doesn't tell.48    #[serde(49        default,50        skip_serializing_if = "Option::is_none",51        serialize_with = "vocab_opt_to",52        deserialize_with = "vocab_opt_from"53    )]54    pub link: Option<NodeLink>,55    /// Its hardware, as its own inventory says, signed with it (56    /// discussion:owner/314 and 400). Absent where the daemon doesn't tell.57    #[serde(default, skip_serializing_if = "Option::is_none")]58    pub hardware: Option<NodeHardware>,59    /// Its `lvcs` release (`0.1.2`), as its identify agent version names60    /// it. Absent where the daemon doesn't tell, and for a node whose61    /// agent version names none.62    #[serde(default, skip_serializing_if = "Option::is_none")]63    pub version: Option<String>,64    /// The connections this daemon holds to it now, direct and relayed:65    /// one once a dial race settles (session-9468d544/26). Absent where the66    /// daemon doesn't tell.67    #[serde(default, skip_serializing_if = "Option::is_none")]68    pub connections: Option<u32>,69}7071/// A node's hardware (discussion:owner/400), from its inventory.72#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]73pub struct NodeHardware {74    /// Its operating system, as Rust's `std::env::consts::OS` names it.75    pub os: String,76    /// Its CPU architecture, as Rust's `std::env::consts::ARCH` names it.77    pub arch: String,78    /// Its CPU model, at most `HOST_NAME_MAX_BYTES`, where the platform79    /// says.80    #[serde(default, skip_serializing_if = "Option::is_none")]81    pub cpu_model: Option<String>,82    /// Its logical CPU cores.83    pub cores: u32,84    /// Its physical memory, in bytes.85    pub memory_bytes: u64,86}8788/// A role a node plays in the project.89#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize)]90#[serde(rename_all = "snake_case")]91pub enum NodeRole {92    /// One of its peers runs actions.93    Runner,94}9596/// `node.load` (discussion:owner/400): one connected node's recent load in this97/// project, asked of that node's daemon over the project's swarm and98/// answered only to a node hosting the project's owner or a peer that holds99/// a live grant in the project. The asking daemon keeps the answer and serves100/// it to every caller until the next `RESOURCE_STEP_SECS`, asking the node at101/// most once a step and only when someone calls (discussion:owner/487). An anonymous102/// reader may call it only under `lvcs.toml`'s `[public] machines`. Refused `unknown_node` when the node isn't connected, and103/// `not_supported` when it doesn't speak the protocol.104#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]105pub struct NodeLoadParams {106    /// The node id, as `node.list` names it, its `own` too.107    pub node: String,108    /// At most this many of the latest samples; all it keeps when absent.109    #[serde(default, skip_serializing_if = "Option::is_none")]110    pub samples: Option<u32>,111}112113/// `node.load` result.114#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]115pub struct NodeLoadResult {116    /// The node it answers for.117    pub node: String,118    /// The step between samples, in seconds (`RESOURCE_STEP_SECS`).119    pub step_secs: u64,120    /// The latest samples that node's daemon took, oldest first, at most121    /// `NODE_LOAD_SAMPLES_MAX`; each sample's `storage` names this122    /// project's kinds only, its `root` empty.123    #[serde(default)]124    pub samples: Vec<ResourceSample>,125    /// Its memory now, by part.126    #[serde(default)]127    pub memory: Vec<MemoryUse>,128    /// Its logical CPU cores, which a sample's CPU time is a share of.129    #[serde(default, skip_serializing_if = "Option::is_none")]130    pub cores: Option<u32>,131}132133/// One part's resident memory on a node.134#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]135pub struct MemoryUse {136    /// A `memory_part` value.137    #[serde(serialize_with = "vocab_to", deserialize_with = "vocab_from")]138    pub part: MemoryPart,139    /// Its resident memory, in bytes.140    pub rss_bytes: u64,141}142143/// `presence.list` (discussion:owner/303): every peer the coord actor144/// counts as present, on a document, until145/// `PRESENCE_TTL_SECS` after its latest presence.146#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]147pub struct PresenceListParams {}148149/// `presence.list` result, newest first.150#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]151pub struct PresenceListResult {152    #[serde(default)]153    pub presences: Vec<PresenceEntry>,154}155156/// One peer's presence.157#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]158pub struct PresenceEntry {159    /// Its peer id, in `ID_ENCODING`.160    pub peer: String,161    /// Its name (`Named`).162    pub name: String,163    /// The document it is on, if any.164    #[serde(default, skip_serializing_if = "Option::is_none")]165    pub address: Option<String>,166    /// Its signed time, in Unix milliseconds.167    pub at_ms: i64,168}169170/// Server push, JSON-RPC notification method `presence` (`watch`).171#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]172pub struct PresencePush {173    /// The `watch` it is pushed for.174    pub sub: u64,175    pub presence: PresenceEntry,176}177178/// `sync.deliver` (release-qual/16), in test builds only: the receiver179/// takes `payload` for `address` as if connected node `from` had sent it180/// on its sync stream, down the same path a frame it read takes: the181/// sync machine's held flag and intake, the node's share of the byte182/// budget, and the document's signature, grant, and dep checks. Only the183/// stream's own device signature is not checked, since no frame is read.184#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]185pub struct SyncDeliverParams {186    /// The connected node, its id as `node.list` names it, whose sync187    /// stream the payload arrives on.188    pub from: String,189    /// The document's address.190    pub address: String,191    /// The document's sync payload (a CBOR `SyncPayload`), base64.192    pub payload: String,193}194195/// `sync.deliver` result: the payload was handed to the node's sync196/// machine. What its document did is told as for any frame (its sync197/// answers, holds, and refusals).198#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]199pub struct SyncDeliverResult {}