api-channels

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

/// `approve` (decision 123): the caller approves the protected `paths`
/// (file addresses) at `frontier` (a frontier id from `channel.read`), as
/// an approval in `.lvcs/approvals` (decision 297). Refused `REJECTED`,
/// with nothing committed, when the caller isn't the owner or a holder of
/// `approve` on `.lvcs/approvals` and every named path (whatever its tier
/// or its connection's uid, decision 147), a channel of the change set
/// holds no attestation of `frontier`, a named path isn't protected, the frontier changes a
/// protected path that `paths` doesn't name, or the entry would pass the
/// change quota of the grant it is signed under (decision 178).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ApproveParams {
    pub frontier: String,
    pub paths: Vec<String>,
}

/// `approve` result: the approval's entry id (`ID_ENCODING`) and, for each
/// named path, the participants who signed its changes beyond its approved
/// heads in the frontier.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ApproveResult {
    pub approval: String,
    pub paths: Vec<ApprovedPath>,
}

/// One approved path and its signers beyond its approved heads, each in
/// `ID_ENCODING`.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ApprovedPath {
    pub path: String,
    pub signers: Vec<String>,
}

/// `checkpoint` (decision 124): write one git commit of main's visible
/// frontier and advance `refs/lvcs/checkpoints/main`. Refused `REJECTED`
/// when the project root is not a git repository.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct CheckpointParams {}

/// `checkpoint` result: the commit's git object id (hex), the frontier id
/// it holds (`ID_ENCODING`), and the ref it advanced.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct CheckpointResult {
    pub commit: String,
    pub frontier: String,
    pub reference: String,
}

/// `channel.read` (decision 120): the value of channel `channel` (a
/// channel name: any action's channel, or a `[channels]` combination,
/// decision 297).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ChannelReadParams {
    pub channel: String,
}

/// `channel.read` result: the channel's value, its counted frontiers that
/// no other counted frontier supersedes, sorted by id (none for a
/// action channel).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ChannelReadResult {
    pub frontiers: Vec<ChannelFrontier>,
}

/// One frontier of a channel's value: its id (`ID_ENCODING`), the size of
/// its largest counted set of attestations, and the approvals naming it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ChannelFrontier {
    pub frontier: String,
    #[serde(default)]
    pub attestations: u32,
    #[serde(default)]
    pub approvals: u32,
}

/// `run` (decisions 141 and 204, the triggers row): run a gated action by
/// hand, its manual trigger.
///
/// CLI: `lvcs run <action> [<frontier-id>]`. The caller signs the run
/// request under a grant holding `Approve` on the action's channel's
/// address. With no frontier, the action runs on the one frontier its
/// `after` channel holds that it is eligible for. A rollback is a run on an
/// earlier frontier the channel held. A change action is never run by
/// hand: it runs on every merge into main. Retried under `request`
/// (decision 167).
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct RunParams {
    /// The gated action's name, which is its channel's.
    pub action: String,
    /// A frontier id (`ID_ENCODING`), as [`ChannelFrontier`] names one;
    /// by default the one the action's `after` channel holds.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub frontier: Option<String>,
}

/// `run` result: the run request's entry id, and the frontier it runs on.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RunResult {
    /// The run request's entry id (`ID_ENCODING`).
    pub request: String,
    /// The frontier it runs on (`ID_ENCODING`).
    pub frontier: String,
}

/// `channel.list` (decision 303): every action's channel and every
/// `[channels]` combination of main's approved `lvcs.toml`, sorted by name.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
pub struct ChannelListParams {}

/// `channel.list` result. `waiting` names the protected paths main
/// changed past their approved heads (decision 314), as `status` details
/// them: an `lvcs.toml` with new actions waits there until approved.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ChannelListResult {
    #[serde(default)]
    pub channels: Vec<ChannelEntry>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub waiting: Vec<crate::status::StatusWaiting>,
}

/// One channel, with its value as `channel.read` answers it.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct ChannelEntry {
    pub name: String,
    pub trigger: ChannelTrigger,
    /// The channels it runs after (a gated action), or its members (a
    /// combination), sorted; empty for a change action.
    #[serde(default)]
    pub after: Vec<String>,
    /// Its value's frontiers, as `channel.read` answers them.
    pub frontiers: Vec<ChannelFrontier>,
    /// For an action's channel, the participants a live grant lets attest
    /// it, the owner aside, by name, sorted (decision 321); empty for a
    /// combination.
    #[serde(default)]
    pub attesters: Vec<String>,
    /// For an action's channel, the runners whose presence on it arrived
    /// within `RUNNER_ONLINE_MS`, by name, sorted; empty for a combination.
    #[serde(default)]
    pub online: Vec<String>,
}

/// What moves a channel (decision 297).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum ChannelTrigger {
    /// A change action, run on every merge into main.
    Change,
    /// A gated action triggered by another channel's value.
    Channel,
    /// A gated action run by hand (`lvcs run`).
    Manual,
    /// A `[channels]` combination, which no action moves.
    Combination,
}