snapimport

type ChildRef struct {
	APIVersion string `json:"apiVersion"`
	Kind       string `json:"kind"`
	Name       string `json:"name"`
}

type Config struct {
	// Namespace is the target namespace the snapshot tree is reconstructed into.
	Namespace string
	// InputDir is the root archive directory produced by `d8 snapshot download`.
	InputDir string
	// TTL is the DataImport TTL used for data-leaf imports.
	TTL string
	// Timeout bounds the per-node readiness/completion waits.
	Timeout time.Duration
	// ControlRequestTimeout bounds each Kubernetes and aggregated-API request
	// independently of the longer readiness/completion polling budget.
	ControlRequestTimeout time.Duration
	// PollInterval is the readiness polling cadence.
	PollInterval time.Duration

	// SelectedNodeKind restricts the import to a single node subtree when non-empty.
	// After BuildPlan the plan is filtered to the selected node and its descendants.
	// The selected node becomes the import root for waitRootReady; it must be a core
	// Snapshot or a CSI VolumeSnapshot data leaf (domain aggregators are rejected).
	SelectedNodeKind string
	// SelectedNodeName is the name of the selected node. Required when SelectedNodeKind is set.
	SelectedNodeName string

	// Uploader posts manifests-and-children-refs-upload (aggregated API).
	Uploader ManifestUploader
	// Volumes imports data-leaf volume bytes (DataImport + HTTP upload).
	Volumes VolumeImporter
	// Dynamic creates import-mode CRs and reads readiness status.
	Dynamic dynamic.Interface
	// Workers is the maximum number of data-leaf volume uploads to run concurrently in
	// pass 2b. Defaults to 5 when zero. Block-volume uploads stream-decode directly into
	// the PUT (see snapimport.putBlock), so raising Workers no longer multiplies temporary
	// disk usage — only per-worker in-memory codec buffers.
	Workers int
	// AllowExisting, when true, downgrades the namespace preflight conflict check to a
	// warning instead of an error. Import-mode markers from a prior run of this import
	// are never treated as conflicts regardless of this flag. When false (default), the
	// run aborts before any cluster mutation if conflicting non-import-mode objects exist.
	AllowExisting bool
	// AllowUnauthenticatedLegacy permits pre-version snapshot.yaml metadata that has no
	// metadata checksum. The default rejects it as a possible version-downgrade attack.
	AllowUnauthenticatedLegacy bool
	// Mapper resolves node GVKs to resources.
	Mapper meta.RESTMapper
	// Log receives progress output.
	Log *slog.Logger
	// Progress, when non-nil, receives per-stream byte increments for each data-leaf
	// volume upload. Each leaf gets its own Stream; nil disables progress reporting
	// and leaves upload behaviour unchanged.
	Progress progress.Sink
	// contains filtered or unexported fields
}

type ManifestUploader interface {
	UploadManifests(ctx context.Context, ref aggapi.NodeRef, body []byte) ([]byte, error)
}

type PlanLimits struct {
	MaxDepth              int
	MaxNodes              int
	MaxManifestBytes      int64
	MaxTotalMetadataBytes int64
	MaxManifestsPerNode   int
}

type PlannedNode struct {
	// Dir is the absolute path of the node directory in the archive.
	Dir string
	// APIVersion/Kind/Name identify the snapshot CR for this node (from snapshot.yaml).
	APIVersion string
	Kind       string
	Name       string
	// SourceNamespace is the namespace recorded in the archive (informational; the import
	// always targets the user-supplied namespace).
	SourceNamespace string
	// Manifests are the node's own captured manifests (from manifests/), the same shape
	// the server returned from manifests-download.
	Manifests []unstructured.Unstructured
	// Children are the direct child snapshot refs (from snapshots/<child>/snapshot.yaml).
	Children []ChildRef
	// DataFile is the absolute path to the node's single-volume block data file
	// (data.bin[.<ext>]) when present; empty when the node carries no importable
	// block volume data.
	DataFile string
	// Ext is DataFile's codec extension, resolved by
	// archive.ClassifyBlockPayload alongside DataFile: "" for the raw/none
	// codec, ".zst", ".gz", or ".lz4" — matching compress.Codec.Ext. Callers
	// MUST use this field instead of filepath.Ext(DataFile): filepath.Ext on
	// the raw name "data.bin" returns ".bin", not "" (see
	// archive.BlockPayload.Ext's doc comment). Empty when HasBlockData() is
	// false.
	Ext string
	// FilesystemData is true when the node carries filesystem-volume data (data.tar).
	FilesystemData bool
	// TarFile is the absolute path to the node's filesystem-volume data file (data.tar).
	// It is always set when FilesystemData is true.
	TarFile string
	// SourceObjectRef carries the structured spec.sourceRef from a domain snapshot CR
	// ({apiVersion,kind,name} of the source object), read from snapshot.yaml. Nil for
	// core Snapshot nodes and CSI VolumeSnapshot data leaves.
	SourceObjectRef *archive.SourceObjectRef
	// StorageClassName/Size/VolumeMode are the captured scratch-volume parameters of this
	// leaf's volume, read from snapshot.yaml Volumes[0]. They feed the PopulateData
	// DataImport spec.storageParams on re-import (storageClassName and size are required by
	// the DataImport CRD; volumeMode is optional). Empty for structural/aggregator nodes
	// that own no volume data.
	StorageClassName string
	Size             string
	VolumeMode       string
	// NodeChecksum is the full checksum verified by the archive integrity preflight.
	NodeChecksum string
	// SizeBytes is Size parsed once into its canonical byte count before cluster mutation.
	SizeBytes int64
	// PayloadKind and Codec are the classified on-disk upload representation.
	PayloadKind string
	Codec       string
	// DataImportIdentity is the versioned full content identity used to qualify and
	// validate the shared DataImport object.
	DataImportIdentity string
	// contains filtered or unexported fields
}

type VolumeImporter interface {
	// DataImportName returns the deterministic identity-qualified DataImport name for the leaf.
	// The DataImport is created bottom-up immediately before its upload — its TTL is an idle
	// timer that starts at importer-pod start, so a freshly created importer must not sit
	// idle waiting for earlier siblings to finish.
	DataImportName(leaf PlannedNode) string
	// EnsureDataImport creates (idempotently) the DataImport for the leaf and returns its name.
	EnsureDataImport(ctx context.Context, leaf PlannedNode, namespace string) (string, error)
	// UploadVolumeData waits for the DataImport to become ready, streams the leaf's block
	// or filesystem data, finalises, and waits for completion. onProgress, when non-nil, is
	// called as raw bytes become known durable, including a validated server-side resume
	// prefix and each chunk or file upload; nil disables progress reporting and leaves upload
	// behaviour unchanged. setTotal, when non-nil, is
	// called with the expected total byte count: once, before any bytes are sent, on the
	// block path (the total is known up front from leaf.Size); progressively, with a
	// growing running sum as each file's exact size becomes known, on the filesystem path
	// (see sendVolumeData for why an accurate a-priori FS total is not free). activate, when
	// non-nil, is called at least once but ONLY when a real transfer occurs — never on a
	// leaf whose upload is entirely a server-side skip (offset==totalSize on the block HEAD,
	// or every file already done on the filesystem HEAD) — so the caller's progress stream
	// can distinguish a genuine transfer from a full resume-skip (see progress.Stream.Activate).
	UploadVolumeData(ctx context.Context, leaf PlannedNode, diName, namespace string, setTotal func(int64), onProgress func(int), activate func()) error
}