pail

README

go-pail

DAG based key value store. Sharded DAG that minimises traversals and work to build shards.

• 📖 Read the SPEC.
• 🎬 Watch the Presentation.

Install

go get github.com/storacha/go-pail

Usage

package main

import (
  "context"
  "fmt"

  "github.com/ipfs/go-cid"
  cidlink "github.com/ipld/go-ipld-prime/linking/cid"
  "github.com/storacha/go-pail"
  "github.com/storacha/go-pail/block"
)

func main() {
  ctx := context.Background()

  rootBlock, _ := pail.New()

  blocks := block.NewMapBlockstore()
  _ = blocks.Put(ctx, rootBlock)

  fmt.Printf("Root: %s\n",  rootBlock.Link())

  key := "room-guardian.jpg"
  value := cidlink.Link{Cid: cid.MustParse("bafkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy")}

  fmt.Printf("Putting %s: %s\n", key, value)

  root, diff, _ := pail.Put(ctx, blocks, rootBlock.Link(), key, value)

  fmt.Printf("Root: %s\n", root)
  fmt.Println("Added blocks:")
  for _, b := range diff.Additions {
    fmt.Printf("+ %s\n", b.Link())
    _ = blocks.Put(ctx, b)
  }
  fmt.Println("Removed blocks:")
  for _, b := range diff.Removals {
    fmt.Printf("- %s\n", b.Link())
    _ = blocks.Del(ctx, b.Link())
  }

  fmt.Println("Entries:")
  for entry := range pail.Entries(ctx, blocks, root) {
    fmt.Printf("%s: %s\n", entry.Key, entry.Value)
  }
}

// Output:
//
// Root: bafyreiesj77bspnvajezltkvavgngyve7pucqcx527s42jzmo66tdewg44
// Putting room-guardian.jpg: bafkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy
// Root: bafyreidijignftc2p2dgt32eu2d5ge24jo74xxbmcn4clxuvfd52wo6sve
// Added blocks:
// + bafyreidijignftc2p2dgt32eu2d5ge24jo74xxbmcn4clxuvfd52wo6sve
// Removed blocks:
// - bafyreiesj77bspnvajezltkvavgngyve7pucqcx527s42jzmo66tdewg44
// Entries:
// room-guardian.jpg: bafkreigh2akiscaildcqabsyg3dfr6chu3fgpregiymsck7e7aqa4s52zy

Contributing

Feel free to join in. All welcome. Open an issue!

License

Dual-licensed under MIT or Apache 2.0

Documentation

Index

• Variables
• func Del(ctx context.Context, blocks block.Fetcher, root ipld.Link, key string) (ipld.Link, shard.Diff, error)
• func Entries(ctx context.Context, blocks block.Fetcher, root ipld.Link, ...) iter.Seq2[Entry, error]
• func Get(ctx context.Context, blocks block.Fetcher, root ipld.Link, key string) (ipld.Link, error)
• func New() (block.BlockView[shard.RootShard], error)
• func Put(ctx context.Context, blocks block.Fetcher, root ipld.Link, key string, ...) (ipld.Link, shard.Diff, error)
• type EntriesOption
  • func WithKeyGreaterThan(gt string) EntriesOption
  • func WithKeyGreaterThanOrEqual(gte string) EntriesOption
  • func WithKeyLessThan(lt string) EntriesOption
  • func WithKeyLessThanOrEqual(lte string) EntriesOption
  • func WithKeyPrefix(prefix string) EntriesOption
• type Entry

Variables

var ErrNotFound = errors.New("not found")

Functions

func Del

func Del(ctx context.Context, blocks block.Fetcher, root ipld.Link, key string) (ipld.Link, shard.Diff, error)

Del deletes the value for the given key from the bucket. If the key is not found, ErrNotFound is returned as the error value.

func Entries

func Entries(ctx context.Context, blocks block.Fetcher, root ipld.Link, opts ...EntriesOption) iter.Seq2[Entry, error]

func Get

func Get(ctx context.Context, blocks block.Fetcher, root ipld.Link, key string) (ipld.Link, error)

Get the stored value for the given key from the bucket. If the key is not found, ErrNotFound is returned as the error value.

func New

func New() (block.BlockView[shard.RootShard], error)

New creates a new empty pail. It encodes and hashes the data and returns a block view of the root shard.

func Put

func Put(ctx context.Context, blocks block.Fetcher, root ipld.Link, key string, value ipld.Link) (ipld.Link, shard.Diff, error)

Put a value (a CID) for the given key. If the key exists it's value is overwritten.

Types

type EntriesOption

type EntriesOption func(*entriesOptions)

func WithKeyGreaterThan

func WithKeyGreaterThan(gt string) EntriesOption

func WithKeyGreaterThanOrEqual

func WithKeyGreaterThanOrEqual(gte string) EntriesOption

func WithKeyLessThan

func WithKeyLessThan(lt string) EntriesOption

func WithKeyLessThanOrEqual

func WithKeyLessThanOrEqual(lte string) EntriesOption

func WithKeyPrefix

func WithKeyPrefix(prefix string) EntriesOption

type Entry

type Entry struct {
	Key   string
	Value ipld.Link
}