diskguard

package

v0.8.0 Latest Latest Go to latest Published: Oct 21, 2026 License: Apache-2.0 Imports: 12 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/GLINCKER/levelrail

Links

Open Source Insights

Documentation ¶

Overview ¶

Package diskguard watches free space on the volumes the platform writes to, refuses risky operations before they fill a disk and keeps a reserve file so SQLite can still commit when space runs out.

Index ¶

Constants
func DockerRootFromEnv(lookup func(string) (string, bool)) string
func IsNoSpace(err error) bool
func SystemStat(path string) (free, total int64, err error)
type Guard
- func New(dataDir, dockerRoot string, th Thresholds, stat StatFunc, logger *slog.Logger) *Guard
type Level
type LowDiskError
- func (e *LowDiskError) Error() string
type Op
type StatFunc
type Status
type Thresholds
- func ThresholdsFromEnv(lookup func(string) (string, bool)) Thresholds
type Volume

Constants ¶

View Source

const (
	EnvLowFreeMB      = "APP_DISK_LOW_FREE_MB"
	EnvCriticalFreeMB = "APP_DISK_CRITICAL_FREE_MB"
	EnvReserveMB      = "APP_DISK_RESERVE_MB"
	EnvDockerRoot     = "APP_DISK_DOCKER_ROOT"
)

Env names for the thresholds, in MiB.

View Source

const (
	VolumeData   = "data"
	VolumeDocker = "docker"
)

Volume names.

View Source

const (

	// Interval is how often Run checks, kept low because a statfs call is cheap.
	Interval = time.Minute
)

Variables ¶

This section is empty.

Functions ¶

func DockerRootFromEnv ¶

func DockerRootFromEnv(lookup func(string) (string, bool)) string

DockerRootFromEnv returns the Docker root dir to watch.

func IsNoSpace ¶

func IsNoSpace(err error) bool

IsNoSpace reports whether err is an out-of-space write error.

func SystemStat ¶

func SystemStat(path string) (free, total int64, err error)

SystemStat is the real statfs reader.

Types ¶

type Guard ¶

type Guard struct {

	// Notify receives a plain-text message on a level change to low or critical.
	Notify func(ctx context.Context, text string)
	// contains filtered or unexported fields
}

Guard reads volumes on demand; Tick keeps the reserve and the alert state current.

func New ¶

func New(dataDir, dockerRoot string, th Thresholds, stat StatFunc, logger *slog.Logger) *Guard

New builds a Guard for the data dir and the Docker root. stat nil means the real reader.

func (*Guard) Refuse ¶

func (g *Guard) Refuse(op Op) error

Refuse returns a *LowDiskError when a volume op writes to is below the critical floor.

func (*Guard) ReleaseReserve ¶

func (g *Guard) ReleaseReserve() bool

ReleaseReserve drops the reserve now, for a caller that just saw ENOSPC.

func (*Guard) Run ¶

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

Run ticks on Interval until ctx ends, through the shared loop registry.

func (*Guard) Status ¶

func (g *Guard) Status() Status

Status reads every volume now. An unreadable volume is reported unknown, never as a refusal.

func (*Guard) Tick ¶

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

Tick refreshes the reserve and notifies once per drop into low or critical.

type Level ¶

type Level string

Level is how close a volume is to full.

const (
	LevelUnknown  Level = "unknown"
	LevelOK       Level = "ok"
	LevelLow      Level = "low"
	LevelCritical Level = "critical"
)

Levels, worst last.

type LowDiskError ¶

type LowDiskError struct {
	Op        Op
	Volume    string
	Path      string
	FreeBytes int64
	NeedBytes int64
}

LowDiskError is returned when an operation is refused for lack of space.

func (*LowDiskError) Error ¶

func (e *LowDiskError) Error() string

type Op ¶

type Op string

Op is a risky operation the guard can refuse.

const (
	OpBuild  Op = "build"
	OpPull   Op = "pull"
	OpBackup Op = "backup"
)

Operations that write a lot.

type StatFunc ¶

type StatFunc func(path string) (free, total int64, err error)

StatFunc reads free and total bytes for a path.

type Status ¶

type Status struct {
	Volumes      []Volume   `json:"volumes"`
	Thresholds   Thresholds `json:"thresholds"`
	Worst        Level      `json:"worst"`
	ReserveBytes int64      `json:"reserve_held_bytes"`
}

Status is a point-in-time reading.

type Thresholds ¶

type Thresholds struct {
	LowFree      int64 `json:"low_free_bytes"`
	CriticalFree int64 `json:"critical_free_bytes"`
	Reserve      int64 `json:"reserve_bytes"`
}

Thresholds are free-byte floors.

func ThresholdsFromEnv ¶

func ThresholdsFromEnv(lookup func(string) (string, bool)) Thresholds

ThresholdsFromEnv reads the thresholds, falling back to defaults on unset or invalid values.

type Volume ¶

type Volume struct {
	Name       string `json:"name"`
	Path       string `json:"path"`
	FreeBytes  int64  `json:"free_bytes"`
	TotalBytes int64  `json:"total_bytes"`
	Level      Level  `json:"level"`
}

Volume is one watched filesystem.

Source Files ¶

View all Source files

diskguard.go

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