storage

Documentation

Index

• Variables
• func ChunkType(ch swarm.Chunk) swarm.ChunkType
• type Batch
• type BatchStore
• type Batcher
• type ChunkGetterDeleter
• type ChunkState
• type ChunkStore
• type Cloner
• type Deleter
• type Descriptor
  • func (d *Descriptor) String() string
• type Filter
• type Getter
• type GetterFunc
  • func (f GetterFunc) Get(ctx context.Context, address swarm.Address) (swarm.Chunk, error)
• type Hasser
• type IndexStore
• type Item
• type IterateChunkFn
• type IterateFn
• type Key
• type Marshaler
• type Order
• type PullSubscriber
• type PushReporter
• type PushSubscriber
• type Putter
• type PutterFunc
  • func (f PutterFunc) Put(ctx context.Context, chunk swarm.Chunk) error
• type Query
  • func (q Query) Validate() error
• type QueryItemProperty
• type ReadOnlyChunkStore
• type Reader
• type Recoverer
• type Result
• type Sharky
• type SizeReporter
• type StateIterFunc
• type StateStorer
• type StateStorerCleaner
• type Store
• type Unmarshaler
• type Writer

Variables

var (
	ErrInvalidQuery    = errors.New("storage: invalid query")
	ErrNotFound        = errors.New("storage: not found")
	ErrReferenceLength = errors.New("storage: invalid reference length")
	ErrInvalidChunk    = errors.New("storage: invalid chunk")
)

ErrInvalidQuery indicates that the query is not a valid query.

var ErrBatchCommitted = errors.New("storage: batch has already been committed")

ErrBatchCommitted is returned by Batch.Commit call when a batch has already been committed.

var (
	ErrOverwriteNewerChunk = errors.New("overwriting chunk with newer timestamp")
)

Functions

func ChunkType

func ChunkType(ch swarm.Chunk) swarm.ChunkType

Types

type Batch

type Batch interface {
	// Put adds a new item to the batch.
	Put(Item) error

	// Delete adds a new delete operation to the batch.
	Delete(Item) error

	// Commit commits the batch.
	Commit() error
}

Batch provides set of operations that are batched.

type BatchStore

type BatchStore interface {
	Store
	Batcher
}

BatchStore is a store that supports batching of Writer method calls.

type Batcher

type Batcher interface {
	// Batch returns a new Batch.
	Batch(context.Context) Batch
}

Batcher specifies a constructor for creating new batches.

type ChunkGetterDeleter

type ChunkGetterDeleter interface {
	Getter
	Deleter
}

ChunkGetterDeleter is a storage that provides only read and delete operations for chunks.

type ChunkState

type ChunkState = int

const (
	// ChunkSent is used by the pusher component to notify about successful push of chunk from
	// the node. A chunk could be retried on failure so, this sent count is maintained to
	// understand how many attempts were made by the node while pushing. The attempts are
	// registered only when an actual request was sent from this node.
	ChunkSent ChunkState = iota
	// ChunkStored is used by the pusher component to notify that the uploader node is
	// the closest node and has stored the chunk.
	ChunkStored
	// ChunkSynced is used by the pusher component to notify that the chunk is synced to the
	// network. This is reported when a valid receipt was received after the chunk was
	// pushed.
	ChunkSynced
	ChunkCouldNotSync
)

type ChunkStore

type ChunkStore interface {
	Getter
	Putter
	Deleter
	Hasser

	// Iterate over chunks in no particular order.
	Iterate(context.Context, IterateChunkFn) error
}

type Cloner

type Cloner interface {
	Clone() Item
}

Cloner makes a deep copy of the Item.

type Deleter

type Deleter interface {
	// Delete a chunk by the given swarm.Address.
	Delete(context.Context, swarm.Address) error
}

Deleter is the interface that wraps the basic Delete method.

type Descriptor

type Descriptor struct {
	Address swarm.Address
	BinID   uint64
}

Descriptor holds information required for Pull syncing. This struct is provided by subscribing to pull index.

func (*Descriptor) String

func (d *Descriptor) String() string

type Filter

type Filter func(string, []byte) bool

Filter subtracts entries from the iteration. Filters would not construct the Item from the serialized bytes. Instead, users can add logic to check the entries directly in byte format or partially or fully unmarshal the data and check.

type Getter

type Getter interface {
	// Get a chunk by its swarm.Address. Returns the chunk associated with
	// the address alongside with its postage stamp, or a storage.ErrNotFound
	// if the chunk is not found.
	// If the chunk has multiple stamps, then the first stamp is returned in this
	// query. In order to deterministically get the stamp, use the GetterWithStamp
	// interface. If the chunk is not found storage.ErrNotFound will be returned.
	Get(context.Context, swarm.Address) (swarm.Chunk, error)
}

Getter is the interface that wraps the basic Get method.

type GetterFunc

type GetterFunc func(context.Context, swarm.Address) (swarm.Chunk, error)

func (GetterFunc) Get

func (f GetterFunc) Get(ctx context.Context, address swarm.Address) (swarm.Chunk, error)

type Hasser

type Hasser interface {
	// Has checks whether a chunk exists in the store.
	Has(context.Context, swarm.Address) (bool, error)
}

Hasser is the interface that wraps the basic Has method.

type IndexStore

type IndexStore interface {
	Reader
	Writer
}

type Item

type Item interface {
	Key
	Marshaler
	Unmarshaler
	Cloner
	fmt.Stringer
}

Item represents an item which can be used in the Store.

type IterateChunkFn

type IterateChunkFn func(swarm.Chunk) (stop bool, err error)

type IterateFn

type IterateFn func(Result) (bool, error)

IterateFn iterates through the Items of the store in the Key.Namespace. The function returns a boolean to indicate if the iteration should stop.

type Key

type Key interface {
	// ID is the unique identifier of Item.
	ID() string

	// Namespace is used to separate similar items.
	// E.g.: can be seen as a table construct.
	Namespace() string
}

Key represents the item identifiers.

type Marshaler

type Marshaler interface {
	Marshal() ([]byte, error)
}

Marshaler is the interface implemented by types that can marshal themselves into valid Item.

type Order

type Order int

Order represents order of the iteration

const (
	// KeyAscendingOrder indicates a forward iteration based on ordering of keys.
	KeyAscendingOrder Order = iota

	// KeyDescendingOrder denotes the backward iteration based on ordering of keys.
	KeyDescendingOrder
)

type PullSubscriber

type PullSubscriber interface {
	SubscribePull(ctx context.Context, bin uint8, since, until uint64) (c <-chan Descriptor, closed <-chan struct{}, stop func())
}

type PushReporter

type PushReporter interface {
	Report(context.Context, swarm.Chunk, ChunkState) error
}

PushReporter is used to report chunk state.

type PushSubscriber

type PushSubscriber interface {
	SubscribePush(ctx context.Context) (c <-chan swarm.Chunk, stop func())
}

type Putter

type Putter interface {
	// Put a chunk into the store alongside with its postage stamp.
	Put(context.Context, swarm.Chunk) error
}

Putter is the interface that wraps the basic Put method.

type PutterFunc

type PutterFunc func(context.Context, swarm.Chunk) error

PutterFunc type is an adapter to allow the use of ChunkStore as Putter interface. If f is a function with the appropriate signature, PutterFunc(f) is a Putter that calls f.

func (PutterFunc) Put

func (f PutterFunc) Put(ctx context.Context, chunk swarm.Chunk) error

Put calls f(ctx, chunk).

type Query

type Query struct {
	// Factory is a constructor passed by client
	// to construct new object for the result.
	Factory func() Item

	// Prefix indicates interest in an item
	// that contains this prefix in its ID.
	Prefix string

	// PrefixAtStart indicates that the
	// iteration should start at the prefix.
	PrefixAtStart bool

	// SkipFirst skips the first element in the iteration.
	SkipFirst bool

	// ItemProperty indicates a specific interest of an Item property.
	ItemProperty QueryItemProperty

	// Order denotes the order of iteration.
	Order Order

	// Filters represent further constraints on the iteration.
	Filters []Filter
}

Query denotes the iteration attributes.

func (Query) Validate

func (q Query) Validate() error

Validate checks if the query is a valid query.

type QueryItemProperty

type QueryItemProperty int

QueryItemProperty tells the Query which Item property should be loaded from the store to the result.

const (
	// QueryItem indicates interest in the whole Item.
	QueryItem QueryItemProperty = iota

	// QueryItemID indicates interest in the Result.ID.
	// No data will be unmarshalled.
	QueryItemID

	// QueryItemSize indicates interest in the Result.Size.
	// No data will be unmarshalled.
	QueryItemSize
)

type ReadOnlyChunkStore

type ReadOnlyChunkStore interface {
	Getter
	Hasser
}

type Reader

type Reader interface {
	// Get unmarshalls object with the given Item.Key.ID into the given Item.
	Get(Item) error

	// Has reports whether the Item with the given Key.ID exists in the store.
	Has(Key) (bool, error)

	// GetSize returns the size of Item with the given Key.ID.
	GetSize(Key) (int, error)

	// Iterate executes the given IterateFn on this store.
	// The Result of the iteration will be affected by the given Query.
	Iterate(Query, IterateFn) error

	// Count returns the count of items in the
	// store that are in the same Key.Namespace.
	Count(Key) (int, error)
}

Reader groups methods that read from the store.

type Recoverer

type Recoverer interface {
	Recover() error
}

Recoverer allows store to recover from a failure when the transaction was not committed or rolled back.

type Result

type Result struct {
	// ID is the Key.ID of the result Item.
	ID string

	// Size is the size of the result Item.
	Size int

	// Entry in the result Item.
	Entry Item
}

Result represents the item returned by the read operation, which returns the item as the result. Or Key and/or Size in case the whole Item is not needed.

type Sharky

type Sharky interface {
	Read(context.Context, sharky.Location, []byte) error
	Write(context.Context, []byte) (sharky.Location, error)
	Release(context.Context, sharky.Location) error
}

type SizeReporter

type SizeReporter interface {
	Size() (uint64, error)
	Capacity() uint64
}

type StateIterFunc

type StateIterFunc func(key, val []byte) (stop bool, err error)

StateIterFunc is used when iterating through StateStorer key/value pairs

type StateStorer

type StateStorer interface {
	io.Closer

	// Get unmarshalls object with the given key into the given obj.
	Get(key string, obj interface{}) error

	// Put inserts or updates the given obj stored under the given key.
	Put(key string, obj interface{}) error

	// Delete removes object form the store stored under the given key.
	Delete(key string) error

	// Iterate iterates over all keys with the given prefix and calls iterFunc.
	Iterate(prefix string, iterFunc StateIterFunc) error
}

StateStorer is a storage interface for storing and retrieving key/value pairs.

type StateStorerCleaner

type StateStorerCleaner interface {
	// Nuke the store so that only the bare essential entries are left.
	Nuke() error
}

StateStorerCleaner is the interface for cleaning the store.

type Store

type Store interface {
	io.Closer

	Reader
	Writer
}

Store contains the methods required for the Data Abstraction Layer.

type Unmarshaler

type Unmarshaler interface {
	Unmarshal([]byte) error
}

Unmarshaler is the interface implemented by types that can unmarshal a JSON description of themselves. The input can be assumed to be a valid encoding of a Item value.

type Writer

type Writer interface {
	// Put inserts or updates the given Item identified by its Key.ID.
	Put(Item) error

	// Delete removes the given Item form the store.
	// It will not return error if the key doesn't exist.
	Delete(Item) error
}

Writer groups methods that change the state of the store.