registryprune

type BlobGC struct {
	Podman PodRunner
	// HostID is the host carrying the registry.
	HostID string
	// RegistryPod is the podman pod name of the managed registry instance.
	// Lifecycle is native podman, not systemd: podman-api speaks libpod over
	// an SSH tunnel and has no shell on the far end, and the quadlet's
	// Restart=always would have systemd restart the registry mid-GC anyway.
	RegistryPod string
	// RegistryContainer is the container to measure storage size in. Empty
	// disables sizing; sizing never fails the job either way.
	RegistryContainer string
	// StoragePath is the registry storage directory ON THE HOST, hostPath-
	// mounted into the GC pod. Must be absolute.
	StoragePath string

	// MountPath is where StoragePath is mounted inside the GC POD. It is not
	// where the registry container mounts it — see SizePath, which is measured
	// in a different container and is deliberately a separate field. The two
	// coincide only because both default to /var/lib/registry.
	MountPath string
	// SizePath is the storage directory as seen inside the REGISTRY container
	// (its `rootdirectory`), used only for `du`. Defaults to
	// /var/lib/registry — NOT to MountPath, which would silently re-couple
	// the two and make sizing measure a path that does not exist in the
	// registry container the moment MountPath is configured.
	SizePath string

	// ConfigPath, Image, PodName and Timeout all default; see the default*
	// constants.
	ConfigPath string
	Image      string
	// PodName is the one-shot GC pod's name. It must NOT be the registry's own
	// pod name; see validate.
	PodName string
	Timeout time.Duration
}

type Class string

type Config struct {
	// RegistryHosts are every spelling of the registry being pruned as it may
	// appear in an image reference (e.g. "reg.example:5000", "reg.example",
	// "100.64.0.23:5000"). They are what separate our refs from foreign ones;
	// an empty list aborts, because without one a host-qualified foreign ref
	// cannot be told from one of ours.
	RegistryHosts []string
	// MaxSnapshotAge bounds how stale a host's inventory snapshot may be. Must
	// be positive — a zero value is treated as unconfigured and aborts, rather
	// than silently disabling the staleness check.
	MaxSnapshotAge time.Duration
	// Now is a test seam; defaults to time.Now.
	Now func() time.Time
}

type Handler struct {
	// Registry is the full client, including Delete. Note that the in-use
	// pass is handed only the read-only ManifestResolver slice of it, so no
	// bug in the protection computation can reach a delete.
	Registry  imgregistry.Client
	Hosts     HostEnumerator
	Inventory InventorySource
	Specs     SpecSource
	Config    Config
	Metrics   Metrics // optional

	// BlobGC is Stage B (blob reclamation). nil disables it entirely, which is
	// Stage A only: manifests unlinked, blobs left recoverable. See blobgc.go.
	BlobGC *BlobGC
	// contains filtered or unexported fields
}

type HostEnumerator interface {
	Hosts() []config.Host
}

type InUseSet struct {
	// Valid is true only on a set BuildInUseSet returned without error. The
	// zero value, and every aborted return, is false. Check it before acting:
	// an aborted set answers Has() false for every digest in the registry, so
	// a caller that logs the error and carries on would delete all of it.
	Valid   bool
	Digests map[string]struct{}
	// NonDigestObserved names running containers whose observed image was not
	// digest-form, i.e. podman gave us an image ID rather than a manifest
	// digest and the entry we derived from it can never match anything in the
	// registry. Such a container is protected only by its ImageTag and by its
	// spec, so the gap must be recorded (a job step) rather than left silent.
	// Entries are "host/slug/container: <image>".
	NonDigestObserved []string
	// ForeignSkipped lists the image references skipped as belonging to some
	// other registry, deduped. A run that skips everything is a misconfigured
	// registry host, and must be visible rather than silent.
	ForeignSkipped []string
}

type InventorySource interface {
	ListAllInstancesWithMeta(ctx context.Context, host string) ([]instance.Observed, instance.Freshness, error)
}

type ManifestResolver interface {
	Catalog(ctx context.Context) ([]string, error)
	Manifest(ctx context.Context, repo, ref string) (imgregistry.Manifest, error)
}

type Metrics interface {
	// RunDone records a terminal run outcome ("succeeded", "failed",
	// "dry-run", "aborted").
	RunDone(result string)
	// ManifestsDeleted records manifests actually removed from repo.
	ManifestsDeleted(repo string, n int)
	// RepoSkipped records a repo skipped by the per-repo tripwire, with the
	// number of delete candidates that tripped it. This is the counter that
	// would have surfaced the 2026-08-02 incident within a tick instead of a
	// week.
	RepoSkipped(repo string, candidates int)
	// BytesReclaimed records the bytes Stage B's blob GC freed on disk. It is
	// called ONLY when the measurement is real (BlobGC.Result.Measured): an
	// unmeasured run must record nothing rather than zero, because "we could
	// not size the registry" and "the GC freed nothing" are different facts
	// and only one of them is a reason to look at the GC.
	BytesReclaimed(bytes int64)
}

type Payload struct {
	Policy Policy `json:"policy"`
	// DryRun performs the full classification and records every job step, and
	// issues ZERO deletes.
	DryRun bool `json:"dry_run"`
	// SkipBlobGC is the "--no-gc" equivalent: manifest deletion only, leaving
	// the blobs recoverable. Stage B (blob GC) is a separate component; this
	// field is the payload half of its gate.
	SkipBlobGC bool `json:"skip_blob_gc"`
}

type PodRunner interface {
	PlayKube(ctx context.Context, hostID, yaml string, replace bool, networks ...string) error
	WaitForPodCompletion(ctx context.Context, hostID, podName string, timeout time.Duration) (int, error)
	PodStop(ctx context.Context, hostID, name string) error
	PodStart(ctx context.Context, hostID, name string) error
	PodRemove(ctx context.Context, hostID, name string, force bool) error
	ContainerExec(ctx context.Context, hostID, container string, cmd []string) (podman.ExecResult, error)
}

type Policy struct {
	// ProtectedExact is a list of tag names that are always kept, matched
	// case-sensitively and exactly.
	ProtectedExact []string
	// CalVer matches calendar-versioned release tags (e.g. "2024.01.01").
	// Nil means no calver protection.
	CalVer *regexp.Regexp
	// ExtraPerRepo adds repo-specific protected-tag patterns on top of
	// ProtectedExact/CalVer. A repo with no entry gets no extra protection.
	ExtraPerRepo map[string]*regexp.Regexp
	// RetentionDays is how long a "feat-*" tag survives before it is
	// eligible for deletion, aged from the digest's config-blob .created.
	RetentionDays int
	// MaxDeletesPerRepo is the per-repo tripwire threshold. Not used by
	// Classify/Deletable directly — it is Task 5's concern — but it lives on
	// Policy because it is part of the same reviewable ruleset.
	MaxDeletesPerRepo int
	// DeleteUnrecognised opts a run into deleting ClassUnclassified tags. The
	// #66 fix: false by default, because some repos have no CI-enforced tag
	// vocabulary and ~13% of their tags are legitimate developer-branch
	// names indistinguishable, by pattern alone, from garbage.
	DeleteUnrecognised bool
}

type Result struct {
	Before    int64
	After     int64
	Reclaimed int64
	// Measured is true only when BOTH sizes were read. A false Measured means
	// the byte fields say nothing — they must not be reported as zero bytes
	// reclaimed.
	Measured bool
}

type Scheduler struct {
	Store store.JobStore
	// Interval is the run cadence. Zero or negative disables the scheduler
	// entirely (it never enqueues), rather than meaning "every tick".
	Interval time.Duration
	// Payload is evaluated once per enqueue. (The server does not re-parse
	// flags on SIGHUP — only hosts and the operator file are reloaded — so this
	// is a seam for a future reload, not one today.)
	Payload func() Payload
	Now     func() time.Time
	// contains filtered or unexported fields
}

type SpecSource interface {
	ListSpecKeys(ctx context.Context, host string) ([]store.SpecKey, error)
	GetSpec(ctx context.Context, host, template, slug string) (store.Spec, error)
}