Documentation
¶
Overview ¶
Package cache acquires verified source bytes into immutable memory or OCI-backed filesystems.
Index ¶
- Constants
- func AcquisitionIdentity(input any) string
- func FileName(input fs.FS) string
- func MachineCredentialErr(cause error) error
- func NameBlob(name string, generation fs.FS) fs.FS
- func RecordInventory[T io.WriterTo](ctx context.Context, c *Cache, inventory AcceptedInventory[T]) error
- func RenderPersistenceDisabledReason() string
- type AcceptedInventory
- type ArchiveKey
- type BlobKey
- type Cache
- func (c *Cache) Acquire(ctx context.Context, key ArchiveKey, policyValue *Policy, ...) (fs.FS, ocispec.Descriptor, string, error)
- func (c *Cache) Blob(ctx context.Context, key BlobKey, policyValue *Policy, ...) (fs.FS, ocispec.Descriptor, string, error)
- func (c *Cache) CanPersistRenders() bool
- func (c *Cache) Close() error
- func (c *Cache) Directory() string
- func (c *Cache) Git(ctx context.Context, key GitKey, policyValue *Policy, ...) (*GitGeneration, string, error)
- func (c *Cache) ProducersForPaths(ctx context.Context, query []manifest.SourceEvidence) (map[manifest.NamedResource][]manifest.SourceEvidence, error)
- func (c *Cache) RenderMetadata(ctx context.Context, content, lookup string, work *manifest.AcquisitionWork) (RenderMetadata, error)
- type CacheError
- type GitGeneration
- type GitKey
- type Policy
- type ProducerInput
- type ProducerResult
- type RenderHistory
- type RenderMetadata
- type RenderMode
- type RetryConfig
- type SweepOpts
- type SweepResult
- type TerminalError
Constants ¶
const Forever time.Duration = -1
Forever retains a successfully resolved pin regardless of elapsed time.
Variables ¶
This section is empty.
Functions ¶
func AcquisitionIdentity ¶
AcquisitionIdentity reports the held generation and shaping of cache-owned filesystems. Anonymous inputs and wrappers have no acquisition authority.
func MachineCredentialErr ¶
MachineCredentialErr masks machine diagnostics while preserving typed causes.
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 (*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 ¶
CanPersistRenders reports whether the cache owner can persist accepted renders.
func (*Cache) Directory ¶
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 ¶
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 ¶
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 ¶
func (p ProducerInput) Work() *manifest.AcquisitionWork
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.
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.