Documentation
¶
Overview ¶
Package cache provides disk-based caching for Git packfiles with in-memory metadata.
The cache manager stores packfiles on disk and uses Ristretto for in-memory metadata caching. It supports size-based eviction, concurrent access, and provides statistics about cache usage.
Index ¶
- Variables
- func IsNotFound(err error) bool
- type Config
- type Entry
- type IdleBucket
- type Manager
- func (m *Manager) Clear(ctx context.Context) error
- func (m *Manager) Delete(ctx context.Context, key string) error
- func (m *Manager) DiskStats() (bytes, entries int64, err error)
- func (m *Manager) Get(ctx context.Context, key string) (io.ReadCloser, int64, error)
- func (m *Manager) Has(ctx context.Context, key string) bool
- func (m *Manager) IdleStats(thresholds []time.Duration) []IdleBucket
- func (m *Manager) Limits() (maxSizeBytes, maxEntries int64)
- func (m *Manager) NewPendingWrite(key string) (*PendingWrite, error)
- func (m *Manager) Stats() Stats
- func (m *Manager) Store(ctx context.Context, key string, reader io.Reader) (string, int64, error)
- type PendingWrite
- type Stats
Constants ¶
This section is empty.
Variables ¶
var ( ErrFailedToCreateCacheDirectory = errors.New("failed to create cache directory") ErrFailedToCreateRistrettoCache = errors.New("failed to create ristretto cache") ErrFailedToCalculateDiskUsage = errors.New("failed to calculate disk usage") // ErrCacheEntryNotFound means the entry is not currently in the cache. It // covers both an entry absent from the in-memory index (never stored, or // evicted) and one whose backing file has gone from disk. Callers use // IsNotFound to tell an evicted entry from a genuine I/O error. ErrCacheEntryNotFound = errors.New("cache entry not found") ErrCachedFileNotFound = errors.New("cached file not found") ErrFailedToCreateCacheFile = errors.New("failed to create cache file") ErrFailedToWriteCacheFile = errors.New("failed to write cache file") ErrFailedToRenameCacheFile = errors.New("failed to rename cache file") ErrFailedToRemoveCacheFile = errors.New("failed to remove cache file") )
Functions ¶
func IsNotFound ¶ added in v1.28.2
IsNotFound reports whether err indicates the cache entry is not currently retrievable (never stored, evicted, or its file is gone from disk), as opposed to a genuine I/O error.
Types ¶
type Config ¶
type Config struct {
// CacheDir is the directory to store packfiles
CacheDir string
// MaxSizeBytes is the maximum cache size in bytes
MaxSizeBytes int64
// MaxEntries is the maximum number of entries to keep in memory
MaxEntries int64
// MaxIdleAge, if non-zero, enables a sliding TTL on cache entries: an
// entry expires when it has been idle (no Get) for at least this long.
// Every Get renews the TTL. Zero disables the TTL and relies solely on
// size-based (LFU-ish) eviction against MaxSizeBytes.
MaxIdleAge time.Duration
// OnEviction, if non-nil, is called every time a cache entry is removed
// by ristretto — TTL expiration, size/LFU pressure, or admission-policy
// rejection. Reason values: "ttl", "size", "reject" (see observability
// package's EvictionReason* constants).
OnEviction func(reason string)
}
Config holds configuration for the cache manager.
type Entry ¶
type Entry struct {
// Key is the cache key
Key string
// FilePath is the path to the cached packfile on disk
FilePath string
// Size is the size of the packfile in bytes
Size int64
// CreatedAt is when the entry was created
CreatedAt time.Time
// LastAccessed is when the entry was last accessed
LastAccessed time.Time
}
Entry represents metadata about a cached packfile.
type IdleBucket ¶ added in v1.29.0
IdleBucket is the number of live cache entries, and their total bytes, whose time since last access is at least Threshold.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager handles caching of Git packfiles.
func (*Manager) DiskStats ¶ added in v1.25.0
DiskStats returns the current on-disk cache size in bytes and the number of cached packfiles, by walking the cache directory.
func (*Manager) Get ¶
Get retrieves a cached packfile by key Returns a ReadCloser for the packfile, or nil if not found.
func (*Manager) IdleStats ¶ added in v1.29.0
func (m *Manager) IdleStats(thresholds []time.Duration) []IdleBucket
IdleStats reports, for each threshold, how many live cache entries (and how many bytes) have not been read for at least that long. Buckets are cumulative: an entry idle for 2h counts toward the 1h, 15m, and 5m thresholds. The result is aligned with the thresholds slice.
func (*Manager) Limits ¶ added in v1.25.0
Limits returns the configured cache capacity limits: the maximum size in bytes and the maximum number of entries.
func (*Manager) NewPendingWrite ¶ added in v1.39.6
func (m *Manager) NewPendingWrite(key string) (*PendingWrite, error)
NewPendingWrite opens a temporary cache file for the given key.
func (*Manager) Store ¶
Store saves a packfile to disk and caches its metadata. The reader will be fully consumed and the packfile stored to disk.
Store commits unconditionally once the reader is drained without an I/O error. Callers that must inspect the stream before deciding whether to keep it (for example to reject an in-band git error) should use NewPendingWrite and Commit/Discard directly.
type PendingWrite ¶ added in v1.39.6
type PendingWrite struct {
// contains filtered or unexported fields
}
PendingWrite is an in-progress cache write. Bytes written to it land in a temporary file; Commit atomically publishes them under the key, Discard throws them away. Exactly one of Commit or Discard should be called, and both are idempotent, so a deferred Discard after a successful Commit is a no-op.
This lets a caller stream a response to the client and the cache at once (via an io.MultiWriter) and only publish it once the whole stream has been validated.
func (*PendingWrite) Commit ¶ added in v1.39.6
Commit flushes and atomically renames the temporary file into place, then registers it with the cache. It returns the final path and byte size. On any write, close, empty-body, or rename failure it removes the temporary file and returns an error, leaving nothing cached.
func (*PendingWrite) Discard ¶ added in v1.39.6
func (pw *PendingWrite) Discard() error
Discard closes and removes the temporary file without publishing it. It is safe to call after Commit (no-op) and safe to defer.
Source Files