Module expand 

Selector expansion: turning one SnapshotPolicy source into N concrete per-PVC backups (#346).

The model

A SnapshotPolicy source is exactly one of pvc, nfs, or pvcSelector. The first two name a single thing; the third matches many. Kopiur’s whole data model is built on one Snapshot CR = one mover Job = one kopia source path = one kopia manifest, owned via a finalizer — retention, restore, the catalog and the deletion policy all rest on that 1:1. So a selector is expanded into N ordinary Snapshot CRs, one per matched PVC, each of which is then indistinguishable from a hand-written single-PVC backup.

Expansion happens once, at mint time, in whichever component creates the CR — a SnapshotSchedule fire or kubectl kopiur snapshot now. A Snapshot never expands itself: a CR minting sibling CRs would re-enter the same reconciler for each child and break the one-shot run_decision discipline, and a SnapshotPolicy that minted invocations would collapse the recipe/invocation/schedule split the project is built around.

What was here before

Nothing. pvcSelector was schema-valid, admission-accepted, documented on six pages and shipped as deploy/examples/04-multi-pvc-selector.yaml — and no expansion code existed anywhere, so build_backup_run hit its _ => arm and returned invariant violated … This is likely a bug in kopiur. That is #346.

The restore side (#443)

Expansion is only half the story. A selector policy writes N kopia sources, one per member path; a RESTORE against that policy must read exactly ONE of them, chosen by the PVC it is filling. restore_source_path is that inverse: it re-derives a member’s path from the policy’s own sourcePathStrategy, so the restore’s kopia filter names the same path the backup wrote. Without it the filter is user@host: with no path, which matches EVERY member — and the newest of them wins, so one PVC could be filled with another PVC’s data.

It lives here, next to EffectiveSource::kopia_source_path and strategy_for, on purpose: the backup path and the restore path are then literally the same code, and the two strings cannot drift.

Structs

EffectiveSource

The single source one Snapshot actually backs up, after resolving spec.source (a fanned-out child) against the policy’s sources[].

ExpandedMember

One member of an expanded selector: the child’s name and the spec.source to stamp on it.

MintCell

One Snapshot to mint for a slot/invocation: its deterministic name, the source pin (for a pvcSelector member) and the repository pin (for a multi-repo fan-out child, NORMALIZED via normalized_repository_ref).

Enums

RestoreSourcePath

Where a restore’s kopia source path came from — the result of restore_source_path.

Functions

cache_pvc_name

The kopia-cache PVC name for one (policy, repository) cell.

effective_source

Resolve which source this Snapshot covers.

expand_sources

Pure. Expand one policy’s sources against an already-matched PVC set.

fanout_child_name

The deterministic name of the fanned-out Snapshot for one PVC.

fanout_child_name_for

The deterministic child Snapshot name for one (source-member, repository) cell of a fan-out — the general form behind fanout_child_name.

group_name

The shared VolumeGroupSnapshot name for one expansion in one namespace.

label_selector_string

Render a LabelSelector as the API server’s selector string.

mint_cells

Pure. Cross one policy’s expanded source members with its repository dimension (#368) into the exact set of Snapshots to mint for one slot or one snapshot now invocation. Lives here so the SnapshotSchedule reconciler and kubectl kopiur snapshot now mint byte-identical sets — a divergence would give the same recipe different children depending on who fired it.

populate_job_name

The deterministic name of the populate mover Job for one claiming PVC.

restore_source_path

The kopia source path a restore of target should read from policy (#443).

strategy_for

The sourcePathStrategy governing a source.