Soledad Client API

class leap.soledad.client.Soledad(uuid, passphrase, secrets_path, local_db_path, server_url, cert_file, shared_db=None, auth_token=None, with_blobs=False)[source]

Bases: object

Soledad provides encrypted data storage and sync.

A Soledad instance is used to store and retrieve data in a local encrypted database and synchronize this database with Soledad server.

This class is also responsible for bootstrapping users’ account by creating cryptographic secrets and/or storing/fetching them on Soledad server.

__init__(uuid, passphrase, secrets_path, local_db_path, server_url, cert_file, shared_db=None, auth_token=None, with_blobs=False)[source]

Initialize configuration, cryptographic keys and dbs.

Parameters:
  • uuid (str) – User’s uuid.
  • passphrase (unicode) – The passphrase for locking and unlocking encryption secrets for local and remote storage.
  • secrets_path (str) – Path for storing encrypted key used for symmetric encryption.
  • local_db_path (str) – Path for local encrypted storage db.
  • server_url (str) –

    URL for Soledad server. This is used to fetch and store user’s secrets and to sync with the user’s remote db.

    For the LEAP Platform/Bitmask use case, it is mandatory to check for user secrets previously stored in remote storage during the first initialization, because Soledad needs to encrypt/decrypt to using the same secret as before.

    For testing purposes, a value of None can be passed. If None is passed, verification for a remote secret on first initialization is bypassed and that might lead to unintented consequences.

  • cert_file (str) – Path to the certificate of the ca used to validate the SSL certificate used by the remote soledad server.
  • shared_db (HTTPDatabase) – The shared database.
  • auth_token (str) – Authorization token for accessing remote databases.
  • with_blobs – A boolean that specifies if this soledad instance should enable blobs storage when initialized. This will raise if it’s not the first initialization and the passed value is different from when the database was first initialized.
Raises:

BootstrapSequenceError – Raised when the secret initialization sequence (i.e. retrieval from server or generation and storage on server) has failed for some reason.

change_passphrase(new_passphrase)[source]

Change the passphrase that encrypts the storage secret.

Parameters:new_passphrase (unicode) – The new passphrase.
Raises:NoStorageSecret – Raised if there’s no storage secret available.
close()[source]

Close underlying U1DB database.

create_doc(**kwargs)[source]

Create a new document.

You can optionally specify the document identifier, but the document must not already exist. See ‘put_doc’ if you want to override an existing document. If the database specifies a maximum document size and the document exceeds it, create will fail and raise a DocumentTooBig exception.

Parameters:
  • content (dict) – A Python dictionary.
  • doc_id (str) – An optional identifier specifying the document id.
Returns:

A deferred whose callback will be invoked with a document.

Return type:

twisted.internet.defer.Deferred

create_doc_from_json(json, doc_id=None)[source]

Create a new document.

You can optionally specify the document identifier, but the document must not already exist. See ‘put_doc’ if you want to override an existing document. If the database specifies a maximum document size and the document exceeds it, create will fail and raise a DocumentTooBig exception.

Parameters:
  • json (dict) – The JSON document string
  • doc_id (str) – An optional identifier specifying the document id.
Returns:

A deferred whose callback will be invoked with a document.

Return type:

twisted.internet.defer.Deferred

create_index(index_name, *index_expressions)[source]

Create a named index, which can then be queried for future lookups.

Creating an index which already exists is not an error, and is cheap. Creating an index which does not match the index_expressions of the existing index is an error. Creating an index will block until the expressions have been evaluated and the index generated.

Parameters:
  • index_name (str) – A unique name which can be used as a key prefix
  • index_expressions

    index expressions defining the index information.

    Examples:

    ”fieldname”, or “fieldname.subfieldname” to index alphabetically sorted on the contents of a field.

    ”number(fieldname, width)”, “lower(fieldname)”

Returns:

A deferred.

Return type:

twisted.internet.defer.Deferred

create_recovery_code()[source]
default_prefix = '/home/docs/.config/leap/soledad'

A dictionary that holds locks which avoid multiple sync attempts from the same database replica. The dictionary indexes are the paths to each local db, so we guarantee that only one sync happens for a local db at a time.

delete_doc(doc)[source]

Mark a document as deleted.

Will abort if the current revision doesn’t match doc.rev. This will also set doc.content to None.

Parameters:doc (leap.soledad.common.document.Document) – A document to be deleted.
Returns:A deferred.
Return type:twisted.internet.defer.Deferred
delete_index(index_name)[source]

Remove a named index.

Parameters:index_name (str) – The name of the index we are removing
Returns:A deferred.
Return type:twisted.internet.defer.Deferred
get_all_docs(include_deleted=False)[source]

Get the JSON content for all documents in the database.

Parameters:include_deleted (bool) – If set to True, deleted documents will be returned with empty content. Otherwise deleted documents will not be included in the results.
Returns:A deferred which, when fired, will pass the a tuple containing (generation, [Document]) to the callback, with the current generation of the database, followed by a list of all the documents in the database.
Return type:twisted.internet.defer.Deferred
get_count_from_index(index_name, *key_values)[source]

Return the count for a given combination of index_name and key values.

Extension method made from similar methods in u1db version 13.09

Parameters:
  • index_name (str) – The index to query
  • key_values (tuple) – values to match. eg, if you have an index with 3 fields then you would have: get_from_index(index_name, val1, val2, val3)
Returns:

A deferred whose callback will be invoked with the count.

Return type:

twisted.internet.defer.Deferred

get_doc(doc_id, include_deleted=False)[source]

Get the JSON string for the given document.

Parameters:
  • doc_id (str) – The unique document identifier
  • include_deleted (bool) – If set to True, deleted documents will be returned with empty content. Otherwise asking for a deleted document will return None.
Returns:

A deferred whose callback will be invoked with a document object.

Return type:

twisted.internet.defer.Deferred

get_doc_conflicts(doc_id)[source]

Get the list of conflicts for the given document.

The order of the conflicts is such that the first entry is the value that would be returned by “get_doc”.

Parameters:doc_id (str) – The unique document identifier
Returns:A deferred whose callback will be invoked with a list of the Document entries that are conflicted.
Return type:twisted.internet.defer.Deferred
get_docs(doc_ids, check_for_conflicts=True, include_deleted=False)[source]

Get the JSON content for many documents.

Parameters:
  • doc_ids (list) – A list of document identifiers.
  • check_for_conflicts (bool) – If set to False, then the conflict check will be skipped, and ‘None’ will be returned instead of True/False.
  • include_deleted (bool) – If set to True, deleted documents will be returned with empty content. Otherwise deleted documents will not be included in the results.
Returns:

A deferred whose callback will be invoked with an iterable giving the document object for each document id in matching doc_ids order.

Return type:

twisted.internet.defer.Deferred

get_from_index(index_name, *key_values)[source]

Return documents that match the keys supplied.

You must supply exactly the same number of values as have been defined in the index. It is possible to do a prefix match by using ‘*’ to indicate a wildcard match. You can only supply ‘*’ to trailing entries, (eg ‘val’, ‘*’, ‘*’ is allowed, but ‘*’, ‘val’, ‘val’ is not.) It is also possible to append a ‘*’ to the last supplied value (eg ‘val*’, ‘*’, ‘*’ or ‘val’, ‘val*’, ‘*’, but not ‘val*’, ‘val’, ‘*’)

Parameters:
  • index_name (str) – The index to query
  • key_values (list) – values to match. eg, if you have an index with 3 fields then you would have: get_from_index(index_name, val1, val2, val3)
Returns:

A deferred whose callback will be invoked with a list of [Document].

Return type:

twisted.internet.defer.Deferred

get_index_keys(index_name)[source]

Return all keys under which documents are indexed in this index.

Parameters:index_name (str) – The index to query
Returns:A deferred whose callback will be invoked with a list of tuples of indexed keys.
Return type:twisted.internet.defer.Deferred
get_or_create_service_token(**kwargs)[source]

Return the stored token for a given service, or generates and stores a random one if it does not exist.

These tokens can be used to authenticate services.

get_range_from_index(index_name, start_value, end_value)[source]

Return documents that fall within the specified range.

Both ends of the range are inclusive. For both start_value and end_value, one must supply exactly the same number of values as have been defined in the index, or pass None. In case of a single column index, a string is accepted as an alternative for a tuple with a single value. It is possible to do a prefix match by using ‘*’ to indicate a wildcard match. You can only supply ‘*’ to trailing entries, (eg ‘val’, ‘*’, ‘*’ is allowed, but ‘*’, ‘val’, ‘val’ is not.) It is also possible to append a ‘*’ to the last supplied value (eg ‘val*’, ‘*’, ‘*’ or ‘val’, ‘val*’, ‘*’, but not ‘val*’, ‘val’, ‘*’)

Parameters:
  • index_name (str) – The index to query
  • start_values (tuple) – tuples of values that define the lower bound of the range. eg, if you have an index with 3 fields then you would have: (val1, val2, val3)
  • end_values (tuple) – tuples of values that define the upper bound of the range. eg, if you have an index with 3 fields then you would have: (val1, val2, val3)
Returns:

A deferred whose callback will be invoked with a list of [Document].

Return type:

twisted.internet.defer.Deferred

list_indexes()[source]

List the definitions of all known indexes.

Returns:A deferred whose callback will be invoked with a list of [(‘index-name’, [‘field’, ‘field2’])] definitions.
Return type:twisted.internet.defer.Deferred
local_db_file_name = 'soledad.u1db'
local_db_path
put_doc(doc)[source]

Update a document.

If the document currently has conflicts, put will fail. If the database specifies a maximum document size and the document exceeds it, put will fail and raise a DocumentTooBig exception.

============================== WARNING ============================== This method converts the document’s contents to unicode in-place. This means that after calling put_doc(doc), the contents of the document, i.e. doc.content, might be different from before the call. ============================== WARNING ==============================

Parameters:doc (leap.soledad.common.document.Document) – A document with new content.
Returns:A deferred whose callback will be invoked with the new revision identifier for the document. The document object will also be updated.
Return type:twisted.internet.defer.Deferred
raw_sqlcipher_operation(*args, **kw)[source]

Run a raw sqlcipher operation in the local database, and return a deferred that will be fired with None.

raw_sqlcipher_query(*args, **kw)[source]

Run a raw sqlcipher query in the local database, and return a deferred that will be fired with the result.

resolve_doc(doc, conflicted_doc_revs)[source]

Mark a document as no longer conflicted.

We take the list of revisions that the client knows about that it is superseding. This may be a different list from the actual current conflicts, in which case only those are removed as conflicted. This may fail if the conflict list is significantly different from the supplied information. (sync could have happened in the background from the time you GET_DOC_CONFLICTS until the point where you RESOLVE)

Parameters:
  • doc (Document) – A Document with the new content to be inserted.
  • conflicted_doc_revs (list(str)) – A list of revisions that the new content supersedes.
Returns:

A deferred.

Return type:

twisted.internet.defer.Deferred

secrets

Return the secrets object.

Returns:The secrets object.
Return type:Secrets
secrets_file_name = 'soledad.json'
sync()[source]

Synchronize documents with the server replica.

This method uses a lock to prevent multiple concurrent sync processes over the same local db file.

Returns:A deferred lock that will run the actual sync process when the lock is acquired, and which will fire with with the local generation before the synchronization was performed.
Return type:twisted.internet.defer.Deferred
sync_lock

Class based lock to prevent concurrent syncs using the same local db file.

Returns:A shared lock based on this instance’s db file path.
Return type:DeferredLock
sync_stats()[source]
syncing

Return wether Soledad is currently synchronizing with the server.

Returns:Wether Soledad is currently synchronizing with the server.
Return type:bool
userid