Module client 

The tokio::process-based kopia client.

KopiaClient is controller-agnostic: it knows how to invoke the kopia binary, stream its output, and parse the trailing JSON on stdout into the typed crate::model structs. It has no kube/k8s-openapi dependency (SKILL “keep it controller-agnostic”).

Per ADR §5.4, kopia prints progress to stderr and the --json result to stdout. We capture both: stdout is parsed as JSON, stderr is retained so a failure can carry the tail of the real error message.

Secrets (the repository password) are passed via the environment (KOPIA_PASSWORD), never on argv, so they never leak into process listings or error messages.

Structs

CacheTuning

Per-connection kopia cache budgets, applied at repository connect/create time (--content-cache-size-mb / --metadata-cache-size-mb). Each mover pod connects fresh, so these size that pod’s local cache. None leaves kopia’s default. Serializable so it rides the mover work spec from controller to mover.

CreateOptions

Create-time-fixed repository options applied at kopia repository create (ADR-0005 §13(a)): the encryption/splitter/hash algorithms baked into the repo format, plus optional Reed-Solomon ECC parity guarding blobs against backend bit-rot. All fields are immutable post-create (webhook-enforced, §7); kopia only honors them at create time. Pure args builder so it’s unit-testable.

KopiaClient

A kopia client backed by the real kopia binary via tokio::process.

KopiaClientBuilder

Builder for KopiaClient.

PolicyArgs

Policy fields kopia applies via kopia policy set. Mirrors the operator’s SnapshotPolicy.spec.policy without depending on the api crate, so the kopia crate stays controller-agnostic. The caller translates the CRD policy into this and the controller applies it before the first snapshot.

RestoreOptions

Options for kopia restore / kopia snapshot restore. The tri-state booleans map to kopia’s --[no-]flag form: Some(true) → --flag, Some(false) → --no-flag, None → omit (kopia default). M2 flag sweep (issue #216 gap analysis) added everything below overwrite_files; all of them, plus delete_extra, were previously either absent or dormant (the mover’s RestoreOp::restore_options() dropped them via ..Default::default()).

ServerStartSpec

A typed description of how to run kopia server start (the web UI).

SetParametersArgs

Flags for kopia repository set-parameters. Modeled on ThrottleArgs: an all-None builder whose caller skips the invocation entirely when nothing is set.

SnapshotCreateOptions

Options for kopia snapshot create (M4 flag sweep, issue #216 category sweep). All-default reproduces kopia’s own defaults / today’s argv: fail_fast: None (kopia default: keep going past per-file errors, subject to the errorHandling.ignore*Errors policy knobs), upload_limit_mb: None (kopia default: unlimited), description: None (kopia default: empty).

SyncToOptions

Options for kopia repository sync-to (ADR-0005 §13(d) / issue #216). Every field’s None/false reproduces kopia’s own default — an all-None, delete_extra: false instance yields the exact same argv sync_to_args produced before this struct existed. The tri-state booleans map to kopia’s --[no-]flag grammar, same as RestoreOptions: Some(true) → --flag, Some(false) → --no-flag, None → omit (kopia default).

ThrottleArgs

Repository throttling limits applied via kopia repository throttle set (ADR-0005 §13(e)). Each None leaves kopia’s current value untouched. Pure args builder so it’s unit-testable; an all-None instance yields no flags.

VerifyOptions

Options for kopia snapshot verify. All fields default to kopia’s defaults when None/empty.

Enums

ConnectSpec

A typed description of how to reach a kopia repository. This is the input to KopiaClient::repository_connect / KopiaClient::repository_create. Externally-tagged so exactly one backend is representable (mirrors the API crate’s Backend discipline, though this is a separate, simpler type with no kube dependency).

MaintenanceMode

Which maintenance pass to run.

ServerAuthMode

UI authentication mode for kopia server start. Controller-agnostic mirror of the api crate’s ServerAuth (this crate has no kube dependency).

Functions

split_policy_scopes

Split PolicyArgs into the path-scoped part and an optional identity-scoped part. kopia rejects --max-parallel-snapshots on a path-scoped policy (“max parallel snapshots cannot be specified for paths, only global, username@hostname or @hostname” — the policy_knobs e2e regression), so that one knob must be applied in a second policy set against the bare username@hostname identity. Pure.