docs/generated/contracts.mdgenerated from code
Reference · 5 min read
api-nodes
Contracts: api-nodes.
Read as
Source: crates/lvcs-api/src/nodes.rs.
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 {}