Enum SnapshotPhase 

pub enum SnapshotPhase {
    Pending,
    Running,
    Succeeded,
    Failed,
    Deleting,
    Discovered,
    Unchanged,
    Unknown(String),
}

Lifecycle phase of a Snapshot.

use kopiur_api::SnapshotPhase;
use kopiur_api::common::PhaseLabel;

// Canonical values round-trip as bare strings.
assert_eq!(serde_json::to_value(SnapshotPhase::Succeeded).unwrap(), "Succeeded");
let p: SnapshotPhase = serde_json::from_value(serde_json::json!("Running")).unwrap();
assert_eq!(p, SnapshotPhase::Running);

// A phase written by a NEWER operator decodes into `Unknown` (never a
// watcher-poisoning serde error) and re-serializes verbatim.
let p: SnapshotPhase = serde_json::from_value(serde_json::json!("Quiescing")).unwrap();
assert_eq!(p, SnapshotPhase::Unknown("Quiescing".into()));
assert_eq!(serde_json::to_value(&p).unwrap(), "Quiescing");
assert_eq!(p.label(), "Quiescing");
// Never terminal: an unrecognized phase is held and surfaced, not finished.
assert!(!p.is_terminal());

Variants

Pending

Admitted, not yet started (also the default).

Running

Mover Job is in flight.

Succeeded

Snapshot created successfully.

Failed

Mover Job exhausted its retries.

Deleting

CR is being deleted; finalizer is reclaiming the snapshot.

Discovered

Catalog-materialized backup kopiur didn’t produce.

Unchanged

The backup ran to completion but kopia wrote no new manifest: the source was byte-identical to the previous snapshot, and this policy has files.ignoreIdenticalSnapshots enabled.

Terminal, and a success: the source was read and hashed, and it is protected — by the previous snapshot, which remains the live restore point. So an Unchanged run advances every liveness signal (last-backup timestamp, policy health, failure-streak reset) exactly like Succeeded.

What it does NOT do is own a kopia manifest. status.snapshot is absent, the finalizer has nothing to reclaim, and it takes no GFS retention slot — a restore point that does not exist must not displace one that does. Recording it as Succeeded instead would make the controller resolve “its” snapshot and find its predecessor’s, leaving two CRs claiming one manifest and the first prune deleting it out from under the second.

Unreachable unless the policy opts in: the mover pins --ignore-identical-snapshots=false at the identity scope on every run. See #351.

Unknown(String)

A phase string this build does not recognize — written by a newer operator during a rolling upgrade, or persisted before this variant set existed. Decode-compat only: hidden from the CRD schema (the apiserver rejects it on every new write) and never produced by this build.

Never terminal, never schedulable, never reapable, never a success — every consumer holds and surfaces it rather than acting on a phase whose meaning it does not know.

Implementations

impl SnapshotPhase

pub fn is_terminal(&self) -> bool

Whether this phase is terminal: the operator will do no further work on the object of its own accord, so a diagnostic must not report it as in-flight (nor as stuck).

Deleting is deliberately not terminal. A CR sitting in Deleting has a finalizer that is still trying to reclaim its kopia snapshot — a wedged finalizer (an unreachable backend, a held mass-deletion breaker) is in-flight work that never completes, which is exactly the state worth surfacing. Classifying it terminal is how a stuck deletion becomes invisible.

Discovered and Unchanged ARE terminal: a discovered CR mirrors a kopia snapshot the operator did not produce and never advances on its own, and an Unchanged run already finished (successfully, owning no manifest). A Discovered CR that is later deleted moves to Deleting like any other, so nothing is lost by treating the phase itself as done.

Pure + exhaustive so the single definition lives in one tested place — the CLI and the controller must never disagree about what “still working” means.

use kopiur_api::SnapshotPhase;

assert!(SnapshotPhase::Succeeded.is_terminal());
assert!(SnapshotPhase::Failed.is_terminal());
assert!(SnapshotPhase::Discovered.is_terminal());
assert!(SnapshotPhase::Unchanged.is_terminal());
assert!(!SnapshotPhase::Pending.is_terminal());
assert!(!SnapshotPhase::Running.is_terminal());
// A wedged finalizer is in-flight work, not a finished object.
assert!(!SnapshotPhase::Deleting.is_terminal());
// An unrecognized phase is never terminal — hold and surface it.
assert!(!SnapshotPhase::Unknown("Quiescing".into()).is_terminal());

pub fn is_unknown(&self) -> bool

Whether this phase is the decode sentinel — a value the running build cannot interpret, kept verbatim by Unknown instead of failing the whole typed list()/watch (#359, defect 3).

The contract is narrow on purpose, and it is the reason this is a method rather than an inline matches! at each caller: true means only “this string is not a phase this binary knows”, never “unusual” or “not one I handle”. A canonical variant added to this enum later is by definition not the sentinel, so false is the right answer for it — which is exactly why the exhaustive match below is written out. Callers asking a set-shaped question (“is this finished?”, “is this a failure?”) want is_terminal or their own exhaustive match, not this.

use kopiur_api::SnapshotPhase;

assert!(SnapshotPhase::Unknown("Quiescing".into()).is_unknown());
assert!(!SnapshotPhase::Succeeded.is_unknown());
assert!(!SnapshotPhase::Failed.is_unknown());
assert!(!SnapshotPhase::Deleting.is_unknown());

Trait Implementations

impl Clone for SnapshotPhase

fn clone(&self) -> SnapshotPhase

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SnapshotPhase

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for SnapshotPhase

fn default() -> SnapshotPhase

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for SnapshotPhase

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Eq for SnapshotPhase

impl JsonSchema for SnapshotPhase

fn schema_name() -> Cow<'static, str>

The name of the generated JSON Schema.

fn json_schema(_: &mut SchemaGenerator) -> Schema

Generates a JSON Schema for this type.

fn inline_schema() -> bool

Whether JSON Schemas generated for this type should be included directly in parent schemas, rather than being re-used where possible using the $ref keyword.

fn schema_id() -> Cow<'static, str>

Returns a string that uniquely identifies the schema produced by this type.

impl PartialEq for SnapshotPhase

fn eq(&self, other: &SnapshotPhase) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PhaseLabel for SnapshotPhase

const ALL: &'static [Self]

Every canonical variant, in declaration order. Never contains Unknown.

fn label(&self) -> &str

The stable metric/wire label string for this variant (exhaustive match); the Unknown arm echoes the stored value verbatim so a read-modify-write never mutates a phase this build does not understand.

fn unknown(raw: String) -> Self

Build the decode-compat fallback for a non-canonical stored string. Implemented by the phase_serde! macro’s host enum.

fn parse(s: &str) -> Option<Self>

Parse a canonical label; None for anything else (including a value that would decode to Unknown). Derived from ALL + label() so a new variant is parseable the moment it is declared.

fn canonical() -> Vec<&'static str>

The canonical label set, for the CRD schema enum and “valid values” messages. One definition, derived from ALL.

impl Serialize for SnapshotPhase

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for SnapshotPhase