diskwatch

type Clock interface {
	Now() time.Time
}

type Policy struct {
	// MinInterval is the shortest wait between two samples.
	MinInterval time.Duration
	// MaxInterval is the longest wait when nothing calls for a sooner one. A
	// walk costlier than MaxInterval/CostFactor still waits CostFactor times
	// its cost: the cost bound wins.
	MaxInterval time.Duration
	// FirstInterval is the wait after a sample with no growth history behind
	// it — the one taken at the start — when the tree is not near its limit.
	// Shorter than MaxInterval because until a second sample there is no rate
	// to schedule by, and the start of a run is when a workload that writes
	// fast has the most room to overshoot.
	FirstInterval time.Duration
	// CostFactor is how many times the last walk's duration the next sample
	// waits at least.
	CostFactor int
	// Deadline bounds one walk. A walk that misses it is unknown.
	Deadline time.Duration
}

type Root struct {
	// Path is the directory measured. It is not resolved: a symlink here is a
	// symlink, and is measured as one.
	Path string
	// Exclude names entries directly under Path that are not counted, such as
	// ".cloop". Deeper entries with the same name are counted: a fixture
	// directory called .cloop inside the workload's tree is the workload's.
	Exclude []string
	// Allowance is how many bytes of this root go uncounted. A tree whose
	// size at the start is not the workload's — a project's own .cloop/ —
	// counts only what it grows by; math.MaxInt64 counts none of it. Its own
	// size is still reported, in Usage.RootBytes.
	Allowance int64
	// Optional makes a root that does not exist, or is not a directory,
	// measure as empty rather than fail the measurement.
	Optional bool
}

type Sample struct {
	Bytes int64
	At    time.Time
	// Cost is how long the walk took.
	Cost time.Duration
}

type Usage struct {
	// Bytes is what counts against a limit: each root's allocated size beyond
	// its Allowance, summed.
	Bytes int64
	// RootBytes is each root's own allocated size, before any allowance, in
	// the order the roots were given. A walk that stopped early leaves the
	// roots it never reached at zero.
	RootBytes []int64
	// Entries is how many directory entries the walk visited.
	Entries int
	// Elapsed is how long the walk took, by the walker's clock.
	Elapsed time.Duration
	// MountsSkipped counts the mount points below a root that were left out.
	MountsSkipped int
	// Unreadable counts directories whose contents could not be listed, and
	// UnreadablePaths names the first few.
	Unreadable      int
	UnreadablePaths []string
}

type Walker struct {
	// Clock reads the time for the deadline; nil means the real clock.
	Clock Clock
	// Deadline bounds one Measure call; 0 means none.
	Deadline time.Duration
	// MountPoints returns the mount points below the given roots, keyed by
	// cleaned absolute path, and whether the mount table could be read at
	// all. Nil reads the process's own table, /proc/self/mountinfo on Linux;
	// tests inject theirs, because creating a mount needs a privilege CI does
	// not have.
	//
	// A readable table is the whole answer: a directory is a mount point
	// when the table lists it, whatever its st_dev. A device check would
	// skip every btrfs subvolume — each has a device number of its own, and
	// any user may create one in a directory they can write — so a workload
	// could put its data where no walk counts it. Only when the table cannot
	// be read does a change of device stand in for it.
	MountPoints func(roots []string) (map[string]bool, bool)
	// contains filtered or unexported fields
}

type Watchdog struct {
	// Roots are the trees measured together.
	Roots []Root
	// LimitBytes is the limit; a non-positive one makes Run return at once.
	LimitBytes int64
	// Walker measures; its Deadline is set from Policy.Deadline when zero.
	Walker Walker
	// Policy is the schedule; its zero value is DefaultPolicy.
	Policy Policy
	// Initial is the measurement taken before the workload started, which
	// schedules the first sample. Nil schedules it at MinInterval.
	Initial *Sample

	// Now and Sleep are the loop's clock. Sleep returns false when ctx ended
	// first. Nil means the real ones.
	Now   func() time.Time
	Sleep func(ctx context.Context, d time.Duration) bool
	// Measure takes one measurement; nil walks Roots with Walker on a
	// low-priority thread (LowPriority).
	Measure func(ctx context.Context) (Usage, error)

	// OnBreach is called with a measurement over the limit. It returns
	// whether the workload was stopped: Run returns if so, and samples again
	// at MinInterval if not — a stop that failed is a workload still writing.
	OnBreach func(u Usage, at time.Time) bool
	// OnUnknown is called for a measurement that did not complete and is not
	// already over the limit, with the wait before the next attempt. It is
	// the caller's to log: the sample is unknown, and never counts as under.
	OnUnknown func(err error, u Usage, next time.Duration)
}