Documentation
¶
Overview ¶
Package prune is StageFreight's disk-GC lifecycle: it gives every SF-created artifact a default retention lifecycle so a CI runner never fills its disk from SF residue, while NEVER touching anything StageFreight cannot positively claim.
The invariant the whole package is built around:
StageFreight never needs to guess whether something belongs to someone else in order to reclaim space.
Ownership is established at the ARTIFACT level, never inferred from the daemon or host containing it. Three classes:
namespace — inside the SF cache root (cache/ + toolchains/): inherently SF-owned.
Every object there participates in a default lifecycle even when its
subsystem has no specialized policy (the backstop).
provenance — SF-created artifacts identified positively (the repo's own published
image streams, the sf-builder's cache via its own API).
declared — third-party artifacts the OPERATOR adopted by declaration
(build_cache.cleanup.prune.images.refs) — an authorization boundary,
never a confidence boundary. Requires cleanup enabled/--host-cleanup.
Anything not in those classes is left alone, in every daemon, always.
Index ¶
Constants ¶
const (
DefaultTarget = 0.80 // pressure gate
)
Engine defaults — behavior, not policy (deliberately NOT config; see the plan's "Rejected shapes"). Visible in every dry-run and the perform Disk GC box.
Variables ¶
This section is empty.
Functions ¶
func UsedFraction ¶
UsedFraction reports the used fraction of the filesystem containing path.
Types ¶
type Action ¶
type Action struct {
Kind Kind
Class Class
Label string // human label ("cache/go/build", "toolchains", …)
Path string // filesystem dir (evict-dir / toolchains root)
Reason string
MaxAge time.Duration // evict-dir: entries older are evicted
MaxSize int64 // evict-dir: then oldest-first down to this
Policy config.RetentionPolicy // toolchains / image-stream
Pins map[string]string // toolchains: tool → pinned constraint (protected)
Streams []string // image-stream: repo path suffixes (slugs) owned by this config
Templates []string // image-stream: the publish targets' tag templates (candidacy)
Refs []config.RetentionRef // declared-images: the operator's adoption list
Builder string // buildkit: builder name
KeepStore string // buildkit: --keep-storage
Until string // buildkit / host-residue: --filter until=
}
Action is one planned reclaim. The planner only plans — Execute mutates.
func Plan ¶
Plan computes the reclaim actions the ownership model + declared policy allow. cfg may be nil (running on a bare runner host with no .stagefreight.yml): the SF-owned namespace lifecycle still applies with engine defaults; provenance-class image streams and declared adoptions need the config that declares them. Pure planning — nothing is mutated.
type ActionResult ¶
type ActionResult struct {
Action Action
Items []string // what was (or would be) removed, human-labeled
Freed int64 // bytes freed (0 in dry-run and for daemon-side prunes that don't report)
Skipped string // non-fatal reason the action did nothing ("no docker daemon", …)
Err error
}
ActionResult is one executed (or previewed) action's outcome.
type Kind ¶
type Kind string
Kind selects the executor for an action.
const ( KindEvictDir Kind = "evict-dir" // age→size eviction of a cache subsystem dir KindToolchains Kind = "toolchains" // keep-N toolchain versions (policy grammar) KindImageStream Kind = "image-stream" // SF's own published generations, local daemon KindBuildkit Kind = "buildkit" // sf-builder cache via `docker buildx prune` KindDeclaredImages Kind = "declared-images" // operator-declared third-party eviction KindHostResidue Kind = "host-residue" // dangling layers + exited containers (authorized) )
type Options ¶
type Options struct {
CacheRoot string // SF cache mount root ("" = discover via caller)
Target float64 // pressure gate: plan only when used-fraction ≥ Target (0 = always plan)
HostCleanup bool // authorization: include declared/host actions (cleanup config or --host-cleanup)
}
Options steers a planning pass.
Source Files