Documentation
¶
Overview ¶
Package persistence provides a bounded bbolt reference for local CRDT checkpoints.
A checkpoint saves one complete CRDT snapshot, its frontier and HLC state, a durable-transport cursor, and an application-owned opaque outbox in one bbolt transaction. It is intended for one process owning one protected database file. It is neither a clustered database nor an authenticated replication protocol.
Each Store has one concrete StateValidator. The validator runs before a checkpoint is committed and whenever one is loaded, so a damaged file or a codec/schema mismatch fails closed before a caller restores a replica. The caller must still make its local CRDT mutation and its call to Save part of its own failure policy, and must not retire tombstones merely because a checkpoint exists.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidConfig reports a missing or unsafe persistence configuration. ErrInvalidConfig = errors.New("crdt persistence: invalid configuration") // ErrInvalidCheckpoint reports a checkpoint that cannot safely be stored. ErrInvalidCheckpoint = errors.New("crdt persistence: invalid checkpoint") // ErrCorruptStore reports a damaged, unknown-version, or semantically // invalid record. Callers must restore from an independently verified backup // or checkpoint rather than accept a partial record. ErrCorruptStore = errors.New("crdt persistence: corrupt store") // ErrClosed reports use of a store after Close. ErrClosed = errors.New("crdt persistence: closed") )
Functions ¶
This section is empty.
Types ¶
type Checkpoint ¶
Checkpoint is one atomically stored local recovery boundary. Snapshot already contains the canonical state, frontier, and (when required) HLC state. Cursor is normally the last durable-relay sequence whose effects are represented by Snapshot. Outbox remains opaque so the application can retain its canonical pending payloads in the same transaction without this package inventing transport or authorization semantics.
type Config ¶
type Config struct {
// MaxRecordBytes bounds the complete encoded record, including metadata and
// its checksum.
MaxRecordBytes int
// MaxStateBytes bounds the canonical CRDT state frame retained per record.
MaxStateBytes int
// MaxFrontierEntries bounds the number of replica tags retained with one
// snapshot.
MaxFrontierEntries int
// MaxReplicaIDBytes bounds a frontier or HLC replica ID before allocating or
// converting it to a string.
MaxReplicaIDBytes int
// MaxOutboxBytes bounds the application-owned opaque outbox retained with a
// checkpoint. It is not a substitute for a bounded retry policy.
MaxOutboxBytes int
// MaxNameBytes bounds a checkpoint name. Names use a deliberately small
// ASCII namespace so callers cannot accidentally treat them as file paths.
MaxNameBytes int
// OpenTimeout bounds waiting for bbolt's exclusive file lock. A zero value
// uses five seconds.
OpenTimeout time.Duration
// Validate must perform concrete, bounded CRDT decoding for this store's
// state type and codec. It runs on Save and Load.
Validate snapshot.StateValidator
}
Config bounds every record before it is written or decoded. Limits are intentionally required rather than hidden defaults because a checkpoint's state, frontier, and outbox are application capacity decisions.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store owns a bbolt file containing checkpoints for one concrete CRDT state codec. bbolt serializes writes and permits concurrent read transactions; callers must still run one active process for a database path.
func Open ¶
Open opens or creates a checkpoint store at path with mode 0600. The parent directory must already exist and be protected by the host. A store is bound to Config.Validate, so a type or codec change must use an explicit migration rather than silently reinterpreting old bytes.
func (*Store) Load ¶
func (store *Store) Load(name string) (checkpoint Checkpoint, found bool, err error)
Load returns one validated checkpoint. found is false when name has not been saved. A malformed or semantically invalid stored value returns ErrCorruptStore and never returns a partial checkpoint.
func (*Store) Save ¶
func (store *Store) Save(name string, checkpoint Checkpoint) error
Save validates and atomically replaces name's complete checkpoint. The return from Save is the durable boundary for its snapshot, frontier, clock, cursor, and outbox; it does not acknowledge a remote peer or a separate database transaction.
Source Files