storage

Documentation

Index

• Constants
• Variables
• func DecodeGetResponse[V Value](resp *clientv3.GetResponse) ([]V, error)
• func Key(elem ...string) string
• func Prefix(elem ...string) string
• type DeleteOp
  • func NewDeleteKeyOp(client *clientv3.Client, key string, options ...clientv3.OpOption) DeleteOp
  • func NewDeletePrefixOp(client *clientv3.Client, prefix string, options ...clientv3.OpOption) DeleteOp
• type DeleteValueOp
  • func NewDeleteValueOp[V Value](client *clientv3.Client, key string, val V, options ...clientv3.OpOption) DeleteValueOp[V]
• type Event
• type EventType
• type ExistsOp
  • func NewExistsOp(client *clientv3.Client, key string) ExistsOp
• type GetMultipleOp
  • func NewGetMultipleOp[V Value](client *clientv3.Client, keys []string, options ...clientv3.OpOption) GetMultipleOp[V]
  • func NewGetPrefixOp[V Value](client *clientv3.Client, prefix string, options ...clientv3.OpOption) GetMultipleOp[V]
  • func NewGetRangeOp[V Value](client *clientv3.Client, start, end string, options ...clientv3.OpOption) GetMultipleOp[V]
• type GetOp
  • func NewGetOp[V Value](client *clientv3.Client, key string, options ...clientv3.OpOption) GetOp[V]
• type PutOp
  • func NewCreateOp[V Value](client *clientv3.Client, key string, val V, options ...clientv3.OpOption) PutOp[V]
  • func NewPutOp[V Value](client *clientv3.Client, key string, val V, options ...clientv3.OpOption) PutOp[V]
  • func NewUpdateOp[V Value](client *clientv3.Client, key string, val V, options ...clientv3.OpOption) PutOp[V]
• type StoredValue
  • func (v *StoredValue) SetVersion(version int64)
  • func (v *StoredValue) Version() int64
• type Txn
  • func NewTxn(client *clientv3.Client, ops ...TxnOperation) Txn
• type TxnOperation
• type Value
• type WatchOp
  • func NewWatchOp[V Value](client *clientv3.Client, key string, options ...clientv3.OpOption) WatchOp[V]
  • func NewWatchPrefixOp[V Value](client *clientv3.Client, key string, options ...clientv3.OpOption) WatchOp[V]

Constants

const (
	EventTypePut     = "put"
	EventTypeDelete  = "delete"
	EventTypeError   = "error"
	EventTypeUnknown = "unknown"
)

Variables

var ErrAlreadyExists = errors.New("key already exists")

ErrAlreadyExists indicates that a value could not be created because the key already exists.

var ErrDuplicateKeysInTransaction = errors.New("duplicate keys in transaction")

ErrDuplicateKeysInTransaction indicates that the transaction contained duplicate keys.

var ErrNotFound = errors.New("key not found")

ErrNotFound indicates that no values were found for the given key.

var ErrOperationConstraintViolated = errors.New("operation constraint violated")

ErrOperationConstraintViolated indicates that one of the constraints on the operation, such as 'version = 0', was violated.

var ErrValueVersionMismatch = errors.New("value version mismatch")

ErrValueVersionMismatch indicates that the operation failed because the stored value's version didn't match the given value's version.

var ErrWatchAlreadyInProgress = errors.New("watch already in progress")

ErrWatchAlreadyInProgress indicates that the WatchOp has already been started and cannot be started again until it's closed.

var ErrWatchClosed = errors.New("watch closed by server")

ErrWatchClosed indicates that the server has forced the watch to close. Callers should either restart or recreate the watch in that case.

var ErrWatchUntilTimedOut = errors.New("timed out waiting for watch condition")

ErrWatchUntilTimedOut indicates that the condition given to Watch.Until was not met before the given timeout.

Functions

func DecodeGetResponse

func DecodeGetResponse[V Value](resp *clientv3.GetResponse) ([]V, error)

DecodeGetResponse is a helper function to extract typed values from a clientv3.GetResponse

func Key

func Key(elem ...string) string

Key returns a slash-separated key.

func Prefix

func Prefix(elem ...string) string

Prefix returns a slash-separated key prefix with a trailing slash to ensure that its safe for use in all storage operations.

Types

type DeleteOp

type DeleteOp interface {
	TxnOperation
	Exec(ctx context.Context) (int64, error)
}

DeleteOp is an operation that deletes one or more values from storage, and returns the number of values deleted.

func NewDeleteKeyOp

func NewDeleteKeyOp(client *clientv3.Client, key string, options ...clientv3.OpOption) DeleteOp

NewDeleteKeyOp returns an operation that deletes a single value by key.

func NewDeletePrefixOp

func NewDeletePrefixOp(client *clientv3.Client, prefix string, options ...clientv3.OpOption) DeleteOp

NewDeletePrefixOp returns an operation that deletes a multiple values by prefix.

type DeleteValueOp

type DeleteValueOp[V Value] interface {
	TxnOperation
	Exec(ctx context.Context) error
}

DeleteValueOp is a delete operation that deletes a single value from storage and enforces value version constraints. Implementations should return an ErrValueVersionMismatch if the constraint fails.

func NewDeleteValueOp

func NewDeleteValueOp[V Value](client *clientv3.Client, key string, val V, options ...clientv3.OpOption) DeleteValueOp[V]

NewDeleteValueOp deletes a single value if its version matches the given value's version. Its Exec method will return an ErrValueVersionMismatch if the stored value version did not match the given value version.

type Event

type Event[V Value] struct {
	// Err will be non-nil when Type is "error". The error will be an
	// ErrWatchClosed if the server forced the watch to close. In that case,
	// callers are able to call Watch() again to restart the watch.
	Err      error
	Type     EventType
	Key      string
	Value    V
	IsCreate bool
	IsModify bool
}

Event is generated by a modification to the watched key.

type EventType

type EventType string

type ExistsOp

type ExistsOp interface {
	Exec(ctx context.Context) (bool, error)
}

ExistsOp is an operation that returns true if a the given key(s) exist.

func NewExistsOp

func NewExistsOp(client *clientv3.Client, key string) ExistsOp

NewExistsOp returns an operation that returns true if a key exists.

type GetMultipleOp

type GetMultipleOp[V Value] interface {
	Exec(ctx context.Context) ([]V, error)
}

GetMultipleOp is an operation that returns multiple values.

func NewGetMultipleOp

func NewGetMultipleOp[V Value](client *clientv3.Client, keys []string, options ...clientv3.OpOption) GetMultipleOp[V]

NewGetMultipleOp returns an operation that returns multiple values by key.

func NewGetPrefixOp

func NewGetPrefixOp[V Value](client *clientv3.Client, prefix string, options ...clientv3.OpOption) GetMultipleOp[V]

NewGetPrefixOp returns an operation that returns multiple values by prefix.

func NewGetRangeOp

func NewGetRangeOp[V Value](client *clientv3.Client, start, end string, options ...clientv3.OpOption) GetMultipleOp[V]

NewGetRangeOp returns an operation that returns values in the range [start, end).

type GetOp

type GetOp[V Value] interface {
	Exec(ctx context.Context) (V, error)
}

GetOp is an operation that returns a single value.

func NewGetOp

func NewGetOp[V Value](client *clientv3.Client, key string, options ...clientv3.OpOption) GetOp[V]

NewGetOp returns an operation that returns a single value by key.

type PutOp

type PutOp[V Value] interface {
	TxnOperation
	// WithTTL sets a time-to-live for this value. The value will automatically
	// be removed after the TTL has expired.
	WithTTL(ttl time.Duration) PutOp[V]
	Exec(ctx context.Context) error
}

PutOp is an operation that puts a key-value pair into storage.

func NewCreateOp

func NewCreateOp[V Value](client *clientv3.Client, key string, val V, options ...clientv3.OpOption) PutOp[V]

func NewPutOp

func NewPutOp[V Value](client *clientv3.Client, key string, val V, options ...clientv3.OpOption) PutOp[V]

func NewUpdateOp

func NewUpdateOp[V Value](client *clientv3.Client, key string, val V, options ...clientv3.OpOption) PutOp[V]

type StoredValue

type StoredValue struct {
	// contains filtered or unexported fields
}

StoredValue is an embeddable struct that can be used to implement the Value interface on other structs.

func (*StoredValue) SetVersion

func (v *StoredValue) SetVersion(version int64)

func (*StoredValue) Version

func (v *StoredValue) Version() int64

type Txn

type Txn interface {
	AddOps(ops ...TxnOperation)
	Commit(ctx context.Context) error
}

Txn is a group of operations that will be executed together in a transaction. Similar to transactions in other systems, if any of the operations contains a condition, such as the CreateOp operation, and that condition fails, the entire transaction will fail. Each operation in the transaction must operate on a unique key.

func NewTxn

func NewTxn(client *clientv3.Client, ops ...TxnOperation) Txn

type TxnOperation

type TxnOperation interface {
	Ops(ctx context.Context) ([]clientv3.Op, error)
	Cmps() []clientv3.Cmp
}

TxnOperation is a storage operation that can be used in a transaction.

type Value

type Value interface {
	Version() int64
	SetVersion(version int64)
}

Value is the interface that all stored values must adhere to. Values must be JSON-serializable and have a 'version' field that they expose through the methods on this interface. The 'version' field should be omitted from the JSON representation using a `json:"-"` tag.

type WatchOp

type WatchOp[V Value] interface {
	// Watch persistently watches for modifications until Close is called or
	// until Etcd returns an error. Watch will automatically call Close in case
	// of an error. This method is non-blocking.
	Watch(ctx context.Context, handle func(e *Event[V])) error
	// Until blocks until either the timeout has elapsed or until handle returns
	// true. Until automatically calls Close before returning.
	Until(ctx context.Context, timeout time.Duration, handle func(e *Event[V]) bool) error
	// Close cancels the active watch and enables callers to use Watch or Until
	// again.
	Close()
}

WatchOp watches one or more keys for modifications.

func NewWatchOp

func NewWatchOp[V Value](client *clientv3.Client, key string, options ...clientv3.OpOption) WatchOp[V]

func NewWatchPrefixOp

func NewWatchPrefixOp[V Value](client *clientv3.Client, key string, options ...clientv3.OpOption) WatchOp[V]