diskguard

package
v0.22.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 14, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package diskguard reclaims disk space from cachestore.CacheStore instances under pressure: it groups stores by the filesystem their Path() resolves to, reads point-in-time capacity via StatFor, and walks cachestore's tier ladder (or a store's own configured budget) filesystem by filesystem until TargetFree is met or every allowed tier has run. Threshold parsing (percentages and absolute sizes) lives in the leaf package internal/bytesize, imported by both this package and internal/config.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config

type Config struct {
	Enabled             bool
	MinFree, TargetFree bytesize.Threshold
	MaxTier             cachestore.Tier
}

Config configures a Guard: whether it runs at all, the free-space floor that triggers reclaim and the level it reclaims back up to, and the highest tier it is allowed to reach while doing so.

type FSStat

type FSStat struct {
	ID         string
	TotalBytes uint64
	FreeBytes  uint64
}

FSStat is a point-in-time capacity snapshot for one filesystem. ID is stable across every path mounted on that filesystem, so callers group by ID (see Guard.statByFilesystem) rather than by path — usage is measured and reclaimed per filesystem, not per store.

func StatFor

func StatFor(path string) (FSStat, error)

StatFor reports capacity for the filesystem containing path.

type Guard

type Guard struct {
	// contains filtered or unexported fields
}

Guard decides when to reclaim disk space, from which cachestore.CacheStore stores, in what order, and when to stop. It runs two independent mechanisms on every Sweep: a per-store budget check (enforceBudgets — runs regardless of disk pressure, unbounded by MaxTier), and a disk-pressure tier ladder (sweepFilesystem — runs only when a filesystem's free space has dropped below MinFree, and never reclaims past MaxTier).

Neither mechanism consults a store's Enabled(). Enabled() means "run this store's own routine periodic cleanup", not "never touch this even under disk pressure" — the periodic sweepers in cmd/runner gate on it, but the guard reclaims from every configured store regardless, because refusing to touch a store the operator merely left off its routine schedule would leave the guard unable to reclaim anything on a stock config (prune and buildx-cleanup default off since v0.4). A host whose disk this guard must never touch at all should set `[disk] guard = false`, not rely on a per-store Enabled() it was never designed to satisfy.

func New

func New(cfg Config, stores []cachestore.CacheStore, statFn func(string) (FSStat, error), logger *slog.Logger) *Guard

New constructs a Guard. statFn is injected rather than the package's own StatFor being called directly so tests can fake filesystem stats without touching a real mount; production callers pass StatFor itself.

func (*Guard) NeedsReclaim

func (g *Guard) NeedsReclaim() (bool, error)

NeedsReclaim reports whether any store's filesystem is currently below MinFree. It is the cheap pre-job-start check: one statfs per distinct filesystem, no Measure calls (Measure can walk an entire volume) and no reclaiming — callers that get true back are expected to run Sweep themselves before proceeding.

If statfs failed for every configured store, NeedsReclaim returns an error instead of a verdict, rather than silently reporting "false". This is the pre-job gate whose entire reason to exist is stopping a host from filling up mid-build, so reporting "healthy" when it actually has no idea would be the worst available failure mode — indistinguishable from the disk genuinely being fine. The bool returned alongside the error is true, not the zero value, as a second line of defense for a caller that inspects it without checking the error first. A partial failure — at least one filesystem still statfs-able — is unaffected: it still returns a real verdict from what it could read, exactly as before.

NeedsReclaim does not take sweepMu and is safe to call concurrently with itself and with Sweep: g.cfg and g.stores are fixed after New, and statByFilesystem only calls statFn — a stateless syscall, not a store's Reclaim or Measure — so there is no shared mutable state here for a lock to protect.

func (*Guard) Sweep

func (g *Guard) Sweep(ctx context.Context) error

Sweep runs the budget-enforcement pass and then the disk-pressure tier ladder, filesystem by filesystem. It always returns nil: every failure mode below (a store's statfs, Measure, or Reclaim call failing) is logged and skipped rather than propagated, so one misbehaving store or filesystem never stops the sweep from doing what it can for the rest.

Safe for concurrent callers, which is not hypothetical: the periodic ticker in cmd/runner and every scale set's pre-job-start check (controller.WithDiskChecker) share one Guard instance and can each call Sweep from their own goroutine (see startDiskGuard/runScaleSetController in cmd/runner/main.go). The store-level work Sweep drives — daemon prunes, helper containers walking and deleting volume contents — is not safe to run twice at once: two `du; find -delete; du` passes over one volume each measure the other's deletions, and Docker's daemon-side prune lock rejects the second caller outright ("a prune operation is already running"), which this guard would read as "that tier freed nothing" and escalate past.

sweepMu is not what protects against that, and never could: cmd/runner gives the same store instances to the periodic sweepers as to this guard, and those sweepers do not go through Sweep at all. Each store serializes its own Measure/Reclaim instead, so any two callers of one store exclude each other regardless of which path they arrived by — see cachestore.serialized. sweepMu's remaining job is narrower: keeping one Sweep from redundantly walking the whole tier ladder while another is already walking it.

sweepMu.TryLock, not Lock: a sweep already in flight is already addressing whatever pressure triggered this call, so a second caller has nothing to gain by waiting for it — only latency stacked onto the job-start path this guard exists to keep unblocked (the controller's pre-job-start check, controller.WithDiskChecker, logs a reclaim failure or timeout and starts the runner anyway, never refusing service). A concurrent caller that finds a sweep already in progress logs that and returns nil immediately instead of queuing behind it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL