github.com/tickoalcantara12/micro/v3@v3.0.0-20221007104245-9d75b9bcbab9/service/store/store.go (about)

     1  // Licensed under the Apache License, Version 2.0 (the "License");
     2  // you may not use this file except in compliance with the License.
     3  // You may obtain a copy of the License at
     4  //
     5  //     https://www.apache.org/licenses/LICENSE-2.0
     6  //
     7  // Unless required by applicable law or agreed to in writing, software
     8  // distributed under the License is distributed on an "AS IS" BASIS,
     9  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    10  // See the License for the specific language governing permissions and
    11  // limitations under the License.
    12  //
    13  // Original source: github.com/micro/go-micro/v3/store/store.go
    14  
    15  // Package store is an interface for distributed data storage.
    16  // The design document is located at https://github.com/micro/development/blob/master/design/framework/store.md
    17  package store
    18  
    19  import (
    20  	"encoding/json"
    21  	"errors"
    22  	"time"
    23  )
    24  
    25  // Order
    26  type Order string
    27  
    28  const (
    29  	OrderAsc  = Order("asc")
    30  	OrderDesc = Order("desc")
    31  )
    32  
    33  var (
    34  	// DefaultStore implementation
    35  	DefaultStore Store
    36  	// DefaultBlobStore implementation
    37  	DefaultBlobStore BlobStore
    38  	// ErrNotFound is returned when a key doesn't exist
    39  	ErrNotFound = errors.New("not found")
    40  )
    41  
    42  // Store is a data storage interface
    43  type Store interface {
    44  	// 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.
    45  	Init(...Option) error
    46  	// Options allows you to view the current options.
    47  	Options() Options
    48  	// Read takes a single key name and optional ReadOptions. It returns matching []*Record or an error.
    49  	Read(key string, opts ...ReadOption) ([]*Record, error)
    50  	// Write writes a record to the store, and returns an error if the record was not written.
    51  	Write(r *Record, opts ...WriteOption) error
    52  	// Delete removes the record with the corresponding key from the store.
    53  	Delete(key string, opts ...DeleteOption) error
    54  	// List returns any keys that match, or an empty list with no error if none matched.
    55  	List(opts ...ListOption) ([]string, error)
    56  	// Close the store
    57  	Close() error
    58  	// String returns the name of the implementation.
    59  	String() string
    60  }
    61  
    62  // Record is an item stored or retrieved from a Store
    63  type Record struct {
    64  	// The key to store the record
    65  	Key string `json:"key"`
    66  	// The value within the record
    67  	Value []byte `json:"value"`
    68  	// Any associated metadata for indexing
    69  	Metadata map[string]interface{} `json:"metadata"`
    70  	// Time to expire a record: TODO: change to timestamp
    71  	Expiry time.Duration `json:"expiry,omitempty"`
    72  }
    73  
    74  // NewRecord returns a record from key, val
    75  func NewRecord(key string, val interface{}) *Record {
    76  	b, _ := json.Marshal(val)
    77  	return &Record{
    78  		Key:   key,
    79  		Value: b,
    80  	}
    81  }
    82  
    83  // Encode will marshal any type into the byte Value field
    84  func (r *Record) Encode(v interface{}) error {
    85  	b, err := json.Marshal(v)
    86  	if err != nil {
    87  		return err
    88  	}
    89  	r.Value = b
    90  	return nil
    91  }
    92  
    93  // Decode is a convenience helper for decoding records
    94  func (r *Record) Decode(v interface{}) error {
    95  	return json.Unmarshal(r.Value, v)
    96  }
    97  
    98  // Read records
    99  func Read(key string, opts ...ReadOption) ([]*Record, error) {
   100  	// execute the query
   101  	return DefaultStore.Read(key, opts...)
   102  }
   103  
   104  // Write a record to the store
   105  func Write(r *Record) error {
   106  	return DefaultStore.Write(r)
   107  }
   108  
   109  // Delete removes the record with the corresponding key from the store.
   110  func Delete(key string) error {
   111  	return DefaultStore.Delete(key)
   112  }
   113  
   114  // List returns any keys that match, or an empty list with no error if none matched.
   115  func List(opts ...ListOption) ([]string, error) {
   116  	return DefaultStore.List(opts...)
   117  }