Documentation
¶
Overview ¶
Package cacheroot owns the layout of flate's on-disk cache. Every other package — fetchers, baseline materialization, GC, helm — asks a Layout for the path of the subtree it operates on; nothing else constructs those paths by hand. The intent is that renaming a subdirectory means editing one method here, not chasing string literals across seven files (and silently breaking the sweeper in the process).
Layout is a zero-cost value type. Construct via New(root) or Layout{Root: …}; pass by value freely. The zero value (Root == "") is valid and means "no persistent cache"; callers that skip materialization for empty roots guard the Root field themselves.
Index ¶
- Constants
- func Default() string
- type Layout
- func (l Layout) Baseline(commitSHA string) string
- func (l Layout) Baselines() string
- func (l Layout) Blob(digest string) string
- func (l Layout) Blobs() string
- func (l Layout) GitMirror(urlHash string) string
- func (l Layout) GitMirrors() string
- func (l Layout) HelmTmp() string
- func (l Layout) RefsCategory(name string) string
- func (l Layout) RefsRoot() string
- func (l Layout) RenderHelmCache() string
- func (l Layout) SourceSlot(slug, hash string) string
- func (l Layout) Sources() string
- func (l Layout) Stage() string
- func (l Layout) StageEntry(fingerprint string) string
Constants ¶
const ( SourcesDir = "sources" BaselinesDir = "baselines" BlobsDir = "blobs" BlobsAlgo = "sha256" RefsDir = "refs" GitMirrorsDir = "git-mirrors" HelmTmpDir = "helm-tmp" StageDir = "stage" // RenderHelmCacheDir holds the persisted helm template-output // cache. Entries are sharded `<root>/render/helm/<hex[:2]>/<hex>` // where <hex> is the full sha256 of the template-cache key. Content // is gzipped rendered manifest bytes. Cross-process safe via atomic // rename; eviction is mtime-LRU bounded by the caller's byte cap. RenderHelmCacheDir = "render/helm" )
Subdirectory names. Exported so audit tooling can grep for which packages touch a given subtree without chasing raw string literals. Writers and the sweeper consume these via Layout methods, not directly.
Variables ¶
This section is empty.
Functions ¶
func Default ¶
func Default() string
Default returns the on-disk cache root for embedders that don't override it. Prefers the OS user cache dir ($XDG_CACHE_HOME on Linux, ~/Library/Caches on macOS, %LocalAppData% on Windows) with a "flate" subdir, so caches survive reboots and OS tmpfs cleanups. Falls back to $TMPDIR/flate-cache only when UserCacheDir errors (HOME unset, etc.).
One canonical implementation here; the CLI and the orchestrator both consume it, and tests that want a deterministic root pass an explicit Root via New(...) or Layout{Root: …}.
Types ¶
type Layout ¶
type Layout struct {
// Root is the on-disk cache root (typically $XDG_CACHE_HOME/flate
// or the user-supplied --cache-dir override).
Root string
}
Layout describes where the various caches live under a single root. All methods return absolute paths derived from Root + a constant subdirectory name. Methods that take a key (slug, hash, digest, …) append it; methods that return a parent directory are the GC and listing entry points.
func New ¶
New cleans root and returns a Layout. Prefer New over Layout{Root:} to ensure Root is canonical; the path methods skip a redundant filepath.Clean pass when Root is already clean.
func (Layout) Baseline ¶
Baseline returns the on-disk path for a baseline tree keyed by its commit sha.
func (Layout) Baselines ¶
Baselines returns the parent directory of every materialized baseline tree.
func (Layout) Blob ¶
Blob returns the on-disk directory for a single blob keyed by its hex sha256 digest.
func (Layout) Blobs ¶
Blobs returns the parent of every content-addressed blob. Always includes the algorithm segment so blobs/sha512/ etc. can land here later without rewriting the GC's walk.
func (Layout) GitMirror ¶
GitMirror returns the on-disk path for a bare mirror keyed by the stable hash of an upstream URL.
func (Layout) GitMirrors ¶
GitMirrors returns the parent of every bare git mirror.
func (Layout) HelmTmp ¶
HelmTmp returns the scratch directory the HelmChart fetcher uses for transient writes (index.yaml downloads, TLS cert materialization).
func (Layout) RefsCategory ¶
RefsCategory carves out a subdirectory under refs/ for one caller's identity→digest mapping. The first arg is a stable name (e.g. "chart-tarballs", "git-revisions") shared between the writer and any introspection tooling.
func (Layout) RefsRoot ¶
RefsRoot returns the parent of every refs table. Walked by GC to clean dangling pointers.
func (Layout) RenderHelmCache ¶
RenderHelmCache returns the parent directory of the persisted helm template-output cache. Entries live under sharded subdirs keyed by the first two hex chars of the cache key; the disk layer in pkg/helm owns the layout below this root.
func (Layout) SourceSlot ¶
SourceSlot returns the on-disk slot for a given (slug, hash) pair. slug is a human-readable repo name; hash is the content-keyed identifier source.Cache computes from (url, ref, authID).
func (Layout) Sources ¶
Sources returns the parent directory of every source slot. Used by GC's age sweep and listing tools.
func (Layout) Stage ¶
Stage returns the kustomize staging root. Two consumers share it:
- Per-process scratch stages land as flate-stage-<rand> children (legacy fallback for sources without a content-addressable fingerprint).
- Persistent content-addressed stages land at <stage>/<digest[:2]>/<digest>/ keyed by the source artifact's fingerprint (git SHA, OCI digest…).
The two-char fan-out prefix keeps any one subdir below typical FS dirent limits and never collides with the `flate-stage-` legacy prefix.
func (Layout) StageEntry ¶
StageEntry returns the on-disk persistent stage directory for the given source fingerprint. The fingerprint must be a non-empty printable token (commit SHA, OCI digest, content hash); callers fall back to per-process staging when no fingerprint is available.
Source Files