diff options
Diffstat (limited to 'docs/reference/blobs.rst')
| -rw-r--r-- | docs/reference/blobs.rst | 114 |
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 |