Repository: canonical/operator

Issue:
save_shapshot validation failures unhelpful
The following validation code is in save_snapshot() in framework.py:

```python
# Use marshal as a validator, enforcing the use of simple types.
marshal.dumps(data)
```

Unfortunately, when validation fails the charm developer is left with nothing but the useless traceback:
```
Traceback (most recent call last):
  File "/var/lib/juju/agents/unit-plinth-4/charm/hooks/db-relation-changed", line 499, in <module>
    ops.main.main(PlinthCharm)
  File "lib/ops/main.py", line 197, in main
    framework.commit()
  File "lib/ops/framework.py", line 496, in commit
    self.on.commit.emit()
  File "lib/ops/framework.py", line 199, in emit
    framework._emit(event)
  File "lib/ops/framework.py", line 633, in _emit
    self._reemit(event_path)
  File "lib/ops/framework.py", line 668, in _reemit
    custom_handler(event)
  File "lib/ops/framework.py", line 717, in on_commit
    self.framework.save_snapshot(self)
  File "lib/ops/framework.py", line 526, in save_snapshot
    marshal.dumps(data)
ValueError: unmarshallable object
```

As you can see, there is no context about what was being snapshotted, nor information about what bad data the object contained.

The unmarshallable exception needs to be caught, and a new one raised with more context so the developer can continue without hacking framework.py.

Comments:

Patch:
diff --git a/ops/framework.py b/ops/framework.py
index c8df98b..edfe802 100755
--- a/ops/framework.py
+++ b/ops/framework.py
@@ -558,8 +558,18 @@ class Framework(Object):
             raise RuntimeError(
                 'cannot save {} values before registering that type'.format(type(value).__name__))
         data = value.snapshot()
-        # Use marshal as a validator, enforcing the use of simple types.
-        marshal.dumps(data)
+
+        # Use marshal as a validator, enforcing the use of simple types, as we later the
+        # information is really pickled, which is too error prone for future evolution of the
+        # stored data (e.g. if the developer stores a custom object and later changes its
+        # class name; when unpickling the original class will not be there and event
+        # data loading will fail).
+        try:
+            marshal.dumps(data)
+        except ValueError:
+            msg = "unable to save the data for {}, it must contain only simple types: {!r}"
+            raise ValueError(msg.format(value.__class__.__name__, data))
+
         # Use pickle for serialization, so the value remains portable.
         raw_data = pickle.dumps(data)
         self._storage.save_snapshot(value.handle.path, raw_data)


Test patch:
diff --git a/test/test_framework.py b/test/test_framework.py
index 1977c1e..fc64566 100644
--- a/test/test_framework.py
+++ b/test/test_framework.py
@@ -761,6 +761,26 @@ class TestFramework(unittest.TestCase):
         self.assertIn('database is locked', str(cm.exception))
         f.close()
 
+    def test_snapshot_saving_restricted_to_simple_types(self):
+        # this can not be saved, as it has not simple types!
+        to_be_saved = {"bar": TestFramework}
+
+        class FooEvent(EventSetBase):
+            def snapshot(self):
+                return to_be_saved
+
+        handle = Handle(None, "a_foo", "some_key")
+        event = FooEvent()
+
+        framework = self.create_framework()
+        framework.register_type(FooEvent, None, handle.kind)
+        with self.assertRaises(ValueError) as cm:
+            framework.save_snapshot(event)
+        expected = (
+            "unable to save the data for FooEvent, it must contain only simple types: "
+            "{'bar': <class 'test.test_framework.TestFramework'>}")
+        self.assertEqual(str(cm.exception), expected)
+
 
 class TestStoredState(unittest.TestCase):