docs/generated/contracts.mdgenerated from code

Reference · 5 min read

api-channels

Contracts: api-channels.

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

ruston main
1/// `approve` (discussion:owner/123): the caller approves the protected `paths`2/// (file addresses) at `frontier` (a frontier id from `channel.read`; empty,3/// main's visible frontier when the daemon serves the request,4/// discussion:owner/613), as5/// an approval in `.lvcs/approvals` (discussion:owner/297). Refused `REJECTED`,6/// with nothing committed, when the caller isn't the owner or a holder of7/// `approve` on `.lvcs/approvals` and every named path (whatever its tier8/// or its connection's uid, discussion:owner/147), no named path is protected, or the entry would pass the9/// change quota of the grant it is signed under (discussion:owner/178). A named10/// path that isn't a file address is refused `INVALID_PARAMS`; a file11/// address no protected pattern matches is approved as nothing and listed12/// in the result's `not_protected` (discussion:owner/372). Core counts no13/// attestation (discussion:owner/518): the frontier is the one `entries` gives14/// (as `frontier.read`'s `entries` shape it), whose id must be `frontier`15/// and whose named paths' heads their documents must hold; without16/// `entries`, main's visible frontier or one a channel names, else17/// `unknown_base`. The approval carries the whole frontier. With18/// `unattested` (discussion:owner/407), accepted only from the project's owner,19/// the approval is marked made early, before the actions plugin's quorum.20/// With `waiting` (only with no `frontier`, discussion:owner/613), every protected21/// path main's visible frontier holds beyond its approved heads, as22/// `status`'s `waiting` lists them, is added to `paths`; refused23/// `INVALID_PARAMS` when none is. An approval approves exactly the24/// protected paths it names: every other protected path the frontier25/// changes keeps waiting for its own approval (orchestrator/25).26#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]27pub struct ApproveParams {28    #[serde(default)]29    pub frontier: String,30    #[serde(default)]31    pub paths: Vec<String>,32    #[serde(default, skip_serializing_if = "std::ops::Not::not")]33    pub unattested: bool,34    #[serde(default, skip_serializing_if = "Option::is_none")]35    pub entries: Option<std::collections::BTreeMap<String, crate::files::FrontierDoc>>,36    #[serde(default, skip_serializing_if = "std::ops::Not::not")]37    pub waiting: bool,38}3940/// `approve` result: the approval's entry id (`ID_ENCODING`) and, for each41/// named protected path, the peers who signed its changes beyond42/// its approved heads in the frontier; `not_protected` lists the named43/// paths no protected pattern matches, sorted, which nothing approves44/// (discussion:owner/372).45#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]46pub struct ApproveResult {47    pub approval: String,48    pub paths: Vec<ApprovedPath>,49    #[serde(default, skip_serializing_if = "Vec::is_empty")]50    pub not_protected: Vec<String>,51    /// The named paths whose changes at the frontier's heads this daemon52    /// doesn't hold, left out of the approval and not committed against: a53    /// delete-and-recreate or an unsynced change (session-29a3231b/13). They54    /// stay waiting; `approve` them again once the change is held.55    #[serde(default, skip_serializing_if = "Vec::is_empty")]56    pub not_held: Vec<String>,57}5859/// One approved path and its signers beyond its approved heads, each in60/// `ID_ENCODING`.61#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]62pub struct ApprovedPath {63    pub path: String,64    pub signers: Vec<String>,65}6667/// `channel.read` (discussion:owner/120): the value of channel `channel` (a68/// channel name: any action's channel, or a `[channels]` combination,69/// discussion:owner/297).70#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]71pub struct ChannelReadParams {72    pub channel: String,73}7475/// `channel.read` result: the channel's value, its counted frontiers that76/// no other counted frontier supersedes, sorted by id (none for a77/// action channel).78#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]79pub struct ChannelReadResult {80    pub frontiers: Vec<ChannelFrontier>,81}8283/// One frontier of a channel's value: its id (`ID_ENCODING`), the size of84/// its largest counted set of attestations, and the approvals naming it.85#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]86pub struct ChannelFrontier {87    pub frontier: String,88    #[serde(default)]89    pub attestations: u32,90    #[serde(default)]91    pub approvals: u32,92}9394/// `run` (discussion:owner/141 and discussion:owner/204, the triggers row): run a gated action by95/// hand, its manual trigger.96///97/// CLI: `lvcs run <action> [<frontier-id>]`. The caller signs the run98/// request under a grant holding `Approve` on the action's channel's99/// address. With no frontier, the action runs on the one frontier its100/// `after` channel holds that it is eligible for. A rollback is a run on an101/// earlier frontier the channel held. A change action is never run by102/// hand: it runs on every change to main. Retried under `request`103/// (discussion:owner/167).104#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]105pub struct RunParams {106    /// The gated action's name, which is its channel's.107    pub action: String,108    /// A frontier id (`ID_ENCODING`), as [`ChannelFrontier`] names one;109    /// by default the one the action's `after` channel holds.110    #[serde(default, skip_serializing_if = "Option::is_none")]111    pub frontier: Option<String>,112}113114/// `run` result: the run request's entry id, and the frontier it runs on.115#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]116pub struct RunResult {117    /// The run request's entry id (`ID_ENCODING`).118    pub request: String,119    /// The frontier it runs on (`ID_ENCODING`).120    pub frontier: String,121}122123/// `channel.list` (discussion:owner/303): every action's channel and every124/// `[channels]` combination of main's approved `lvcs.toml`, sorted by name.125#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]126pub struct ChannelListParams {}127128/// `channel.list` result. `waiting` names the protected paths main129/// changed past their approved heads (discussion:owner/314), as `status` details130/// them: an `lvcs.toml` with new actions waits there until approved.131#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]132pub struct ChannelListResult {133    #[serde(default)]134    pub channels: Vec<ChannelEntry>,135    #[serde(default, skip_serializing_if = "Vec::is_empty")]136    pub waiting: Vec<crate::status::StatusWaiting>,137}138139/// One channel, with its value as `channel.read` answers it.140#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]141pub struct ChannelEntry {142    pub name: String,143    pub trigger: ChannelTrigger,144    /// The channels it runs after (a gated action), or its members (a145    /// combination), sorted; empty for a change action.146    #[serde(default)]147    pub after: Vec<String>,148    /// Its value's frontiers, as `channel.read` answers them.149    pub frontiers: Vec<ChannelFrontier>,150    /// For an action's channel, the peers a live grant lets attest151    /// it, the owner aside, by name, sorted (discussion:owner/321); empty for a152    /// combination.153    #[serde(default)]154    pub attesters: Vec<String>,155    /// For an action's channel, the runners whose presence on it arrived156    /// within `RUNNER_ONLINE_MS`, by name, sorted; empty for a combination.157    #[serde(default)]158    pub online: Vec<String>,159}160161/// What moves a channel (discussion:owner/297).162#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]163#[serde(rename_all = "snake_case")]164pub enum ChannelTrigger {165    /// A change action, run on every change to main.166    Change,167    /// A gated action triggered by another channel's value.168    Channel,169    /// A gated action run on run requests: by hand (`lvcs run`), or for170    /// each durable event its trigger matches (discussion:owner/522).171    Manual,172    /// A `[channels]` combination, which no action moves.173    Combination,174}