docs/generated/contracts.mdgenerated from code

Reference · 10 min read

channel

Contracts: channel.

Source: crates/lvcs-doc/src/kinds/channel/mod.rs.

ruston main
1/// A channel's name (discussion:owner/119, discussion:owner/245, and discussion:owner/297): one or more2/// `/`-separated segments of `[a-z0-9._-]`, none of them empty or `.`,3/// holding no `..` anywhere, and at most `CHANNEL_NAME_MAX_BYTES` bytes in4/// all. Every action moves the channel named for it (a workflow change5/// job's is `<file stem>/<job id>` lowercased), and no name is reserved; a6/// `[channels]` combination's name is one too, with no document. Its7/// document is at8/// `CHANNEL_PREFIX` + the name, written literally, and stores no name: the9/// verifier reads it from the address. Every API parameter and `[git]10/// branches` key parses with [`ChannelName::parse`]. A JSON or CBOR text11/// string; one that doesn't parse is refused.12#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]13#[serde(try_from = "String", into = "String")]14pub struct ChannelName(String);1516/// Why [`ChannelName::parse`] refused a name.17#[derive(Debug, Clone, Copy, PartialEq, Eq)]18pub enum ChannelNameError {19    /// A segment is empty or `.`, the name holds `..`, or a segment holds20    /// a byte outside `[a-z0-9._-]`.21    Segment,22    /// It is longer than `CHANNEL_NAME_MAX_BYTES` bytes.23    TooLong,24}2526/// An action's id (discussion:owner/245): `HASH([ACTION_DOMAIN, action])` over27/// the canonical encoding of the action less its name, source, and quorum,28/// computed by lvcs-action's `Action::id`. Change actions, gated actions,29/// and the generator are all keyed by it. Written in `ID_ENCODING`.30#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]31pub struct ActionId(#[serde(with = "crate::cbor::fixed")] pub [u8; 32]);3233/// The `HASH` of everything one action read at a frontier (discussion:owner/12134/// and 245).35///36/// It covers the action id, the heads of the documents its `paths` and37/// `uses` match (discussion:owner/161), the dependency frontier, and the toolchain38/// hash. Two runners that ran an action on equal inputs name equal hashes.39#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]40pub struct InputsHash(#[serde(with = "crate::cbor::fixed")] pub [u8; 32]);4142/// A runner's attestation (discussion:owner/119, discussion:owner/245, and discussion:owner/297), in a change43/// action's channel: every change action of that channel, in `actions`44/// with its `InputsHash`, passed or was reused on `frontier` under the45/// toolchain46/// `toolchain_hash`. `sig` (the `runner` key's) and `device_sig` (the47/// `device` key's, the runner's daemon) both cover48/// [`Attestation::signing_input`]. Keyed [`Attestation::key`],49/// `HASH([runner, frontier id])`, so a runner attests a frontier once.50#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]51pub struct Attestation {52    pub frontier: Frontier,53    pub actions: BTreeMap<ActionId, InputsHash>,54    #[serde(with = "crate::cbor::fixed")]55    pub toolchain_hash: [u8; 32],56    pub runner: PeerKey,57    pub device: DeviceKey,58    #[serde(with = "crate::cbor::fixed")]59    pub sig: [u8; 64],60    #[serde(with = "crate::cbor::fixed")]61    pub device_sig: [u8; 64],62}6364/// An approval (discussion:owner/119 and discussion:owner/297), only in the approvals document:65/// `approver`66/// approves the changes `frontier` carries to each of `paths`, which are67/// sorted, unique, non-empty, at most `APPROVAL_MAX_PATHS`, and each a file68/// address (which of them are protected is the policy's, discussion:owner/378). It carries no grant and no inner69/// signature: the `ChangeSig` of the change that puts it names the grant70/// and signs it. Keyed [`Approval::key`], `HASH([approver, frontier id,71/// paths])`. It carries the whole frontier it approves (`named`, whose id72/// is `frontier`, discussion:owner/518: core counts no attestation, so the entry73/// itself says what it approves). An owner's unattested approval74/// (discussion:owner/407), made before the actions plugin's quorum, carries it as75/// `unattested` too, which the plugin reads as approved early. Each is76/// left out of the encoding when absent.77///78/// A gated approval (discussion:owner/805) carries `gates` instead: the79/// frontier's entries at exactly the named paths it holds, and at80/// `Frontier::TREE` when it holds none at some named path (the removal81/// it approves, discussion:owner/806), and no `named` or `unattested`. An82/// owner's approval before the quorum says `early`. Its size is its named83/// paths', whatever the tree's. The signer's `ChangeSig` vouches for the84/// entries, since a partial frontier doesn't hash to `frontier`.85#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]86pub struct Approval {87    pub frontier: FrontierId,88    pub approver: PeerKey,89    pub paths: Vec<String>,90    #[serde(default, skip_serializing_if = "Option::is_none")]91    pub unattested: Option<Frontier>,92    #[serde(default, skip_serializing_if = "Option::is_none")]93    pub named: Option<Frontier>,94    #[serde(default, skip_serializing_if = "Option::is_none")]95    pub gates: Option<Frontier>,96    #[serde(default, skip_serializing_if = "std::ops::Not::not")]97    pub early: bool,98}99100/// A gated action's run key (discussion:owner/141 and discussion:owner/245).101///102/// It is `HASH([ACTION_DOMAIN, action, frontier id, run request])` for the103/// run request it serves, so each run request runs once. A run's commands104/// receive it as `LVCS_RUN`.105/// Written in `ID_ENCODING`.106#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]107pub struct RunKey(#[serde(with = "crate::cbor::fixed")] pub [u8; 32]);108109/// A gated action's run outcome (discussion:owner/141 and discussion:owner/245), in its110/// channel.111///112/// `runner` ran the gated action `action` on `frontier` as the run113/// `run`, and it `passed` or failed, at `time_ms` on the runner's clock;114/// `inputs` is the run's `InputsHash` when the runner could hash it, and115/// `reused` says the runner ran nothing, since its own last pass of the116/// action had the same inputs (row 387):117/// the change that puts it is dated `time_ms / 1000` seconds, floored, or118/// every verifier refuses it, and a passed trigger run ranks by the least119/// `time_ms` of its passed outcomes. `sig` (the `runner` key's) and120/// `device_sig` (the `device` key's, the runner's daemon) both cover121/// [`Outcome::signing_input`]. Keyed [`Outcome::key`],122/// `HASH([runner, run])`.123#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]124pub struct Outcome {125    /// The frontier the run ran on.126    pub frontier: Frontier,127    /// The gated action that ran.128    pub action: ActionId,129    /// The run's key.130    pub run: RunKey,131    /// Whether the run's commands exited zero.132    pub passed: bool,133    /// The run's `InputsHash`, when the runner could hash it (row 387).134    pub inputs: Option<InputsHash>,135    /// Whether it is a reused pass: no command ran (row 387).136    pub reused: bool,137    /// The peer whose runner ran it, and the change's signer.138    pub runner: PeerKey,139    /// The runner's daemon.140    pub device: DeviceKey,141    /// When the run ended, in milliseconds since the Unix epoch.142    pub time_ms: i64,143    /// The runner key's signature over the signing input.144    #[serde(with = "crate::cbor::fixed")]145    pub sig: [u8; 64],146    /// The device key's signature over the signing input.147    #[serde(with = "crate::cbor::fixed")]148    pub device_sig: [u8; 64],149}150151/// A run request (discussion:owner/141), in a channel; the channels actor counts152/// only a gated action's.153///154/// `requester` asks that the channel's gated action run on `frontier`, at155/// `time_ms`.156/// Run requests are ordered by `(time_ms, entry id)`. It carries no inner157/// signature: the `ChangeSig` of the change that puts it names the grant158/// and signs it. Keyed [`RunRequest::key`], `HASH([requester, frontier id,159/// time_ms])`.160#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]161pub struct RunRequest {162    /// The frontier to run on.163    pub frontier: FrontierId,164    /// The peer that asked for the run, and the change's signer.165    pub requester: PeerKey,166    /// When it was asked for, in milliseconds since the Unix epoch: the167    /// change that puts it is dated `time_ms / 1000` seconds, floored, or168    /// every verifier refuses it.169    pub time_ms: i64,170}171172/// One output of a generation (row 180): the SHA-256 of the output's173/// bytes, and the heads holding those bytes in its document.174#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]175pub struct GeneratedOutput {176    /// The SHA-256 of the output's bytes.177    #[serde(with = "crate::cbor::fixed")]178    pub digest: [u8; 32],179    /// The heads holding those bytes in the output's document.180    #[serde(with = "crate::cbor::heads")]181    pub heads: Vec<ChangeId>,182}183184/// Why a derivation failed (row 180).185#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]186pub enum DeriveFailure {187    /// The generator exited non-zero, was killed, or timed out.188    Exit,189    /// The run created, changed, or removed a file the classifier doesn't190    /// call derived.191    NonDerivedWrite,192}193194/// A runner's generation record (row 180, discussion:owner/245 and discussion:owner/297), in the195/// generator's channel.196///197/// `runner` ran the generator `action` (the one action with `writes`) on198/// the inputs `inputs` at `frontier` under the toolchain `toolchain_hash`,199/// and it wrote or found `outputs` (each output address's digest and200/// heads), or it failed with `failure`. `outputs` is empty exactly when201/// `failure` is set, and it holds at most `GENERATION_OUTPUTS_MAX`202/// addresses (a map, so sorted and unique). `sig` (the `runner` key's) and203/// `device_sig` (the `device` key's, the runner's daemon) both cover204/// [`Generation::signing_input`]. Keyed [`Generation::key`],205/// `HASH([runner, inputs])`, so a runner records one outcome per inputs.206#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]207pub struct Generation {208    /// The generator that ran.209    pub action: ActionId,210    /// The generator's `InputsHash`.211    pub inputs: InputsHash,212    /// The frontier the derivation ran on.213    pub frontier: Frontier,214    /// Each output address's digest and heads.215    pub outputs: BTreeMap<String, GeneratedOutput>,216    /// Why the derivation failed, when it did.217    pub failure: Option<DeriveFailure>,218    /// The toolchain the derivation ran under.219    #[serde(with = "crate::cbor::fixed")]220    pub toolchain_hash: [u8; 32],221    /// The runner that ran it, and the change's signer.222    pub runner: PeerKey,223    /// The runner's daemon.224    pub device: DeviceKey,225    /// The runner key's signature over the signing input.226    #[serde(with = "crate::cbor::fixed")]227    pub sig: [u8; 64],228    /// The device key's signature over the signing input.229    #[serde(with = "crate::cbor::fixed")]230    pub device_sig: [u8; 64],231}232233/// One entry of a channel document.234///235/// It is a value of one of its genesis maps (`/attestations`,236/// `/generations`, `/outcomes`, or `/requests` in a channel; `/approvals`237/// in the approvals document), at the key [`ChannelEntry::key`] gives.238#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]239pub enum ChannelEntry {240    Attestation(Attestation),241    Approval(Approval),242    /// An approvals segment's carry of one path, in `/carry`243    /// (discussion:owner/805).244    Carry(Carry),245    /// A gated action's run outcome, in `/outcomes`.246    Outcome(Outcome),247    /// A run request, in `/requests`.248    Request(RunRequest),249    /// A generation record, in `/generations`.250    Generation(Generation),251}252253/// A channel entry's key in its map, written in `ID_ENCODING`.254#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Serialize, Deserialize)]255pub struct EntryId(#[serde(with = "crate::cbor::fixed")] pub [u8; 32]);256257/// Put `entry` into a channel document or the approvals document258/// (discussion:owner/119, discussion:owner/141, and discussion:owner/297).259///260/// It is committed by `origin` like an edit and answered like one:261/// `DocOutput::Changed` with `req`, or `DocOutput::Rejected` `Failed` when262/// the document has no map for the entry (an approval in a channel, or263/// any other entry in the approvals document), the entry's key264/// doesn't encode, its key holds another entry (an attestation of the same265/// frontier by the same runner with other bytes, such as another266/// device's), or the document is of another kind or closed. An entry is267/// its canonical CBOR as a byte string at its key ([`ChannelEntry::key`]268/// in `ID_ENCODING`) in its map, put only at a key269/// that holds nothing, so no put overwrites an entry; one the document270/// already holds at its key commits nothing and answers at the current271/// heads, so a re-put is a no-op. The caller checks it first (the shell272/// signs attestations and outcomes and checks approvals and run requests):273/// every node's verifier refuses274/// a change whose entry would fail there.275#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]276pub struct ChannelPut {277    pub req: RequestId,278    pub origin: Origin,279    pub entry: ChannelEntry,280}281282/// A channel document's or the approvals document's render (283/// discussion:owner/119 and 297).284///285/// It comes after every change that adds entries and on286/// `DocEvent::Render`: the incarnation's first render287/// is `full`, listing every entry the document holds, and every later one288/// lists only the entries the changes since the previous render added, so289/// journals grow linearly. A key holds one value: an author's second value290/// at its key is equivocation, and the key is void, left out of every291/// render (history row 461). Every render lists entries map by map292/// (attestations, approvals, outcomes, run requests, then generations),293/// each map by key. A rendered approval's frontiers hold only the entries294/// at the paths it names, its gates, not the whole tree it approved295/// (discussion:owner/776); its key is unchanged.296#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]297pub struct ChannelRendered {298    #[serde(with = "crate::cbor::heads")]299    pub heads: Vec<ChangeId>,300    pub added: Vec<ChannelEntry>,301    pub full: bool,302}303304/// What a fold reads of an approvals segment (discussion:owner/805): at305/// `at` (its live heads when `None`), only the keys put after `since` when306/// given. Answered [`ChannelFolded`] with `req`; another kind's document307/// refuses it as foreign.308#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]309pub struct ChannelFold {310    pub req: RequestId,311    pub at: Option<Vec<ChangeId>>,312    pub since: Option<Vec<ChangeId>>,313}314315/// The answer to [`ChannelFold`] `req`: the heads it was read at, each316/// approval (gates only) with its putting change's time, and each carry;317/// `unknown` when the ledger doesn't hold the heads it was asked at, and318/// then nothing else.319#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]320pub struct ChannelFolded {321    pub req: RequestId,322    #[serde(with = "crate::cbor::heads")]323    pub heads: Vec<ChangeId>,324    pub approvals: Vec<fold::Timed>,325    pub carries: Vec<Carry>,326    /// Who put each of `carries`, in the same order.327    #[serde(default, skip_serializing_if = "Vec::is_empty")]328    pub signers: Vec<PeerKey>,329    pub unknown: bool,330}