diskcache

Documentation

Overview

Package diskcache provides a small on-disk blob cache for data that is expensive to fetch and safe to lose. WaxTap uses it for YouTube's player JS (base.js), which is a few MiB and only changes when YouTube rotates players.

The cache is deliberately fail-soft. Disk errors are logged and treated as misses or skipped writes; callers never receive them. A read-only or full filesystem just means the resolver fetches from the network again.

Entries are individual SHA-256(key) files under Dir/v<schema>. Writes use a sibling temp file and rename, files are mode 0600, and eviction removes the least-recently-used entries once the size cap is exceeded. Stores are safe for concurrent use inside one process; atomic renames keep cross-process readers from seeing torn writes.

Index

• type Options
• type Store
  • func New(opts Options) *Store
  • func (s *Store) Get(key string) ([]byte, bool)
  • func (s *Store) Put(key string, data []byte)

Types

type Options

type Options struct {
	// Dir is the base cache directory. Entries live under Dir/v<SchemaVersion>.
	// An empty Dir yields a disabled store whose operations are no-ops.
	Dir string
	// MaxBytes caps total retained bytes (0 => default). A non-positive value
	// after defaulting disables eviction.
	MaxBytes int64
	// TTL is how long an entry survives without being read (0 => default).
	TTL time.Duration
	// SchemaVersion namespaces entries; bumping it hides every older entry.
	SchemaVersion int
	// Logger receives best-effort debug logs. If nil, logging is discarded.
	Logger *slog.Logger
}

Options configures a Store. New fills zero values with defaults.

type Store

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

Store is a size-capped, schema-versioned, on-disk blob cache. The zero value is not usable; construct one with New.

func New

func New(opts Options) *Store

New returns a Store with defaults applied. It never fails: directory creation is deferred to the first write and is itself best-effort, so a Store backed by an unwritable location simply behaves as a perpetual miss.

func (*Store) Get

func (s *Store) Get(key string) ([]byte, bool)

Get returns the cached bytes for key if present and unexpired. A miss (absent, expired, or unreadable) returns ok=false. Reading refreshes the entry's recency for LRU eviction.

func (*Store) Put

func (s *Store) Put(key string, data []byte)

Put stores data under key, evicting least-recently-used entries if the total exceeds MaxBytes. All failures are logged at debug and dropped: the cache is an optimization, never a source of caller errors.