cache

Documentation

Overview

Package cache owns deterministic persistent-cache identity and storage.

Index

• Constants
• Variables
• type Component
• type ComponentKind
• type Digest
  • func DigestOf(value []byte) Digest
• type Key
  • func BuildKey(input KeyInput) (Key, error)
  • func (k Key) String() string
• type KeyInput
• type PruneOptions
• type PruneResult
• type RuleInput
• type Store
  • func Open(path string) (*Store, error)
  • func OpenValidated(path string, validate func(string) error) (*Store, error)
  • func (s *Store) Close() error
  • func (s *Store) Get(ctx context.Context, key Key) ([]byte, bool, error)
  • func (s *Store) Prune(ctx context.Context, options PruneOptions) (PruneResult, error)
  • func (s *Store) Put(ctx context.Context, key Key, payload []byte) (resultErr error)

Constants

const (

	// MaxEntrySize bounds one decoded cache value.
	MaxEntrySize = 16 << 20
)

Variables

var ErrConflict = errors.New("cache entry conflicts with an existing value")

ErrConflict reports two valid values for one deterministic cache key.

Types

type Component

type Component struct {
	Kind     ComponentKind
	Identity string
	Digest   Digest
}

Component binds one named input to its exact digest.

type ComponentKind

type ComponentKind string

ComponentKind identifies one result-changing input class.

const (
	ComponentSource           ComponentKind = "source"
	ComponentModule           ComponentKind = "module"
	ComponentWorkspace        ComponentKind = "workspace"
	ComponentOverlay          ComponentKind = "overlay"
	ComponentBuildSelection   ComponentKind = "build-selection"
	ComponentEnvironment      ComponentKind = "environment"
	ComponentDependencyExport ComponentKind = "dependency-export"
	ComponentFact             ComponentKind = "fact"
)

type Digest

type Digest [sha256.Size]byte

Digest is one SHA-256 identity used as a cache-key component.

func DigestOf

func DigestOf(value []byte) Digest

DigestOf returns the SHA-256 digest of exact bytes.

type Key

type Key [sha256.Size]byte

Key is one complete cache identity.

func BuildKey

func BuildKey(input KeyInput) (Key, error)

BuildKey validates and canonically hashes one complete input set.

func (Key) String

func (k Key) String() string

String returns the lowercase hexadecimal key.

type KeyInput

type KeyInput struct {
	Namespace       string
	ToolVersion     string
	BuildGoVersion  string
	SourceGoVersion string
	Configuration   Digest
	Rules           []RuleInput
	BuildTags       []string
	GOOS            string
	GOARCH          string
	CGOEnabled      bool
	FormatterMode   string
	Components      []Component
}

KeyInput contains every explicit result-changing input selected by a cache consumer for one result namespace. It performs no ambient environment lookup.

type PruneOptions

type PruneOptions struct {
	MaxEntries           int
	MaxBytes             int64
	StaleTemporaryBefore time.Time
}

PruneOptions bounds retained canonical entries and may remove publication temporaries older than an explicit cutoff. A zero size field leaves that dimension unlimited; at least one positive size limit is required.

type PruneResult

type PruneResult struct {
	EntriesBefore    int
	BytesBefore      int64
	EntriesRemoved   int
	BytesRemoved     int64
	CorruptRemoved   int
	TemporaryRemoved int
	EntriesAfter     int
	BytesAfter       int64
}

PruneResult reports one best-effort snapshot of canonical cache entries. Concurrent stores may change the root after it is scanned.

type RuleInput

type RuleInput struct {
	ID       string
	Severity string
	Options  Digest
}

RuleInput binds one enabled rule and severity to its canonical options.

type Store

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

Store is one rooted, content-verifying persistent cache.

func Open

func Open(path string) (*Store, error)

Open creates or opens one normalized absolute cache root.

func OpenValidated

func OpenValidated(path string, validate func(string) error) (*Store, error)

OpenValidated resolves a cache root, validates that immutable target, and then opens or creates it without following mutable path components. The validator runs before any directory is created.

func (*Store) Close

func (s *Store) Close() error

Close releases the rooted cache handle.

func (*Store) Get

func (s *Store) Get(ctx context.Context, key Key) ([]byte, bool, error)

Get returns an independently owned verified payload. Missing and corrupt entries are cache misses so callers can recompute them.

func (*Store) Prune

func (s *Store) Prune(ctx context.Context, options PruneOptions) (PruneResult, error)

Prune removes eligible stale publication temporaries and canonical corrupt entries, then evicts the oldest valid entries until both configured limits are satisfied. Publication time is represented by file modification time; equal times are ordered by key.

func (*Store) Put

func (s *Store) Put(ctx context.Context, key Key, payload []byte) (resultErr error)

Put atomically publishes one verified payload. A valid different value for the same key fails instead of hiding nondeterministic computation.