go-micro.dev/v5@v5.12.0/store/store.go (about)

     1  // Package store is an interface for distributed data storage.
     2  // The design document is located at https://github.com/micro/development/blob/master/design/store.md
     3  package store
     4  
     5  import (
     6  	"errors"
     7  	"time"
     8  
     9  	"encoding/json"
    10  )
    11  
    12  var (
    13  	// ErrNotFound is returned when a key doesn't exist.
    14  	ErrNotFound = errors.New("not found")
    15  	// DefaultStore is the memory store.
    16  	DefaultStore Store = NewStore()
    17  )
    18  
    19  // Store is a data storage interface.
    20  type Store interface {
    21  	// Init initializes the store. It must perform any required setup on the backing storage implementation and check that it is ready for use, returning any errors.
    22  	Init(...Option) error
    23  	// Options allows you to view the current options.
    24  	Options() Options
    25  	// Read takes a single key name and optional ReadOptions. It returns matching []*Record or an error.
    26  	Read(key string, opts ...ReadOption) ([]*Record, error)
    27  	// Write() writes a record to the store, and returns an error if the record was not written.
    28  	Write(r *Record, opts ...WriteOption) error
    29  	// Delete removes the record with the corresponding key from the store.
    30  	Delete(key string, opts ...DeleteOption) error
    31  	// List returns any keys that match, or an empty list with no error if none matched.
    32  	List(opts ...ListOption) ([]string, error)
    33  	// Close the store
    34  	Close() error
    35  	// String returns the name of the implementation.
    36  	String() string
    37  }
    38  
    39  // Record is an item stored or retrieved from a Store.
    40  type Record struct {
    41  	// Any associated metadata for indexing
    42  	Metadata map[string]interface{} `json:"metadata"`
    43  	// The key to store the record
    44  	Key string `json:"key"`
    45  	// The value within the record
    46  	Value []byte `json:"value"`
    47  	// Time to expire a record: TODO: change to timestamp
    48  	Expiry time.Duration `json:"expiry,omitempty"`
    49  }
    50  
    51  func NewStore(opts ...Option) Store {
    52  	return NewFileStore(opts...)
    53  }
    54  
    55  func NewRecord(key string, val interface{}) *Record {
    56  	b, _ := json.Marshal(val)
    57  	return &Record{
    58  		Key:   key,
    59  		Value: b,
    60  	}
    61  }
    62  
    63  // Encode will marshal any type into the byte Value field
    64  func (r *Record) Encode(v interface{}) error {
    65  	b, err := json.Marshal(v)
    66  	if err != nil {
    67  		return err
    68  	}
    69  	r.Value = b
    70  	return nil
    71  }
    72  
    73  // Decode is a convenience helper for decoding records
    74  func (r *Record) Decode(v interface{}) error {
    75  	return json.Unmarshal(r.Value, v)
    76  }
    77  
    78  // Read records
    79  func Read(key string, opts ...ReadOption) ([]*Record, error) {
    80  	// execute the query
    81  	return DefaultStore.Read(key, opts...)
    82  }
    83  
    84  // Write a record to the store
    85  func Write(r *Record) error {
    86  	return DefaultStore.Write(r)
    87  }
    88  
    89  // Delete removes the record with the corresponding key from the store.
    90  func Delete(key string) error {
    91  	return DefaultStore.Delete(key)
    92  }
    93  
    94  // List returns any keys that match, or an empty list with no error if none matched.
    95  func List(opts ...ListOption) ([]string, error) {
    96  	return DefaultStore.List(opts...)
    97  }