Kopiur Design

Kopiur design norms & decisions

Kopiur is a Kopia-native Kubernetes backup operator in Rust on kube-rs. The source of truth for current behavior is the code: the CRD types live in crates/api/src/, their generated schemas in deploy/crds/. Read docs/dev/api-conventions.md for the encoding rulebook and CLAUDE.md for the quick map. The ADRs (docs/adr/) are historical rationale — reach for one only to recover the why behind a decision, not for current field names or behavior, which they may pre-date.

The thesis you must protect

Invalid states are unrepresentable; reconcilers handle every variant. Concretely:

• Model every "exactly one of" surface as a Rust enum, never a bag of mutually exclusive Option fields + a runtime check.
• In reconcile/finalizer paths, use exhaustive match — avoid _ => catch-alls and if let ... else { /* ignore */ }. A new enum variant should fail to compile until handled. This is the entire reason the project is Rust, not Go.

Hard rules (violating these breaks the build or the CRDs)

1. Externally-tagged enums for discriminated unions. backend: { s3: {...} }, not backend: { kind: S3, ... }. Do NOT use #[serde(tag = "...")]: internally-tagged enums make kube's structural-schema rewriter panic (property "kind" ... must be identical) because each variant needs a distinct tag const. External tagging keeps the type-safety guarantee AND produces valid structural schemas. Provide a kind_str() helper for status/metrics/print-columns. Applies to Backend, AllowedNamespaces, RestoreSource, RestoreTarget, Hook, etc.
2. No Eq when embedding k8s-openapi types. LabelSelector, ResourceRequirements, SecurityContext, JobSpec, Condition, PodSpec are PartialEq but not Eq. Derive PartialEq only on any struct that contains one (directly or transitively). Reuse these types — never re-declare them. The schemars feature is on for k8s-openapi so they derive JsonSchema.
3. crates/api has no controller-runtime deps. No tokio, no kube::Client. It's the shared types + pure logic crate. The webhook and controller both import its validators so validation is identical.
4. One validator, two callers. Cross-field rules live in api::validate as pure functions returning a typed error; the webhook calls them at admission and the controller calls them defensively. Never fork validation logic.
5. Tests use the cluster's parse path. from_yaml = YAML → serde_json::Value → typed (crates/api/src/lib.rs::testutil). Direct serde_yaml::from_str::<T> mis-encodes externally-tagged enums (serde_yaml 0.9 !Variant syntax) and is not representative of the real wire format.

Semantic decisions to honor

• Retention is GFS-only. SnapshotPolicy.spec.retention is the sole successful- retention driver (operator prunes Snapshot CRs). Failures use a flat SnapshotSchedule.spec.failedJobsHistoryLimit. There is deliberately no successfulJobsHistoryLimit.
• Snapshot lifecycle = CR lifecycle. Every Snapshot carries the kopiur.home-operations.com/snapshot-cleanup finalizer. deletionPolicy: Delete (default for produced) / Retain (FORCED for origin: discovered, webhook-rejected otherwise) / Orphan. Match all three exhaustively; the kopiur.home-operations.com/skip-snapshot-cleanup annotation is the repo-offline escape hatch.
• Identity defaults to username=name, hostname=namespace, sourcePath=/pvc/<name>; ClusterRepository.identityDefaults *Expr fields evaluate as CEL at admission and are pinned to status.resolved.identity — never re-rendered after admission.
• Scheduling: wall-clock anchor (cron(now)), deterministic jitter seeded by (scheduleUID, slot_start) (no RNG — must be identical across HA replicas and restarts). runOnCreate: false and concurrencyPolicy: Forbid are defaults.
• Restores fail closed (onMissingSnapshot: Fail) except source.fromConfig, which defaults to Continue for the GitOps deploy-or-restore pattern.

Build & verify discipline

cargo test --workspace                 # hermetic; must be green before claiming done
cargo clippy --workspace --all-targets -- -D warnings
cargo xtask gen-all --check            # generated CRDs/RBAC must match checked-in
scripts/with-kind.sh cargo test --workspace --features integration -- --include-ignored

• Integration tests are #[ignore] + --features integration, run only on an ephemeral kind cluster via scripts/with-kind.sh. Never point them at a real/homelab cluster.
• Land one milestone, prove it green, then move on. Show the passing output — don't assert completion without evidence (a T::crd() call doubles as the schema-generation smoke test; it panics if an enum is mis-encoded).
• Delegating a milestone to a subagent is encouraged when it's well-specified, but always re-run cargo test/clippy yourself before trusting the result.

Every change ships with tests (non-negotiable)

This is data-protection software: an untested path can silently lose backups. So every new feature AND every bug fix ships with tests — you have NOT finished until the work is proven by tests that would fail without it.