summaryrefslogtreecommitdiff
path: root/docs/reference/blobs.rst
diff options
context:
space:
mode:
Diffstat (limited to 'docs/reference/blobs.rst')
-rw-r--r--docs/reference/blobs.rst114
1 files changed, 4 insertions, 110 deletions
diff --git a/docs/reference/blobs.rst b/docs/reference/blobs.rst
index 17880802..dd76a2ce 100644
--- a/docs/reference/blobs.rst
+++ b/docs/reference/blobs.rst
@@ -12,114 +12,8 @@ Starting with version **0.10.0**, Soledad now has a proper blob infrastructure
that decouples payloads from metadata both in storage and in the
synchronization process.
+.. toctree::
+ :maxdepth: 2
-Server-side
------------
-
-Soledad Server provides two different REST APIs for interacting with blobs:
-
-* A public **HTTP Blobs API**, providing the *Blobs* service for Soledad Client
- (i.e. actual users of the infrastructure).
-
-* A local **HTTP Incoming Box API**, providing the delivery part of the
- :ref:`incoming-box` service, currently used for the MX mail delivery.
-
-Authentication is handled differently for each of the endpoints, see
-:ref:`authentication` for more details.
-
-
-.. _http-blobs-api:
-
-HTTP Blobs API
-~~~~~~~~~~~~~~
-
-The public endpoint provides the following REST API for interacting with the
-*Blobs* service:
-
-=========================== ========== ================================= ============================================
-path method action accepted query string fields
-=========================== ========== ================================= ============================================
-``/blobs/{uuid}`` ``GET`` Get a list of blobs. filtered by ``namespace``, ``filter_flag``, ``order_by``
- a flag.
-``/blobs/{uuid}/{blob_id}`` ``GET`` Get the contents of a blob. ``namespace``
-``/blobs/{uuid}/{blob_id}`` ``PUT`` Create a blob. The content of the ``namespace``
- blob should be sent in the body
- of the request.
-``/blobs/{uuid}/{blob_id}`` ``POST`` Set the flags for a blob. A list ``namespace``
- of flags should be sent in the
- body of the request.
-``/blobs/{uuid}/{blob_id}`` ``DELETE`` Delete a blob. ``namespace``
-=========================== ========== ================================= ============================================
-
-The Blobs service supports *namespaces*. All requests can be modified by the
-``namespace`` query string parameter, and the results will be restricted to
-a certain namespace. When no namespace explicitelly given, the ``default``
-namespace is used.
-
-When listing blobs, the results can be filtered by flag and/or ordered by date
-using the ``filter_flag`` and ``order_by`` query string parameters. The
-possible values for ``order_by`` are ``date`` or ``+date`` for increasing
-order, or ``-date`` for decreasing order.
-
-
-HTTP Incoming Box API
-~~~~~~~~~~~~~~~~~~~~~
-
-The local endpoint provides the following REST API for interacting with the
-:ref:`incoming-box` service.
-
-============================== ========== =================================
-path method action
-============================== ========== =================================
-``/incoming/{uuid}/{blob_id}`` ``PUT`` Create an incoming blob. The content of the blob should be sent in the body of the request.
-============================== ========== =================================
-
-All blobs created using this API are inserted under the namespace ``MX`` and
-flagged as ``PENDING``.
-
-
-.. _filesystem-backend:
-
-Filesystem backend
-~~~~~~~~~~~~~~~~~~
-
-On the server side, all blobs are currently stored in the filesystem, under
-``/var/lib/soledad/blobs`` by default. Blobs are split in subdirectories
-according to the user's uuid, the namespace, and the 3-letter and 6-letter
-prefixes of the blobs uuid to prevent too many files in the same directory.
-A second file with the extension ``.flags`` stores the flags for a blob.
-
-As an example, a ``PUT`` request to
-``/incoming/68625dcb68dab741adf29c7159ccff96/c56da69b25a9a11ec2f408a559ccffc6``
-would result in the following::
-
- /var/lib/soledad/blobs
- └── 68625dcb68dab741adf29c7159ccff96
- └── MX
- └── c56
- └── c56da6
- ├── c56da69b25a9a11ec2f408a559ccffc6
- └── c56da69b25a9a11ec2f408a559ccffc6.flags
-
-
-Client-side
------------
-
-On the client-side, blobs can be managed using the BlobManager API. The
-BlobManager is responsible for managing storage of blobs both in local and
-remote storages
-
-All data is stored locally in the ``blobs`` table of a SQLCipher database
-called ``{uuid}_blobs.db`` that lies in the same directory as the Soledad
-Client's JSON documents database. Both databases are encrypted with the same
-symmetric secret. All actions performed locally are mirrored remotelly using
-the :ref:`http-blobs-api`.
-
-The BlobManager supports *namespaces* and *flags* and can list local and remote
-blobs, possibly filtering by flags and ordering by date (increasingly or
-decreasingly). It has helper methods to send or fetch all missing blobs, thus
-aiding in synchronization of local and remote data.
-
-When uploading, the content of the blob is encrypted with a symmetric secret
-prior to being sent to the server. When downloading, the content of the blob is
-decrypted accordingly.
+ blobs/server
+ blobs/client