summaryrefslogtreecommitdiff
path: root/docs/incoming_box.rst
diff options
context:
space:
mode:
authorVictor Shyba <victor1984@riseup.net>2017-08-16 03:22:45 -0300
committerVictor Shyba <victor1984@riseup.net>2017-08-16 03:22:45 -0300
commit94a3d0371adea1222f969b4812cf47b13e5ea262 (patch)
treeec28acda503b8d07fb9b272ac4f57f3bf5f131a9 /docs/incoming_box.rst
parent7a89cdf056497ed3addc402618683373732cac85 (diff)
[docs] improve incoming spec from review
Fixed some typos and added a example for Trusted App Client Consumer. -- Resolves: #8928
Diffstat (limited to 'docs/incoming_box.rst')
-rw-r--r--docs/incoming_box.rst32
1 files changed, 25 insertions, 7 deletions
diff --git a/docs/incoming_box.rst b/docs/incoming_box.rst
index 36b6d75f..cbea6d32 100644
--- a/docs/incoming_box.rst
+++ b/docs/incoming_box.rst
@@ -175,12 +175,12 @@ same process space than the rest of the Soledad Server.
Preffix Namespaces
~~~~~~~~~~~~~~~~~~
-The Trusted Application code responsible for writing messages through Soledad
-Server ``Incoming Box`` endpoint MUST specify a dedicated "namespace" that it
-desires to use and be authorized to write into it. This is done so Soledad can
-list, filter, flag, fetch and reserve only messages known to the Trusted
-Application, avoiding to mix operations with blobs from the global namespace or
-messages from another Trusted Application.
+The Trusted Application code responsible for delivering messages into Soledad
+Server ``Incoming Box`` endpoint MUST specify as a request parameter the
+dedicated namespace that it desires to use and be authorized to write into it.
+This is done so Soledad can list, filter, flag, fetch and reserve only messages
+known to the Trusted Application, avoiding to mix operations with blobs from
+the global namespace or messages from another Trusted Application.
LIST commands
~~~~~~~~~~~~~
@@ -205,7 +205,7 @@ implementation shares the process memory space with the soledad client, but
this doesn't have to hold true in the future.
The class responsible for client side processing on Soledad Client is named
-``IncomingBoxProcessingLoop``. It's role is to orchestrate processing with the
+``IncomingBoxProcessingLoop``. Its role is to orchestrate processing with the
Incoming Box features on server side, so it can deliver messages to it's
registered Trusted Application Consumers.
@@ -228,6 +228,24 @@ registered Trusted Application Consumers.
process, attention SHOULD be payed to the callbacks not blocking the main
event loop.
+Example of a Trusted Application Client Consumer:
+
+```python
+@implementer(interfaces.IIncomingBoxConsumer)
+class MyConsumer(object):
+ def __init__(self):
+ self.name = 'My Consumer'
+
+ def process(self, item, item_id, encrypted=True):
+ cleartext = my_custom_decrypt(item) if encrypted else item
+ processed_parts = my_custom_processing(item)
+ return defer.succeed(processed_parts)
+
+ def save(self, parts, item_id):
+ return defer.gatherResults([db.save(part) for part in parts])
+```
+
+
Future Features
---------------