store

Documentation

Overview

Package store manages a volume's local on-disk state: a content-addressed blob store, the per-device journals, and small JSON state files. Everything a volume needs works offline; the remote is only used to exchange blobs and journals.

Layout under <beardrive home>/volumes/<volume>/:

blobs/<aa>/<sha256>   content-addressed file contents (immutable)
journal/<device>.jsonl per-device op logs (own + cached copies of peers)
state.json            what is currently materialized in the folder
sync.json             lamport clock + push cursor
lock                  flock guarding cycles

Index

• func WriteFileAtomic(path string, data []byte, mode os.FileMode) error
• func WriteJSONAtomic(path string, v any) error
• type CachedFile
• type Note
• type ReadEvent
• type Store
  • func Open(dir string) (*Store, error)
  • func (s *Store) AllOps() ([]journal.Op, error)
  • func (s *Store) AppendOps(device string, ops []journal.Op) error
  • func (s *Store) BlobPath(sum string) string
  • func (s *Store) ClearNote() error
  • func (s *Store) ClearPendingReads() error
  • func (s *Store) DeviceOps(device string) ([]journal.Op, error)
  • func (s *Store) Devices() ([]string, error)
  • func (s *Store) Dir() string
  • func (s *Store) HasBlob(sum string) bool
  • func (s *Store) JournalPath(device string) string
  • func (s *Store) LoadCache(mountID string) (map[string]CachedFile, error)
  • func (s *Store) LoadNote() string
  • func (s *Store) LoadSync() (SyncState, error)
  • func (s *Store) Lock() (func() error, error)
  • func (s *Store) LogRead(rel string) error
  • func (s *Store) OpenBlob(sum string) (*os.File, error)
  • func (s *Store) PendingReads() ([]ReadEvent, error)
  • func (s *Store) PutBlobBytes(b []byte) (string, int64, error)
  • func (s *Store) PutBlobFile(path string) (string, int64, error)
  • func (s *Store) PutBlobReader(r io.Reader) (string, int64, error)
  • func (s *Store) SaveCache(mountID string, c map[string]CachedFile) error
  • func (s *Store) SaveNote(text string, ttl time.Duration) error
  • func (s *Store) SaveSync(st SyncState) error
• type SyncState

Functions

func WriteFileAtomic

func WriteFileAtomic(path string, data []byte, mode os.FileMode) error

WriteFileAtomic writes data via a temp file in the same directory + rename.

func WriteJSONAtomic

func WriteJSONAtomic(path string, v any) error

WriteJSONAtomic writes v as JSON via temp-file + rename.

Types

type CachedFile

type CachedFile struct {
	Blob    string `json:"blob"`
	Size    int64  `json:"size"`
	Mode    uint32 `json:"mode"`
	MTimeNS int64  `json:"mtime_ns"`
}

CachedFile records what beardrive last wrote to / observed in the working folder for a path. Size+MTimeNS make change detection cheap; Blob ties it back to content. The cache is per mount (one volume can be materialized into several folders, each with its own stat fingerprints).

type Note

type Note struct {
	Text    string    `json:"text"`
	Expires time.Time `json:"expires,omitzero"` // zero = never expires
}

Note is the on-disk shape of the session note.

type ReadEvent

type ReadEvent struct {
	Path string    `json:"path"`
	Time time.Time `json:"time"`
}

ReadEvent is one observed read of a synced file (mount-relative path).

type Store

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

func Open

func Open(dir string) (*Store, error)

func (*Store) AllOps

func (s *Store) AllOps() ([]journal.Op, error)

AllOps returns the union of every journal known locally.

func (*Store) AppendOps

func (s *Store) AppendOps(device string, ops []journal.Op) error

func (*Store) BlobPath

func (s *Store) BlobPath(sum string) string

func (*Store) ClearNote

func (s *Store) ClearNote() error

ClearNote removes the session note.

func (*Store) ClearPendingReads

func (s *Store) ClearPendingReads() error

ClearPendingReads drops the batch PendingReads returned, after a successful report.

func (*Store) DeviceOps

func (s *Store) DeviceOps(device string) ([]journal.Op, error)

func (*Store) Devices

func (s *Store) Devices() ([]string, error)

Devices lists device IDs that have a local journal copy.

func (*Store) Dir

func (s *Store) Dir() string

func (*Store) HasBlob

func (s *Store) HasBlob(sum string) bool

func (*Store) JournalPath

func (s *Store) JournalPath(device string) string

func (*Store) LoadCache

func (s *Store) LoadCache(mountID string) (map[string]CachedFile, error)

func (*Store) LoadNote

func (s *Store) LoadNote() string

LoadNote returns the live session note, or "" if none is set or it has expired. Never errors: a missing or unreadable note is just no note.

func (*Store) LoadSync

func (s *Store) LoadSync() (SyncState, error)

func (*Store) Lock

func (s *Store) Lock() (func() error, error)

Lock takes an exclusive flock for the volume, serializing sync cycles between the daemon and one-shot commands. Blocks until acquired.

func (*Store) LogRead

func (s *Store) LogRead(rel string) error

LogRead appends one read event to the spool. Single-line O_APPEND writes keep concurrent hook invocations from interleaving.

func (*Store) OpenBlob

func (s *Store) OpenBlob(sum string) (*os.File, error)

func (*Store) PendingReads

func (s *Store) PendingReads() ([]ReadEvent, error)

PendingReads returns the queued batch awaiting report, deduplicated by path (latest time wins). The spool is rotated aside first, so events logged after this call land in a fresh spool; the batch survives until ClearPendingReads — a failed report is simply retried next cycle.

func (*Store) PutBlobBytes

func (s *Store) PutBlobBytes(b []byte) (string, int64, error)

func (*Store) PutBlobFile

func (s *Store) PutBlobFile(path string) (string, int64, error)

func (*Store) PutBlobReader

func (s *Store) PutBlobReader(r io.Reader) (string, int64, error)

PutBlobReader streams r into the blob store, returning its sha256 and size.

func (*Store) SaveCache

func (s *Store) SaveCache(mountID string, c map[string]CachedFile) error

func (*Store) SaveNote

func (s *Store) SaveNote(text string, ttl time.Duration) error

SaveNote sets the session note. ttl > 0 bounds its life; empty text clears.

func (*Store) SaveSync

func (s *Store) SaveSync(st SyncState) error

type SyncState

type SyncState struct {
	Lamport   int64 `json:"lamport"`
	PushedOps int64 `json:"pushed_ops"` // how many of our own ops the remote has
}