From 8a0daa4a9eddbf8fee0961eaf3ca1a502f55bb0c Mon Sep 17 00:00:00 2001
From: drebs <drebs@leap.se>
Date: Wed, 6 Dec 2017 17:48:32 -0200
Subject: [PATCH] [doc] add api doc for blobs backend
---
docs/api.rst | 1 +
docs/api/blobs-server-backend.rst | 21 ++++
src/leap/soledad/server/interfaces.py | 171 +++++++++++++++++++++-----
3 files changed, 163 insertions(+), 30 deletions(-)
create mode 100644 docs/api/blobs-server-backend.rst
diff --git a/docs/api.rst b/docs/api.rst
index a184c9f7..31d8b36a 100644
--- a/docs/api.rst
+++ b/docs/api.rst
@@ -8,3 +8,4 @@ API Reference
api/attachments
api/blobs-client
api/blobs-server
+ api/blobs-server-backend
diff --git a/docs/api/blobs-server-backend.rst b/docs/api/blobs-server-backend.rst
new file mode 100644
index 00000000..5a9e1033
--- /dev/null
+++ b/docs/api/blobs-server-backend.rst
@@ -0,0 +1,21 @@
+Blobs Server-side Data Backend API
+==================================
+
+Blobs Backend Interface
+-----------------------
+
+.. autoclass:: leap.soledad.server.interfaces.IBlobsBackend
+ :members:
+ :undoc-members:
+ :special-members: __init__
+ :show-inheritance:
+
+
+Incoming Box Backend Interface
+------------------------------
+
+.. autoclass:: leap.soledad.server.interfaces.IIncomingBoxBackend
+ :members:
+ :undoc-members:
+ :special-members: __init__
+ :show-inheritance:
diff --git a/src/leap/soledad/server/interfaces.py b/src/leap/soledad/server/interfaces.py
index 5e586ade..9a64ee76 100644
--- a/src/leap/soledad/server/interfaces.py
+++ b/src/leap/soledad/server/interfaces.py
@@ -22,86 +22,197 @@ from zope.interface import Interface
class IBlobsBackend(Interface):
"""
- An interface for a BlobsBackend.
+ An interface for a backend that can store blobs.
+
+ Classes that implement this interface are supposed to be used by
+ ``BlobsResource``, which is a ``twisted.web.resource.Resource`` that serves
+ the Blobs API. Because of that, their methods receive instances of
+ ``twisted.web.server.Request`` and should use them to serve the Blobs API.
"""
def read_blob(user, blob_id, request, namespace=''):
"""
- Read blob with a given blob_id, and write it to the passed request.
+ Read a blob from the backend storage and write it as a response to a
+ request.
+
+ :param user: The id of the user who owns the blob.
+ :type user: str
+ :param blob_id: The id of the blob.
+ :type blob_id: str
+ :param request: A representation of all of the information about the
+ request that is being made.
+ :type request: twisted.web.server.Request
+ :param namespace: An optional namespace for the blob.
+ :type namespace: str
- :returns: a deferred that fires upon finishing.
+ :return: Either ``server.NOT_DONE_YET`` to indicate an asynchronous
+ operation or a ``bytes`` instance to write as the response to the
+ request. If ``NOT_DONE_YET`` is returned, at some point later (for
+ example, in a Deferred callback) call ``request.write(b"data")`` to
+ write data to the request, and ``request.finish()`` to send the
+ data to the browser.
"""
def write_blob(user, blob_id, request, namespace=''):
"""
- Write blob to the storage, reading it from the passed request.
+ Write a blob to the backend storage after reading it from a request.
+
+ :param user: The id of the user who owns the blob.
+ :type user: str
+ :param blob_id: The id of the blob.
+ :type blob_id: str
+ :param request: A representation of all of the information about the
+ request that is being made.
+ :type request: twisted.web.server.Request
+ :param namespace: An optional namespace for the blob.
+ :type namespace: str
- :returns: a deferred that fires upon finishing.
+ :return: A deferred that fires when the blob has been written to the
+ backend storage.
"""
def delete_blob(user, blob_id, namespace=''):
"""
- Delete the given blob_id.
+ Delete a blob from the backend storage.
+
+ :param user: The id of the user who owns the blob.
+ :type user: str
+ :param blob_id: The id of the blob.
+ :type blob_id: str
+ :param namespace: An optional namespace for the blob.
+ :type namespace: str
"""
def get_blob_size(user, blob_id, namespace=''):
"""
- Get the size of the given blob id.
+ Get the size of a blob.
+
+ :param user: The id of the user who owns the blob.
+ :type user: str
+ :param blob_id: The id of the blob.
+ :type blob_id: str
+ :param namespace: An optional namespace for the blob.
+ :type namespace: str
+
+ :return: The size of the blob.
+ :rtype: int
"""
def count(user, request, namespace=''):
"""
- Counts the total number of blobs.
+ Count the total number of blobs.
+
+ :param user: The id of the user who owns the blob.
+ :type user: str
+ :param request: A representation of all of the information about the
+ request that is being made.
+ :type request: twisted.web.server.Request
+ :param namespace: Restrict the count to a certain namespace.
+ :type namespace: str
+
+ :return: The number of blobs in the backend storage, possibly
+ restricted to a certain namespace.
+ :rtype: int
"""
- def list_blobs(user, request, namespace='', order_by=None):
+ def list_blobs(user, request, namespace='', order_by=None, deleted=False,
+ filter_flag=None):
"""
- Returns a json-encoded list of ids from user's blobs storage,
- optionally ordered by order_by parameter and optionally restricted by
- namespace.
+ List the blobs stored in the backend.
+
+ The resulting list can be ordered by date, filtered by namespace or
+ flag, and include deleted items or not.
- :returns: a deferred that fires upon finishing.
+ :param user: The id of the user who owns the blob.
+ :type user: str
+ :param request: A representation of all of the information about the
+ request that is being made.
+ :type request: twisted.web.server.Request
+ :param namespace: Restrict the count to a certain namespace.
+ :type namespace: str
+
+ :param order_by: 'date' (equivalent to '+date') or '-date', to sort
+ ascending or descending by date, respectivelly.
+ :type order_by: str
+ :param deleted: Whether to include deleted items in the result.
+ :type deleted: bool
+ :param filter_flag: If given, only results flagged with that flag will
+ be returned.
+ :type filter_flag: str
+
+ :return: A JSON list of blob ids, optionally ordered and/or restricted
+ by namespace.
+ :rtype: str
"""
def get_total_storage(user):
"""
Get the size used by a given user as the sum of all the blobs stored
- unders its namespace.
+ under all that user's namespaces.
+
+ :param user: The id of a user.
+ :type user: str
+
+ :return: The size in units of 1024 bytes.
+ :rtype: int
"""
def add_tag_header(user, blob_id, request, namespace=''):
"""
- Adds a header 'Tag' to the passed request object, containing the last
- 16 bytes of the encoded blob, which according to the spec contains the
- tag.
+ Add a ``Tag`` HTTP header to the passed request containing the tag of
+ a blob.
- :returns: a deferred that fires upon finishing.
+ :param blob_id: The id of the blob.
+ :type blob_id: str
+ :param request: A representation of all of the information about the
+ request that is being made.
+ :type request: twisted.web.server.Request
+ :param namespace: An optional namespace for the blob.
+ :type namespace: str
"""
class IIncomingBoxBackend(Interface):
"""
- An interface for an IncomingBoxBackend implementation.
+ An interface for a backend that can deliver
"""
def get_flags(user, blob_id, request, namespace=''):
"""
- Given a blob_id, return it's associated flags.
+ Get the flags for a blob.
- :returns: a JSON encoded string with a list of flags.
- """
+ :param user: The id of the user who owns the blob.
+ :type user: str
+ :param blob_id: The id of the blob.
+ :type blob_id: str
+ :param request: A representation of all of the information about the
+ request that is being made.
+ :type request: twisted.web.server.Request
+ :param namespace: An optional namespace for the blob.
+ :type namespace: str
- def set_flags(self, user, blob_id, request, namespace=''):
- """
- Set flags for a blob_id.
+ :return: a JSON encoded string with a list of flags.
+ :rtype: str
"""
- def list_blobs(self, user, request, namespace='', order_by=None,
- filter_flag=False):
+ def set_flags(user, blob_id, request, namespace=''):
"""
- Blobs listing with flags support. Accepts a filter_flag parameter,
- which is a flag that can be used to filter results matching it.
+ Set flags for a blob.
+
+ The flags are expected to be send in the body of the request, as a JSON
+ list of strings.
+
+ :param user: The id of the user who owns the blob.
+ :type user: str
+ :param blob_id: The id of the blob.
+ :type blob_id: str
+ :param request: A representation of all of the information about the
+ request that is being made.
+ :type request: twisted.web.server.Request
+ :param namespace: An optional namespace for the blob.
+ :type namespace: str
- :returns: a deferred that fires upon finishing.
+ :return: A string describing an error or ``None`` in case of success.
+ :rtype: str
"""
--
GitLab