Verified Commit ad065fc8 authored by drebs's avatar drebs
Browse files

[doc] add attachments documentation

parent 6008e999
......@@ -107,8 +107,9 @@ class IDocumentWithAttachment(Interface):
Return whether this document's content differs from the contents stored
in local database.
:return: Whether this document is dirty or not.
:rtype: bool
:return: A deferred which fires with True or False, depending on
whether this document is dirty or not.
:rtype: Deferred
"""
def upload_attachment(self):
......
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
SPHINXPROJ = Soledad
SOURCEDIR = .
BUILDDIR = _build
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: help Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
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:
* the only way to store data in JSON is as unicode string, and this uses more
space than needed for binary data storage.
* 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.
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.
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
you create a new document with soledad, that document will already know about
the store that created it, and can put/get/delete an attachment:
.. code-block:: python
from twisted.internet.defer import inlineCallbacks
@inlineCallbacks
def attachment_example(soledad):
doc = yield soledad.create_doc({})
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()
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
-----------------------
.. autoclass:: leap.soledad.client._document.AttachmentStates
:members:
:undoc-members:
.. autointerface:: leap.soledad.client._document.IDocumentWithAttachment
:members:
:undoc-members:
......@@ -36,6 +36,7 @@ extensions = [
'sphinx.ext.coverage',
'sphinx.ext.imgmath',
'sphinx.ext.viewcode',
'sphinxcontrib.zopeext.autointerface',
]
# Add any paths that contain templates here, relative to this directory.
......
......@@ -14,6 +14,7 @@ all user's devices that access a LEAP provider.
:maxdepth: 2
client
attachments
server
Indices and tables
......
sphinx
sphinxcontrib-zopeext
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment