diff options
Diffstat (limited to 'docs/sphinx')
| -rw-r--r-- | docs/sphinx/.gitignore | 1 | ||||
| -rw-r--r-- | docs/sphinx/Makefile | 20 | ||||
| -rw-r--r-- | docs/sphinx/attachments.rst | 77 | ||||
| -rw-r--r-- | docs/sphinx/conf.py | 1 | ||||
| -rw-r--r-- | docs/sphinx/index.rst | 1 | ||||
| -rw-r--r-- | docs/sphinx/requirements.pip | 2 |
6 files changed, 102 insertions, 0 deletions
diff --git a/docs/sphinx/.gitignore b/docs/sphinx/.gitignore new file mode 100644 index 00000000..e35d8850 --- /dev/null +++ b/docs/sphinx/.gitignore @@ -0,0 +1 @@ +_build diff --git a/docs/sphinx/Makefile b/docs/sphinx/Makefile new file mode 100644 index 00000000..dcc387ce --- /dev/null +++ b/docs/sphinx/Makefile @@ -0,0 +1,20 @@ +# 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) diff --git a/docs/sphinx/attachments.rst b/docs/sphinx/attachments.rst new file mode 100644 index 00000000..098f634f --- /dev/null +++ b/docs/sphinx/attachments.rst @@ -0,0 +1,77 @@ +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: diff --git a/docs/sphinx/conf.py b/docs/sphinx/conf.py index bad9da6e..38ff330f 100644 --- a/docs/sphinx/conf.py +++ b/docs/sphinx/conf.py @@ -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. diff --git a/docs/sphinx/index.rst b/docs/sphinx/index.rst index c4ccffc9..6800ee42 100644 --- a/docs/sphinx/index.rst +++ b/docs/sphinx/index.rst @@ -14,6 +14,7 @@ all user's devices that access a LEAP provider. :maxdepth: 2 client + attachments server Indices and tables diff --git a/docs/sphinx/requirements.pip b/docs/sphinx/requirements.pip new file mode 100644 index 00000000..39055139 --- /dev/null +++ b/docs/sphinx/requirements.pip @@ -0,0 +1,2 @@ +sphinx +sphinxcontrib-zopeext |