cache

package
v0.7.3 Latest Latest
Warning

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

Go to latest
Published: Nov 9, 2026 License: AGPL-3.0 Imports: 56 Imported by: 0

Documentation

Overview

Package cache acquires verified source bytes into immutable memory or OCI-backed filesystems.

Index

Constants

View Source
const Forever time.Duration = -1

Forever retains a successfully resolved pin regardless of elapsed time.

Variables

This section is empty.

Functions

func AcquisitionIdentity

func AcquisitionIdentity(input any) string

AcquisitionIdentity reports the held generation and shaping of cache-owned filesystems. Anonymous inputs and wrappers have no acquisition authority.

func FileName

func FileName(input fs.FS) string

FileName returns the acquired payload path, or empty for a directory view.

func MachineCredentialErr

func MachineCredentialErr(cause error) error

MachineCredentialErr masks machine diagnostics while preserving typed causes.

func NameBlob

func NameBlob(name string, generation fs.FS) fs.FS

NameBlob gives an acquired Blob generation a filename and shaping identity.

func RecordInventory

func RecordInventory[T io.WriterTo](ctx context.Context, c *Cache, inventory AcceptedInventory[T]) error

RecordInventory atomically replaces accepted content and its searchable provenance.

func RenderPersistenceDisabledReason

func RenderPersistenceDisabledReason() string

RenderPersistenceDisabledReason returns why this binary cannot persist renders, or an empty string when it can.

Types

type AcceptedInventory

type AcceptedInventory[T io.WriterTo] struct {
	Key, Lookup, Acceptance string
	History                 RenderHistory
	Content                 T
	Work                    *manifest.AcquisitionWork
}

AcceptedInventory publishes one complete inventory and its source evidence.

type ArchiveKey

type ArchiveKey struct {
	// Content describes the producer inputs.
	Content any
	Ignore  string
	Policy  string
	// Required lists unprefixed descriptor annotation names; it does not affect identity.
	Required []string
}

ArchiveKey identifies an archive and its source-ignore policy. Content MUST include the effective credentials used by the producer.

type BlobKey

type BlobKey struct {
	// Content describes the producer inputs, or a nonempty identity for rendered content.
	Content any
	// Render selects pending work or accepted history; zero denotes source content.
	Render RenderMode
	// Validate checks a candidate against this caller's inputs under the acquisition lock.
	// Streams belong to the callback; the callback never affects identity.
	Validate func(context.Context, fs.FS) (bool, error)
	// Observe receives the validated candidate or nil before production, once per call.
	// Returning true completes this call without producing or publishing a generation.
	Observe func(context.Context, fs.FS) (bool, error)
	// Required lists unprefixed descriptor annotation names; it does not affect identity.
	Required []string
}

BlobKey identifies single-file content. Content MUST include the effective credentials used by the producer.

type Cache

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

Cache owns acquired generations until Close. Readers MUST finish before Close.

func New

func New(ctx context.Context, root string) (*Cache, error)

New selects backing once. An empty root allocates no files or directories.

func (*Cache) Acquire

func (c *Cache) Acquire(
	ctx context.Context,
	key ArchiveKey,
	policyValue *Policy,
	produce func(context.Context, ProducerInput) (ProducerResult, error),
) (fs.FS, ocispec.Descriptor, string, error)

Acquire publishes a complete archive or revalidates its previous generation after produce succeeds. Its acquisition identity is empty on failure.

func (*Cache) Blob

func (c *Cache) Blob(
	ctx context.Context,
	key BlobKey,
	policyValue *Policy,
	produce func(context.Context, ProducerInput) (ProducerResult, error),
) (fs.FS, ocispec.Descriptor, string, error)

Blob returns an immutable filesystem over a complete generation. A nil producer only looks up a fresh generation; zero Policy.MaxAge with a producer replaces the generation. Unchanged production retains the previous payload and replaces its upstream metadata. A successful generation rejected by Validate is returned once without being retained for reuse. Its acquisition identity is empty on failure.

func (*Cache) CanPersistRenders

func (c *Cache) CanPersistRenders() bool

CanPersistRenders reports whether the cache owner can persist accepted renders.

func (*Cache) Close

func (c *Cache) Close() error

Close releases this owner's share. It MUST follow all acquired readers.

func (*Cache) Directory

func (c *Cache) Directory() string

Directory returns the resolved disk boundary, or empty for a memory owner.

func (*Cache) Git

func (c *Cache) Git(
	ctx context.Context,
	key GitKey,
	policyValue *Policy,
	produce func(context.Context, storage.Storer, billy.Filesystem) (plumbing.Hash, error),
) (*GitGeneration, string, error)

Git acquires a private generation through the common freshness and publication path. Its acquisition identity is empty on failure.

func (*Cache) ProducersForPaths

func (c *Cache) ProducersForPaths(
	ctx context.Context,
	query []manifest.SourceEvidence,
) (map[manifest.NamedResource][]manifest.SourceEvidence, error)

ProducersForPaths returns producers whose accepted source paths reach the supplied changes. The result is positive admission evidence, never proof that an inventory remains complete.

func (*Cache) RenderMetadata

func (c *Cache) RenderMetadata(
	ctx context.Context,
	content, lookup string,
	work *manifest.AcquisitionWork,
) (RenderMetadata, error)

RenderMetadata returns the current descriptor and generation without opening the payload. Enabled reports whether this owner can persist renders. A nonempty lookup MUST identify Blob accepted history for this content; an empty lookup derives it.

type CacheError

type CacheError struct{ Err error } //nolint:revive // The public acquisition contract names CacheError.

CacheError identifies a cache operation failure, including failed persistence.

func (*CacheError) Error

func (e *CacheError) Error() string

func (*CacheError) Unwrap

func (e *CacheError) Unwrap() []error

type GitGeneration

type GitGeneration struct {
	Backing  billy.Filesystem
	Worktree billy.Filesystem
	Commit   plumbing.Hash
	// contains filtered or unexported fields
}

GitGeneration retains sealed object backing and any upstream recursive checkout. Every reader MUST construct its own storer; publication retains no producer handles.

type GitKey

type GitKey struct {
	Content           any
	Ref               string
	RecurseSubmodules bool
}

GitKey identifies a Git family, its normalized requested ref and recursion policy. Content MUST include the effective credentials used by the producer.

type Policy

type Policy struct {
	// Work borrows counters owned by this acquisition caller.
	Work *manifest.AcquisitionWork
	// HistoryWork borrows separate cells for accepted render history.
	HistoryWork *manifest.AcquisitionWork
	// Machine classifies producer failures before retry diagnostics and persistence.
	Machine bool
	// Admit runs before each production attempt's timeout and staged storage.
	// Success MUST return a non-nil release, called once after cleanup/publication.
	// On error the callback owns partial cleanup; cache failures do not retry or persist outcomes.
	Admit func(context.Context) (func(), error)
	// Timeout bounds each production attempt; nil adds no deadline.
	Timeout *time.Duration
	// MaxAge bounds freshness; Forever retains immutable pins.
	MaxAge time.Duration
	// Retry applies only to producer failures.
	Retry RetryConfig
}

Policy is the caller's immutable freshness, retry, admission and operation timeout policy.

type ProducerInput

type ProducerInput struct {
	io.Writer
	// contains filtered or unexported fields
}

ProducerInput writes new content or exposes the owner's last complete generation.

func (ProducerInput) Previous

func (p ProducerInput) Previous(ctx context.Context) (*ocispec.Descriptor, error)

Previous returns independent upstream metadata, or nil when no usable payload exists. It retains no open reader and MUST only be called during production.

func (ProducerInput) Work

Work returns the physical acquisition counters borrowed from the caller.

type ProducerResult

type ProducerResult struct {
	ocispec.Descriptor

	// Unchanged requires a usable previous payload and forbids writing new bytes.
	Unchanged bool
}

ProducerResult reports new bytes or successful validation of the previous payload.

type RenderHistory

type RenderHistory struct {
	Owner   manifest.NamedResource `json:"Owner"`
	Sources []manifest.SourceEvidence
}

RenderHistory supplies source paths associated with one accepted inventory.

type RenderMetadata

type RenderMetadata struct {
	Descriptor ocispec.Descriptor
	Identity   string
	Enabled    bool
}

RenderMetadata identifies the accepted generation without opening its payload.

type RenderMode

type RenderMode uint8

RenderMode identifies the acquisition phase of rendered content.

const (
	// RenderPending validates accepted history, then coalesces immutable work until Close.
	RenderPending RenderMode = iota + 1
	// RenderAccepted persists only complete accepted render history with identified backing.
	RenderAccepted
)

type RetryConfig

type RetryConfig struct {
	// Attempts includes the first try; values <= 1 disable retries.
	Attempts int
	// MinWait defaults to 750 milliseconds when nonpositive.
	MinWait time.Duration
	// MaxWait defaults to 15 minutes when nonpositive.
	MaxWait time.Duration
	// Jitter is a fraction in [0,1]; non-finite values disable jitter.
	Jitter float64
}

RetryConfig bounds producer attempts within one acquisition.

type SweepOpts

type SweepOpts struct {
	// MaxAge retires named tags whose payload mtime predates now-MaxAge.
	// Coalesced access timestamps allow one second of retention grace.
	// Zero disables age retirement; unreachable Git generations are always collected.
	MaxAge time.Duration
	// DryRun reports the selection without locking or changing the cache.
	DryRun bool
}

SweepOpts tunes Sweep's behavior.

type SweepResult

type SweepResult struct {
	// Removed lists selected tags and absolute Git-generation paths, sorted together.
	Removed []string
	// Bytes counts selected Git-generation bytes only. Upstream graph GC decides
	// blob reclamation; dry-run does not estimate reclaimed blob bytes.
	Bytes int64
	// Errors aggregates failures applying the selection.
	Errors []error
}

SweepResult summarizes Sweep's selection and any failures applying it.

func Sweep

func Sweep(ctx context.Context, root string, opts SweepOpts) (SweepResult, error)

Sweep retires unused named tags and collects unreachable Git generations. Destructive sweeps require exclusive store ownership; dry-run never writes.

type TerminalError

type TerminalError struct {
	// Err retains the typed cause and its diagnostic text.
	Err error
	// Attempted distinguishes producer exhaustion from a suppressed non-attempt.
	Attempted bool
}

TerminalError prevents an outer acquisition from repeating a completed sequence.

func (*TerminalError) Error

func (e *TerminalError) Error() string

Error preserves the underlying diagnostic.

func (*TerminalError) Unwrap

func (e *TerminalError) Unwrap() []error

Unwrap exposes the domain sentinel and the underlying cause.

Jump to

Keyboard shortcuts

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