retention

package

v0.15.0 Latest Latest Go to latest Published: Oct 27, 2026 License: MIT Imports: 21 Imported by: 0

Details

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

Repository

github.com/spfuzzylink/questlock

Links

Open Source Insights

Documentation ¶

Rendered for

Overview ¶

Package retention provides explicit storage policies and an immutable local cold-content store. It does not choose which application state is safe to archive, delete archives, call providers, or schedule background work.

Index ¶

Variables
type BlobRef
type Budget
- func Plan(c Config, x admission.Snapshot, now time.Time) Budget
type ColdStore
type Config
- func Decode(data []byte) (Config, error)
- func DefaultConfig(absColdDir string) Config
- func (c Config) Validate() error
type Event
type Inventory

Constants ¶

This section is empty.

Variables ¶

View Source

var (
	ErrUnavailable = errors.New("retention_unavailable")
	ErrIntegrity   = errors.New("retention_integrity")
	ErrBudget      = errors.New("retention_budget")
	ErrInvalid     = errors.New("retention_invalid")
)

Functions ¶

This section is empty.

Types ¶

type BlobRef ¶

type BlobRef struct {
	Digest      string `json:"sha256"`
	Size        int64  `json:"size"`
	StoredBytes int64  `json:"stored_bytes"`
}

type Budget ¶

type Budget struct {
	Items    int    `json:"items"`
	Bytes    int64  `json:"bytes"`
	Deferred bool   `json:"deferred"`
	Reason   string `json:"reason"`
}

Budget limits the next maintenance batch only. It does not change the eligibility rules for content or represent an OS resource reservation.

func Plan ¶

func Plan(c Config, x admission.Snapshot, now time.Time) Budget

Plan fails closed for invalid or stale adaptive signals. CPU load is normalized by the probe's load denominator, not mistaken for CPU percent. Memory estimates reserve headroom and allow overhead for compression and copies; they cannot guarantee allocation or enforce OS resource limits.

type ColdStore ¶

type ColdStore struct {
	Root     string
	MaxBytes int64
}

ColdStore stores immutable content-addressed gzip files in a private local directory. MaxBytes charges all regular data files, including unreferenced blobs, unknown files and interrupted temporary writes. It is a logical byte limit, not filesystem block accounting. There is deliberately no deletion API.

func (ColdStore) Inventory ¶

func (s ColdStore) Inventory(ctx context.Context) (Inventory, error)

Inventory uses bounded directory pages and fails closed on unsafe entries or excessive file counts. A missing directory is an empty inventory; no files or directories are created in that case.

func (ColdStore) Put ¶

func (s ColdStore) Put(ctx context.Context, content string) (BlobRef, error)

Put durably publishes one content-addressed file before returning its reference. A per-directory process lock serializes quota checks across stores and databases sharing the directory. An existing file is verified and never overwritten. A failed or canceled call can leave an unreferenced durable blob; callers must never infer that an error authorizes deleting its final name.

func (ColdStore) Read ¶

func (s ColdStore) Read(ctx context.Context, ref BlobRef) (string, error)

Read verifies the exact reference and bounded gzip member. Missing files, malformed members, changed content and trailing data all fail closed.

type Config ¶

type Config struct {
	Schema                  int    `json:"schema"`
	ColdDir                 string `json:"cold_dir"`
	HotHistoryDays          int    `json:"hot_history_days"`
	KeepRecentVersions      int    `json:"keep_recent_versions"`
	ArchiveCompletedCurrent bool   `json:"archive_completed_current"`
	MaxDatabaseBytes        int64  `json:"max_database_bytes"`
	MaxColdBytes            int64  `json:"max_cold_bytes"`
	BatchItems              int    `json:"batch_items"`
	BatchBytes              int64  `json:"batch_bytes"`
	Adaptive                bool   `json:"adaptive"`
	MinFreeMemoryBytes      int64  `json:"min_free_memory_bytes"`
	MemoryPercent           int64  `json:"memory_percent"`
	MaxCPULoadMilli         int64  `json:"max_cpu_load_milli"`
}

Config is a complete opt-in policy. MaxDatabaseBytes may be zero for an explicit unlimited hot database; cold storage always has a positive limit. Callers control when to run maintenance and whether to apply a proposed batch.

func Decode ¶

func Decode(data []byte) (Config, error)

Decode accepts one complete, bounded JSON object. Duplicate, missing, unknown and null fields are rejected, including explicitly false policy switches.

func DefaultConfig ¶

func DefaultConfig(absColdDir string) Config

func (Config) Validate ¶

func (c Config) Validate() error

type Event ¶

type Event struct {
	Operation string    `json:"operation"`
	Outcome   string    `json:"outcome"`
	ErrorCode string    `json:"error_code,omitempty"`
	StartedAt time.Time `json:"started_at"`
	EndedAt   time.Time `json:"ended_at"`
	Items     int64     `json:"items"`
	Bytes     int64     `json:"bytes"`
}

Event carries maintenance measurements only. It deliberately has no paths, content, digests, keys, tokens, exception messages or provider data.

type Inventory ¶

type Inventory struct {
	Bytes          int64 `json:"bytes"`
	Files          int64 `json:"files"`
	TemporaryBytes int64 `json:"temporary_bytes"`
}

Bytes and Files include all non-lock regular files; TemporaryBytes is the subset occupied by temporary files. Inventory never recursively follows paths.

Source Files ¶

View all Source files

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