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 five backends (streams/, leases/, kv/, blobs/, ordered/); 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 OrderedCodecError ¶ added in v0.5.0

type OrderedCodecError struct {
	Fault OrderedCodecFault
	// Field names the implicated field ("stable_key", "value", ...) when the
	// fault is attributable to one.
	Field string
	// Have and Need are byte counts for a short payload.
	Have int
	Need int
	// Length is the declared or supplied field length for an oversize fault.
	Length uint64
	// Max is the ceiling Length exceeded.
	Max uint64
	// Cause is the underlying storage validation error, when there is one.
	Cause error
}

OrderedCodecError is the single typed error the ordered mutation codec returns. Fault names the exact cause and Cause, when set, carries the underlying storage validation error (for example *storage.InvalidNameError or *storage.InvalidStableKeyError) so callers can classify with errors.As at either level. Field names the offending field where one is implicated.

The Error() text carries only field names and integers, never payload bytes: a StableKey may be arbitrary user data and must not be echoed into logs.

Classification precedence ¶

This one type reports two different things, and the wrapper is what tells them apart. An append REJECTING a caller's mutation returns a BARE *OrderedCodecError; a replay finding the same fault ON DISK returns it wrapped in an *OrderedLogCorruptError. errors.As(&OrderedCodecError) therefore matches both, and a caller that must distinguish invalid input from a damaged log has to test *OrderedLogCorruptError FIRST.

A public API whose contract names a specific error for bad input — such as OrderedIndex.CreateOrdered, which owes *storage.InvalidNameError or *storage.InvalidStableKeyError for a malformed OrderedID — must not rely on this precedence at all. It should validate the caller's ID up front with storage.ValidateOrderedID and return THAT error unwrapped, leaving the codec's validation as the internal backstop it is.

func (e *OrderedCodecError) Error() string

func (e *OrderedCodecError) Unwrap() error

type OrderedCodecFault ¶ added in v0.5.0

type OrderedCodecFault uint8

OrderedCodecFault identifies the precise reason an ordered mutation payload failed to encode or decode. Every fault is fail-closed: unlike a frame fault, none of them is recoverable by truncating the log, because the outer frame checksum has already established that the bytes are complete and unaltered.

const (
	// OrderedFaultShortPayload: the payload is shorter than the fixed header, or
	// shorter than the field widths its own header declares.
	OrderedFaultShortPayload OrderedCodecFault = iota + 1
	// OrderedFaultUnknownVersion: the version byte is not orderedMutationVersion.
	OrderedFaultUnknownVersion
	// OrderedFaultUnknownOp: the op byte is not one of the defined orderedOp
	// values.
	OrderedFaultUnknownOp
	// OrderedFaultFieldOversize: a declared (or supplied) field length exceeds
	// its contractual ceiling. Checked before any buffer is sized to it.
	OrderedFaultFieldOversize
	// OrderedFaultTrailingBytes: the payload contains bytes beyond the fields its
	// header declares, so the encoding is not canonical.
	OrderedFaultTrailingBytes
	// OrderedFaultInvalidIdentity: the ordering scope or stable key violates the
	// OrderedID rules. Cause carries the storage validation error.
	OrderedFaultInvalidIdentity
	// OrderedFaultInvalidRecord: the mutation's non-identity state is illegal —
	// an invalid ranking scope or due state, a zero revision or order, a
	// non-boolean rank flag, or a tombstone that is still ranked or due.
	OrderedFaultInvalidRecord
)

type OrderedLogClosedError ¶ added in v0.5.0

type OrderedLogClosedError struct {
	Root      string
	Namespace string
}

OrderedLogClosedError reports an operation on a closed ordered log store. Close drops the namespace->orderedLog registry, so a later logFor would mint a FRESH orderedLog with a NEW mutex for a namespace another goroutine may still be appending to under the old one — two mutexes guarding one file, surviving only because the advisory lock happens to serialize the descriptors. Failing closed is the same discipline Store.Close already applies.

func (e *OrderedLogClosedError) Error() string

type OrderedLogCorruptError ¶ added in v0.5.0

type OrderedLogCorruptError struct {
	Path  string
	Seq   uint64
	Cause error
}

OrderedLogCorruptError reports that a namespace's mutation log could not be trusted: the frame at Seq is present-but-invalid (a checksum mismatch or an over-ceiling length), decodes to an illegal mutation, or breaks the sequence. Unlike a torn tail this is not recoverable by truncation, so every operation fails closed. Cause carries the underlying *FrameError, *OrderedCodecError, or errOrderedNonContiguousSeq.

PRECEDENCE: because a codec fault read off the disk is wrapped in this type, errors.As finds BOTH *OrderedLogCorruptError and *OrderedCodecError on one disk-corruption error, while a caller's invalid mutation carries only the codec type. A caller separating "your input was bad" from "the log is damaged" must test *OrderedLogCorruptError FIRST.

func (e *OrderedLogCorruptError) Error() string

func (e *OrderedLogCorruptError) Unwrap() error

type OrderedLogIOError ¶ added in v0.5.0

type OrderedLogIOError struct {
	Op    string
	Path  string
	Cause error
}

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

func (e *OrderedLogIOError) Error() string

func (e *OrderedLogIOError) Unwrap() error

type OrderedLogPathError ¶ added in v0.5.0

type OrderedLogPathError struct {
	Namespace string
	Path      string
}

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

func (e *OrderedLogPathError) Error() string

type OrderedLogRootError ¶ added in v0.5.0

type OrderedLogRootError struct {
	Root   string
	Reason string
}

OrderedLogRootError reports that newOrderedLogStore was given an unusable root (for example, an empty or blank path).

func (e *OrderedLogRootError) Error() string

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, store.OrderedIndex — and hands the whole bundle to a consumer as store.Composite or via Backend. The five primitives collide on method names, so no single type can implement all five (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