natsjskv

README

NATS JetStream Key Value Store Plugin

This plugin uses the NATS JetStream KeyValue Store to implement the Go-Micro store interface.

You can use this plugin like any other store plugin. To start a local NATS JetStream server run nats-server -js.

To manually create a new storage object call:

natsjskv.NewStore(opts ...store.Option)

The Go-Micro store interface uses databases and tables to store keys. These translate to buckets (key value stores) and key prefixes. If no database (bucket name) is provided, "default" will be used.

You can call Write with any arbitrary database name, and if a bucket with that name does not exist yet, it will be automatically created.

If a table name is provided, it will use it to prefix the key as <table>_<key>.

To delete a bucket, and all the key/value pairs in it, pass the DeleteBucket option to the Delete method, then they key name will be interpreted as a bucket name, and the bucket will be deleted.

Next to the default store options, a few NATS specific options are available:

// NatsOptions accepts nats.Options
NatsOptions(opts nats.Options)

// JetStreamOptions accepts multiple nats.JSOpt
JetStreamOptions(opts ...nats.JSOpt)

// KeyValueOptions accepts multiple nats.KeyValueConfig
// This will create buckets with the provided configs at initialization.
//
// type KeyValueConfig struct {
//    Bucket       string
//   Description  string
//   MaxValueSize int32
//   History      uint8
//   TTL          time.Duration
//   MaxBytes     int64
//   Storage      StorageType
//   Replicas     int
//   Placement    *Placement
//   RePublish    *RePublish
//   Mirror       *StreamSource
//   Sources      []*StreamSource
}
KeyValueOptions(cfg ...*nats.KeyValueConfig)

// DefaultTTL sets the default TTL to use for new buckets
//  By default no TTL is set.
//
// TTL ON INDIVIDUAL WRITE CALLS IS NOT SUPPORTED, only bucket wide TTL.
// Either set a default TTL with this option or provide bucket specific options
//  with ObjectStoreOptions
DefaultTTL(ttl time.Duration)

// DefaultMemory sets the default storage type to memory only.
//
//  The default is file storage, persisting storage between service restarts.
// Be aware that the default storage location of NATS the /tmp dir is, and thus
//  won't persist reboots.
DefaultMemory()

// DefaultDescription sets the default description to use when creating new
//  buckets. The default is "Store managed by go-micro"
DefaultDescription(text string)

// DeleteBucket will use the key passed to Delete as a bucket (database) name,
//  and delete the bucket.
// This option should not be combined with the store.DeleteFrom option, as
//  that will overwrite the delete action.
DeleteBucket()

Documentation

Overview

Package natsjskv is a go-micro store plugin for NATS JetStream Key-Value store.

Index

• Variables
• func DefaultDescription(text string) store.Option
• func DefaultMemory() store.Option
• func DefaultTTL(ttl time.Duration) store.Option
• func DeleteBucket() store.DeleteOption
• func EncodeKeys() store.Option
• func JetStreamOptions(opts ...nats.JSOpt) store.Option
• func KeyValueOptions(cfg ...*nats.KeyValueConfig) store.Option
• func NatsOptions(opts nats.Options) store.Option
• func NewStore(opts ...store.Option) store.Store
• type Key
  • func (k *Key) Check(table, prefix, suffix string) bool
  • func (k *Key) MicroKey() string
  • func (k *Key) NatsKey() string
• type KeyValueEnvelope

Variables

var (
	// ErrBucketNotFound is returned when the requested bucket does not exist.
	ErrBucketNotFound = errors.New("Bucket (database) not found")
)

Functions

func DefaultDescription

func DefaultDescription(text string) store.Option

DefaultDescription sets the default description to use when creating new

buckets. The default is "Store managed by go-micro"

func DefaultMemory

func DefaultMemory() store.Option

DefaultMemory sets the default storage type to memory only.

The default is file storage, persisting storage between service restarts.

Be aware that the default storage location of NATS the /tmp dir is, and thus

won't persist reboots.

func DefaultTTL

func DefaultTTL(ttl time.Duration) store.Option

DefaultTTL sets the default TTL to use for new buckets

By default no TTL is set.

TTL ON INDIVIDUAL WRITE CALLS IS NOT SUPPORTED, only bucket wide TTL. Either set a default TTL with this option or provide bucket specific options

with ObjectStoreOptions

func DeleteBucket

func DeleteBucket() store.DeleteOption

DeleteBucket will use the key passed to Delete as a bucket (database) name,

and delete the bucket.

This option should not be combined with the store.DeleteFrom option, as

that will overwrite the delete action.

func EncodeKeys

func EncodeKeys() store.Option

EncodeKeys will "base32" encode the keys. This is to work around limited characters usable as keys for the natsjs kv store. See details here: https://docs.nats.io/nats-concepts/subjects#characters-allowed-for-subject-names

func JetStreamOptions

func JetStreamOptions(opts ...nats.JSOpt) store.Option

JetStreamOptions accepts multiple nats.JSOpt.

func KeyValueOptions

func KeyValueOptions(cfg ...*nats.KeyValueConfig) store.Option

KeyValueOptions accepts multiple nats.KeyValueConfig This will create buckets with the provided configs at initialization.

func NatsOptions

func NatsOptions(opts nats.Options) store.Option

NatsOptions accepts nats.Options.

func NewStore

func NewStore(opts ...store.Option) store.Store

NewStore will create a new NATS JetStream Object Store.

Types

type Key

type Key struct {
	// Plain is the plain key as requested by the go-micro interface.
	Plain string
	// Full is the full key including the table prefix.
	Full string
	// Encoded is the base64 encoded key as used by the nats kv store.
	Encoded string
}

Key represents a key in the store. They are used to convert nats keys (base32 encoded) to micro keys (plain text - no table prefix) and vice versa.

func (*Key) Check

func (k *Key) Check(table, prefix, suffix string) bool

Check returns false if the key does not match the table, prefix or suffix.

func (*Key) MicroKey

func (k *Key) MicroKey() string

MicroKey returns a key the micro interface can work with.

func (*Key) NatsKey

func (k *Key) NatsKey() string

NatsKey returns a key the nats kv store can work with.

type KeyValueEnvelope

type KeyValueEnvelope struct {
	Key      string                 `json:"key"`
	Data     []byte                 `json:"data"`
	Metadata map[string]interface{} `json:"metadata"`
}

KeyValueEnvelope is the data structure stored in the key value store.