[feature] Interface for incoming callbacks

This interface is intended to be used by Soledad users in order to
implement consumers for IncomingBox feature. This happens by declaring
how to process and save a incoming item, optionally decrypting if
Soledad isn't able to decrypt it (planned feature for asymmetric
encryption).

-- Resolves: #8875

1 files changed, 47 insertions, 0 deletions

diff --git a/src/leap/soledad/client/interfaces.py b/src/leap/soledad/client/interfaces.py
index 0600449f..25a7130f 100644
--- a/src/leap/soledad/client/interfaces.py
+++ b/src/leap/soledad/client/interfaces.py
@@ -366,3 +366,50 @@ class ISecretsStorage(Interface):
 
         :raise NoStorageSecret: Raised if there's no storage secret available.
         """
+
+
+class IIncomingBoxConsumer(Interface):
+    """
+    Interface that users can implement to provide a consumer for incoming box.
+
+    Note that processing and saving are separated from each other. That's
+    important for error handling on Soledad side as saving has side effects
+    while processing doesn't, so we can always retry processing while retrying
+    to save is risky.
+    Remember that on multiple devices scenario a replica that fails processing
+    of an item can give it to another replica retry, as long as there are no
+    side effects from processing.
+    """
+    name = Attribute("Consumer name, for readable error logging")
+
+    def process(self, item, item_id, encrypted=True):
+        """
+        This method process an incoming box item.
+        :param item: Incoming box item data
+        :type item: file-like object
+        :param item_id: Unique identifier of the item being processed.
+        :type item_id: str
+        :param encrypted: Should this function decrypt?
+            If Soledad knows how to decrypt the item, then `encrypted`
+            parameter will be `False` and item will be cleartext. Otherwise, it
+            will be `True` and item will be an encrypted blob.
+        :param encrypted: bool
+        :return:
+            A deferred that fires with a list of parts to be delivered to
+            `save` function. This list type should match `save` method `parts`
+            parameter. It is implementation dependant.
+        :rtype: Deferred
+        """
+
+    def save(self, parts, item_id):
+        """
+        This method persists resulting items from processing.
+        :param parts: resulting parts from processing
+        :type parts: Implementation dependant.
+        :param item_id: Unique identifier of the item being processed.
+        :type item_id: str
+        :return:
+            A deferred that fires when all parts are persisted, returning a
+            boolean telling if the operation succeeded or not.
+        :rtype: Deferred
+        """