cache

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 16 Imported by: 0

Documentation

Overview

Package cache stores downloaded artifacts and their scan results.

Index

Constants

View Source
const DefaultStaleAfterDays = 30

DefaultStaleAfterDays is the idle threshold applied when cache.local.stale_after_days is unset or zero.

Variables

This section is empty.

Functions

func AsArtifactCache added in v0.2.0

func AsArtifactCache(c Cache) gate.ArtifactCache

AsArtifactCache bridges a Cache to the narrower gate.ArtifactCache the proxy handler consumes (gate cannot import cache — see gate.ArtifactEntry).

Types

type Cache

type Cache interface {
	// Get returns the cached entry for ref, or (nil, false) on miss.
	Get(ref *gate.PackageRef) (*CacheEntry, bool)
	// Put copies the artifact at tmpPath into the cache store and records the scan result.
	Put(ref *gate.PackageRef, tmpPath string, scanClean bool, scanJSON string) error
	// Invalidate removes the cached entry and its artifact file for ref.
	Invalidate(ref *gate.PackageRef) error
	// MarkCVEChecked records a passed CVE re-check for ref at ts.
	MarkCVEChecked(ref *gate.PackageRef, ts time.Time) error
	// MarkMalwareChecked records a passed malware re-check for ref at ts.
	MarkMalwareChecked(ref *gate.PackageRef, ts time.Time) error
	// Stats returns aggregate cache statistics.
	Stats() (CacheStats, error)
	// Close stops background workers and releases the index.
	Close() error
}

Cache is the storage interface for package artifacts and scan results.

func New

func New(cfg config.CacheConfig) (Cache, error)

New constructs the cache backend selected by cfg.Backend. "" and "local" build a LocalCache; "s3" is reserved but not yet implemented (fail-fast rather than silently falling back to local).

type CacheEntry

type CacheEntry struct {
	// ArtifactPath is the absolute path to the cached file on disk.
	ArtifactPath string
	// ScanClean is true if all scanners passed.
	ScanClean bool
	// ScanJSON stores the serialized ScanResult for future inspection.
	ScanJSON  string
	StoredAt  time.Time
	HitCount  int64
	SizeBytes int64
	// LastCVECheck / LastMalwareCheck record when each gate last confirmed
	// this entry clean; lazy re-validation compares them to the configured TTLs.
	LastCVECheck     time.Time
	LastMalwareCheck time.Time
}

CacheEntry stores an artifact path and its scan results.

type CacheStats

type CacheStats struct {
	Entries   int64
	SizeBytes int64
	HitRatio  float64
	Evictions int64
	// StaleBytes is the total size of entries idle longer than the configured
	// staleness threshold — reclaimable via PurgeStale / console cleanup.
	StaleBytes int64
}

CacheStats holds aggregate statistics about the cache.

type Index

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

Index manages the SQLite-backed metadata index for the local cache.

func NewIndex

func NewIndex(path string) (*Index, error)

NewIndex opens (or creates) a SQLite database at path and applies the schema.

func (*Index) ApplyUsageBatch added in v1.1.0

func (idx *Index) ApplyUsageBatch(ctx context.Context, token string, deltas []UsageDelta) error

ApplyUsageBatch updates existing row identities and its latest retry receipt atomically. A retired row is an acknowledged no-op; it cannot be recreated.

func (*Index) Close

func (idx *Index) Close() error

Close releases the database connection.

func (*Index) Count

func (idx *Index) Count(ctx context.Context) (int64, error)

Count returns the total number of entries in the index.

func (*Index) Delete

func (idx *Index) Delete(ref *gate.PackageRef) (int64, error)

Delete removes an entry from the index, reporting how many rows matched (0 when the entry was already gone — callers use this to avoid counting no-op deletions).

func (*Index) Get

func (idx *Index) Get(ref *gate.PackageRef) (*CacheEntry, bool)

Get retrieves a cache entry. Returns (nil, false) if not found.

func (*Index) GetWithID added in v1.1.0

func (idx *Index) GetWithID(ref *gate.PackageRef) (*CacheEntry, int64, bool)

GetWithID returns the immutable row identity used for deferred usage updates.

func (*Index) Insert

func (idx *Index) Insert(ref *gate.PackageRef, entry *CacheEntry) error

Insert adds or updates a cache entry (UPSERT semantics).

func (*Index) LRUCandidates

func (idx *Index) LRUCandidates(ctx context.Context, n int) ([]gate.PackageRef, error)

LRUCandidates returns up to n entries sorted by last_hit ascending (LRU first).

func (*Index) MarkCVEChecked added in v0.2.0

func (idx *Index) MarkCVEChecked(ref *gate.PackageRef, ts int64) error

MarkCVEChecked sets last_cve_check for ref to ts (unix seconds).

func (*Index) MarkMalwareChecked added in v0.2.0

func (idx *Index) MarkMalwareChecked(ref *gate.PackageRef, ts int64) error

MarkMalwareChecked sets last_malware_check for ref to ts (unix seconds).

func (*Index) StaleCandidates added in v0.2.0

func (idx *Index) StaleCandidates(ctx context.Context, cutoff int64, n int) ([]StaleCandidate, error)

StaleCandidates returns up to n entries whose last_hit is older than cutoff, oldest first.

func (*Index) StaleSizeBytes added in v0.2.0

func (idx *Index) StaleSizeBytes(ctx context.Context, cutoff int64) (int64, error)

StaleSizeBytes returns the sum of size_bytes for entries whose last_hit is older than cutoff — the reclaimable portion surfaced in the console.

func (*Index) TotalSizeBytes

func (idx *Index) TotalSizeBytes(ctx context.Context) (int64, error)

TotalSizeBytes returns the sum of size_bytes for all entries.

type LocalCache

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

LocalCache implements Cache using the local filesystem with a SQLite index.

func NewLocalCache

func NewLocalCache(cfg LocalCacheConfig) (*LocalCache, error)

NewLocalCache creates a LocalCache rooted at cfg.RootPath.

func (*LocalCache) Close

func (lc *LocalCache) Close() error

Close stops the workers before closing the index. Safe to call twice.

func (*LocalCache) FlushUsage added in v1.1.0

func (lc *LocalCache) FlushUsage(ctx context.Context) error

FlushUsage fences accepted hits, for maintenance only.

func (*LocalCache) Get

func (lc *LocalCache) Get(ref *gate.PackageRef) (*CacheEntry, bool)

Get returns a cached entry, or (nil, false) on miss.

func (*LocalCache) Invalidate

func (lc *LocalCache) Invalidate(ref *gate.PackageRef) error

Invalidate removes an entry from both the index and disk.

func (*LocalCache) MarkCVEChecked added in v0.2.0

func (lc *LocalCache) MarkCVEChecked(ref *gate.PackageRef, ts time.Time) error

MarkCVEChecked records a passed CVE re-check for ref.

func (*LocalCache) MarkMalwareChecked added in v0.2.0

func (lc *LocalCache) MarkMalwareChecked(ref *gate.PackageRef, ts time.Time) error

MarkMalwareChecked records a passed malware re-check for ref.

func (*LocalCache) PurgeStale added in v0.2.0

func (lc *LocalCache) PurgeStale(ctx context.Context) (removed, freedBytes int64, err error)

PurgeStale removes every entry idle longer than cfg.StaleAfter and returns how many entries were removed and their total size. Individual failures are skipped (same policy as evictToSize); a round that makes no progress aborts instead of spinning on undeletable rows. A cancelled ctx stops the purge between rounds (what was removed so far stays removed).

func (*LocalCache) Put

func (lc *LocalCache) Put(ref *gate.PackageRef, tmpPath string, scanClean bool, scanJSON string) error

Put copies the artifact from tmpPath into the cache store and records scan results.

func (*LocalCache) RequestUsageFlush added in v1.1.0

func (lc *LocalCache) RequestUsageFlush()

RequestUsageFlush wakes the usage writer without waiting for persistence.

func (*LocalCache) Shutdown added in v1.1.0

func (lc *LocalCache) Shutdown(ctx context.Context) error

Shutdown cancels maintenance and drains usage before joining maintenance: an already selected invalidation may be waiting on the writer's connection.

func (*LocalCache) Stats

func (lc *LocalCache) Stats() (CacheStats, error)

Stats returns aggregate cache statistics.

func (*LocalCache) UsageWriterStats added in v1.1.0

func (lc *LocalCache) UsageWriterStats() storage.WriterStats

UsageWriterStats reads only in-memory observational state.

type LocalCacheConfig

type LocalCacheConfig struct {
	RootPath  string
	MaxSizeGB int
	// StaleAfter is the idle threshold: entries not hit for this long count
	// as stale (reclaimable via PurgeStale / the console Clean up button).
	StaleAfter time.Duration
}

LocalCacheConfig configures the local filesystem cache.

type StaleCandidate added in v0.2.0

type StaleCandidate struct {
	Ref       gate.PackageRef
	SizeBytes int64
}

StaleCandidate is a stale entry surfaced for purging: the ref plus its size so the purge can report freed bytes without a second lookup.

type UsageBatcher added in v1.1.0

type UsageBatcher interface {
	RequestUsageFlush()
	FlushUsage(context.Context) error
	Shutdown(context.Context) error
	UsageWriterStats() storage.WriterStats
}

UsageBatcher is an optional observational capability. Package handlers need only Cache; maintenance and application shutdown may fence accepted usage.

type UsageDelta added in v1.1.0

type UsageDelta struct {
	RowID   int64
	Hits    int64
	LastHit int64
}

UsageDelta contains observational data only, never a security verdict.

Jump to

Keyboard shortcuts

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