MM-8602: KV Store Json helper tweaks (#11502)

* move kv helpers to helpers_kv*.go

* change KVGetJSON return signature

Return a boolean and an error, to clearly indicate if no value was found and thus no value unmarshalled into the target interface.

Also fix an issue with CompareAndSet to allow an oldValue of nil (i.e.
expected to be unset).

* add missing license

* tweak documentation

* document KVSetWithExpiryJSON minimum version

plugin/helpers.go

@@ -6,25 +6,28 @@ package plugin
 import "github.com/mattermost/mattermost-server/model"
 
 type Helpers interface {
-	// EnsureBot either returns an existing bot user or creates a bot user with
-	// the specifications of the passed bot.
-	// Returns the id of the bot created or existing.
+	// EnsureBot either returns an existing bot user matching the given bot, or creates a bot user from the given bot.
+	// Returns the id of the resulting bot.
 	EnsureBot(bot *model.Bot) (string, error)
 
-	// KVGetJSON retrievs a value based on the key.
-	KVGetJSON(key string, value interface{}) error
-
-	// KVSetJSON stores a key-value pair.
+	// KVSetJSON stores a key-value pair, unique per plugin, marshalling the given value as a JSON string.
 	KVSetJSON(key string, value interface{}) error
 
-	// KVCompareAndSetJSON updates a key-value pair if the current
-	// value is equal to oldValue.
-	// Returns (false, err) if DB/marshal/unmarshal error occurred
-	// Returns (false, nil) if current value != old value
-	// Returns (true, nil) if current value == old value or new key is inserted
+	// KVCompareAndSetJSON updates a key-value pair, unique per plugin, but only if the current value matches the given oldValue after marshalling as a JSON string.
+	// Inserts a new key if oldValue == nil.
+	// Returns (false, err) if DB error occurred
+	// Returns (false, nil) if current value != oldValue or key already exists when inserting
+	// Returns (true, nil) if current value == oldValue or new key is inserted
+	//
+	// Minimum server version: 5.12
 	KVCompareAndSetJSON(key string, oldValue interface{}, newValue interface{}) (bool, error)
 
-	// KVSetWithExpiryJSON stores a key-value pair with an expiry time.
+	// KVGetJSON retrieves a value based on the key, unique per plugin, unmarshalling the previously set JSON string into the given value. Returns true if the key exists.
+	KVGetJSON(key string, value interface{}) (bool, error)
+
+	// KVSetWithExpiryJSON stores a key-value pair with an expiry time, unique per plugin, marshalling the given value as a JSON string.
+	//
+	// Minimum server version: 5.6
 	KVSetWithExpiryJSON(key string, value interface{}, expireInSeconds int64) error
 }