gotkv

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 24, 2026 License: GPL-3.0 Imports: 19 Imported by: 0

README

GotKV

GotKV is a copy-on-write, encrypted, convergent, key-value store built on top of content-addressed storage.

Example: Put/Get

package main

import "github.com/gotvc/got/src/gotkv"

func main() {
    // create operator
    avgSize := 1 << 13
    maxSize := 1 << 16
    kvop := gotkv.NewMachine(avgSize, maxSize)

    // create store
    s := cadata.NewMem(cadata.DefaultHash, maxSize)

    // ignoring errors for brevity
    x, _ := ag.NewEmpty(ctx, s)
    x, _ = ag.Put(ctx, s, *x, []byte("my key"), []byte("my value"))
    value, _ := ag.Get(ctx, s, *x, []byte("my key"))
    // value == []byte("my value")
}

Example: Builder

package main

import "github.com/gotvc/got/src/gotkv"

func main() {
    ctx := context.Background()
    // create operator
    avgSize := 1 << 13
    maxSize := 1 << 16
    kvop := gotkv.NewMachine(avgSize, maxSize)

    // create store
    s := cadata.NewMem(cadata.DefaultHash, maxSize)

    // ignoring errors for brevity
    b := kvag.NewBuilder(s)
    for i := 0; i < 10; i++ {
        b.Put(ctx, []byte("key-" + strconv.Itoa(i)), []byte("my value"))
    }
    root, _ := b.Finish(ctx)
    // the instance rooted at root contains key-0 through key-10
}

Documentation

Index

Constants

View Source 
const (
	MaxKeySize = 4096
)

Variables

View Source 
var (
	ErrKeyNotFound = fmt.Errorf("key not found")
)

Functions

func CopyAll 

func CopyAll(ctx context.Context, b *Builder, it kvstreams.Iterator) error

CopyAll copies all the entries from iterator to builder.

func DebugTree 

func DebugTree(ctx context.Context, s stores.Reading, root Root, w io.Writer) error

DebugTree writes human-readable debug information about the tree to w.

func Get 

func Get(ctx context.Context, s Getter, x Root, key []byte) ([]byte, error)

Get is a convenience function for performing Get without creating an Machine.

func GetF 

func GetF(ctx context.Context, s Getter, x Root, key []byte, fn func([]byte) error) error

GetF is a convenience function for performing GetF without creating an Machine

func IsErrKeyNotFound 

func IsErrKeyNotFound(err error) bool

func KeyAfter 

func KeyAfter(x []byte) []byte

func PrefixEnd 

func PrefixEnd(prefix []byte) []byte

Types

type Builder 

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

Builder is used to construct GotKV instances by adding keys in lexicographical order.

func (*Builder) Finish 

func (b *Builder) Finish(ctx context.Context) (*Root, error)

func (*Builder) Put 

func (b *Builder) Put(ctx context.Context, key, value []byte) error

type DEntry 

type DEntry struct {
	Key   []byte
	Left  maybe.Maybe[[]byte]
	Right maybe.Maybe[[]byte]
}

DEntry is the delta between 2 Entries

type Decoder 

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

func (*Decoder) Peek 

func (d *Decoder) Peek(src []byte, ent *Entry) error

func (*Decoder) Read 

func (d *Decoder) Read(src []byte, ent *Entry) (int, error)

func (*Decoder) Reset 

func (d *Decoder) Reset(parent Index)

type Differ 

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

func (*Differ) Next 

func (d *Differ) Next(ctx context.Context, dst []DEntry) (int, error)

func (*Differ) Seek 

func (d *Differ) Seek(ctx context.Context, gteq []byte) error

type Edit 

type Edit struct {
	Span    Span
	Entries []Entry
}

Edit represents a declarative change to a Span of entries. The result of applying a Edit is that the entire contents of the Span are replaced with Entries.

type Encoder 

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

Encoder is a ptree.Encoder

func (*Encoder) EncodedLen 

func (e *Encoder) EncodedLen(ent Entry) int

func (*Encoder) Reset 

func (e *Encoder) Reset()

func (*Encoder) Write 

func (e *Encoder) Write(dst []byte, ent Entry) (int, error)

type Entry 

type Entry = kvstreams.Entry

type Getter 

type Getter = stores.Reading

type ID 

type ID = blobcache.CID

type Index 

type Index = ptree.Index[kvstreams.Entry, gdat.Ref]

type IndexDecoder 

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

func (*IndexDecoder) Peek 

func (d *IndexDecoder) Peek(src []byte, dst *Index) error

func (*IndexDecoder) Read 

func (d *IndexDecoder) Read(src []byte, dst *Index) (int, error)

func (*IndexDecoder) Reset 

func (d *IndexDecoder) Reset(parent Index)

type IndexEncoder 

type IndexEncoder struct {
	Encoder
}

IndexEncoder encodes indexes

func (*IndexEncoder) EncodedLen 

func (e *IndexEncoder) EncodedLen(x Index) int

func (*IndexEncoder) Reset 

func (e *IndexEncoder) Reset()

func (*IndexEncoder) Write 

func (e *IndexEncoder) Write(dst []byte, x ptree.Index[Entry, Ref]) (int, error)

type Iterator 

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

Iterator is used to iterate through entries in GotKV instances.

func (*Iterator) Next 

func (it *Iterator) Next(ctx context.Context, dst []Entry) (int, error)

func (*Iterator) Peek 

func (it *Iterator) Peek(ctx context.Context, dst *Entry) error

func (*Iterator) Seek 

func (it *Iterator) Seek(ctx context.Context, gteq []byte) error

type Machine 

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

Machine holds common configuration for operations on gotkv instances. It has nothing to do with the state of a particular gotkv instance. It is NOT analagous to a collection object. It is safe for use by multiple goroutines.

func NewMachine 

func NewMachine(meanSize, maxSize int, opts ...Option) Machine

NewMachine returns an operator which will create nodes with mean size `meanSize` and maximum size `maxSize`.

func (*Machine) AddPrefix 

func (a *Machine) AddPrefix(x Root, prefix []byte) Root

AddPrefix prepends prefix to all the keys in instance x. This is a O(1) operation.

func (*Machine) Concat 

func (a *Machine) Concat(ctx context.Context, s stores.RW, iters ...kvstreams.Iterator) (*Root, error)

Concat copies data from the iterators in order. If the iterators produce out of order keys concat errors.

func (*Machine) Delete 

func (a *Machine) Delete(ctx context.Context, s stores.RW, x Root, key []byte) (*Root, error)

Delete returns a new version of the instance x where there is no entry for key. If key does not exist no error is returned.

func (*Machine) DeleteSpan 

func (a *Machine) DeleteSpan(ctx context.Context, s stores.RW, x Root, span Span) (*Root, error)

DeleteSpan returns a new version of the instance x where there are no entries contained in span.

func (*Machine) Edit 

func (a *Machine) Edit(ctx context.Context, s stores.RW, x Root, edits ...Edit) (*Root, error)

Edit applies a batch of edits to the tree x. If edits overlap, the later edit takes prescendence.

func (*Machine) ForEach 

func (a *Machine) ForEach(ctx context.Context, s Getter, root Root, span Span, fn func(Entry) error) error

ForEach calls fn with every entry, in the GotKV instance rooted at root, contained in span, in lexicographical order. If fn returns an error, ForEach immediately returns that error.

func (*Machine) Get 

func (a *Machine) Get(ctx context.Context, s stores.Reading, x Root, key []byte) ([]byte, error)

Get returns the value corresponding to key in the instance x.

func (*Machine) GetF 

func (a *Machine) GetF(ctx context.Context, s stores.Reading, x Root, key []byte, fn func([]byte) error) error

GetF calls fn with the value corresponding to key in the instance x. The value must not be used outside the callback.

func (*Machine) HasPrefix 

func (a *Machine) HasPrefix(ctx context.Context, s stores.Reading, x Root, prefix []byte) (bool, error)

func (*Machine) MaxEntry 

func (a *Machine) MaxEntry(ctx context.Context, s stores.Reading, x Root, span Span) (*Entry, error)

MaxEntry returns the entry in the instance x, within span, with the greatest lexicographic value.

func (*Machine) MaxSize 

func (a *Machine) MaxSize() int

func (*Machine) MeanSize 

func (a *Machine) MeanSize() int

func (*Machine) NewBuilder 

func (a *Machine) NewBuilder(s stores.RW) *Builder

NewBuilder returns a Builder for constructing a GotKV instance. Data will be persisted to s.

func (*Machine) NewDiffer 

func (ag *Machine) NewDiffer(s stores.Reading, left, right Root, span Span) *Differ

func (*Machine) NewEmpty 

func (a *Machine) NewEmpty(ctx context.Context, s stores.RW) (*Root, error)

NewEmpty returns a new GotKV instance with no entries.

func (*Machine) NewIterator 

func (a *Machine) NewIterator(s stores.Reading, root Root, span Span) *Iterator

NewIterator returns an iterator for the instance rooted at x, which will emit all keys within span in the instance.

func (*Machine) NewTx 

func (m *Machine) NewTx(s stores.RW, prev Root) *Tx

func (*Machine) Populate 

func (a *Machine) Populate(ctx context.Context, s stores.Reading, x Root, set cadata.Set, entryFn func(ent Entry) error) error

Populate adds all blobs reachable from x to set. If an item is in set all of the blobs reachable from it are also assumed to also be in set.

func (*Machine) Put 

func (a *Machine) Put(ctx context.Context, s stores.RW, x Root, key, value []byte) (*Root, error)

Put returns a new version of the instance x with the entry at key corresponding to value. If an entry at key already exists it is overwritten, otherwise it will be created.

func (*Machine) RemovePrefix 

func (a *Machine) RemovePrefix(ctx context.Context, s stores.RW, x Root, prefix []byte) (*Root, error)

RemovePrefix removes a prefix from all the keys in instance x. RemotePrefix errors if all the entries in x do not share a common prefix. This is a O(1) operation.

func (*Machine) Sync 

func (a *Machine) Sync(ctx context.Context, src stores.Reading, dst stores.Writing, x Root, entryFn func(Entry) error) error

Sync ensures dst has all the data reachable from x.

type Option 

type Option func(ag *Machine)

Option is used to configure an Machine

func WithDataMachine 

func WithDataMachine(ro *gdat.Machine) Option

func WithSeed 

func WithSeed(seed *[16]byte) Option

WithSeed returns an Option which sets the seed for an Machine. Seed affects node boundaries.

type Ref 

type Ref = gdat.Ref

type Root 

type Root struct {
	Ref   gdat.Ref `json:"ref"`
	Depth uint8    `json:"depth"`
	First []byte   `json:"first,omitempty"`
}

func AddPrefix 

func AddPrefix(x Root, prefix []byte) Root

AddPrefix returns a new version of root with the prefix prepended to all the keys

func (Root) Marshal 

func (r Root) Marshal(out []byte) []byte

func (*Root) Unmarshal 

func (r *Root) Unmarshal(data []byte) error

type Span 

type Span = kvstreams.Span

func PrefixSpan 

func PrefixSpan(prefix []byte) Span

func SingleKeySpan 

func SingleKeySpan(k []byte) Span

func TotalSpan 

func TotalSpan() Span

type Store 

type Store = stores.RWD

type Tx 

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

Tx allows operations to be batched.

func (*Tx) Delete 

func (tx *Tx) Delete(ctx context.Context, key []byte) error

func (*Tx) Flush 

func (tx *Tx) Flush(ctx context.Context) (*Root, error)

Flush writes all in queued mutations to the key-value store.

func (*Tx) Get 

func (tx *Tx) Get(ctx context.Context, key []byte, dst *[]byte) (bool, error)

func (*Tx) Iterate 

func (tx *Tx) Iterate(ctx context.Context, span Span) *TxIterator

Iterate returns an iterator for the current state of the transaction. - Flush must be called before Iterate, or it panics.

func (*Tx) Put 

func (tx *Tx) Put(ctx context.Context, key, value []byte) error

type TxIterator 

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

func (*TxIterator) Next 

func (it *TxIterator) Next(ctx context.Context, dst []Entry) (int, error)

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.