buildcache

package
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 4, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package buildcache is the on-disk content-hash build cache (solution design D6, NFR-001): generated output keyed by SHA-256 of the source content, salted with everything else that shapes the output — toolchain version, resolved configuration, and the route-binding state. The salt is folded into the key, so a toolchain or config change orphans every old entry at once. The cache is an optimization, never a correctness dependency: a corrupt or unreadable entry is discarded and the unit rebuilt, and a miss is never an error.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DefaultDir

func DefaultDir(modRoot string) (dir string, ok bool)

DefaultDir returns the per-module cache directory under the user cache root: modules do not share entries, so one project's cache growth never slows another's lookups. ok is false when no user cache dir exists. GHTMX_CACHE_DIR overrides the root — tests isolate through it without disturbing XDG_CACHE_HOME, which the Go toolchain's own caches share.

func Salt

func Salt(parts ...string) []byte

Salt derives a cache salt from the parts that shape generated output. Parts are length-prefixed so no two part lists can collide.

Types

type Store

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

Store is one on-disk cache. A nil *Store is a valid always-miss cache, so callers never branch on cache availability.

func Open

func Open(dir string, salt []byte) (*Store, error)

Open returns a store rooted at dir with the given salt. The directory is created if missing; when the recorded salt differs from the given one the whole directory is wiped first — old-generation entries can never match again, so keeping them only grows the cache (this also sweeps any crashed writer's temp files). On error the caller should log and continue with a nil store — generation must not fail because the cache cannot.

func (*Store) Get

func (s *Store) Get(key [sha256.Size]byte) (payload []byte, ok bool)

Get returns the cached payload for key. A miss — absent, unreadable, or corrupt (which also deletes the entry) — returns ok false, never an error.

func (*Store) Key

func (s *Store) Key(unitID string, content []byte) [sha256.Size]byte

Key derives the cache key of one unit: the salt, the unit's identity (its path relative to the generation root, which itself participates in the salt — identical content in two files generates different output), and the source content.

func (*Store) Put

func (s *Store) Put(key [sha256.Size]byte, payload []byte) error

Put stores payload under key, atomically (temp file + rename), so a crashed writer can only ever leave a discardable temp file behind. Errors are returned for logging but the caller must treat them as non-fatal.

func (*Store) Stats

func (s *Store) Stats() (hits, misses, puts int64)

Stats reports the store's lifetime counters, for the timing report.

Jump to

Keyboard shortcuts

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