blobcache

type Cache ¶

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

Cache provides cache-oriented operations over a blob store while leaving higher-level domain serialization and refresh policy to consumers.

func New(store Store, namespace string, ttl time.Duration) *Cache

func NewWithPolicy(store Store, namespace string, policy Policy) *Cache

func (c *Cache) CleanExpired(ctx context.Context) error

func (c *Cache) Delete(ctx context.Context, key string) error

func (c *Cache) DeleteNamespace(ctx context.Context) error

func (c *Cache) Dir() string

func (c *Cache) Get(ctx context.Context, key string) (data []byte, meta Meta, ok bool, err error)

func (c *Cache) List(ctx context.Context) ([]Entry, error)

func (c *Cache) Put(ctx context.Context, key string, value []byte, opts PutOptions) (Meta, error)

func (c *Cache) TTL() time.Duration

type Clock ¶

type Clock interface {
	Now() time.Time
}

Clock provides time for cache policy calculations.

type Describer ¶ added in v0.10.0

type Describer interface {
	DescribeBlobStore() Info
}

Describer exposes optional diagnostics for a blob store backend.

type Entry ¶ added in v0.10.0

type Entry struct {
	Key       string
	Meta      Meta
	Age       time.Duration
	ExpiresIn time.Duration
}

Entry describes one cached blob entry together with TTL-derived timing.

type HealthChecker ¶ added in v0.10.0

type HealthChecker interface {
	CheckBlobStore(ctx context.Context) error
}

HealthChecker exposes an optional health check for a blob store backend.

type Info ¶ added in v0.10.0

type Info struct {
	Backend                 string
	Root                    string
	SupportsList            bool
	SupportsStream          bool
	SupportsDeleteNamespace bool
}

Info describes optional backend diagnostics exposed by a blob store.

func Describe(store Store, fallbackBackend string) Info

type Inspector ¶ added in v0.10.0

type Inspector interface {
	BlobStoreRootDir() string
}

Inspector exposes optional store details for diagnostics.

type Meta ¶ added in v0.10.0

type Meta struct {
	Size        int64
	UpdatedAt   time.Time
	ExpiresAt   *time.Time
	ETag        string
	ContentType string
	Metadata    map[string]string
}

Meta describes a stored blob object.

type Object ¶

type Object struct {
	Key  string
	Meta Meta
}

Object describes a listed blob object.

type Policy ¶

type Policy struct {
	TTL   time.Duration
	Clock Clock
}

Policy defines cache timing behavior over blob metadata.

type PutOptions ¶

type PutOptions struct {
	ContentType string
	ExpiresAt   *time.Time
	Metadata    map[string]string
}

PutOptions controls how an entry is persisted by a Store.

type Store ¶ added in v0.10.0

type Store interface {
	Get(ctx context.Context, namespace, key string) ([]byte, bool, Meta, error)
	Put(ctx context.Context, namespace, key string, value []byte, opts PutOptions) (Meta, error)
	Open(ctx context.Context, namespace, key string) (io.ReadCloser, bool, Meta, error)
	PutStream(ctx context.Context, namespace, key string, r io.Reader, opts PutOptions) (Meta, error)
	Delete(ctx context.Context, namespace, key string) error
	DeleteNamespace(ctx context.Context, namespace string) error
	List(ctx context.Context, namespace string) ([]Object, error)
}

Store stores opaque binary objects addressed by namespace + key.

Consumers own key layout, serialization, TTL policy, and stale fallback semantics. Backends only persist bytes and metadata.

Thread-safety: implementations MUST be safe for concurrent use across goroutines, including Put + Get + Delete on the same (namespace, key) from multiple goroutines simultaneously. The contract test suite at pkg/cache/blobcache/contracttest exercises this guarantee — register a new backend against it before merging.

Cross-process safety is best-effort and backend-specific. The bundled diskblob backend serializes per-key writes via an in-process keyed mutex; multi-process protection requires either separate root_dir values or external coordination (advisory file locks, etc.).