[doc] add doc on server-side blobs

Closes #8850.

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: