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()