natsjs

README

NATS JetStream Store Plugin

WARNING: NATS Object Storage is still marked as an experimental preview.

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

This enables a key/value store with unlimited message size, allowing you to store files or data of any size under a single key.

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:

natsjs.NewStore(opts ...store.Option)

The Go-Micro store interface uses databases and tables to store keys. These translate to buckets (object 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)

// ObjectStoreOptions accepts multiple nats.ObjectStoreConfigs
// This will create buckets with the provided configs at initialization.
//
// type ObjectStoreConfig struct {
// 	Bucket      string
// 	Description string
// 	TTL         time.Duration
// 	MaxBytes    int64
// 	Storage     StorageType (either memory or file storage)
// 	Replicas    int
// 	Placement   *Placement
// }
//
ObjectStoreOptions(cfg ...*nats.ObjectStoreConfig)

// 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

Index

• Variables
• func DefaultDescription(text string) store.Option
• func DefaultMemory() store.Option
• func DefaultTTL(ttl time.Duration) store.Option
• func DeleteBucket() store.DeleteOption
• func JetStreamOptions(opts ...nats.JSOpt) store.Option
• func NatsOptions(opts nats.Options) store.Option
• func NewStore(opts ...store.Option) store.Store
• func ObjectStoreOptions(cfg ...*nats.ObjectStoreConfig) store.Option

Variables

var (
	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 JetStreamOptions

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

JetStreamOptions accepts multiple nats.JSOpt.

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.

func ObjectStoreOptions

func ObjectStoreOptions(cfg ...*nats.ObjectStoreConfig) store.Option

ObjectStoreOptions accepts multiple nats.ObjectStoreConfigs This will create buckets with the provided configs at initialization.