blob

Documentation

Overview

Package blob implements an interface and support code for persistent storage of untyped binary blobs.

Index

• Variables
• func IsKeyExists(err error) bool
• func IsKeyNotFound(err error) bool
• func KeyExists(key string) error
• func KeyNotFound(key string) error
• func SyncKeys(ctx context.Context, ks KVCore, keys []string) ([]string, error)
• type CAS
  • func CASFromKV(kv KV) CAS
  • func CASFromKVError(kv KV, err error) (CAS, error)
• type Closer
• type KV
• type KVCore
• type KeyError
  • func (k *KeyError) Error() string
  • func (k *KeyError) Unwrap() error
• type PutOptions
• type Store
• type StoreCloser
• type SyncKeyer

Variables

var (
	// ErrKeyExists is reported by Put when writing a key that already exists in
	// the store.
	ErrKeyExists = errors.New("key already exists")

	// ErrKeyNotFound is reported by Get or Size when given a key that does not
	// exist in the store.
	ErrKeyNotFound = errors.New("key not found")

	// ErrStopListing is used by a List callback to terminate the listing.
	ErrStopListing = errors.New("stop listing keys")
)

Functions

func IsKeyExists

func IsKeyExists(err error) bool

IsKeyExists reports whether err is or wraps ErrKeyExists.

func IsKeyNotFound

func IsKeyNotFound(err error) bool

IsKeyNotFound reports whether err or is or wraps ErrKeyNotFound. It is false if err == nil.

func KeyExists

func KeyExists(key string) error

KeyExists returns an ErrKeyExists error reporting that key exists in the store. The concrete type is *blob.KeyError.

func KeyNotFound

func KeyNotFound(key string) error

KeyNotFound returns an ErrKeyNotFound error reporting that key was not found. The concrete type is *blob.KeyError.

func SyncKeys

func SyncKeys(ctx context.Context, ks KVCore, keys []string) ([]string, error)

SyncKeys reports which of the given keys are not present in the key space. If all the keys are present, SyncKeys returns an empty slice or nil. The order of returned keys is unspecified.

If ks implements the SyncKeyer interface, its implementation is used; otherwise an implementation using the List method is provided.

Types

type CAS

type CAS interface {
	KVCore

	// CASPut writes data to a content-addressed blob in the underlying store,
	// and returns the assigned key. The target key is returned even in case of
	// error.
	CASPut(ctx context.Context, data []byte) (string, error)

	// CASKey returns the content address of data without modifying the store.
	// This must be the same value that would be returned by a successful call
	// to CASPut on data.
	CASKey(ctx context.Context, data []byte) string
}

CAS represents a mutable set of content-addressed key-value pairs in which each value is identified by a unique, opaque string key.

func CASFromKV

func CASFromKV(kv KV) CAS

CASFromKV converts a KV into a CAS. This is intended for use by storage implementations to support the CAS method of the Store interface.

func CASFromKVError

func CASFromKVError(kv KV, err error) (CAS, error)

CASFromKVError converts a KV into a CAS. This is a convenience wrapper to combine an error check with a call to CASFromKV for use in storage implementations.

type Closer

type Closer interface {
	Close(context.Context) error
}

Closer is an extension interface representing the ability to close and release resources claimed by a storage component.

type KV

type KV interface {
	KVCore

	// Put writes a blob to the store. If the store already contains the
	// specified key and opts.Replace is true, the existing value is replaced
	// without error; otherwise Put must report an ErrKeyExists error.
	Put(ctx context.Context, opts PutOptions) error
}

A KV represents a mutable set of key-value pairs in which each value is identified by a unique, opaque string key. An implementation of KV is permitted (but not required) to report an error from Put when given an empty key. If the implementation cannot store empty keys, it must report ErrKeyNotFound when operating on an empty key.

Implementations of this interface must be safe for concurrent use by multiple goroutines. Moreover, any sequence of operations on a KV that does not overlap with any Delete executions must be linearizable.1

type KVCore

type KVCore interface {
	// Get fetches the contents of a blob from the store. If the key is not
	// found in the store, Get must report an ErrKeyNotFound error.
	Get(ctx context.Context, key string) ([]byte, error)

	// Delete atomically removes a blob from the store. If the key is not found
	// in the store, Delete must report an ErrKeyNotFound error.
	Delete(ctx context.Context, key string) error

	// List calls f with each key in the store in lexicographic order, beginning
	// with the first key greater than or equal to start.  If f reports an error
	// listing stops and List returns.  If f reported an ErrStopListing error,
	// List returns nil; otherwise List returns the error reported by f.
	List(ctx context.Context, start string, f func(string) error) error

	// Len reports the number of keys currently in the store.
	Len(ctx context.Context) (int64, error)
}

KVCore is the common interface shared by implementations of a key-value namespace. Users will generally not use this interface directly; it is included by reference in KV and CAS.

type KeyError

type KeyError struct {
	Err error  // the underlying error
	Key string // the key implicated by the error
}

KeyError is the concrete type of errors involving a blob key. The caller may type-assert to *blob.KeyError to recover the key.

func (*KeyError) Error

func (k *KeyError) Error() string

Error implements the error interface for KeyError. The default error string does not include the key, since error values are often logged by default and keys may be sensitive.

func (*KeyError) Unwrap

func (k *KeyError) Unwrap() error

Unwrap returns the underlying error from k, to support error wrapping.

type PutOptions

type PutOptions struct {
	Key     string // the key to associate with the data
	Data    []byte // the data to write
	Replace bool   // whether to replace an existing value for this key
}

PutOptions regulate the behaviour of the Put method of a KV implementation.

type Store

type Store interface {
	// KV returns a key space on the store.
	//
	// Multiple calls to KV with the same name are not required to return
	// exactly the same [KV] value, but should return values that will converge
	// (eventually) to the same view of the storage.
	KV(ctx context.Context, name string) (KV, error)

	// CAS returns a content-addressed key space on the store.
	//
	// Multiple calls to CAS with the same name are not required to return
	// exactly the same [KV] value, but should return values that will converge
	// (eventually) to the same view of the storage.
	CAS(ctx context.Context, name string) (CAS, error)

	// Sub returns a new Store subordinate to the receiver (a "substore").
	// A substore shares logical storage with its parent store, but keyspaces
	// derived from the substore are distinct from keyspaces of the parent store
	// or any other substores derived from it.
	//
	// Multiple calls to Sub with the same name are not required to return
	// exactly the same [Store] value, but should return values that will
	// converge (eventually) to the same view of the storage.
	Sub(ctx context.Context, name string) (Store, error)
}

A Store represents a collection of key-value namespaces ("keyspaces") identified by string labels. Each keyspace in a store is logically distinct; the keys from one space are independent of the keys in another.

Implementations of this interface must be safe for concurrent use by multiple goroutines.

The [Store.KV] and [Store.CAS] methods share a namespace, meaning that a KV and a CAS on the same name must share the same underlying key-value space. In particular a Put to a KV or a CASPut (from a CAS) must be visible to a Get or List from either, if both were made from the same Store with the same name.

type StoreCloser

type StoreCloser interface {
	Store
	Closer
}

StoreCloser combines a Store with a Close method that settles state and releases any resources from the store when it is no longer in use.

type SyncKeyer

type SyncKeyer interface {
	// SyncKeys reports which of the given keys are not present in the store.
	// If all the keys are present, SyncKeys returns an empty slice or nil.
	// The order of returned keys is unspecified.
	SyncKeys(ctx context.Context, keys []string) ([]string, error)
}

SyncKeyer is an optional interface that a store may implement to support checking for the presence of keys in the store without fetching them.