Documentation
¶
Overview ¶
Package kvcrdt bridges grove/crdt types into KV storage, enabling distributed, eventually-consistent state without a relational database.
It provides CRDT-backed distributed counters, registers, sets, maps, lists, and documents that use a KV Store for persistence and can be synchronized across stores.
Index ¶
- type Counter
- func (c *Counter) Decrement(ctx context.Context, delta int64) error
- func (c *Counter) Increment(ctx context.Context, delta int64) error
- func (c *Counter) Merge(ctx context.Context, remote *crdt.PNCounterState) error
- func (c *Counter) State(ctx context.Context) (*crdt.PNCounterState, error)
- func (c *Counter) Value(ctx context.Context) (int64, error)
- type Document
- func (d *Document) Delete(ctx context.Context, path string) error
- func (d *Document) Get(ctx context.Context, path string, dest any) error
- func (d *Document) Merge(ctx context.Context, remote *crdt.DocumentCRDTState) error
- func (d *Document) Resolve(ctx context.Context) (map[string]any, error)
- func (d *Document) Set(ctx context.Context, path string, value any) error
- func (d *Document) SetCounter(ctx context.Context, path string, delta int64) error
- func (d *Document) SetFieldState(ctx context.Context, path string, fs *crdt.FieldState) error
- func (d *Document) State(ctx context.Context) (*crdt.DocumentCRDTState, error)
- type List
- func (l *List[T]) Append(ctx context.Context, value T) error
- func (l *List[T]) Delete(ctx context.Context, id crdt.HLC) error
- func (l *List[T]) Elements(ctx context.Context) ([]T, error)
- func (l *List[T]) InsertAfter(ctx context.Context, afterID crdt.HLC, value T) error
- func (l *List[T]) Len(ctx context.Context) (int, error)
- func (l *List[T]) Merge(ctx context.Context, remote *crdt.RGAListState) error
- func (l *List[T]) NodeIDs(ctx context.Context) ([]crdt.HLC, error)
- func (l *List[T]) State(ctx context.Context) (*crdt.RGAListState, error)
- type Map
- func (m *Map) All(ctx context.Context) (map[string]json.RawMessage, error)
- func (m *Map) Delete(ctx context.Context, field string) error
- func (m *Map) Get(ctx context.Context, field string, dest any) error
- func (m *Map) Keys(ctx context.Context) ([]string, error)
- func (m *Map) Merge(ctx context.Context, remote *crdt.State) error
- func (m *Map) Set(ctx context.Context, field string, value any) error
- func (m *Map) State(ctx context.Context) (*crdt.State, error)
- type Option
- type Register
- type Set
- func (s *Set[T]) Add(ctx context.Context, element T) error
- func (s *Set[T]) Contains(ctx context.Context, element T) (bool, error)
- func (s *Set[T]) Members(ctx context.Context) ([]T, error)
- func (s *Set[T]) Merge(ctx context.Context, remote *crdt.ORSetState) error
- func (s *Set[T]) Remove(ctx context.Context, element T) error
- func (s *Set[T]) State(ctx context.Context) (*crdt.ORSetState, error)
- type Syncer
- type SyncerOption
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Counter ¶
type Counter struct {
// contains filtered or unexported fields
}
Counter is a distributed PNCounter backed by a KV store. It stores the full crdt.PNCounterState under the key so that merge is always possible across nodes.
func NewCounter ¶
NewCounter creates a new CRDT counter backed by the given store and key.
type Document ¶
type Document struct {
// contains filtered or unexported fields
}
Document is a distributed nested CRDT document backed by a KV store. Each field at a dot-separated path is independently mergeable with its own CRDT type (LWW, Counter, Set, List), enabling JSON-like nested structures.
func NewDocument ¶
NewDocument creates a new CRDT Document backed by the given store and key.
func (*Document) Resolve ¶
Resolve returns the full document as a nested map by materializing all field paths into a tree structure.
func (*Document) SetCounter ¶
SetCounter sets a counter field at the given path, incrementing by delta. If the path does not yet have a counter, a new PNCounterState is created.
func (*Document) SetFieldState ¶
SetFieldState sets a typed field state at a path. Use this for advanced use cases where you need to set a specific CRDT type (counter, set, list) at a document path.
type List ¶
type List[T any] struct { // contains filtered or unexported fields }
List is a distributed RGA (Replicated Growable Array) backed by a KV store. It stores a crdt.RGAListState under the key, providing ordered sequence semantics with support for concurrent inserts, deletes, and moves.
func (*List[T]) Append ¶
Append adds an element to the end of the list. The element is inserted after the last visible element.
func (*List[T]) Delete ¶
Delete removes the element at the given position ID by marking it as tombstoned.
func (*List[T]) InsertAfter ¶
InsertAfter inserts an element after the given position ID. Use a zero HLC to insert at the beginning of the list.
type Map ¶
type Map struct {
// contains filtered or unexported fields
}
Map is a distributed CRDT Map where each field is an independent LWW register. It stores a crdt.State with per-field FieldState entries.
func (*Map) Merge ¶
Merge merges a remote CRDT State into the local state using per-field LWW merge.
type Option ¶
type Option func(*crdtConfig)
Option configures a CRDT KV type.
func WithClock ¶
WithClock sets the Clock implementation for CRDT timestamps. The clock must implement crdt.Clock (e.g., crdt.NewHybridClock).
func WithNodeID ¶
WithNodeID sets the node identifier for CRDT operations. Each node in a distributed system should have a unique ID.
type Register ¶
type Register[T any] struct { // contains filtered or unexported fields }
Register is a distributed LWW-Register backed by a KV store. The value with the highest HLC timestamp wins.
func NewRegister ¶
NewRegister creates a new CRDT LWW-Register backed by the given store and key.
type Set ¶
type Set[T any] struct { // contains filtered or unexported fields }
Set is a distributed OR-Set (Observed-Remove Set) backed by a KV store. Concurrent add and remove of the same element results in the element being present (add-wins semantics).
type Syncer ¶
type Syncer struct {
// contains filtered or unexported fields
}
Syncer synchronizes CRDT state between two KV stores. It scans for CRDT keys in the primary store and merges them bidirectionally with the replica store.
func NewSyncer ¶
func NewSyncer(primary, replica *kv.Store, opts ...SyncerOption) *Syncer
NewSyncer creates a new CRDT syncer between two KV stores.
type SyncerOption ¶
type SyncerOption func(*syncerConfig)
SyncerOption configures the CRDT Syncer.
func WithKeyPattern ¶
func WithKeyPattern(pattern string) SyncerOption
WithKeyPattern sets the key pattern for scanning CRDT keys during sync.
func WithSyncInterval ¶
func WithSyncInterval(d time.Duration) SyncerOption
WithSyncInterval sets the interval between sync rounds.
Source Files