f9257c9b40f38a7f49a61f7607d62e7a84683dfe
[soledad.git] / src / leap / soledad / server / interfaces.py
1 # -*- coding: utf-8 -*-
2 # interfaces.py
3 # Copyright (C) 2017 LEAP
4 #
5 # This program is free software: you can redistribute it and/or modify
6 # it under the terms of the GNU General Public License as published by
7 # the Free Software Foundation, either version 3 of the License, or
8 # (at your option) any later version.
9 #
10 # This program is distributed in the hope that it will be useful,
11 # but WITHOUT ANY WARRANTY; without even the implied warranty of
12 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 # GNU General Public License for more details.
14 #
15 # You should have received a copy of the GNU General Public License
16 # along with this program. If not, see <http://www.gnu.org/licenses/>.
17
18
19 from zope.interface import Interface
20
21
22 class IBlobsBackend(Interface):
23
24     """
25     An interface for a backend that can store blobs.
26     """
27
28     def read_blob(user, blob_id, namespace=''):
29         """
30         Read a blob from the backend storage return it as a twisted resource.
31
32         :param user: The id of the user who owns the blob.
33         :type user: str
34         :param blob_id: The id of the blob.
35         :type blob_id: str
36         :param namespace: An optional namespace for the blob.
37         :type namespace: str
38
39         :return: The blob as a twisted resource.
40         :rtype: twisted.web.resource.Resource
41         """
42
43     def write_blob(user, blob_id, fd, namespace=''):
44         """
45         Write a blob to the backend storage.
46
47         :param user: The id of the user who owns the blob.
48         :type user: str
49         :param blob_id: The id of the blob.
50         :type blob_id: str
51         :param fd: A file-like object into which the contents of the blob
52             should be written.
53         :type fd: file-like
54         :param namespace: An optional namespace for the blob.
55         :type namespace: str
56
57         :return: A deferred that fires when the blob has been written to the
58                  backend storage.
59         :rtype: twisted.internet.defer.Deferred
60         """
61
62     def delete_blob(user, blob_id, namespace=''):
63         """
64         Delete a blob from the backend storage.
65
66         :param user: The id of the user who owns the blob.
67         :type user: str
68         :param blob_id: The id of the blob.
69         :type blob_id: str
70         :param namespace: An optional namespace for the blob.
71         :type namespace: str
72
73         :return: A deferred that fires when the blob has been deleted.
74         :rtype: twisted.internet.defer.Deferred
75         """
76
77     def get_blob_size(user, blob_id, namespace=''):
78         """
79         Get the size of a blob.
80
81         :param user: The id of the user who owns the blob.
82         :type user: str
83         :param blob_id: The id of the blob.
84         :type blob_id: str
85         :param namespace: An optional namespace for the blob.
86         :type namespace: str
87
88         :return: The size of the blob.
89         :rtype: int
90         """
91
92     def count(user, namespace=''):
93         """
94         Count the total number of blobs.
95
96         :param user: The id of the user who owns the blob.
97         :type user: str
98         :param namespace: Restrict the count to a certain namespace.
99         :type namespace: str
100
101         :return: The number of blobs in the backend storage, possibly
102                  restricted to a certain namespace.
103         :rtype: int
104         """
105
106     def list_blobs(user, namespace='', order_by=None, deleted=False,
107                    filter_flag=None):
108         """
109         List the blobs stored in the backend.
110
111         The resulting list can be ordered by date, filtered by namespace or
112         flag, and include deleted items or not.
113
114         :param user: The id of the user who owns the blob.
115         :type user: str
116         :param namespace: Restrict the count to a certain namespace.
117         :type namespace: str
118         :param order_by: 'date' (equivalent to '+date') or  '-date', to sort
119             ascending or descending by date, respectivelly.
120         :type order_by: str
121         :param deleted: Whether to include deleted items in the result.
122         :type deleted: bool
123         :param filter_flag: If given, only results flagged with that flag will
124             be returned.
125         :type filter_flag: str
126
127         :return: A list of blob ids, optionally ordered and/or restricted by
128                  namespace.
129         :rtype: list of str
130         """
131
132     def get_total_storage(user):
133         """
134         Get the size used by a given user as the sum of all the blobs stored
135         under all that user's namespaces.
136
137         :param user: The id of a user.
138         :type user: str
139
140         :return: The size in units of 1024 bytes.
141         :rtype: int
142         """
143
144     def get_tag(user, blob_id, namespace=''):
145         """
146         Get the tag of a blob.
147
148         :param blob_id: The id of the blob.
149         :type blob_id: str
150         :param namespace: An optional namespace for the blob.
151         :type namespace: str
152
153         :return: The tag of the blob.
154         :rtype: str
155         """
156
157     def get_flags(user, blob_id, namespace=''):
158         """
159         Get the flags for a blob.
160
161         :param user: The id of the user who owns the blob.
162         :type user: str
163         :param blob_id: The id of the blob.
164         :type blob_id: str
165         :param namespace: An optional namespace for the blob.
166         :type namespace: str
167
168         :return: a list of flags.
169         :rtype: list of str
170         """
171
172     def set_flags(user, blob_id, flags, namespace=''):
173         """
174         Set flags for a blob.
175
176         :param user: The id of the user who owns the blob.
177         :type user: str
178         :param blob_id: The id of the blob.
179         :type blob_id: str
180         :param flags: The list of flags to be set.
181         :type flags: list of str
182         :param namespace: An optional namespace for the blob.
183         :type namespace: str
184         """