Label actions as safe and/or idempotent

Author: Joel Collins

examples/builder.py

@@ -44,7 +44,11 @@ def cleanup():
 )
 labthing.add_view(
     action_from(
-        my_component.average_data, description="Take an averaged measurement", task=True
+        my_component.average_data,
+        description="Take an averaged measurement",
+        task=True,  # Is the action a long-running task?
+        safe=True,  # Is the state of the Thing changed by calling the action?
+        idempotent=True,  # Can the action be called repeatedly with the same result?
     ),
     "/average",
 )

labthings/server/decorators.py

@@ -96,7 +96,7 @@ def wrapper(*args, **kwargs):
 
         if not isinstance(data, TaskThread):
             raise TypeError(
-                f"Function {f.__name__} expected to return a TaskThread object, but instead returned a {type(data).__name__}. If it does not return a task, remove the @marshall_task decorator from {f.__name__}.",
+                f"Function {f.__name__} expected to return a TaskThread object, but instead returned a {type(data).__name__}. If it does not return a task, remove the @marshall_task decorator from {f.__name__}."
             )
         return make_response(TaskSchema().jsonify(data), code, headers)
 
@@ -121,6 +121,40 @@ def ThingAction(viewcls: View):
 thing_action = ThingAction
 
 
+def Safe(viewcls: View):
+    """Decorator to tag a view or function as being safe
+
+    Args:
+        viewcls (View): View class to tag as Safe
+
+    Returns:
+        View: View class with Safe spec tags
+    """
+    # Update Views API spec
+    update_spec(viewcls, {"_safe": True})
+    return viewcls
+
+
+safe = Safe
+
+
+def Idempotent(viewcls: View):
+    """Decorator to tag a view or function as being idempotent
+
+    Args:
+        viewcls (View): View class to tag as idempotent
+
+    Returns:
+        View: View class with idempotent spec tags
+    """
+    # Update Views API spec
+    update_spec(viewcls, {"_idempotent": True})
+    return viewcls
+
+
+idempotent = Idempotent
+
+
 def ThingProperty(viewcls):
     """Decorator to tag a view as a Thing Property
 

labthings/server/spec/td.py

@@ -157,6 +157,15 @@ def view_to_thing_property_forms(self, rules: list, view: View):
     def view_to_thing_action(self, rules: list, view: View):
         action_urls = [rule_to_path(rule) for rule in rules]
 
+        # Check if action is safe
+        is_safe = get_spec(view.post).get("_safe", False) or get_spec(view).get(
+            "_safe", False
+        )
+
+        is_idempotent = get_spec(view.post).get("_idempotent", False) or get_spec(
+            view
+        ).get("_idempotent", False)
+
         # Basic description
         action_description = {
             "title": view.__name__,
@@ -166,6 +175,8 @@ def view_to_thing_action(self, rules: list, view: View):
             # TODO: Make URLs absolute
             "links": [{"href": f"{url}"} for url in action_urls],
             "forms": self.view_to_thing_action_forms(rules, view),
+            "safe": is_safe,
+            "idempotent": is_idempotent,
         }
 
         # Look for a _propertySchema in the Property classes API SPec

labthings/server/view/builder.py

@@ -11,6 +11,8 @@
     marshal_task,
     use_args,
     Doc,
+    Safe,
+    Idempotent,
 )
 from . import View
 
@@ -74,7 +76,14 @@ def _put(self, args):
     return generated_class
 
 
-def action_from(function, name: str = None, description=None, task=False):
+def action_from(
+    function,
+    name: str = None,
+    description=None,
+    task=False,
+    safe=False,
+    idempotent=False,
+):
 
     # Create a class name
     if not name:
@@ -108,6 +117,12 @@ def _post(self, args):
             generated_class
         )
 
+    if safe:
+        generated_class = Safe(generated_class)
+
+    if idempotent:
+        generated_class = Idempotent(generated_class)
+
     return generated_class