summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--docs/attachments.rst104
1 files changed, 82 insertions, 22 deletions
diff --git a/docs/attachments.rst b/docs/attachments.rst
index 098f634f..31b47a70 100644
--- a/docs/attachments.rst
+++ b/docs/attachments.rst
@@ -1,25 +1,37 @@
-Document Attachments
+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:
+Reasoning
+---------
+
+The type of a Soledad document's content is `JSON <http://www.json.org/>`_,
+which is good for efficient lookup and indexing. On the other hand, 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.
+ space than what is actually needed for binary data storage.
+
+* upon synchronization, the content of a Soledad document needs to be
+ completelly transferred and decrypted for the document to be available for
+ use.
+
+Document attachments were introduced as a means to efficiently store large
+payloads of binary data while avoiding the need to wait for their transfer to
+have access to the documents' contents.
-* 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.
+Client-side
+-----------
-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.
+In the client, attachments are stored as (SQLite) BLOBs in a separate SQLCipher
+database. Encryption of data before it's sent to the server is the same used
+for Soledad documents' content during usual synchronization process (AES-256
+GCM mode).
-Example
--------
+Usage 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
@@ -57,16 +69,8 @@ the store that created it, and can put/get/delete an attachment:
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
------------------------
+API
+^^^
.. autoclass:: leap.soledad.client._document.AttachmentStates
:members:
@@ -75,3 +79,59 @@ Document attachment API
.. autointerface:: leap.soledad.client._document.IDocumentWithAttachment
:members:
:undoc-members:
+
+Server-side
+-----------
+
+In the server, a simple REST API is served by a `Twisted Resource
+<https://twistedmatrix.com/documents/current/api/twisted.web.resource.Resource.html>`_
+and attachments are stored in the filesystem as they come in without
+modification.
+
+A token is used to allow listing, getting, putting and deleting attachments. It
+has to be added as an HTTP auth header, as in::
+
+ Authorization: Token <base64-encoded uuid:token>
+
+The :ref:`IBlobsBackend <i-blobs-backend>` interface is provided, so in the
+future there can be different ways to store attachments in the server side
+(think of a third-party storage, for example). Currently, the
+:ref:`FilesystemBlobsBackend <filesystem-blobs-backend>` is the only backend
+that implements that interface.
+
+Some characteristics of the :ref:`FilesystemBlobsBackend
+<filesystem-blobs-backend>` are:
+
+* Configurable storage path.
+* Quota support.
+* Username, blob_id and user storage directory sanitization.
+
+Usage example
+^^^^^^^^^^^^^
+
+These are the possible ways to interact with the attachments REST API on the
+server side:
+
+=========== ================ ======== ==================
+HTTP Method URL Content Possible responses
+=========== ================ ======== ==================
+GET /user_id - 200
+GET /user_id/blob_id - 200, 404
+PUT /user_id/blob_id The BLOB 200, 409, 507
+DELETE /user_id/blob_id - 200
+=========== ================ ======== ==================
+
+API
+^^^
+
+.. _i-blobs-backend:
+
+.. autoclass:: leap.soledad.server.interfaces.IBlobsBackend
+ :members:
+ :undoc-members:
+
+.. _filesystem-blobs-backend:
+
+.. autoclass:: leap.soledad.server._blobs.FilesystemBlobsBackend
+ :members:
+ :undoc-members: