Add kv "entry" actions

An "entry" is a JSON object with properties. Multiple entries are stored
under a JSON serialized object (as created by st2.kv.set_object) in the
datastore.

You can upsert or delete properties within an entry. And, you can define a
fallback entry (which is named "default" by default) to allow getting
properties from an entry, and using the fallback entry to provide defaults for
any properties that are undfined in the entry.

One use-case for objects like this is to store environment-specific (eg dev,
stage, prod, etc) variables with global defaults. Each environment would be
an entry and "global" could be the fallback entry. The variables would be
properties inside the entries.

Signed-off-by: Jacob Floyd <cognifloyd@gmail.com>

Author: cognifloyd

README.md

@@ -42,6 +42,17 @@ You can also use dynamic values from the datastore. See the
   is serialized as JSON.
 * ``kv.grep_object`` - Find datastore items which name matches the provided query
   amd deserialize their values from JSON serialized objects.
+  
+* ``kv.get_entry`` - Retrieve entry object in a JSON serialized object from the
+  datastore. An entry is a standard JSON object with properties.
+  Fails if the datastore key does not exist.
+* ``kv.upsert_entry_property`` - Update or insert a property in the named entry
+  of a JSON serialized object. Then, serialize and store the updated object.
+  The property's value may be any json-serializable type.
+  Fails if the datastore key does not exist.
+* ``kv.delete_entry_property`` - Delete a property from a named entry of a JSON
+  serialized object in the datastore. If the entry is empty, delete it as well.
+  Fails if the datastore key does not exist.
 
 Note: ``kv.set`` and ``kv.get`` actions support compressing value before
 storing it in a datastore and decompressing it when retrieving it from

actions/kv_delete_entry_property.py

@@ -0,0 +1,47 @@
+import json
+
+from lib.action import St2BaseAction
+
+__all__ = [
+    'St2KVPDeleteEntryPropertyAction'
+]
+
+
+class St2KVPDeleteEntryPropertyAction(St2BaseAction):
+    # noinspection PyShadowingBuiltins
+    def run(self, key, entry, property):
+        # get and deserialize object or fail.
+        _key = self.client.keys.get_by_name(key, decrypt=False)
+
+        if not _key:
+            raise Exception("Key does not exist in datastore")
+
+        deserialized = json.loads(_key.value)
+
+        # delete object.entry.property
+        _entry = deserialized.get(entry, {})
+        try:
+            del _entry[property]
+        except KeyError:
+            pass
+
+        # delete object.entry if entry is empty
+        if not _entry:
+            try:
+                del deserialized[entry]
+            except KeyError:
+                pass
+
+        # re-serialize and save
+        serialized = json.dumps(deserialized)
+        kvp = self._kvp(name=key, value=serialized)
+        kvp.id = key
+
+        self.client.keys.update(kvp)
+        response = {
+            'key': key,
+            'entry_name': entry,
+            'entry': _entry,
+            'entry_deleted': not _entry,
+        }
+        return response

actions/kv_delete_entry_property.yaml

@@ -0,0 +1,26 @@
+---
+name: 'kv.delete_entry_property'
+enabled: true
+description: |
+  Delete a property (if it exists) under an named entry (sub-object) of a
+  serialized object in kv datastore. If the entry is empty after deleting
+  the property, this deletes the entry as well.
+  Fails if the key does not exist in the datastore.
+  The kv object uses this structure: { entry: { property: value, ... }, entry: {}, ...}
+  This action does not support encrypted datastore objects.
+
+runner_type: python-script
+entry_point: kv_delete_entry_property.py
+parameters:
+  key:
+    required: true
+    type: string
+  entry:
+    description: name of the key's entry
+    required: false
+    type: string
+    default: default
+  property:
+    description: name of the entry's property to upsert
+    required: true
+    type: string

actions/kv_get_entry.py

@@ -0,0 +1,25 @@
+import json
+
+from lib.action import St2BaseAction
+
+__all__ = [
+    'St2KVPGetEntryAction'
+]
+
+
+class St2KVPGetEntryAction(St2BaseAction):
+    # noinspection PyShadowingBuiltins
+    def run(self, key, fallback, entry):
+        # get and deserialize object or fail.
+        _key = self.client.keys.get_by_name(key, decrypt=False)
+
+        if not _key:
+            raise Exception("Key does not exist in datastore")
+
+        deserialized = json.loads(_key.value)
+
+        # try get object.entry.property
+        _entry = deserialized.get(fallback, {})
+        _entry.update(deserialized.get(entry, {}))
+
+        return _entry

actions/kv_get_entry.yaml

@@ -0,0 +1,26 @@
+---
+name: 'kv.get_entry'
+enabled: true
+description: |
+  Get a named entry (sub-object) of a serialized object in kv datastore
+  merged on top of the fallback entry (ie the fallback provides defaults).
+  Fails if the key does not exist in the datastore.
+  Does not fail if the entry or fallback is missing.
+  The kv object uses this structure: { fallback: { property: value, ... }, entry: {}, ...}
+  This action does not support encrypted datastore objects.
+
+runner_type: python-script
+entry_point: kv_get_entry.py
+parameters:
+  key:
+    required: true
+    type: string
+  fallback:
+    description: name of the key's fallback entry
+    required: false
+    type: string
+    default: default
+  entry:
+    description: name of the key's entry
+    required: true
+    type: string

actions/kv_upsert_entry_property.py

@@ -0,0 +1,46 @@
+import json
+
+from lib.action import St2BaseAction
+
+__all__ = [
+    'St2KVPUpsertEntryPropertyAction'
+]
+
+
+class St2KVPUpsertEntryPropertyAction(St2BaseAction):
+    # noinspection PyShadowingBuiltins
+    def run(self, key, entry, property, value):
+        # get and deserialize object or fail.
+        _key = self.client.keys.get_by_name(key, decrypt=False)
+
+        if not _key:
+            raise Exception("Key does not exist in datastore")
+
+        # optimistically try to decode a json value
+        try:
+            value = json.loads(value)
+        except (TypeError, ValueError):
+            # assume it is either already decoded (TypeError)
+            # or it is a plain string (ValueError)
+            # (malformed JSON objects/arrays will be strings)
+            pass
+
+        deserialized = json.loads(_key.value)
+
+        # update or insert object.entry.property
+        _entry = deserialized.get(entry, {})
+        _entry[property] = value
+        deserialized[entry] = _entry
+
+        # re-serialize and save
+        serialized = json.dumps(deserialized)
+        kvp = self._kvp(name=key, value=serialized)
+        kvp.id = key
+
+        self.client.keys.update(kvp)
+        response = {
+            'key': key,
+            'entry_name': entry,
+            'entry': _entry,
+        }
+        return response

actions/kv_upsert_entry_property.yaml

@@ -0,0 +1,28 @@
+---
+name: 'kv.upsert_entry_property'
+enabled: true
+description: |
+  Insert or update a property under an named entry (sub-object) of a serialized object in kv datastore.
+  Fails if the key does not exist in the datastore, as a property inside it can't be upserted yet.
+  The kv object uses this structure: { entry: { property: value, ... }, entry: {}, ...}
+  This action does not support encrypted datastore objects.
+
+runner_type: python-script
+entry_point: kv_upsert_entry_property.py
+parameters:
+  key:
+    required: true
+    type: string
+  entry:
+    description: name of the key's entry
+    required: false
+    type: string
+    default: default
+  property:
+    description: name of the entry's property to upsert
+    required: true
+    type: string
+  value:
+    description: the property value may be any json-serialible type (string, number, array, object)
+    required: true
+    # type: any

pack.yaml

@@ -2,7 +2,7 @@
 ref: st2
 name: st2
 description: StackStorm utility actions and aliases
-version: 1.3.1
+version: 1.4.0
 python_versions:
   - "2"
   - "3"