docs/generated/contracts.mdgenerated from code

Reference · 3 min read

api-hooks

Contracts: api-hooks.

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

ruston main
1/// `stop_gate` (discussion:owner/214 and discussion:owner/217), the `Stop` hook's op: whether the2/// caller may stop now. Read-only, and never retried.3///4/// The daemon keeps the caller's newest change to each file it changed5/// through this daemon, since the daemon started. The answer is `failed` while the caller has6/// an open `action_failed` streak (discussion:owner/193) and changed nothing since7/// the notice that opened it, once per set of open streaks: a later8/// `stop_gate` with the same set and nothing changed answers `pending`,9/// naming no file and those streaks, until a streak closes or opens, the10/// caller changes something, or the window a shown set stays shown for passed since the11/// `failed`, which then answers `failed` again (discussion:owner/230); else `pending`12/// while a streak of its is open, or, for one of those files, no frontier13/// of the change set's value holds its newest change, unless the project14/// configures no check; and `passed` otherwise. Where it would answer15/// `pending`, it answers `waiting` instead while the change set can't move16/// without someone else: a change channel waits on an approval, no peer17/// is granted to attest one, or none who is is online (discussion:owner/321 and18/// 401). A restart forgets the changes, as it forgets `status.checks`.19#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]20pub struct StopGateParams {}2122/// What the `Stop` gate decided (discussion:owner/214 and discussion:owner/217).23#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]24#[serde(rename_all = "snake_case")]25pub enum StopGate {26    /// The caller may stop: the change set holds its newest changes, and27    /// no check of its fails.28    Passed,29    /// The runners haven't passed its newest changes yet, its fix of a30    /// failed check included: ask again after `retry_after_ms`.31    Pending,32    /// A check failed on its changes: read the `action_failed` with33    /// `notifications.read` and fix the change.34    Failed,35    /// The change set can't move without someone else (an approval, a36    /// grant to attest, or a runner online), as `reason` says: nothing the37    /// caller does clears it, so it may stop (discussion:owner/401).38    Waiting,39    /// LVCS refused a save of the caller's tree and no later save of40    /// that file was admitted: the file keeps its bytes, unsynced, and41    /// `main` lacks the change. `reason` gives each refusal's reason and42    /// next step, which the caller can take (amending discussion:owner/401).43    Refused,44}4546/// `stop_gate` result.47#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]48pub struct StopGateResult {49    /// The decision.50    pub gate: StopGate,51    /// `failed`: the caller's open failing streaks, as `status.checks`52    /// lists them (metadata only); `pending` with no file: those streaks,53    /// already shown at a `Stop` (discussion:owner/230); empty otherwise.54    #[serde(default)]55    pub failed: Vec<Notification>,56    /// `pending` and `waiting`: the files whose newest change of the57    /// caller's no frontier of the change set holds yet, sorted; empty58    /// otherwise.59    #[serde(default)]60    pub pending: Vec<String>,61    /// `pending`: how long to wait before asking again (`STOP_RETRY_MS`).62    #[serde(default, skip_serializing_if = "Option::is_none")]63    pub retry_after_ms: Option<u64>,64    /// `waiting`: why the change set can't move, as `status` says it;65    /// absent otherwise.66    #[serde(default, skip_serializing_if = "Option::is_none")]67    pub reason: Option<String>,68    /// The caller has no `notifications.wait` running, and this daemon69    /// hasn't said so to it yet since it started (discussion:owner/424): the70    /// `Stop` hook mentions the background wait once.71    #[serde(default, skip_serializing_if = "std::ops::Not::not")]72    pub wait_hint: bool,73}