From 97fbe66401d1de0f667df6bf3c09506bdce8c7c5 Mon Sep 17 00:00:00 2001 From: Victor Shyba Date: Fri, 21 Jul 2017 05:01:43 -0300 Subject: [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 --- src/leap/soledad/client/interfaces.py | 47 +++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) 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 + """ -- cgit v1.2.3