summaryrefslogtreecommitdiff
path: root/docs/attachments.rst
diff options
context:
space:
mode:
authordrebs <drebs@leap.se>2017-06-06 15:12:56 -0300
committerKali Kaneko <kali@leap.se>2017-06-06 20:35:46 +0200
commit9dd3ebe6bad0bfe05840782c805e961cf4a96c6a (patch)
tree0f8d4b3e907cbdb88a5fcdf0d954cdc600a1fd17 /docs/attachments.rst
parentddef89b093929387614c52896ae4e10b3714be65 (diff)
[doc] move sphinx up to root of docs dir
Diffstat (limited to 'docs/attachments.rst')
-rw-r--r--docs/attachments.rst77
1 files changed, 77 insertions, 0 deletions
diff --git a/docs/attachments.rst b/docs/attachments.rst
new file mode 100644
index 00000000..098f634f
--- /dev/null
+++ b/docs/attachments.rst
@@ -0,0 +1,77 @@
+Document Attachments
+====================
+
+.. contents:: Contents:
+ :local:
+
+The content of a Soledad document is assumed to be JSON. This is particularly
+bad for storing larger amounts of binary data, because:
+
+* the only way to store data in JSON is as unicode string, and this uses more
+ space than needed for binary data storage.
+
+* the process of synchronization of Soledad documents depends on completing the
+ transfer and decryption of the content of all new/updated documents before
+ synchronized documents are available for use.
+
+Document attachments were introduced as a means to store large payloads of
+binary data and have them be synchronized separate from the usual Soledad
+document synchronization process.
+
+Example
+-------
+
+The attachments API is currently available in the `Document` class, and the
+document needs to know about the store to be able to manage attachments. When
+you create a new document with soledad, that document will already know about
+the store that created it, and can put/get/delete an attachment:
+
+.. code-block:: python
+
+ from twisted.internet.defer import inlineCallbacks
+
+ @inlineCallbacks
+ def attachment_example(soledad):
+ doc = yield soledad.create_doc({})
+
+ state = yield doc.get_attachment_state()
+ dirty = yield doc.is_dirty()
+ assert state == AttachmentStates.NONE
+ assert dirty == False
+
+ yield doc.put_attachment(open('hackers.txt'))
+ state = yield doc.get_attachment_state()
+ dirty = yield doc.is_dirty()
+ assert state | AttachmentState.LOCAL
+ assert dirty == True
+
+ yield soledad.put_doc(doc)
+ dirty = yield doc.is_dirty()
+ assert dirty == False
+
+ yield doc.upload_attachment()
+ state = yield doc.get_attachment_state()
+ assert state | AttachmentState.REMOTE
+ assert state == AttachmentState.SYNCED
+
+ fd = yield doc.get_attachment()
+ assert fd.read() == open('hackers.txt').read()
+
+Implementation
+--------------
+
+The current implementation of document attachments store data in a separate
+SQLCipher database in the client (using SQLite's BLOB type) and in the
+filesystem in the server. Encryption of data before it's sent to the server is
+the same used by normal Soledad synchronization process (AES-256 GCM mode).
+
+Document attachment API
+-----------------------
+
+.. autoclass:: leap.soledad.client._document.AttachmentStates
+ :members:
+ :undoc-members:
+
+.. autointerface:: leap.soledad.client._document.IDocumentWithAttachment
+ :members:
+ :undoc-members: