pgdesign v0.26.0 /internal/objstore
Updated
On this page

Package objstore is the content-addressed object store: a hash-keyed, deduplicating, epoch-aware put/get map where an object id is the hash of its content.

#internal/objstore

#internal/objstore

Package objstore is the content-addressed object store: a hash-keyed put/get map with deduplication, an on-disk layout under a configurable root, and codec-epoch awareness.

It is the single implementation of law L2 (content identity / extensionality) as code: id = hash(content); get(put(x)) = x; puts are idempotent; identity is location-free (the same content yields the same id in any root). Because ids are epoch-relative, every stored object records the codec version that produced it, and a read through a store opened at a different epoch is a hard error rather than a silent mis-decode.

The package is pure kernel: it depends only on the filesystem and the standard library. It never imports migrate, introspect, or serve. Multiple roots (migrations/objects/ now, imports// later) are supported by constructing multiple Store values, one per root.

#ErrNotFound

Go go
var ErrNotFound = errors.New("objstore: object not found")

ErrNotFound is returned by Get when no object with the given id exists.

#EpochMismatch

Go go
type EpochMismatch struct

EpochMismatch is returned by Get when an object was stored under a codec epoch different from the one the reading Store was opened with. Reading such an object would mis-decode content produced by a different encoder, so it is a hard error and never a silent fallthrough.

#CorruptObject

Go go
type CorruptObject struct

CorruptObject is returned when a stored object's header is unreadable or its content no longer hashes to its id (on-disk corruption).

#Store

Go go
type Store struct

Store is a content-addressed object store rooted at a single directory and bound to a single codec epoch. It is safe for concurrent use.

#New

Go go
func New(root string, epoch uint32) (*Store, error)

New opens (creating if necessary) a content-addressed store rooted at root and bound to the given codec epoch. All objects written through this Store carry that epoch; reads verify it.

#ID

Go go
func ID(content []byte) string

ID returns the content id (lowercase SHA-256 hex) of content. It is a pure function of the bytes: the same content yields the same id everywhere, which is what makes identity location-free.

#EpochMismatch.Error

Go go
func (e *EpochMismatch) Error() string

#CorruptObject.Error

Go go
func (e *CorruptObject) Error() string

#Store.Root

Go go
func (s *Store) Root() string { return s.root }

Root returns the store's root directory.

#Store.Epoch

Go go
func (s *Store) Epoch() uint32 { return s.epoch }

Epoch returns the codec epoch this store is bound to.

#Store.Put

Go go
func (s *Store) Put(content []byte) (string, error)

Put stores content and returns its content id. Puts are idempotent: storing the same bytes twice yields the same id, no error, and no duplicate on disk. Because the path is content-derived, concurrent puts of the same content converge on one object.

#Store.Has

Go go
func (s *Store) Has(id string) (bool, error)

Has reports whether an object with the given id exists in this store's root.

#Store.Get

Go go
func (s *Store) Get(id string) ([]byte, error)

Get returns the content stored under id. It verifies the recorded codec epoch against the store's epoch (EpochMismatch on disagreement) and verifies that the content still hashes to its id (CorruptObject on disagreement), so a read never silently returns bytes produced by a different codec or a bit-rotted object.

Search