pilorama

Documentation

Index

• Constants
• Variables
• type CIDDescriptor
• type Forest
• type ForestStorage
  • func NewBoltForest(opts ...Option) ForestStorage
  • func NewMemoryForest() ForestStorage
• type Info
• type KeyValue
• type Meta
  • func (x Meta) Bytes() []byte
  • func (x *Meta) DecodeBinary(r *io.BinReader)
  • func (x Meta) EncodeBinary(w *io.BinWriter)
  • func (x *Meta) FromBytes(data []byte) error
  • func (x Meta) GetAttr(name string) []byte
  • func (x Meta) Size() int
• type Move
• type Node
• type Option
  • func WithMaxBatchDelay(d time.Duration) Option
  • func WithMaxBatchSize(size int) Option
  • func WithNoSync(noSync bool) Option
  • func WithOpenFile(openFile func(string, int, fs.FileMode) (*os.File, error)) Option
  • func WithPath(path string) Option
  • func WithPerm(perm fs.FileMode) Option
• type Timestamp

Constants

const (
	AttributeFilename = "FileName"
	AttributeVersion  = "Version"
)

const (
	// RootID represents the ID of a root node.
	RootID = 0
	// TrashID is a parent for all removed nodes.
	TrashID = math.MaxUint64
)

Variables

var (
	// ErrTreeNotFound is returned when the requested tree is not found.
	ErrTreeNotFound = logicerr.New("tree not found")
	// ErrNotPathAttribute is returned when the path is trying to be constructed with a non-internal
	// attribute. Currently the only attribute allowed is AttributeFilename.
	ErrNotPathAttribute = logicerr.New("attribute can't be used in path construction")
)

var ErrDegradedMode = logicerr.New("pilorama is in a degraded mode")

ErrDegradedMode is returned when pilorama is in a degraded mode.

var ErrInvalidCIDDescriptor = logicerr.New("cid descriptor is invalid")

ErrInvalidCIDDescriptor is returned when info about tne node position in the container is invalid.

var ErrReadOnlyMode = logicerr.New("pilorama is in a read-only mode")

ErrReadOnlyMode is returned when pilorama is in a read-only mode.

Types

type CIDDescriptor

type CIDDescriptor struct {
	CID      cidSDK.ID
	Position int
	Size     int
}

CIDDescriptor contains container ID and information about the node position in the list of container nodes.

type Forest

type Forest interface {
	// TreeMove moves node in the tree.
	// If the parent of the move operation is TrashID, the node is removed.
	// If the child of the move operation is RootID, new ID is generated and added to a tree.
	TreeMove(d CIDDescriptor, treeID string, m *Move) (*Move, error)
	// TreeAddByPath adds new node in the tree using provided path.
	// The path is constructed by descending from the root using the values of the attr in meta.
	// Internal nodes in path should have exactly one attribute, otherwise a new node is created.
	TreeAddByPath(d CIDDescriptor, treeID string, attr string, path []string, meta []KeyValue) ([]Move, error)
	// TreeApply applies replicated operation from another node.
	// If background is true, TreeApply will first check whether an operation exists.
	TreeApply(cnr cidSDK.ID, treeID string, m *Move, backgroundSync bool) error
	// TreeGetByPath returns all nodes corresponding to the path.
	// The path is constructed by descending from the root using the values of the
	// AttributeFilename in meta.
	// The last argument determines whether only the node with the latest timestamp is returned.
	// Should return ErrTreeNotFound if the tree is not found, and empty result if the path is not in the tree.
	TreeGetByPath(cid cidSDK.ID, treeID string, attr string, path []string, latest bool) ([]Node, error)
	// TreeGetMeta returns meta information of the node with the specified ID.
	// Should return ErrTreeNotFound if the tree is not found, and empty result if the node is not in the tree.
	TreeGetMeta(cid cidSDK.ID, treeID string, nodeID Node) (Meta, Node, error)
	// TreeGetChildren returns children of the node with the specified ID. The order is arbitrary.
	// Should return ErrTreeNotFound if the tree is not found, and empty result if the node is not in the tree.
	TreeGetChildren(cid cidSDK.ID, treeID string, nodeID Node) ([]uint64, error)
	// TreeGetOpLog returns first log operation stored at or above the height.
	// In case no such operation is found, empty Move and nil error should be returned.
	TreeGetOpLog(cid cidSDK.ID, treeID string, height uint64) (Move, error)
	// TreeDrop drops a tree from the database.
	// If the tree is not found, ErrTreeNotFound should be returned.
	// In case of empty treeID drops all trees related to container.
	TreeDrop(cid cidSDK.ID, treeID string) error
	// TreeList returns all the tree IDs that have been added to the
	// passed container ID. Nil slice should be returned if no tree found.
	TreeList(cid cidSDK.ID) ([]string, error)
	// TreeExists checks if a tree exists locally.
	// If the tree is not found, false and a nil error should be returned.
	TreeExists(cid cidSDK.ID, treeID string) (bool, error)
	// TreeUpdateLastSyncHeight updates last log height synchronized with _all_ container nodes.
	TreeUpdateLastSyncHeight(cid cidSDK.ID, treeID string, height uint64) error
	// TreeLastSyncHeight returns last log height synchronized with _all_ container nodes.
	TreeLastSyncHeight(cid cidSDK.ID, treeID string) (uint64, error)
	// TreeHeight returns current tree height.
	TreeHeight(cid cidSDK.ID, treeID string) (uint64, error)
}

Forest represents CRDT tree.

type ForestStorage

type ForestStorage interface {
	// DumpInfo returns information about the pilorama.
	DumpInfo() Info
	Init() error
	Open(bool) error
	Close() error
	SetMode(m mode.Mode) error
	Forest
}

func NewBoltForest

func NewBoltForest(opts ...Option) ForestStorage

NewBoltForest returns storage wrapper for storing operations on CRDT trees.

Each tree is stored in a separate bucket by `CID + treeID` key. All integers are stored in little-endian unless explicitly specified otherwise.

DB schema (for a single tree): timestamp is 8-byte, id is 4-byte.

log storage (logBucket): timestamp in big-endian -> log operation

tree storage (dataBucket): - 't' + node (id) -> timestamp when the node first appeared, - 'p' + node (id) -> parent (id), - 'm' + node (id) -> serialized meta, - 'c' + parent (id) + child (id) -> 0/1, - 'i' + 0 + attrKey + 0 + attrValue + 0 + parent (id) + node (id) -> 0/1 (1 for automatically created nodes).

func NewMemoryForest

func NewMemoryForest() ForestStorage

NewMemoryForest creates new empty forest. TODO: this function will eventually be removed and is here for debugging.

type Info

type Info struct {
	// Path contains path to the root-directory of the pilorama.
	Path string
	// Backend is the pilorama storage type. Either "boltdb" or "memory".
	Backend string
}

Info groups the information about the pilorama.

type KeyValue

type KeyValue struct {
	Key   string
	Value []byte
}

KeyValue represents a key-value pair.

type Meta

type Meta struct {
	Time  Timestamp
	Items []KeyValue
}

Meta represents arbitrary meta information. TODO: remove after the debugging or create a proper interface.

func (Meta) Bytes

func (x Meta) Bytes() []byte

func (*Meta) DecodeBinary

func (x *Meta) DecodeBinary(r *io.BinReader)

DecodeBinary implements the io.Serializable interface.

func (Meta) EncodeBinary

func (x Meta) EncodeBinary(w *io.BinWriter)

EncodeBinary implements the io.Serializable interface.

func (*Meta) FromBytes

func (x *Meta) FromBytes(data []byte) error

func (Meta) GetAttr

func (x Meta) GetAttr(name string) []byte

func (Meta) Size

func (x Meta) Size() int

Size returns size of x in bytes.

type Move

type Move struct {
	Parent Node
	Meta
	// Child represents the ID of a node being moved. If zero, new ID is generated.
	Child Node
}

Move represents a single move operation.

type Node

type Node = uint64

Node is used to represent nodes. TODO: remove after the debugging.

type Option

type Option func(*cfg)

func WithMaxBatchDelay

func WithMaxBatchDelay(d time.Duration) Option

func WithMaxBatchSize

func WithMaxBatchSize(size int) Option

func WithNoSync

func WithNoSync(noSync bool) Option

func WithOpenFile

func WithOpenFile(openFile func(string, int, fs.FileMode) (*os.File, error)) Option

func WithPath

func WithPath(path string) Option

func WithPerm

func WithPerm(perm fs.FileMode) Option

type Timestamp

type Timestamp = uint64

Timestamp is an alias for integer timestamp type. TODO: remove after the debugging.