store

Documentation

Overview

Package store is an interface for distributed data storage. The design document is located at https://github.com/micro/development/blob/master/design/framework/store.md

Index

• Constants
• Variables
• func Delete(key string) error
• func List(opts ...ListOption) ([]string, error)
• func Write(r *Record) error
• type BlobListOption
  • func BlobListNamespace(namespace string) BlobListOption
  • func BlobListPrefix(prefix string) BlobListOption
• type BlobListOptions
• type BlobOption
  • func BlobContentType(contentType string) BlobOption
  • func BlobNamespace(ns string) BlobOption
  • func BlobPublic(p bool) BlobOption
• type BlobOptions
• type BlobStore
• type DeleteOption
  • func DeleteFrom(database, table string) DeleteOption
• type DeleteOptions
• type ListOption
  • func ListFrom(database, table string) ListOption
  • func ListLimit(l uint) ListOption
  • func ListOffset(o uint) ListOption
  • func ListOrder(o Order) ListOption
  • func ListPrefix(p string) ListOption
  • func ListSuffix(s string) ListOption
• type ListOptions
• type Option
  • func Database(db string) Option
  • func Nodes(a ...string) Option
  • func Table(t string) Option
  • func WithContext(c context.Context) Option
• type Options
• type Order
• type ReadOption
  • func ReadFrom(database, table string) ReadOption
  • func ReadLimit(l uint) ReadOption
  • func ReadOffset(o uint) ReadOption
  • func ReadOrder(o Order) ReadOption
  • func ReadPrefix() ReadOption
  • func ReadSuffix() ReadOption
• type ReadOptions
• type Record
  • func NewRecord(key string, val interface{}) *Record
  • func Read(key string, opts ...ReadOption) ([]*Record, error)
  • func (r *Record) Decode(v interface{}) error
  • func (r *Record) Encode(v interface{}) error
• type Store
• type StoreOption
• type StoreOptions
• type WriteOption
  • func WriteTo(database, table string) WriteOption
• type WriteOptions

Constants

const (
	OrderAsc  = Order("asc")
	OrderDesc = Order("desc")
)

Variables

var (
	// DefaultStore implementation
	DefaultStore Store
	// DefaultBlobStore implementation
	DefaultBlobStore BlobStore
	// ErrNotFound is returned when a key doesn't exist
	ErrNotFound = errors.New("not found")
)

var (
	// ErrMissingKey is returned when no key is passed to blob store Read / Write
	ErrMissingKey = errors.New("missing key")
)

Functions

func Delete

func Delete(key string) error

Delete removes the record with the corresponding key from the store.

func List

func List(opts ...ListOption) ([]string, error)

List returns any keys that match, or an empty list with no error if none matched.

func Write

func Write(r *Record) error

Write a record to the store

Types

type BlobListOption

type BlobListOption func(o *BlobListOptions)

func BlobListNamespace

func BlobListNamespace(namespace string) BlobListOption

func BlobListPrefix

func BlobListPrefix(prefix string) BlobListOption

type BlobListOptions

type BlobListOptions struct {
	Namespace string
	Prefix    string
}

type BlobOption

type BlobOption func(o *BlobOptions)

BlobOption sets one or more BlobOptions

func BlobContentType

func BlobContentType(contentType string) BlobOption

BlobNamespace sets the Public option

func BlobNamespace

func BlobNamespace(ns string) BlobOption

BlobNamespace sets the Namespace option

func BlobPublic

func BlobPublic(p bool) BlobOption

BlobNamespace sets the Public option

type BlobOptions

type BlobOptions struct {
	// Namespace to  from
	Namespace   string
	Public      bool
	ContentType string
}

BlobOptions contains options to use when interacting with the store

type BlobStore

type BlobStore interface {
	Read(key string, opts ...BlobOption) (io.Reader, error)
	Write(key string, blob io.Reader, opts ...BlobOption) error
	Delete(key string, opts ...BlobOption) error
	// List returns any keys that match, or an empty list with no error if none matched.
	List(opts ...BlobListOption) ([]string, error)
}

BlobStore is an interface for reading / writing blobs

type DeleteOption

type DeleteOption func(d *DeleteOptions)

DeleteOption sets values in DeleteOptions

func DeleteFrom

func DeleteFrom(database, table string) DeleteOption

DeleteFrom the database and table

type DeleteOptions

type DeleteOptions struct {
	Database, Table string
}

DeleteOptions configures an individual Delete operation

type ListOption

type ListOption func(l *ListOptions)

ListOption sets values in ListOptions

func ListFrom

func ListFrom(database, table string) ListOption

ListFrom the database and table

func ListLimit

func ListLimit(l uint) ListOption

ListLimit limits the number of returned keys to l

func ListOffset

func ListOffset(o uint) ListOption

ListOffset starts returning responses from o. Use in conjunction with Limit for pagination.

func ListOrder

func ListOrder(o Order) ListOption

ListOrder specifies the order to return the data

func ListPrefix

func ListPrefix(p string) ListOption

ListPrefix returns all keys that are prefixed with key

func ListSuffix

func ListSuffix(s string) ListOption

ListSuffix returns all keys that end with key

type ListOptions

type ListOptions struct {
	// List from the following
	Database, Table string
	// Prefix returns all keys that are prefixed with key
	Prefix string
	// Suffix returns all keys that end with key
	Suffix string
	// Limit limits the number of returned keys
	Limit uint
	// Offset when combined with Limit supports pagination
	Offset uint
	// Order to list the data set
	Order Order
}

ListOptions configures an individual List operation

type Option

type Option func(o *Options)

Option sets values in Options

func Database

func Database(db string) Option

Database allows multiple isolated stores to be kept in one backend, if supported.

func Nodes

func Nodes(a ...string) Option

Nodes contains the addresses or other connection information of the backing storage. For example, an etcd implementation would contain the nodes of the cluster. A SQL implementation could contain one or more connection strings.

func Table

func Table(t string) Option

Table is analagous to a table in database backends or a key prefix in KV backends

func WithContext

func WithContext(c context.Context) Option

WithContext sets the stores context, for any extra configuration

type Options

type Options struct {
	// Nodes contains the addresses or other connection information of the backing storage.
	// For example, an etcd implementation would contain the nodes of the cluster.
	// A SQL implementation could contain one or more connection strings.
	Nodes []string
	// Database allows multiple isolated stores to be kept in one backend, if supported.
	Database string
	// Table is analagous to a table in database backends or a key prefix in KV backends
	Table string
	// Context should contain all implementation specific options, using context.WithValue.
	Context context.Context
}

Options contains configuration for the Store

type Order

type Order string

Order

type ReadOption

type ReadOption func(r *ReadOptions)

ReadOption sets values in ReadOptions

func ReadFrom

func ReadFrom(database, table string) ReadOption

ReadFrom the database and table

func ReadLimit

func ReadLimit(l uint) ReadOption

ReadLimit limits the number of responses to l

func ReadOffset

func ReadOffset(o uint) ReadOption

ReadOffset starts returning responses from o. Use in conjunction with Limit for pagination

func ReadOrder

func ReadOrder(o Order) ReadOption

ReadOrder specifies the order to return the data

func ReadPrefix

func ReadPrefix() ReadOption

ReadPrefix returns all records that are prefixed with key

func ReadSuffix

func ReadSuffix() ReadOption

ReadSuffix returns all records that have the suffix key

type ReadOptions

type ReadOptions struct {
	Database, Table string
	// Prefix returns all records that are prefixed with key
	Prefix bool
	// Suffix returns all records that have the suffix key
	Suffix bool
	// Limit limits the number of returned records
	Limit uint
	// Offset when combined with Limit supports pagination
	Offset uint
	// Order of the data returned e.g asc or desc
	Order Order
}

ReadOptions configures an individual Read operation

type Record

type Record struct {
	// The key to store the record
	Key string `json:"key"`
	// The value within the record
	Value []byte `json:"value"`
	// Any associated metadata for indexing
	Metadata map[string]interface{} `json:"metadata"`
	// Time to expire a record: TODO: change to timestamp
	Expiry time.Duration `json:"expiry,omitempty"`
}

Record is an item stored or retrieved from a Store

func NewRecord

func NewRecord(key string, val interface{}) *Record

NewRecord returns a record from key, val

func Read

func Read(key string, opts ...ReadOption) ([]*Record, error)

Read records

func (*Record) Decode

func (r *Record) Decode(v interface{}) error

Decode is a convenience helper for decoding records

func (*Record) Encode

func (r *Record) Encode(v interface{}) error

Encode will marshal any type into the byte Value field

type Store

type Store interface {
	// Init initialises the store. It must perform any required setup on the backing storage implementation and check that it is ready for use, returning any errors.
	Init(...Option) error
	// Options allows you to view the current options.
	Options() Options
	// Read takes a single key name and optional ReadOptions. It returns matching []*Record or an error.
	Read(key string, opts ...ReadOption) ([]*Record, error)
	// Write writes a record to the store, and returns an error if the record was not written.
	Write(r *Record, opts ...WriteOption) error
	// Delete removes the record with the corresponding key from the store.
	Delete(key string, opts ...DeleteOption) error
	// List returns any keys that match, or an empty list with no error if none matched.
	List(opts ...ListOption) ([]string, error)
	// Close the store
	Close() error
	// String returns the name of the implementation.
	String() string
}

Store is a data storage interface

type StoreOption

type StoreOption = Option

type StoreOptions

type StoreOptions = Options

type WriteOption

type WriteOption func(w *WriteOptions)

WriteOption sets values in WriteOptions

func WriteTo

func WriteTo(database, table string) WriteOption

WriteTo the database and table

type WriteOptions

type WriteOptions struct {
	Database, Table string
}

WriteOptions configures an individual Write operation If Expiry and TTL are set TTL takes precedence