root / docs / api-guide.rst @ a1d0bacb
History | View | Annotate | Download (10.1 kB)
1 | 3df48a3f | Constantinos Venetsanopoulos | .. _api-guide: |
---|---|---|---|
2 | 3df48a3f | Constantinos Venetsanopoulos | |
3 | 3df48a3f | Constantinos Venetsanopoulos | Synnefo REST API Guide |
4 | 3df48a3f | Constantinos Venetsanopoulos | ^^^^^^^^^^^^^^^^^^^^^^ |
5 | 3df48a3f | Constantinos Venetsanopoulos | |
6 | 3df48a3f | Constantinos Venetsanopoulos | This is Synnefo's REST API Guide. |
7 | 3df48a3f | Constantinos Venetsanopoulos | |
8 | 3df48a3f | Constantinos Venetsanopoulos | Here, we document all Synnefo REST APIs, to allow external developers write |
9 | 3df48a3f | Constantinos Venetsanopoulos | independent tools that interact with Synnefo. |
10 | 3df48a3f | Constantinos Venetsanopoulos | |
11 | 3df48a3f | Constantinos Venetsanopoulos | Synnefo exposes the OpenStack APIs for all of its operations. Also, extensions |
12 | 3df48a3f | Constantinos Venetsanopoulos | have been written for advanced operations wherever needed, and minor changes |
13 | 3df48a3f | Constantinos Venetsanopoulos | for things that were missing or change frequently. |
14 | 3df48a3f | Constantinos Venetsanopoulos | |
15 | 3df48a3f | Constantinos Venetsanopoulos | Most Synnefo services have a corresponding OpenStack API: |
16 | 3df48a3f | Constantinos Venetsanopoulos | |
17 | 3df48a3f | Constantinos Venetsanopoulos | | Cyclades/Compute Service -> OpenStack Compute API |
18 | 9b5ae5ed | Stavros Sachtouris | | Cyclades/Network Service -> OpenStack Networking ("Neutron") API |
19 | 9b5ae5ed | Stavros Sachtouris | | Cyclades/Image Service -> OpenStack Image ("Glance") API |
20 | 9b5ae5ed | Stavros Sachtouris | | Pithos/Storage Service -> OpenStack Object Storage API |
21 | 9b5ae5ed | Stavros Sachtouris | | Astakos/Identity Service -> OpenStack Identity ("Keystone") API |
22 | 3df48a3f | Constantinos Venetsanopoulos | | Astakos/Quota Service -> Proprietary API |
23 | 3df48a3f | Constantinos Venetsanopoulos | | Astakos/Resource Service -> Proprietary API |
24 | 9b5ae5ed | Stavros Sachtouris | | Astakos/Project Service -> Proprietary API |
25 | 3df48a3f | Constantinos Venetsanopoulos | |
26 | 3df48a3f | Constantinos Venetsanopoulos | Below, we will describe all Synnefo APIs with conjuction to the OpenStack APIs. |
27 | 3df48a3f | Constantinos Venetsanopoulos | |
28 | 3df48a3f | Constantinos Venetsanopoulos | |
29 | 3df48a3f | Constantinos Venetsanopoulos | Identity Service API (Astakos) |
30 | 3df48a3f | Constantinos Venetsanopoulos | ============================== |
31 | 3df48a3f | Constantinos Venetsanopoulos | |
32 | 3df48a3f | Constantinos Venetsanopoulos | The Identity Management Service of Synnefo, which is part of Astakos, exposes |
33 | 9b5ae5ed | Stavros Sachtouris | the OpenStack Identity ("Keystone") API. |
34 | 3df48a3f | Constantinos Venetsanopoulos | |
35 | 3df48a3f | Constantinos Venetsanopoulos | The current Astakos/Identity API is: |
36 | 3df48a3f | Constantinos Venetsanopoulos | |
37 | 3df48a3f | Constantinos Venetsanopoulos | .. toctree:: |
38 | 3df48a3f | Constantinos Venetsanopoulos | :maxdepth: 2 |
39 | 3df48a3f | Constantinos Venetsanopoulos | |
40 | 20394434 | Constantinos Venetsanopoulos | Identity API (Keystone) <identity-api-guide> |
41 | 3df48a3f | Constantinos Venetsanopoulos | |
42 | 3df48a3f | Constantinos Venetsanopoulos | |
43 | 3df48a3f | Constantinos Venetsanopoulos | Resource and Quota Service API (Astakos) |
44 | 3df48a3f | Constantinos Venetsanopoulos | ======================================== |
45 | 3df48a3f | Constantinos Venetsanopoulos | |
46 | 3df48a3f | Constantinos Venetsanopoulos | The Resource and Quota Service are implemented inside Astakos and have the |
47 | 3df48a3f | Constantinos Venetsanopoulos | following Synnefo specific (proprietary) API: |
48 | 3df48a3f | Constantinos Venetsanopoulos | |
49 | 3df48a3f | Constantinos Venetsanopoulos | .. toctree:: |
50 | 3df48a3f | Constantinos Venetsanopoulos | :maxdepth: 2 |
51 | 3df48a3f | Constantinos Venetsanopoulos | |
52 | 3df48a3f | Constantinos Venetsanopoulos | Resource and Quota API <quota-api-guide.rst> |
53 | 3df48a3f | Constantinos Venetsanopoulos | |
54 | 3df48a3f | Constantinos Venetsanopoulos | Project Service API |
55 | 3df48a3f | Constantinos Venetsanopoulos | =================== |
56 | 3df48a3f | Constantinos Venetsanopoulos | |
57 | 3df48a3f | Constantinos Venetsanopoulos | The Projects Service is implemented inside Astakos and has the following |
58 | 3df48a3f | Constantinos Venetsanopoulos | Synnefo specific (proprietary) API: |
59 | 3df48a3f | Constantinos Venetsanopoulos | |
60 | 3df48a3f | Constantinos Venetsanopoulos | .. toctree:: |
61 | 3df48a3f | Constantinos Venetsanopoulos | :maxdepth: 2 |
62 | 3df48a3f | Constantinos Venetsanopoulos | |
63 | 3df48a3f | Constantinos Venetsanopoulos | Project API <project-api-guide.rst> |
64 | 3df48a3f | Constantinos Venetsanopoulos | |
65 | 3df48a3f | Constantinos Venetsanopoulos | Compute Service API (Cyclades) |
66 | 3df48a3f | Constantinos Venetsanopoulos | ============================== |
67 | 3df48a3f | Constantinos Venetsanopoulos | |
68 | 3df48a3f | Constantinos Venetsanopoulos | The Compute part of Cyclades exposes the OpenStack Compute API with minor |
69 | 3df48a3f | Constantinos Venetsanopoulos | changes wherever needed. |
70 | 3df48a3f | Constantinos Venetsanopoulos | |
71 | 3df48a3f | Constantinos Venetsanopoulos | This is the Cyclades/Compute API: |
72 | 3df48a3f | Constantinos Venetsanopoulos | |
73 | 3df48a3f | Constantinos Venetsanopoulos | .. toctree:: |
74 | 3df48a3f | Constantinos Venetsanopoulos | :maxdepth: 2 |
75 | 3df48a3f | Constantinos Venetsanopoulos | |
76 | 20394434 | Constantinos Venetsanopoulos | Compute API (Compute) <compute-api-guide> |
77 | 20394434 | Constantinos Venetsanopoulos | |
78 | 3df48a3f | Constantinos Venetsanopoulos | |
79 | 3df48a3f | Constantinos Venetsanopoulos | |
80 | 3df48a3f | Constantinos Venetsanopoulos | Network Service API (Cyclades) |
81 | 3df48a3f | Constantinos Venetsanopoulos | ============================== |
82 | 3df48a3f | Constantinos Venetsanopoulos | |
83 | 3df48a3f | Constantinos Venetsanopoulos | The Network Service is implemented inside Cyclades. It exposes the OpenStack |
84 | 9b5ae5ed | Stavros Sachtouris | Networking ("Neutron") API. |
85 | 3df48a3f | Constantinos Venetsanopoulos | |
86 | 3df48a3f | Constantinos Venetsanopoulos | This is the Cyclades/Network API: |
87 | 3df48a3f | Constantinos Venetsanopoulos | |
88 | 3df48a3f | Constantinos Venetsanopoulos | .. toctree:: |
89 | 3df48a3f | Constantinos Venetsanopoulos | :maxdepth: 2 |
90 | 3df48a3f | Constantinos Venetsanopoulos | |
91 | 3df48a3f | Constantinos Venetsanopoulos | Network API (Neutron) <network-api-guide> |
92 | 3df48a3f | Constantinos Venetsanopoulos | |
93 | 3df48a3f | Constantinos Venetsanopoulos | |
94 | 3df48a3f | Constantinos Venetsanopoulos | Image Service API (Cyclades) |
95 | 3df48a3f | Constantinos Venetsanopoulos | ============================ |
96 | 3df48a3f | Constantinos Venetsanopoulos | |
97 | 3df48a3f | Constantinos Venetsanopoulos | The Image Service is implemented inside Cyclades. It exposes the OpenStack |
98 | 9b5ae5ed | Stavros Sachtouris | Image ("Glance") API with minor changes wherever needed. |
99 | 3df48a3f | Constantinos Venetsanopoulos | |
100 | 3df48a3f | Constantinos Venetsanopoulos | This is the Cyclades/Image API: |
101 | 3df48a3f | Constantinos Venetsanopoulos | |
102 | 3df48a3f | Constantinos Venetsanopoulos | .. toctree:: |
103 | 3df48a3f | Constantinos Venetsanopoulos | :maxdepth: 2 |
104 | 3df48a3f | Constantinos Venetsanopoulos | |
105 | 20394434 | Constantinos Venetsanopoulos | Image API (Glance) <image-api-guide> |
106 | 3df48a3f | Constantinos Venetsanopoulos | |
107 | 3df48a3f | Constantinos Venetsanopoulos | |
108 | 3df48a3f | Constantinos Venetsanopoulos | Storage Service API (Pithos) |
109 | 3df48a3f | Constantinos Venetsanopoulos | ============================ |
110 | 3df48a3f | Constantinos Venetsanopoulos | |
111 | 3df48a3f | Constantinos Venetsanopoulos | Pithos is the Storage Service of Synnefo and it exposes the OpenStack Object |
112 | 3df48a3f | Constantinos Venetsanopoulos | Storage API with extensions for advanced operations, e.g., syncing. |
113 | 3df48a3f | Constantinos Venetsanopoulos | |
114 | 3df48a3f | Constantinos Venetsanopoulos | This is the Pithos Object Storage API: |
115 | 3df48a3f | Constantinos Venetsanopoulos | |
116 | 3df48a3f | Constantinos Venetsanopoulos | .. toctree:: |
117 | 3df48a3f | Constantinos Venetsanopoulos | :maxdepth: 2 |
118 | 3df48a3f | Constantinos Venetsanopoulos | |
119 | 20394434 | Constantinos Venetsanopoulos | Storage API (Object Storage) <object-api-guide> |
120 | 3df48a3f | Constantinos Venetsanopoulos | |
121 | 3df48a3f | Constantinos Venetsanopoulos | |
122 | 3df48a3f | Constantinos Venetsanopoulos | Implementing new clients |
123 | 3df48a3f | Constantinos Venetsanopoulos | ======================== |
124 | 3df48a3f | Constantinos Venetsanopoulos | |
125 | 3df48a3f | Constantinos Venetsanopoulos | In this section we discuss implementation guidelines, that a developer should |
126 | 3df48a3f | Constantinos Venetsanopoulos | take into account before writing his own client for the above APIs. Before, |
127 | 3df48a3f | Constantinos Venetsanopoulos | starting your client implementation, make sure you have thoroughly read the |
128 | 3df48a3f | Constantinos Venetsanopoulos | corresponding Synnefo API. |
129 | 3df48a3f | Constantinos Venetsanopoulos | |
130 | 3df48a3f | Constantinos Venetsanopoulos | Pithos clients |
131 | 3df48a3f | Constantinos Venetsanopoulos | -------------- |
132 | 3df48a3f | Constantinos Venetsanopoulos | |
133 | 3df48a3f | Constantinos Venetsanopoulos | User Experience |
134 | 3df48a3f | Constantinos Venetsanopoulos | ~~~~~~~~~~~~~~~ |
135 | 3df48a3f | Constantinos Venetsanopoulos | |
136 | 3df48a3f | Constantinos Venetsanopoulos | Hopefully this API will allow for a multitude of client implementations, each |
137 | 3df48a3f | Constantinos Venetsanopoulos | supporting a different device or operating system. All clients will be able to |
138 | 3df48a3f | Constantinos Venetsanopoulos | manipulate containers and objects - even software only designed for OOS API |
139 | 3df48a3f | Constantinos Venetsanopoulos | compatibility. But a Pithos interface should not be only about showing |
140 | 3df48a3f | Constantinos Venetsanopoulos | containers and folders. There are some extra user interface elements and |
141 | 3df48a3f | Constantinos Venetsanopoulos | functionalities that should be common to all implementations. |
142 | 3df48a3f | Constantinos Venetsanopoulos | |
143 | 3df48a3f | Constantinos Venetsanopoulos | Upon entrance to the service, a user is presented with the following elements - |
144 | 3df48a3f | Constantinos Venetsanopoulos | which can be represented as folders or with other related icons: |
145 | 3df48a3f | Constantinos Venetsanopoulos | |
146 | 3df48a3f | Constantinos Venetsanopoulos | * The ``home`` element, which is used as the default entry point to the user's |
147 | 3df48a3f | Constantinos Venetsanopoulos | "files". Objects under ``home`` are represented in the usual hierarchical |
148 | 3df48a3f | Constantinos Venetsanopoulos | organization of folders and files. |
149 | 3df48a3f | Constantinos Venetsanopoulos | * The ``trash`` element, which contains files that have been marked for |
150 | 3df48a3f | Constantinos Venetsanopoulos | deletion, but can still be recovered. |
151 | 9b5ae5ed | Stavros Sachtouris | * The ``shared by me`` element, which contains all objects shared by the |
152 | 9b5ae5ed | Stavros Sachtouris | user to other users of the system. |
153 | 9b5ae5ed | Stavros Sachtouris | * The ``shared with me`` element, which contains all objects that other users |
154 | 9b5ae5ed | Stavros Sachtouris | share with the user. |
155 | 3df48a3f | Constantinos Venetsanopoulos | * The ``groups`` element, which contains the names of groups the user has |
156 | 3df48a3f | Constantinos Venetsanopoulos | defined. Each group consists of a user list. Group creation, deletion, and |
157 | 3df48a3f | Constantinos Venetsanopoulos | manipulation is carried out by actions originating here. |
158 | 9b5ae5ed | Stavros Sachtouris | .. * The ``history`` element, which allows browsing past instances of ``home`` |
159 | 9b5ae5ed | Stavros Sachtouris | .. and - optionally - ``trash``. |
160 | 3df48a3f | Constantinos Venetsanopoulos | |
161 | 3df48a3f | Constantinos Venetsanopoulos | Objects in Pithos can be: |
162 | 3df48a3f | Constantinos Venetsanopoulos | |
163 | 3df48a3f | Constantinos Venetsanopoulos | * Moved to trash and then deleted. |
164 | 3df48a3f | Constantinos Venetsanopoulos | * Shared with specific permissions. |
165 | 3df48a3f | Constantinos Venetsanopoulos | * Made public (shared with non-Pithos users). |
166 | 3df48a3f | Constantinos Venetsanopoulos | * Restored from previous versions. |
167 | 3df48a3f | Constantinos Venetsanopoulos | |
168 | 3df48a3f | Constantinos Venetsanopoulos | Some of these functions are performed by the client software and some by the |
169 | 3df48a3f | Constantinos Venetsanopoulos | Pithos server. |
170 | 3df48a3f | Constantinos Venetsanopoulos | |
171 | 3df48a3f | Constantinos Venetsanopoulos | In the first version of Pithos, objects could also be assigned custom tags. |
172 | 3df48a3f | Constantinos Venetsanopoulos | This is no longer supported. Existing deployments can migrate tags into a |
173 | 3df48a3f | Constantinos Venetsanopoulos | specific metadata value, i.e. ``X-Object-Meta-Tags``. |
174 | 3df48a3f | Constantinos Venetsanopoulos | |
175 | 3df48a3f | Constantinos Venetsanopoulos | Implementation Guidelines |
176 | 3df48a3f | Constantinos Venetsanopoulos | ~~~~~~~~~~~~~~~~~~~~~~~~~ |
177 | 3df48a3f | Constantinos Venetsanopoulos | |
178 | 3df48a3f | Constantinos Venetsanopoulos | Pithos clients should use the ``pithos`` and ``trash`` containers for active |
179 | 3df48a3f | Constantinos Venetsanopoulos | and inactive objects respectively. If any of these containers is not found, the |
180 | 3df48a3f | Constantinos Venetsanopoulos | client software should create it, without interrupting the user's workflow. The |
181 | 3df48a3f | Constantinos Venetsanopoulos | ``home`` element corresponds to ``pithos`` and the ``trash`` element to |
182 | 3df48a3f | Constantinos Venetsanopoulos | ``trash``. Use ``PUT`` with the ``X-Move-From`` header, or ``MOVE`` to transfer |
183 | 3df48a3f | Constantinos Venetsanopoulos | objects from one container to the other. Use ``DELETE`` to remove from |
184 | 3df48a3f | Constantinos Venetsanopoulos | ``pithos`` without trashing, or to remove from ``trash``. When moving objects, |
185 | 3df48a3f | Constantinos Venetsanopoulos | detect naming conflicts with the ``If-Match`` or ``If-None-Match`` headers. |
186 | 3df48a3f | Constantinos Venetsanopoulos | Such conflicts should be resolved by the user. |
187 | 3df48a3f | Constantinos Venetsanopoulos | |
188 | 3df48a3f | Constantinos Venetsanopoulos | Object names should use the ``/`` delimiter to impose a hierarchy of folders |
189 | 3df48a3f | Constantinos Venetsanopoulos | and files. |
190 | 3df48a3f | Constantinos Venetsanopoulos | |
191 | 3df48a3f | Constantinos Venetsanopoulos | The ``shared`` element should be implemented as a read-only view of the |
192 | 3df48a3f | Constantinos Venetsanopoulos | ``pithos`` container, using the ``shared`` parameter when listing objects. The |
193 | 3df48a3f | Constantinos Venetsanopoulos | ``others`` element, should start with a top-level ``GET`` to retrieve the list |
194 | 3df48a3f | Constantinos Venetsanopoulos | of accounts accessible to the user. It is suggested that the client software |
195 | 3df48a3f | Constantinos Venetsanopoulos | hides the next step of navigation - the container - if it only includes |
196 | 3df48a3f | Constantinos Venetsanopoulos | ``pithos`` and forwards the user directly to the objects. |
197 | 3df48a3f | Constantinos Venetsanopoulos | |
198 | 3df48a3f | Constantinos Venetsanopoulos | Public objects are not included in ``shared`` and ``others`` listings. It is |
199 | 3df48a3f | Constantinos Venetsanopoulos | suggested that they are marked in a visually distinctive way in ``pithos`` |
200 | 3df48a3f | Constantinos Venetsanopoulos | listings (for example using an icon overlay). |
201 | 3df48a3f | Constantinos Venetsanopoulos | |
202 | 3df48a3f | Constantinos Venetsanopoulos | A special application menu, or a section in application preferences, should be |
203 | 3df48a3f | Constantinos Venetsanopoulos | devoted to managing groups (the ``groups`` element). All group-related actions |
204 | 3df48a3f | Constantinos Venetsanopoulos | are implemented at the account level. |
205 | 3df48a3f | Constantinos Venetsanopoulos | |
206 | 3df48a3f | Constantinos Venetsanopoulos | Browsing past versions of objects should be available both at the object and |
207 | 3df48a3f | Constantinos Venetsanopoulos | the container level. At the object level, a list of past versions can be |
208 | 3df48a3f | Constantinos Venetsanopoulos | included in the screen showing details or more information on the object |
209 | 3df48a3f | Constantinos Venetsanopoulos | (metadata, permissions, etc.). At the container level, it is suggested that |
210 | 3df48a3f | Constantinos Venetsanopoulos | clients use a ``history`` element, which presents to the user a read-only, |
211 | 3df48a3f | Constantinos Venetsanopoulos | time-variable view of ``pithos`` contents. This can be accomplished via the |
212 | 3df48a3f | Constantinos Venetsanopoulos | ``until`` parameter in listings. Optionally, ``history`` may include ``trash``. |
213 | 3df48a3f | Constantinos Venetsanopoulos | |
214 | 3df48a3f | Constantinos Venetsanopoulos | Uploading and downloading data |
215 | 3df48a3f | Constantinos Venetsanopoulos | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
216 | 3df48a3f | Constantinos Venetsanopoulos | |
217 | 3df48a3f | Constantinos Venetsanopoulos | By using hashmaps to upload and download objects the corresponding operations |
218 | 3df48a3f | Constantinos Venetsanopoulos | can complete much faster. |
219 | 3df48a3f | Constantinos Venetsanopoulos | |
220 | 3df48a3f | Constantinos Venetsanopoulos | In the case of an upload, only the missing blocks will be submitted to the |
221 | 3df48a3f | Constantinos Venetsanopoulos | server: |
222 | 3df48a3f | Constantinos Venetsanopoulos | |
223 | 3df48a3f | Constantinos Venetsanopoulos | * Calculate the hash value for each block of the object to be uploaded. Use |
224 | 3df48a3f | Constantinos Venetsanopoulos | the hash algorithm and block size of the destination container. |
225 | 3df48a3f | Constantinos Venetsanopoulos | * Send a hashmap ``PUT`` request for the object. |
226 | 3df48a3f | Constantinos Venetsanopoulos | |
227 | 3df48a3f | Constantinos Venetsanopoulos | * Server responds with status ``201`` (Created): |
228 | 3df48a3f | Constantinos Venetsanopoulos | |
229 | 3df48a3f | Constantinos Venetsanopoulos | * Blocks are already on the server. The object has been created. Done. |
230 | 3df48a3f | Constantinos Venetsanopoulos | |
231 | 3df48a3f | Constantinos Venetsanopoulos | * Server responds with status ``409`` (Conflict): |
232 | 3df48a3f | Constantinos Venetsanopoulos | |
233 | 3df48a3f | Constantinos Venetsanopoulos | * Server's response body contains the hashes of the blocks that do not |
234 | 3df48a3f | Constantinos Venetsanopoulos | exist on the server. |
235 | 3df48a3f | Constantinos Venetsanopoulos | * For each hash value in the server's response (or all hashes together): |
236 | 3df48a3f | Constantinos Venetsanopoulos | |
237 | 3df48a3f | Constantinos Venetsanopoulos | * Send a ``POST`` request to the destination container with the |
238 | 3df48a3f | Constantinos Venetsanopoulos | corresponding data. |
239 | 3df48a3f | Constantinos Venetsanopoulos | |
240 | 3df48a3f | Constantinos Venetsanopoulos | * Repeat hashmap ``PUT``. Fail if the server's response is not ``201``. |
241 | 3df48a3f | Constantinos Venetsanopoulos | |
242 | 3df48a3f | Constantinos Venetsanopoulos | Consulting hashmaps when downloading allows for resuming partially transferred |
243 | 3df48a3f | Constantinos Venetsanopoulos | objects. The client should retrieve the hashmap from the server and compare it |
244 | 3df48a3f | Constantinos Venetsanopoulos | with the hashmap computed from the respective local file. Any missing parts can |
245 | 3df48a3f | Constantinos Venetsanopoulos | be downloaded with ``GET`` requests with the additional ``Range`` header. |
246 | 3df48a3f | Constantinos Venetsanopoulos | |
247 | 3df48a3f | Constantinos Venetsanopoulos | Syncing |
248 | 3df48a3f | Constantinos Venetsanopoulos | ~~~~~~~ |
249 | 3df48a3f | Constantinos Venetsanopoulos | |
250 | 3df48a3f | Constantinos Venetsanopoulos | Consider the following algorithm for synchronizing a local folder with the |
251 | 3df48a3f | Constantinos Venetsanopoulos | server. The "state" is the complete object listing, with the corresponding |
252 | 3df48a3f | Constantinos Venetsanopoulos | attributes. |
253 | 3df48a3f | Constantinos Venetsanopoulos | |
254 | 3df48a3f | Constantinos Venetsanopoulos | .. code-block:: python |
255 | 3df48a3f | Constantinos Venetsanopoulos | |
256 | 3df48a3f | Constantinos Venetsanopoulos | # L: Local State, the last synced state of the object. |
257 | 3df48a3f | Constantinos Venetsanopoulos | # Stored locally (e.g. in an SQLite database) |
258 | 3df48a3f | Constantinos Venetsanopoulos | |
259 | 3df48a3f | Constantinos Venetsanopoulos | # C: Current State, the current local state of the object |
260 | 3df48a3f | Constantinos Venetsanopoulos | # Returned by the filesystem |
261 | 3df48a3f | Constantinos Venetsanopoulos | |
262 | 3df48a3f | Constantinos Venetsanopoulos | # S: Server State, the current server state of the object |
263 | 3df48a3f | Constantinos Venetsanopoulos | # Returned by the server (HTTP request) |
264 | 3df48a3f | Constantinos Venetsanopoulos | |
265 | 3df48a3f | Constantinos Venetsanopoulos | def sync(path): |
266 | 3df48a3f | Constantinos Venetsanopoulos | L = get_local_state(path) # Database action |
267 | 3df48a3f | Constantinos Venetsanopoulos | C = get_current_state(path) # Filesystem action |
268 | 3df48a3f | Constantinos Venetsanopoulos | S = get_server_state(path) # Network action |
269 | 3df48a3f | Constantinos Venetsanopoulos | |
270 | 3df48a3f | Constantinos Venetsanopoulos | if C == L: |
271 | 3df48a3f | Constantinos Venetsanopoulos | # No local changes |
272 | 3df48a3f | Constantinos Venetsanopoulos | if S == L: |
273 | 3df48a3f | Constantinos Venetsanopoulos | # No remote changes, nothing to do |
274 | 3df48a3f | Constantinos Venetsanopoulos | return |
275 | 3df48a3f | Constantinos Venetsanopoulos | else: |
276 | 3df48a3f | Constantinos Venetsanopoulos | # Update local state to match that of the server |
277 | 3df48a3f | Constantinos Venetsanopoulos | download(path) |
278 | 3df48a3f | Constantinos Venetsanopoulos | update_local_state(path, S) |
279 | 3df48a3f | Constantinos Venetsanopoulos | else: |
280 | 3df48a3f | Constantinos Venetsanopoulos | # Local changes exist |
281 | 3df48a3f | Constantinos Venetsanopoulos | if S == L: |
282 | 3df48a3f | Constantinos Venetsanopoulos | # No remote changes, update the server and the local state |
283 | 3df48a3f | Constantinos Venetsanopoulos | upload(path) |
284 | 3df48a3f | Constantinos Venetsanopoulos | update_local_state(path, C) |
285 | 3df48a3f | Constantinos Venetsanopoulos | else: |
286 | 3df48a3f | Constantinos Venetsanopoulos | # Both local and server changes exist |
287 | 3df48a3f | Constantinos Venetsanopoulos | if C == S: |
288 | 3df48a3f | Constantinos Venetsanopoulos | # We were lucky, both did the same |
289 | 3df48a3f | Constantinos Venetsanopoulos | update_local_state(path, C) |
290 | 3df48a3f | Constantinos Venetsanopoulos | else: |
291 | 3df48a3f | Constantinos Venetsanopoulos | # Conflicting changes exist |
292 | 3df48a3f | Constantinos Venetsanopoulos | conflict() |
293 | 3df48a3f | Constantinos Venetsanopoulos | |
294 | 3df48a3f | Constantinos Venetsanopoulos | |
295 | 3df48a3f | Constantinos Venetsanopoulos | Notes: |
296 | 3df48a3f | Constantinos Venetsanopoulos | |
297 | 3df48a3f | Constantinos Venetsanopoulos | * States represent file hashes (it is suggested to use Merkle). Deleted or |
298 | 3df48a3f | Constantinos Venetsanopoulos | non-existing files are assumed to have a magic hash (e.g. empty string). |