Documentation
¶
Overview ¶
Package cas provides content-addressable storage for Trove. Objects are stored under their content hash, enabling automatic deduplication, integrity verification, and immutable storage patterns.
Index ¶
- Variables
- type CAS
- func (c *CAS) Algorithm() HashAlgorithm
- func (c *CAS) Bucket() string
- func (c *CAS) Exists(ctx context.Context, hash string) (bool, error)
- func (c *CAS) GC(ctx context.Context) (*GCResult, error)
- func (c *CAS) Pin(ctx context.Context, hash string) error
- func (c *CAS) Retrieve(ctx context.Context, hash string) (*driver.ObjectReader, error)
- func (c *CAS) Stat(ctx context.Context, hash string) (*Entry, error)
- func (c *CAS) Store(ctx context.Context, r io.Reader) (hash string, info *driver.ObjectInfo, err error)
- func (c *CAS) Unpin(ctx context.Context, hash string) error
- type Entry
- type GCResult
- type HashAlgorithm
- type Index
- type MemoryIndex
- func (m *MemoryIndex) DecrementRef(_ context.Context, hash string) error
- func (m *MemoryIndex) Delete(_ context.Context, hash string) error
- func (m *MemoryIndex) Get(_ context.Context, hash string) (*Entry, error)
- func (m *MemoryIndex) IncrementRef(_ context.Context, hash string) error
- func (m *MemoryIndex) ListUnpinned(_ context.Context) ([]*Entry, error)
- func (m *MemoryIndex) Pin(_ context.Context, hash string) error
- func (m *MemoryIndex) Put(_ context.Context, entry *Entry) error
- func (m *MemoryIndex) Unpin(_ context.Context, hash string) error
- type Option
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = fmt.Errorf("cas: hash not found: %w", driver.ErrNotFound)
ErrNotFound is returned when a hash is not in the index.
It wraps driver.ErrNotFound, so content missing from the CAS classifies the same way as an object missing from a bucket: errors.Is(err, cas.ErrNotFound) still identifies it precisely, while a caller that only needs to know the content is permanently gone can match trove.ErrNotFound or call trove.Permanent and get the right answer without special-casing the CAS.
Functions ¶
This section is empty.
Types ¶
type CAS ¶
type CAS struct {
// contains filtered or unexported fields
}
CAS provides content-addressable storage operations. Objects are stored under their content hash, enabling deduplication and integrity verification.
func (*CAS) Algorithm ¶
func (c *CAS) Algorithm() HashAlgorithm
Algorithm returns the hash algorithm used by this CAS instance.
func (*CAS) Stat ¶
Stat returns the index entry for a hash without reading its content.
It returns ErrNotFound when the index has no entry. With the default in-memory index that includes content still present in the bucket after a restart, because the index does not survive one.
func (*CAS) Store ¶
func (c *CAS) Store(ctx context.Context, r io.Reader) (hash string, info *driver.ObjectInfo, err error)
Store stores content and returns its hash. If identical content already exists, the reference count is incremented and no duplicate is stored.
It records a "store cas object" span with the algorithm, the size and whether the content was a duplicate. The hash is never recorded: it identifies the content.
type Entry ¶
type Entry struct {
Hash string `json:"hash"`
Bucket string `json:"bucket"`
Key string `json:"key"`
Size int64 `json:"size"`
RefCount int `json:"ref_count"`
Pinned bool `json:"pinned"`
}
Entry represents a CAS index entry mapping a content hash to its storage location.
type GCResult ¶
type GCResult struct {
// Scanned is the number of entries examined.
Scanned int `json:"scanned"`
// Deleted is the number of unreferenced objects removed.
Deleted int `json:"deleted"`
// FreedBytes is the total bytes freed.
FreedBytes int64 `json:"freed_bytes"`
// Errors is the number of entries that failed to delete.
Errors int `json:"errors"`
}
GCResult reports the outcome of a garbage collection run.
type HashAlgorithm ¶
type HashAlgorithm int
HashAlgorithm identifies the hash algorithm for CAS addressing.
const ( // AlgSHA256 uses SHA-256 (default, widely compatible). AlgSHA256 HashAlgorithm = iota // AlgBlake3 uses BLAKE3 (faster, modern). AlgBlake3 // AlgXXHash uses XXHash (non-cryptographic, fastest). AlgXXHash )
func (HashAlgorithm) String ¶
func (a HashAlgorithm) String() string
String returns the algorithm name.
type Index ¶
type Index interface {
// Get returns the entry for a hash, or an error if not found.
Get(ctx context.Context, hash string) (*Entry, error)
// Put stores or updates an entry. If the hash already exists,
// the ref count is incremented.
Put(ctx context.Context, entry *Entry) error
// Delete removes an entry by hash.
Delete(ctx context.Context, hash string) error
// IncrementRef increments the reference count for a hash.
IncrementRef(ctx context.Context, hash string) error
// DecrementRef decrements the reference count for a hash.
DecrementRef(ctx context.Context, hash string) error
// Pin prevents garbage collection of the entry.
Pin(ctx context.Context, hash string) error
// Unpin allows garbage collection.
Unpin(ctx context.Context, hash string) error
// ListUnpinned returns all entries with ref_count=0 and pinned=false.
ListUnpinned(ctx context.Context) ([]*Entry, error)
}
Index maps content hashes to their storage locations. Implementations can be in-memory, database-backed, etc.
type MemoryIndex ¶
type MemoryIndex struct {
// contains filtered or unexported fields
}
MemoryIndex is an in-memory Index implementation for testing.
func NewMemoryIndex ¶
func NewMemoryIndex() *MemoryIndex
NewMemoryIndex creates a new in-memory CAS index.
func (*MemoryIndex) DecrementRef ¶
func (m *MemoryIndex) DecrementRef(_ context.Context, hash string) error
DecrementRef decrements the reference count (min 0).
func (*MemoryIndex) Delete ¶
func (m *MemoryIndex) Delete(_ context.Context, hash string) error
Delete removes an entry.
func (*MemoryIndex) IncrementRef ¶
func (m *MemoryIndex) IncrementRef(_ context.Context, hash string) error
IncrementRef increments the reference count.
func (*MemoryIndex) ListUnpinned ¶
func (m *MemoryIndex) ListUnpinned(_ context.Context) ([]*Entry, error)
ListUnpinned returns entries eligible for garbage collection.
func (*MemoryIndex) Pin ¶
func (m *MemoryIndex) Pin(_ context.Context, hash string) error
Pin marks the entry as pinned.
type Option ¶
type Option func(*CAS)
Option configures a CAS instance.
func WithAlgorithm ¶
func WithAlgorithm(alg HashAlgorithm) Option
WithAlgorithm sets the hash algorithm (default: SHA256).
func WithBucket ¶
WithBucket sets the storage bucket for CAS objects.
func WithMetrics ¶
WithMetrics records CAS stores and garbage collection on r (trove_cas_stores_total, trove_cas_gc_deleted_total and trove_cas_gc_freed_bytes_total). A nil r, the default, records nothing. trove.WithCAS passes the Trove's own Recorder.
Source Files