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 Metrics
• type Move
• type Node
• type NodeInfo
• type Option
  • func WithMaxBatchDelay(d time.Duration) Option
  • func WithMaxBatchSize(size int) Option
  • func WithMetrics(m Metrics) 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(ctx context.Context, 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(ctx context.Context, 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(ctx context.Context, 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(ctx context.Context, 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(ctx context.Context, 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(ctx context.Context, cid cidSDK.ID, treeID string, nodeID Node) ([]NodeInfo, 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(ctx context.Context, 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(ctx context.Context, 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(ctx context.Context, 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(ctx context.Context, cid cidSDK.ID, treeID string) (bool, error)
	// TreeUpdateLastSyncHeight updates last log height synchronized with _all_ container nodes.
	TreeUpdateLastSyncHeight(ctx context.Context, cid cidSDK.ID, treeID string, height uint64) error
	// TreeLastSyncHeight returns last log height synchronized with _all_ container nodes.
	TreeLastSyncHeight(ctx context.Context, cid cidSDK.ID, treeID string) (uint64, error)
	// TreeHeight returns current tree height.
	TreeHeight(ctx context.Context, 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(context.Context, bool) error
	Close() error
	SetMode(m mode.Mode) error
	SetParentID(id string)
	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 Metrics

type Metrics interface {
	SetParentID(id string)

	SetMode(m mode.Mode)
	Close()

	AddMethodDuration(method string, d time.Duration, success bool)
}

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 NodeInfo

type NodeInfo struct {
	ID       Node
	Meta     Meta
	ParentID Node
}

type Option

type Option func(*cfg)

func WithMaxBatchDelay

func WithMaxBatchDelay(d time.Duration) Option

func WithMaxBatchSize

func WithMaxBatchSize(size int) Option

func WithMetrics

func WithMetrics(m Metrics) 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.