diff options
Diffstat (limited to 'docs/reference/attachments.rst')
| -rw-r--r-- | docs/reference/attachments.rst | 52 |
1 files changed, 17 insertions, 35 deletions
diff --git a/docs/reference/attachments.rst b/docs/reference/attachments.rst index 9561edcf..29387b36 100644 --- a/docs/reference/attachments.rst +++ b/docs/reference/attachments.rst @@ -1,5 +1,3 @@ -.. _blobs-spec: - Document attachments ==================== @@ -24,13 +22,22 @@ 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. +Server-side +----------- + +In the server, attachments are stored as :ref:`blobs`. See +:ref:`http-blobs-api` for more information on how to interact with the server +using HTTP. + +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:`filesystem-backend` is the only one that implements that interface. + Client-side ----------- -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). +In the client, attachments are relations between JSON documents and blobs. See :ref:`client-side-attachment-api` for reference. @@ -52,52 +59,27 @@ the store that created it, and can put/get/delete an attachment: 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() - -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> - -Check out the :ref:`server-side-attachments-rest-api` for more information on -how to interact with the server using HTTP. - -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. |