Documentation
¶
Overview ¶
Package cache provides caching primitives for Deputy.
This package contains subpackages for different caching strategies:
- github.com/temporalio/deputy/internal/cache/memory - In-memory TTL LRU cache
- github.com/temporalio/deputy/internal/cache/disk - Persistent JSON-on-disk cache
Memory Cache ¶
The memory subpackage provides a bounded LRU cache with per-entry TTL:
cache := memory.NewTTLCache[string, MyValue](1000, 5*time.Minute)
cache.Set("key", value)
if v, ok := cache.Get("key"); ok {
// use v
}
Disk Cache ¶
The disk subpackage provides persistent JSON caching for CLI tools:
disk.Write("myservice", "key", myValue)
var value MyType
if disk.Read("myservice", "key", 24*time.Hour, &value) {
// value loaded from cache
}
Package cache provides caching primitives for Deputy.
This file defines the Source interface for cacheable data sources, enabling a unified cache management system across different data providers.
Index ¶
- func ApplyNoCacheFlag(ctx context.Context, value string) context.Context
- func BypassedSources(ctx context.Context) []string
- func ParseNoCacheFlag(value string) (bypassAll bool, sources []string)
- func ShouldBypass(ctx context.Context) bool
- func ShouldBypassSource(ctx context.Context, source string) bool
- func WithBypassAll(ctx context.Context) context.Context
- func WithBypassSources(ctx context.Context, sources []string) context.Context
- type PopulateOptions
- type ProgressWriter
- type Registry
- func (r *Registry) All() []Source
- func (r *Registry) Clear(ctx context.Context, names []string) error
- func (r *Registry) ClearAll(ctx context.Context) error
- func (r *Registry) Get(name string) Source
- func (r *Registry) Names() []string
- func (r *Registry) Populate(ctx context.Context, names []string, opts PopulateOptions) error
- func (r *Registry) PopulateAll(ctx context.Context, opts PopulateOptions) error
- func (r *Registry) Register(s Source)
- func (r *Registry) Status(ctx context.Context) ([]SourceStatus, error)
- func (r *Registry) TotalSize(ctx context.Context) (int64, error)
- type Source
- type SourceStatus
- type UIProgressWriter
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ApplyNoCacheFlag ¶
ApplyNoCacheFlag applies the parsed --no-cache flag to the context.
func BypassedSources ¶
BypassedSources returns the list of sources that should be bypassed, or nil if all caches are bypassed or no specific sources are set.
func ParseNoCacheFlag ¶
ParseNoCacheFlag parses the --no-cache flag value. - Empty string or "true" means bypass all caches. - "false" means don't bypass any caches. - Comma-separated values specify which sources to bypass.
Returns: - bypassAll: true if all caches should be bypassed - sources: list of source names to bypass (empty if bypassAll is true)
func ShouldBypass ¶
ShouldBypass returns true if all caches should be bypassed.
func ShouldBypassSource ¶
ShouldBypassSource returns true if the specified source should be bypassed. It returns true if: - ShouldBypass(ctx) is true (all caches bypassed), or - The source name is in the list of bypassed sources
func WithBypassAll ¶
WithBypassAll returns a context that signals all caches should be bypassed. Use this when the user specifies --no-cache without specific sources.
Types ¶
type PopulateOptions ¶
type PopulateOptions struct {
// Force refreshes the cache even if it's not expired.
Force bool
// ProgressWriter receives progress updates during downloads.
// If nil, no progress is reported.
ProgressWriter ProgressWriter
}
PopulateOptions controls how a source populates its cache.
type ProgressWriter ¶
type ProgressWriter interface {
// SetTotal sets the total number of bytes to be downloaded.
// If unknown, pass -1.
SetTotal(total int64)
// Add reports that n bytes have been downloaded.
Add(n int64)
// Done signals that the operation is complete.
Done()
}
ProgressWriter receives progress updates during cache population.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry manages a collection of cache sources and provides bulk operations.
func (*Registry) Clear ¶
Clear clears specific sources by name. Unknown source names are returned as errors.
func (*Registry) ClearAll ¶
ClearAll clears all registered sources. It returns an error if any source fails, but continues to process remaining sources.
func (*Registry) Populate ¶
Populate populates specific sources by name. Unknown source names are returned as errors.
func (*Registry) PopulateAll ¶
func (r *Registry) PopulateAll(ctx context.Context, opts PopulateOptions) error
PopulateAll populates all registered sources. It returns an error if any source fails, but continues to process remaining sources.
func (*Registry) Register ¶
Register adds a source to the registry. If a source with the same name already exists, it is replaced.
type Source ¶
type Source interface {
// Name returns the unique identifier for this source (e.g., "osv", "kev", "epss").
// This is used for CLI commands and registry lookups.
Name() string
// Description returns a human-readable description of what this source provides.
Description() string
// Status returns the current cache status including freshness and statistics.
Status(ctx context.Context) (*SourceStatus, error)
// Populate downloads and caches the data from the upstream source.
// If opts.Force is true, the cache is refreshed even if not expired.
Populate(ctx context.Context, opts PopulateOptions) error
// Clear removes all cached data for this source.
Clear(ctx context.Context) error
}
Source represents a cacheable data source that can be managed by the cache system. Implementations should handle their own data fetching, storage, and expiration.
type SourceStatus ¶
type SourceStatus struct {
// Name is the source identifier.
Name string
// Description is a human-readable description.
Description string
// Available indicates whether the cache exists on disk.
Available bool
// Fresh indicates whether the cache is within its TTL.
Fresh bool
// EntryCount is the number of entries in the cache (0 if not applicable).
EntryCount int
// Size is the total size in bytes of the cached data.
Size int64
// LastUpdated is when the cache was last populated.
LastUpdated time.Time
// ExpiresAt is when the cache will be considered stale.
ExpiresAt time.Time
// TTL is the time-to-live for this cache source.
TTL time.Duration
// Error contains the last error message if the source failed.
Error string
// OnDemand indicates this source is populated on-demand (e.g., EPSS per-CVE).
OnDemand bool
}
SourceStatus represents the current state of a cache source.
func SortedByName ¶
func SortedByName(statuses []SourceStatus) []SourceStatus
SortedByName returns a copy of statuses sorted alphabetically by name.
type UIProgressWriter ¶
type UIProgressWriter struct {
// contains filtered or unexported fields
}
UIProgressWriter adapts ui.Progress to the cache.ProgressWriter interface.
func NewUIProgressWriter ¶
NewUIProgressWriter creates a progress writer backed by ui.Progress. The message is displayed during the download operation.
func (*UIProgressWriter) Add ¶
func (p *UIProgressWriter) Add(n int64)
Add implements ProgressWriter.
func (*UIProgressWriter) Fail ¶
func (p *UIProgressWriter) Fail()
Fail marks the progress as failed.
func (*UIProgressWriter) SetTotal ¶
func (p *UIProgressWriter) SetTotal(total int64)
SetTotal implements ProgressWriter.
func (*UIProgressWriter) Start ¶
func (p *UIProgressWriter) Start()
Start begins the progress indicator animation.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package disk provides persistent JSON-on-disk caching with TTL support.
|
Package disk provides persistent JSON-on-disk caching with TTL support. |
|
Package lockfile provides content-hash based caching for parsed lockfile data.
|
Package lockfile provides content-hash based caching for parsed lockfile data. |
|
Package memory provides in-memory caching with bounded size and TTL expiration.
|
Package memory provides in-memory caching with bounded size and TTL expiration. |
|
Package sources provides cache.Source implementations for Deputy's data sources.
|
Package sources provides cache.Source implementations for Deputy's data sources. |