fsstore

type BlobIOError ¶

type BlobIOError struct {
	Op    string
	Path  string
	Cause error
}

BlobIOError wraps an underlying filesystem failure (mkdir, open, read, write, fsync, rename, remove, walk) with the operation and path for diagnosis. Cause is the os/syscall error and is exposed via Unwrap.

func (e *BlobIOError) Error() string

func (e *BlobIOError) Unwrap() error

type BlobPathError ¶

type BlobPathError struct {
	Key  string
	Path string
}

BlobPathError reports that a blob key mapped to a filesystem location outside the store's blobs directory. It is defense in depth: ValidateName already forbids the '..' and empty segments that could escape, so a valid key never triggers it — a triggered BlobPathError means an unvalidated key reached path mapping.

func (e *BlobPathError) Error() string

type BlobRootError ¶

type BlobRootError struct {
	Root   string
	Reason string
}

BlobRootError reports that newBlobStore was given an unusable root (for example, an empty path).

func (e *BlobRootError) Error() string

type FlockError ¶

type FlockError struct {
	Op    string
	Path  string
	Cause error
}

FlockError reports that acquiring or releasing a cross-process advisory lock failed. Op is "lock" or "unlock"; Cause carries the underlying syscall error (or errFlockUnsupported on a platform without advisory locking). Callers classify with errors.As(&FlockError), never by string.

func (e *FlockError) Error() string

func (e *FlockError) Unwrap() error

type FrameError ¶

type FrameError struct {
	Fault FrameFault
	// Have is the number of bytes available (Torn faults).
	Have int
	// Need is the number of bytes the frame required (Torn faults).
	Need int
	// Length is the declared or requested payload length (Oversize fault).
	Length uint64
}

FrameError is the single typed error the frame codec returns. Its Fault names the exact cause; IsTorn / IsCorrupt classify it into the two recovery modes the ledger acts on:

• Torn — a clean truncation at a byte boundary (an interrupted final write). Recoverable: the ledger truncates back to the last good frame.
• Corrupt — every declared byte is present but the frame is internally inconsistent (bad CRC, or a length beyond the ceiling). Not recoverable by truncation; the ledger must refuse to open and fail closed.

Callers classify with errors.As(&FrameError) and the predicates, never by string. The Error() text carries only integers, never payload bytes.

func (e *FrameError) Error() string

func (e *FrameError) IsCorrupt() bool

func (e *FrameError) IsTorn() bool

type FrameFault ¶

type FrameFault uint8

FrameFault identifies the precise reason a frame failed to encode or decode. It is the machine-classifiable cause; callers fold faults into the two recovery modes with FrameError.IsTorn / FrameError.IsCorrupt.

const (
	// FaultShortHeader: fewer than frameHeaderSize bytes are present, so the
	// header itself is incomplete. Torn.
	FaultShortHeader FrameFault = iota + 1
	// FaultShortPayload: the header is complete and declares a payload length,
	// but fewer than that many payload bytes are present. Torn.
	FaultShortPayload
	// FaultOversize: a declared or requested payload length exceeds
	// MaxFramePayload. Corrupt — rejected before any buffer is sized to it.
	FaultOversize
	// FaultCRCMismatch: every declared byte is present but the payload CRC does
	// not match the header. Corrupt.
	FaultCRCMismatch
)

type KVCorruptError ¶

type KVCorruptError struct {
	Path  string
	Cause error
}

KVCorruptError reports that a key's file could not be trusted: it is present but too short to hold the revision header. Both Get and Put fail closed rather than treat the file as absent (rev 0), which would let a torn file silently reset the revision counter. Cause is errShortRevHeader.

func (e *KVCorruptError) Error() string

func (e *KVCorruptError) Unwrap() error

type KVIOError ¶

type KVIOError struct {
	Op    string
	Path  string
	Cause error
}

KVIOError wraps an underlying filesystem failure (mkdir, open, read, write, fsync, rename, remove, walk) with the operation and path for diagnosis. Cause is the os/syscall error and is exposed via Unwrap.

func (e *KVIOError) Error() string

func (e *KVIOError) Unwrap() error

type KVPathError ¶

type KVPathError struct {
	Key  string
	Path string
}

KVPathError reports that a KV key mapped to a filesystem location outside the store's kv directory. It is defense in depth: ValidateName already forbids the '..' and empty segments that could escape, so a valid key never triggers it — a triggered KVPathError means an unvalidated key reached path mapping.

func (e *KVPathError) Error() string

type KVRootError ¶

type KVRootError struct {
	Root   string
	Reason string
}

KVRootError reports that newKVStore was given an unusable root (for example, an empty path).

func (e *KVRootError) Error() string

type LeaseCorruptError ¶

type LeaseCorruptError struct {
	Path  string
	Cause error
}

LeaseCorruptError reports that a lock file's persisted epoch counter could not be trusted: it is present but not a valid decimal uint64. Acquire fails closed rather than reset the counter to 0 (which would let a stale holder's epoch be reissued, breaking the strictly-increasing guarantee). Cause is errBadEpoch.

func (e *LeaseCorruptError) Error() string

func (e *LeaseCorruptError) Unwrap() error

type LeaseIOError ¶

type LeaseIOError struct {
	Op    string
	Path  string
	Cause error
}

LeaseIOError wraps an underlying filesystem failure (mkdir, open, read, write, truncate, fsync, close) with the operation and path for diagnosis. Cause is the os/syscall error and is exposed via Unwrap.

func (e *LeaseIOError) Error() string

func (e *LeaseIOError) Unwrap() error

type LeasePathError ¶

type LeasePathError struct {
	Name string
	Path string
}

LeasePathError reports that a lease Name mapped to a filesystem location outside the store's leases directory. It is defense in depth: ValidateName already forbids the '..' and empty segments that could escape, so a valid name never triggers it — a triggered LeasePathError means an unvalidated name reached path mapping.

func (e *LeasePathError) Error() string

type LeaseRootError ¶

type LeaseRootError struct {
	Root   string
	Reason string
}

LeaseRootError reports that newLeaserStore was given an unusable root (for example, an empty path).

func (e *LeaseRootError) Error() string

type LedgerCorruptError ¶

type LedgerCorruptError struct {
	Path  string
	Seq   uint64
	Cause error
}

LedgerCorruptError reports that a ledger file could not be trusted: a frame at Seq is present-but-invalid (CRC mismatch, over-ceiling length) or the sequence is non-contiguous. Unlike a torn tail, this is not recoverable by truncation, so every operation fails closed rather than silently drop data. Cause carries the underlying frame fault or errNonContiguousSeq.

func (e *LedgerCorruptError) Error() string

func (e *LedgerCorruptError) Unwrap() error

type LedgerIOError ¶

type LedgerIOError struct {
	Op    string
	Path  string
	Cause error
}

LedgerIOError wraps an underlying filesystem failure (open, read, write, fsync, truncate, mkdir, stat) with the operation and path for diagnosis. Cause is the os/syscall error and is exposed via Unwrap.

func (e *LedgerIOError) Error() string

func (e *LedgerIOError) Unwrap() error

type LedgerPathError ¶

type LedgerPathError struct {
	Name string
	Path string
}

LedgerPathError reports that a ledger Name mapped to a filesystem location outside the store root. It is defense in depth: ValidateName already forbids the '..' and empty segments that could escape, so a valid name never triggers it — a triggered LedgerPathError means an unvalidated name reached path mapping.

func (e *LedgerPathError) Error() string

type LedgerRootError ¶

type LedgerRootError struct {
	Root   string
	Reason string
}

LedgerRootError reports that newLedgerStore was given an unusable root (for example, an empty path).

func (e *LedgerRootError) Error() string

type Options ¶

type Options struct {
	// Root is the store root directory. It is created at 0700 if absent. Required:
	// an empty Root is rejected with an *OptionsError.
	Root string
}

Options configures Open. Root is the single directory under which the store lays out its four backends (streams/, leases/, kv/, blobs/); it is required.

type OptionsError ¶

type OptionsError struct {
	Field  string
	Reason string
	Cause  error
}

OptionsError reports an invalid or unusable Open option. Field names the option (currently always "Root") and Reason explains the fault; Cause carries the underlying filesystem error (or errRootNotDir) when the fault was not a plain validation failure, and is exposed via Unwrap for errors.Is/As.

func (e *OptionsError) Error() string

func (e *OptionsError) Unwrap() error

type Store ¶

type Store struct {
	*storage.Composite
	// contains filtered or unexported fields
}

Store is an open fsstore rooted at a single directory on the local filesystem. It embeds *storage.Composite, so a caller reaches each primitive as a promoted field — store.Ledger, store.Leaser, store.KV, store.Blobs — and hands the whole bundle to a consumer as store.Composite or via Backend. The four primitives collide on method names, so no single type can implement all four (see the file-level comment); embedding the field-bundle is how Store sidesteps that.

func Open(opts Options) (*Store, error)

func (s *Store) Backend() *storage.Composite

func (s *Store) Close() error

func (s *Store) StoragePaths() []string