store

README

Store

The store interface allows efficient storing and querying of ChainScript data.

Once links have been added to the store, other links will depend on them and reference their hash. Thus, it's important that links cannot be deleted otherwise it would invalidate a lot of other links. Updates aren't possible either for the same reason.

This is reflected in the interface exposed, that focuses only on addition and structured querying over ChainScript data.

See the Golang documentation here.

Documentation

Overview

Package store defines types to implement a store.

Package store defines types to implement a store.

Index

• Constants
• Variables
• type Adapter
• type AdapterConfig
• type Batch
• type Event
  • func NewSavedEvidences() *Event
  • func NewSavedLinks(linkArgs ...*chainscript.Link) *Event
  • func (event *Event) AddSavedEvidence(linkHash chainscript.LinkHash, e *chainscript.Evidence)
  • func (event *Event) AddSavedLinks(links ...*chainscript.Link)
  • func (event *Event) UnmarshalJSON(b []byte) error
• type EventType
• type EvidenceReader
• type EvidenceStore
• type EvidenceWriter
• type KeyValueReader
• type KeyValueStore
• type KeyValueWriter
• type LinkWriter
• type MapFilter
  • func (filter MapFilter) Match(segment *chainscript.Segment) bool
  • func (filter MapFilter) MatchLink(link *chainscript.Link) bool
• type Pagination
  • func (p *Pagination) PaginateSegments(a *types.PaginatedSegments) *types.PaginatedSegments
  • func (p *Pagination) PaginateStrings(a []string) []string
• type SegmentFilter
  • func (filter SegmentFilter) Match(segment *chainscript.Segment) bool
  • func (filter SegmentFilter) MatchLink(link *chainscript.Link) bool
• type SegmentReader

Constants

const (
	// Component name for monitoring.
	Component = "store"

	// DefaultLimit is the default pagination limit.
	DefaultLimit = 20

	// MaxLimit is the maximum pagination limit.
	MaxLimit = 200
)

Variables

var (
	ErrLinkAlreadyExists       = errors.New("link already exists")
	ErrOutDegreeNotSupported   = errors.New("out degree is not supported by the current implementation")
	ErrUniqueMapEntry          = errors.New("unique map entry is set and map already has an initial link")
	ErrReferencingNotSupported = errors.New("filtering on referencing segments is not supported by the current implementation")
	ErrBatchFailed             = errors.New("cannot add to batch: failures have been detected")
)

Common errors that can be used by store implementations.

Types

type Adapter

type Adapter interface {
	SegmentReader
	LinkWriter
	EvidenceStore

	// Returns arbitrary information about the adapter.
	GetInfo(ctx context.Context) (interface{}, error)

	// Adds a channel that receives events from the store.
	AddStoreEventChannel(chan *Event)

	// Creates a new Batch
	NewBatch(ctx context.Context) (Batch, error)
}

Adapter is the minimal interface that all stores should implement. Then a store may optionally implement the KeyValueStore interface.

type AdapterConfig

type AdapterConfig interface {
	// EnforceUniqueMapEntry prevents multiple "first" links from being added
	// to the same map.
	// By default maps can have any number of "first" links (links without a
	// parent).
	// In some cases that doesn't reflect the reality of your process: each map
	// should be started with a single link and other links should be children
	// of the first link. If that's the case, you need to call this method when
	// creating your store adapter.
	EnforceUniqueMapEntry() error
}

AdapterConfig lets users configure advanced store adapter settings. Some stores can't offer these advanced features, so you'll have to test if the store you're using supports it by type-casting it to this interface.

type Batch

type Batch interface {
	SegmentReader
	LinkWriter

	// Write definitely writes the content of the Batch
	Write(ctx context.Context) error
}

Batch represents a database transaction.

type Event

type Event struct {
	EventType EventType
	Data      interface{}
}

Event is the object stores send to notify of important events.

func NewSavedEvidences

func NewSavedEvidences() *Event

NewSavedEvidences creates a new event to notify evidences were saved.

func NewSavedLinks

func NewSavedLinks(linkArgs ...*chainscript.Link) *Event

NewSavedLinks creates a new event to notify links were saved.

func (*Event) AddSavedEvidence

func (event *Event) AddSavedEvidence(linkHash chainscript.LinkHash, e *chainscript.Evidence)

AddSavedEvidence adds an evidence to the event. It assumes the event is a correctly initialized SavedEvidences event.

func (*Event) AddSavedLinks

func (event *Event) AddSavedLinks(links ...*chainscript.Link)

AddSavedLinks adds links to the event. It assumes the event is a correctly initialized SavedLinks event.

func (*Event) UnmarshalJSON

func (event *Event) UnmarshalJSON(b []byte) error

UnmarshalJSON does custom deserialization to correctly type the Data field.

type EventType

type EventType string

EventType lets you know the kind of event received. A client should ignore events it doesn't care about or doesn't understand.

const (
	// SavedLinks means that segment links were saved.
	SavedLinks EventType = "SavedLinks"
	// SavedEvidences means that segment evidences were saved.
	SavedEvidences EventType = "SavedEvidences"
)

type EvidenceReader

type EvidenceReader interface {
	// Get the evidences for a segment.
	// Can return a nil error with an empty evidence slice if
	// the segment currently doesn't have evidence.
	GetEvidences(ctx context.Context, linkHash chainscript.LinkHash) (types.EvidenceSlice, error)
}

EvidenceReader is the interface for reading segment evidence from a store.

type EvidenceStore

type EvidenceStore interface {
	EvidenceReader
	EvidenceWriter
}

EvidenceStore is the interface for storing and reading segment evidence.

type EvidenceWriter

type EvidenceWriter interface {
	// Add an evidence to a segment.
	AddEvidence(ctx context.Context, linkHash chainscript.LinkHash, evidence *chainscript.Evidence) error
}

EvidenceWriter is the interface for adding evidence to a segment in a store.

type KeyValueReader

type KeyValueReader interface {
	GetValue(ctx context.Context, key []byte) ([]byte, error)
}

KeyValueReader is the interface for reading key-value pairs.

type KeyValueStore

type KeyValueStore interface {
	KeyValueReader
	KeyValueWriter
}

KeyValueStore is the interface for a key-value store. Some stores will implement this interface, but not all.

type KeyValueWriter

type KeyValueWriter interface {
	SetValue(ctx context.Context, key []byte, value []byte) error
	DeleteValue(ctx context.Context, key []byte) ([]byte, error)
}

KeyValueWriter is the interface for writing key-value pairs.

type LinkWriter

type LinkWriter interface {
	// Create the immutable part of a segment.
	// The input link is expected to be valid.
	// Returns the link hash or an error.
	CreateLink(ctx context.Context, link *chainscript.Link) (chainscript.LinkHash, error)
}

LinkWriter is the interface for writing links to a store. Links are immutable and cannot be deleted.

type MapFilter

type MapFilter struct {
	Pagination `json:"pagination"`

	// Filter to get maps with IDs starting with a given prefix.
	Prefix string `json:"prefix" url:"prefix"`

	// Filter to get maps with IDs ending with a given suffix.
	Suffix string `json:"suffix" url:"suffix"`

	// Process name is optional.
	Process string `json:"process" url:"process"`
}

MapFilter contains filtering options for segments.

func (MapFilter) Match

func (filter MapFilter) Match(segment *chainscript.Segment) bool

Match checks if segment matches with filter.

func (MapFilter) MatchLink

func (filter MapFilter) MatchLink(link *chainscript.Link) bool

MatchLink checks if link matches with filter.

type Pagination

type Pagination struct {
	// Index of the first entry.
	Offset int `json:"offset" url:"offset"`

	// Maximum number of entries.
	Limit int `json:"limit" url:"limit"`
}

Pagination contains pagination options.

func (*Pagination) PaginateSegments

func (p *Pagination) PaginateSegments(a *types.PaginatedSegments) *types.PaginatedSegments

PaginateSegments paginate a list of segments.

func (*Pagination) PaginateStrings

func (p *Pagination) PaginateStrings(a []string) []string

PaginateStrings paginates a list of strings.

type SegmentFilter

type SegmentFilter struct {
	Pagination `json:"pagination"`

	// Map IDs the segments must have.
	MapIDs []string `json:"mapIds" url:"mapIds,brackets"`

	// Process name the segments must have.
	Process string `json:"process" url:"process"`

	// Step the segments must have.
	Step string `json:"step" url:"step"`

	// If true, selects only segments that don't have a parent.
	WithoutParent bool `json:"withoutParent" url:"withoutParent"`

	// A previous link hash the segments must have.
	PrevLinkHash chainscript.LinkHash `json:"prevLinkHash" url:"-"`

	// A slice of linkHashes to search Segments.
	LinkHashes []chainscript.LinkHash `json:"linkHashes" url:"-"`

	// A link that should be referenced by the matching segments.
	Referencing chainscript.LinkHash `json:"referencing" url:"-"`

	// A slice of tags the segments must all contain.
	Tags []string `json:"tags" url:"tags,brackets"`

	// Flag to reverse segment ordering.
	Reverse bool `json:"reverse" url:"reverse"`
}

SegmentFilter contains filtering options for segments.

func (SegmentFilter) Match

func (filter SegmentFilter) Match(segment *chainscript.Segment) bool

Match checks if segment matches with filter.

func (SegmentFilter) MatchLink

func (filter SegmentFilter) MatchLink(link *chainscript.Link) bool

MatchLink checks if link matches with filter.

type SegmentReader

type SegmentReader interface {
	// Get a segment by link hash. Returns nil if no match is found.
	// Will return link and evidences (if there are some in that store).
	GetSegment(ctx context.Context, linkHash chainscript.LinkHash) (*chainscript.Segment, error)

	// Find segments. Returns an empty slice if there are no results.
	// Will return links and evidences (if there are some).
	FindSegments(ctx context.Context, filter *SegmentFilter) (*types.PaginatedSegments, error)

	// Get all the existing map IDs.
	GetMapIDs(ctx context.Context, filter *MapFilter) ([]string, error)
}

SegmentReader is the interface for reading Segments from a store.