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.

ConnectOptions

Options for kopia repository connect beyond backend/cache selection. Copy + Default so the common read-write, non-persisted connect is ConnectOptions::default() — which produces byte-identical argv to a pre-ConnectOptions KopiaClient::repository_connect.

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).

SnapshotMigrateOptions

Options for kopia snapshot migrate --source-config <path> — logical (snapshot-level) replication from another repository into the CONNECTED one. See KopiaClient::snapshot_migrate for the execution contract.

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.

MigratePolicies

How kopia snapshot migrate treats kopia-side policies on the destination.

MigrateSources

Which source-repository snapshot sources kopia snapshot migrate copies.

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.