cache

type Config struct {
	Dir string // clean read-cache root (the reclaimable, evictable cache/ tree)
	// StagingDir, when set, places the DURABLE write-back data — staging/ (the
	// only copy of an acked-but-not-yet-uploaded write) and corrupt/ (quarantined
	// acked writes) — on a separate filesystem from Dir. Empty = under Dir (the
	// original layout). Splitting them lets Dir live on fast/ephemeral storage
	// (instance-store NVMe) without weakening the "an acked write survives node
	// termination" guarantee: point StagingDir (and the WAL) at a persistent disk.
	StagingDir string
	MaxBytes   int64 // clean-cache size cap (0 = unlimited)
	MaxItems   int   // clean-cache item cap (0 = unlimited)
	// MinFreeFraction evicts the clean cache to keep at least this fraction of the
	// cache *filesystem* free (0 = disabled; e.g. 0.15 = treat the cache as full
	// once free space ≤ 15% of the volume). It lets the LRU self-size to each
	// node's disk without a hard-coded byte cap, and composes with MaxBytes (the
	// cache is trimmed to satisfy whichever bound bites first). Only the clean
	// cache is reclaimable — staging (undurable writes) is never evicted — so the
	// floor is best-effort when staging + other on-disk usage already exceed it.
	MinFreeFraction float64
	AutoUpload      bool          // run the background uploader (off → drain only on recover/Flush)
	UploadInterval  time.Duration // background drain cadence (default 1s)
	// UploadConcurrency bounds how many uploads a single drain runs in parallel
	// (≤1 = serial). It applies to BOTH drain paths: the batched path (backings
	// implementing chunkstore.BatchWriter) flushes up to this many ~pack-sized
	// batches at once; the per-slice fallback uploads up to this many slices at
	// once. On the high-latency -remote path serial uploads are round-trip-bound,
	// so a bounded pool multiplies throughput. This is INTRA-drain concurrency
	// only — the upload loop is still a single nudge-coalesced goroutine.
	UploadConcurrency int

	// OnCorrupt is invoked when a staging entry fails its checksum on drain.
	// The bytes are first quarantined (moved to corrupt/) so the acknowledged
	// write is preserved for forensics/manual recovery, then this fires with
	// the quarantine path. Use it to alert/log. If nil, Flush/Close surface
	// ErrStagingCorrupt instead; recovery on open never blocks the mount.
	OnCorrupt func(id uint64, quarantinePath string, cause error)

	// OnError is invoked when a background drain (driven by the upload loop or a
	// write nudge) fails. Those drains have no caller to return the error to, so
	// without a sink the failure would be swallowed. If nil, errors are logged
	// via slog.Default(). Synchronous drains (recover/Flush/Close) still return
	// their errors to the caller and do NOT route through OnError.
	OnError func(error)

	// Metrics, if set, records cache hit/miss and write-back upload counters and
	// exposes the live staging depth. nil disables instrumentation (all calls are
	// nil-safe).
	Metrics *metrics.Registry
}

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