Documentation
¶
Overview ¶
Package cache stores downloaded artifacts and their scan results.
Index ¶
- Constants
- func AsArtifactCache(c Cache) gate.ArtifactCache
- type Cache
- type CacheEntry
- type CacheStats
- type Index
- func (idx *Index) ApplyUsageBatch(ctx context.Context, token string, deltas []UsageDelta) error
- func (idx *Index) Close() error
- func (idx *Index) Count(ctx context.Context) (int64, error)
- func (idx *Index) Delete(ref *gate.PackageRef) (int64, error)
- func (idx *Index) Get(ref *gate.PackageRef) (*CacheEntry, bool)
- func (idx *Index) GetWithID(ref *gate.PackageRef) (*CacheEntry, int64, bool)
- func (idx *Index) Insert(ref *gate.PackageRef, entry *CacheEntry) error
- func (idx *Index) LRUCandidates(ctx context.Context, n int) ([]gate.PackageRef, error)
- func (idx *Index) MarkCVEChecked(ref *gate.PackageRef, ts int64) error
- func (idx *Index) MarkMalwareChecked(ref *gate.PackageRef, ts int64) error
- func (idx *Index) StaleCandidates(ctx context.Context, cutoff int64, n int) ([]StaleCandidate, error)
- func (idx *Index) StaleSizeBytes(ctx context.Context, cutoff int64) (int64, error)
- func (idx *Index) TotalSizeBytes(ctx context.Context) (int64, error)
- type LocalCache
- func (lc *LocalCache) Close() error
- func (lc *LocalCache) FlushUsage(ctx context.Context) error
- func (lc *LocalCache) Get(ref *gate.PackageRef) (*CacheEntry, bool)
- func (lc *LocalCache) Invalidate(ref *gate.PackageRef) error
- func (lc *LocalCache) MarkCVEChecked(ref *gate.PackageRef, ts time.Time) error
- func (lc *LocalCache) MarkMalwareChecked(ref *gate.PackageRef, ts time.Time) error
- func (lc *LocalCache) PurgeStale(ctx context.Context) (removed, freedBytes int64, err error)
- func (lc *LocalCache) Put(ref *gate.PackageRef, tmpPath string, scanClean bool, scanJSON string) error
- func (lc *LocalCache) RequestUsageFlush()
- func (lc *LocalCache) Shutdown(ctx context.Context) error
- func (lc *LocalCache) Stats() (CacheStats, error)
- func (lc *LocalCache) UsageWriterStats() storage.WriterStats
- type LocalCacheConfig
- type StaleCandidate
- type UsageBatcher
- type UsageDelta
Constants ¶
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.
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 (*Index) ApplyUsageBatch ¶ added in v1.1.0
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) 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 ¶
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
StaleSizeBytes returns the sum of size_bytes for entries whose last_hit is older than cutoff — the reclaimable portion surfaced in the console.
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
UsageDelta contains observational data only, never a security verdict.