Documentation
¶
Overview ¶
Package blobcache is Ether's on-disk whole-blob cache for plugin content kinds (spec §5.4, §15.5). Each library owns an isolated namespace with its own directory, persistent index, quota, and optional TTL, while all namespaces share an overall cap of min(10 GiB, 5% of cache disk) and honour the segcache free-space floor so no plugin library can fill the disk.
Index ¶
- Constants
- Variables
- func ParseRef(raw string) (string, error)
- type ByteSource
- type Cache
- func (c *Cache) BindPluginLibrary(pluginID, libraryKey string)
- func (c *Cache) Close() error
- func (c *Cache) EffectiveSharedCap() int64
- func (c *Cache) HostBackends(quotaFor func(pluginID, libraryKey string) Quota) (...)
- func (c *Cache) Namespace(libraryKey string, quota Quota) *Namespace
- func (c *Cache) SetDiskUsage(fn segcache.DiskUsageFunc)
- func (c *Cache) SweepAll()
- func (c *Cache) TotalStats() (bytes int64, blobs int)
- type Namespace
- func (n *Namespace) LookupKey(key string) (Ref, bool)
- func (n *Namespace) Open(ref Ref) (ByteSource, error)
- func (n *Namespace) OpenByKey(key string) (ByteSource, error)
- func (n *Namespace) Purge()
- func (n *Namespace) Put(ctx context.Context, key string, r io.Reader, size int64) (Ref, error)
- func (n *Namespace) PutWithExpectedSHA256(ctx context.Context, key string, r io.Reader, size int64, ...) (Ref, error)
- func (n *Namespace) Quota() Quota
- func (n *Namespace) SetQuota(q Quota)
- func (n *Namespace) SingleFlightPut(ctx context.Context, key string, fn func(ctx context.Context) (Ref, error)) (Ref, error)
- func (n *Namespace) Stats() (bytes int64, blobs int)
- func (n *Namespace) Sweep()
- type Options
- type Quota
- type Ref
Constants ¶
const ( DefaultMaxBytes int64 = 2 << 30 // 2 GiB per library default )
Default budget constants (spec §15.5).
Variables ¶
var ( // ErrNotFound is returned when a blob reference or key is not in the cache. ErrNotFound = errors.New("blobcache: blob not found") // ErrTooLarge is returned when a blob exceeds the namespace or shared quota. ErrTooLarge = errors.New("blobcache: blob exceeds quota") // ErrClosed is returned on mutating operations after Close. ErrClosed = errors.New("blobcache: cache closed") // ErrBadRef is returned when a blob reference is not "blob:<64-hex>". ErrBadRef = errors.New("blobcache: invalid blob reference") )
Functions ¶
Types ¶
type ByteSource ¶
type ByteSource interface {
io.ReaderAt
io.ReadSeekCloser
Size() int64
Name() string
MIME() string
}
ByteSource is a random-access, closable byte stream with size, name and MIME metadata. It matches kindstream.ByteSource and also implements io.ReadSeekCloser.
type Cache ¶
type Cache struct {
// contains filtered or unexported fields
}
Cache manages per-library blob namespaces under a root directory.
func (*Cache) BindPluginLibrary ¶
BindPluginLibrary associates libraryKey with pluginID so HostKindBackends CacheOpen can scope blob lookups to the calling plugin's own libraries.
func (*Cache) EffectiveSharedCap ¶
EffectiveSharedCap computes the global cap across all plugin libraries: min(sharedCap, 5% of total disk, used + free - segcache.MinFreeBytes(total)).
func (*Cache) HostBackends ¶
func (c *Cache) HostBackends(quotaFor func(pluginID, libraryKey string) Quota) ( cachePut func(ctx context.Context, pluginID, libraryKey, name string, r io.Reader) (string, error), cacheOpen func(ctx context.Context, pluginID, blobRef string) (io.ReadSeekCloser, error), )
HostBackends returns CachePut and CacheOpen functions suitable for wiring into plugins.KindBackends (spec §3.6, §5.4).
quotaFor may be nil, in which case the namespace's existing or default quota is used. CacheOpen searches namespaces owned by pluginID (or any namespace whose libraryKey starts with "pk-" + slug(pluginID) + "-").
func (*Cache) Namespace ¶
Namespace returns (creating if needed) the per-library blob namespace for libraryKey and applies quota.
func (*Cache) SetDiskUsage ¶
func (c *Cache) SetDiskUsage(fn segcache.DiskUsageFunc)
SetDiskUsage sets or updates the volume free-space measurement callback.
func (*Cache) SweepAll ¶
func (c *Cache) SweepAll()
SweepAll sweeps every namespace and enforces the shared cap and disk floor.
func (*Cache) TotalStats ¶
TotalStats returns aggregate bytes and blob count across all namespaces.
type Namespace ¶
type Namespace struct {
// contains filtered or unexported fields
}
Namespace is one library's isolated blob cache directory and index.
func (*Namespace) LookupKey ¶
LookupKey checks if a blob was stored under key, is not expired, and still exists on disk. If found, it returns its Ref ("blob:<sha256>").
func (*Namespace) Open ¶
func (n *Namespace) Open(ref Ref) (ByteSource, error)
Open opens a cached blob by its reference ("blob:<sha256>"), updating its last-open timestamp in the index.
func (*Namespace) OpenByKey ¶
func (n *Namespace) OpenByKey(key string) (ByteSource, error)
OpenByKey opens a blob previously stored under key, touching its LRU atime.
func (*Namespace) Purge ¶
func (n *Namespace) Purge()
Purge removes all cached blobs and index state for this library namespace (used on plugin removal, spec §2.5, §5.4).
func (*Namespace) Put ¶
Put streams r to a temporary file while computing its SHA-256, atomically renames it into `<libraryKey>/<sha256[:2]>/<sha256>`, records key -> ref, and sweeps the namespace and global cache if over quota.
When size >= 0, Put verifies that the number of bytes read equals size. Concurrent Puts with the same non-empty key single-flight when the key is already cached or in flight.
func (*Namespace) PutWithExpectedSHA256 ¶
func (n *Namespace) PutWithExpectedSHA256(ctx context.Context, key string, r io.Reader, size int64, expectedSHA256, mimeType string) (Ref, error)
PutWithExpectedSHA256 is Put with optional expected SHA-256 verification and MIME metadata. If expectedSHA256 is non-empty and does not match the stream's digest, the temp file is discarded and an error is returned.
func (*Namespace) SetQuota ¶
SetQuota updates the namespace's quota and immediately sweeps if over budget.
func (*Namespace) SingleFlightPut ¶
func (n *Namespace) SingleFlightPut(ctx context.Context, key string, fn func(ctx context.Context) (Ref, error)) (Ref, error)
SingleFlightPut returns an existing cached blob for key if present, or runs fn once across concurrent callers for the same key.
type Options ¶
type Options struct {
Logger *slog.Logger
DiskUsage segcache.DiskUsageFunc
SweepPeriod time.Duration // 0 = 15m; negative disables background ticker
Now func() time.Time
}
Options configures a Cache.
type Quota ¶
Quota configures a library namespace's maximum bytes and optional TTL. A zero MaxBytes uses DefaultMaxBytes (2 GiB).
func (Quota) EffectiveMaxBytes ¶
EffectiveMaxBytes returns MaxBytes or DefaultMaxBytes when MaxBytes <= 0.
Source Files