Skip to content
GitLab
Menu
Projects
Groups
Snippets
/
Help
Help
Support
Community forum
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
Menu
Open sidebar
leap
soledad
Commits
ad065fc8
Verified
Commit
ad065fc8
authored
May 04, 2017
by
drebs
Browse files
[doc] add attachments documentation
parent
6008e999
Changes
7
Hide whitespace changes
Inline
Side-by-side
client/src/leap/soledad/client/_document.py
View file @
ad065fc8
...
...
@@ -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
):
...
...
docs/sphinx/.gitignore
0 → 100644
View file @
ad065fc8
_build
docs/sphinx/Makefile
0 → 100644
View file @
ad065fc8
# 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)
docs/sphinx/attachments.rst
0 → 100644
View file @
ad065fc8
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:
docs/sphinx/conf.py
View file @
ad065fc8
...
...
@@ -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.
...
...
docs/sphinx/index.rst
View file @
ad065fc8
...
...
@@ -14,6 +14,7 @@ all user's devices that access a LEAP provider.
:maxdepth: 2
client
attachments
server
Indices and tables
...
...
docs/sphinx/requirements.pip
0 → 100644
View file @
ad065fc8
sphinx
sphinxcontrib-zopeext
drebs
@drebs
mentioned in merge request
!88 (closed)
·
May 08, 2017
mentioned in merge request
!88 (closed)
mentioned in merge request !88
Toggle commit list
Write
Preview
Supports
Markdown
0%
Try again
or
attach a new file
.
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment