upload

type CleanupStats struct {
	// Sessions and ReservedBytes describe the declared reservations, not the
	// bytes currently allocated; the free-space budget is what bounds the
	// allocation those reservations imply.
	Sessions         int           `json:"sessions"`
	ReservedBytes    int64         `json:"reserved_bytes"`
	OldestSessionAge time.Duration `json:"oldest_session_age"`
	LastScan         time.Time     `json:"last_scan"`
	// LastScanDurationNS measures the most recent successful reservation scan,
	// excluding time spent waiting for the store lock. Fast scans can measure
	// zero on clocks with coarse resolution.
	LastScanDurationNS int64 `json:"last_scan_duration_ns"`
	// LastSuccess is the last cleanup pass that completed without error.
	LastSuccess time.Time `json:"last_success"`
	// LastError is the most recent cleanup failure, empty after a success.
	LastError string `json:"last_error,omitempty"`
	// ReclaimedFiles and ReclaimedBytes are running totals for the abandoned
	// scratch files and empty reservation directories that reconciliation has
	// removed since the process started.
	ReclaimedFiles int   `json:"reclaimed_files"`
	ReclaimedBytes int64 `json:"reclaimed_bytes"`
	// Contention reports how often the store lock refused a caller and how long
	// it was held. It is the evidence for whether the single lock needs
	// splitting, which is why it is measured before anything is changed; see
	// contention.go.
	Contention ContentionStats `json:"contention"`
}

type ContentionStats struct {
	// Busy counts refused lock acquisitions by operation: the direct evidence
	// of one caller blocking another.
	Busy map[string]int `json:"busy"`
	// Hold counts completed lock holds by operation, with total and worst-case
	// duration. Complete is the one to watch: it holds the lock across the whole
	// installation, which is the longest hold by construction.
	Hold map[string]OpTiming `json:"hold"`
}

type Finalizer func(Session) (Result, error)

type Handler struct {
	Store      *Store
	Finalizers map[Purpose]Finalizer
}

type Metadata struct {
	Purpose  Purpose `json:"purpose"`
	Size     int64   `json:"size"`
	Filename string  `json:"filename"`
}

type OpTiming struct {
	Count int           `json:"count"`
	Total time.Duration `json:"total"`
	Max   time.Duration `json:"max"`
}

type Purpose string

type Result struct {
	Message string
	Data    any
}

type Session struct {
	ID          string
	Metadata    Metadata
	Directory   string
	ArchivePath string
}

type Store struct {
	Root    string
	MaxSize int64
	// Zero values select 16 sessions, 8 GiB of reserved payload and 24 hours.
	MaxSessions  int
	MaxTotalSize int64
	TTL          time.Duration
	// FreeSpace reports the bytes available to this process on the filesystem
	// holding the store root. Nil selects the build-tagged platform query in
	// freespace_windows.go / freespace_unix.go / freespace_other.go; tests
	// inject a deterministic implementation so admission never depends on the
	// host's real disk.
	FreeSpace func(path string) (int64, error)
	// contains filtered or unexported fields
}