Revision 07c87d4f
b/snf-astakos-app/docs/projects_specs.rst | ||
---|---|---|
1 |
Synnefo Projects |
|
2 |
================ |
|
3 |
|
|
4 |
Projects can be thought of as contracts between the infrastructure |
|
5 |
and the members of the project, so that resources can be allocated |
|
6 |
by the members and used for a specified period in time. |
|
7 |
|
|
8 |
Definition |
|
9 |
---------- |
|
10 |
A **definition** for a project represents the initialization |
|
11 |
or modification of a project has the following attributes: |
|
12 |
|
|
13 |
``name`` |
|
14 |
*in dot-hierarchical dns-like form* |
|
15 |
|
|
16 |
``description`` |
|
17 |
*text describing the project for the public* |
|
18 |
|
|
19 |
``start_date`` |
|
20 |
*when the project is to be started* |
|
21 |
|
|
22 |
``end_date`` |
|
23 |
*when the project is to be ended* |
|
24 |
|
|
25 |
``member_join_policy`` |
|
26 |
*an enumeration of policies on how new join requests are to be accepted. |
|
27 |
The policies include the following:* |
|
28 |
|
|
29 |
``auto_accept`` |
|
30 |
*new join requests are automatically accepted by the system* |
|
31 |
|
|
32 |
``owner_accepts`` |
|
33 |
*new join requests must be accepted by the owner of the project* |
|
34 |
|
|
35 |
``closed`` |
|
36 |
*no new members can join the project, even if old ones leave* |
|
37 |
|
|
38 |
``member_leave_policy`` |
|
39 |
*an enumeration of policies on how new leave requests are to be accepted. |
|
40 |
The policies include the following:* |
|
41 |
|
|
42 |
``auto_accept`` |
|
43 |
*leave requests are automatically accepted by the system* |
|
44 |
|
|
45 |
``owner_accepts`` |
|
46 |
*leave requests must be accepted by the owner of the project** |
|
47 |
|
|
48 |
``closed`` |
|
49 |
*no member can leave the project* |
|
50 |
|
|
51 |
``limit_on_members_number`` |
|
52 |
*the maximum number of members that can be admitted to the project* |
|
53 |
|
|
54 |
``limits_on_resources`` |
|
55 |
*a set of limits on the total resources the group can grant to its members* |
|
56 |
|
|
57 |
``resource_grants`` |
|
58 |
*a set of resource usage limits each member is granted by the project* |
|
59 |
|
|
60 |
|
|
61 |
|
|
62 |
Application for a Project |
|
63 |
------------------------- |
|
64 |
An **application** for a project must be issued by a user and |
|
65 |
approved by the Service before any resources are granted. |
|
66 |
Its attributes are: |
|
67 |
|
|
68 |
``serial`` |
|
69 |
*a unique serial number identifying the application* |
|
70 |
|
|
71 |
``applicant`` |
|
72 |
*who applies for creation or modification of a project* |
|
73 |
|
|
74 |
``owner`` |
|
75 |
*the requested owner of the project* |
|
76 |
|
|
77 |
``comments`` |
|
78 |
*text comments for the application* |
|
79 |
|
|
80 |
``definition`` |
|
81 |
*the definition of the project being requested* |
|
82 |
|
|
83 |
``issue_date`` |
|
84 |
*when the application was submitted* |
|
85 |
|
|
86 |
``precursor_application`` |
|
87 |
*a reference by serial to a previous application which this application |
|
88 |
requests to modify. It can be null if there is no precursor.* |
|
89 |
|
|
90 |
|
|
91 |
|
|
92 |
Project Membership |
|
93 |
------------------------- |
|
94 |
A *project membership* object maps a user to a project and holds |
|
95 |
state for this mapping. |
|
96 |
There are no inherent constraints to this mapping, |
|
97 |
any user might be a member to any project. |
|
98 |
|
|
99 |
The **state** of membership can be: |
|
100 |
|
|
101 |
:(1): *pending acceptance* |
|
102 |
:(2a): *rejected* |
|
103 |
:(2b): *accepted, pending synchronization* |
|
104 |
:(3): *active* |
|
105 |
:(4): *pending removal* |
|
106 |
:(5): *removed, pending synchronization* |
|
107 |
:(6): *removed* |
|
108 |
|
|
109 |
The transitions from 2b to 3, and 5 to 6, must first |
|
110 |
commit their starting state and then only update to the next state |
|
111 |
after the *Synchronize Membership* procedure has been |
|
112 |
acknowledged as successful. |
|
113 |
|
|
114 |
Except states 2b and 5 which explicitly state that they are *pending*, |
|
115 |
all other states are considered *synchronized* |
|
116 |
|
|
117 |
|
|
118 |
|
|
119 |
Project |
|
120 |
------- |
|
121 |
A **project** is created or modified upon the approval of an application. |
|
122 |
It is initialized with the *definition* contained in the application, |
|
123 |
and grants resources as specified, and acquires all the extra state needed. |
|
124 |
The *definition* of a project does not belong to its mutable state, |
|
125 |
and can only be changed by approving a new application. |
|
126 |
The attributes for a project are: |
|
127 |
|
|
128 |
``serial`` |
|
129 |
*a unique serial number identifying the project* |
|
130 |
|
|
131 |
``application`` |
|
132 |
*the application which has created or modified the project. |
|
133 |
An application is approved by setting it to this attribute.* |
|
134 |
|
|
135 |
``last_application_synced`` |
|
136 |
*the last application that was successfully synchronized with Quotaholder. |
|
137 |
Normally, this is the same as the ``application`` above. |
|
138 |
However, on approval, only ``application`` is set |
|
139 |
so the two attributes differ, marking the project as pending definition |
|
140 |
synchronization. Upon successful synchronization with Quotaholder, |
|
141 |
``last_application_synced`` is also set, |
|
142 |
marking the project definition synchronized. |
|
143 |
Note that if during the synchronization another approval |
|
144 |
updates ``application``, then after synchronization the project |
|
145 |
is still out of sync, and needs another loop.* |
|
146 |
|
|
147 |
``creation_date`` |
|
148 |
*when the project was created (i.e. was first approved)* |
|
149 |
|
|
150 |
``last_approval_date`` |
|
151 |
*when was the last approval (i.e. creation or modification). |
|
152 |
Null if the project has not been approved or has been suspended.* |
|
153 |
|
|
154 |
``termination_start_date`` |
|
155 |
*when the project was ordered to terminate, |
|
156 |
and declared out of sync for its resource grants to be removed. |
|
157 |
(is null if the project has not been ordered to terminate)* |
|
158 |
|
|
159 |
``termination_date`` |
|
160 |
*when the project termination was actually completed by the service |
|
161 |
following the successful revocation of resource grants. |
|
162 |
(is null if the project has not been terminated)* |
|
163 |
|
|
164 |
``members`` |
|
165 |
*the set of members for this project* |
|
166 |
|
|
167 |
``membership_updated`` |
|
168 |
*boolean attribute declaring that the project |
|
169 |
needs membership synchronization. |
|
170 |
It must be atomically set and committed before |
|
171 |
any synchronization begins. |
|
172 |
It must be unset only after synchronization |
|
173 |
has been confirmed as successful.* |
|
174 |
|
|
175 |
|
|
176 |
|
|
177 |
Rules |
|
178 |
----- |
|
179 |
|
|
180 |
1. **Valid projects** |
|
181 |
|
|
182 |
Projects are valid only if they violate none of the rules |
|
183 |
|
|
184 |
2. **Active projects** |
|
185 |
|
|
186 |
A project is declared **active** when its resource grants are in effect. |
|
187 |
A valid project can be active if and only if |
|
188 |
- its ``last_approval_date`` is not null |
|
189 |
- its ``termination_date`` is null |
|
190 |
- its ``limit_on_members_number`` and ``limits_on_resources`` are not violated |
|
191 |
|
|
192 |
2. **Terminated projects** |
|
193 |
|
|
194 |
A valid project is declared **terminated**, if and only if |
|
195 |
its ``termination_date`` is not null |
|
196 |
|
|
197 |
4. **Suspended projects** |
|
198 |
|
|
199 |
A valid project is declared **terminated** if and only if |
|
200 |
|
|
201 |
- its ``termination_date`` is null |
|
202 |
- its ``last_approval_date`` is null, |
|
203 |
or its ``limit_on_members_number`` and ``limits_on_resources`` are violated |
|
204 |
|
|
205 |
5. **Alive projects** |
|
206 |
|
|
207 |
Projects are declared **alive** if they are either *active*, or *suspended*. |
|
208 |
Users and owners are always able to interact with alive projects. |
|
209 |
|
|
210 |
6. **Life status** |
|
211 |
|
|
212 |
The status of being alive, active, suspended, terminated. |
|
213 |
|
|
214 |
7. **Project states** |
|
215 |
|
|
216 |
The states of a project that are significant from a control flow aspect, |
|
217 |
are the following: |
|
218 |
|
|
219 |
:(0): pending approval |
|
220 |
:(1a): alive, pending definition sync |
|
221 |
:(1b): alive, pending membership sync |
|
222 |
:(1c): alive, pending total sync |
|
223 |
:(2): alive |
|
224 |
:(3a): terminated, pending definition sync |
|
225 |
:(3b): terminated, pending membership sync |
|
226 |
:(3c): terminated, pending total sync |
|
227 |
:(4): terminated |
|
228 |
|
|
229 |
|
|
230 |
7. **Synchronization status** |
|
231 |
|
|
232 |
The status of the project's synchronization with Quotaholder |
|
233 |
can be either **synchronized** or **unsyncrhonized**. |
|
234 |
|
|
235 |
An alive project is delcared synchronized by setting |
|
236 |
``last_application_synced`` to be equal to the ``application``, |
|
237 |
and setting ``membership_updated`` to false, |
|
238 |
|
|
239 |
Semantically, the project becomes synchronized when its application |
|
240 |
definition has been fully implemented and committed to quotaholder, |
|
241 |
and all its memberships are also synchronized. |
|
242 |
|
|
243 |
The alive project loses its synchronization on two occasions. |
|
244 |
On the approval of a new application modifying the project, |
|
245 |
and on the addition or removal of any of its memberships. |
|
246 |
|
|
247 |
In general, also considering projects under termination, |
|
248 |
a project is declared synchronized if and only if: |
|
249 |
|
|
250 |
- ``last_application_synced`` equals ``application`` |
|
251 |
- ``membership_updated`` is false |
|
252 |
- ``termination_start_date`` is null or ``termination_date`` is set |
|
253 |
|
|
254 |
Depending on which of the previous three clauses fail, |
|
255 |
a synchronizing process knows what to do: |
|
256 |
definition, membership, or termination and combinations. |
|
257 |
|
|
258 |
8. **Unique project names** |
|
259 |
|
|
260 |
The project name (as specified in its application's definition) |
|
261 |
must be unique among all *alive* projects. |
|
262 |
|
|
263 |
9. **Inconsistent dates** |
|
264 |
|
|
265 |
If either ``creation_date`` or ``last_approval_date`` |
|
266 |
is in the future, the project state is declared **inconsistent** |
|
267 |
but the project is still considered created or approved, respectively. |
|
268 |
|
|
269 |
If ``termination_date`` is in the future, the project state is declared |
|
270 |
**inconsistent** but the project is still considered terminated. |
|
271 |
|
|
272 |
10. **No project without application** |
|
273 |
|
|
274 |
A project can only exist in reference of the application that has defined it. |
|
275 |
The attributes in the definition such as its name, resource grants |
|
276 |
cannot be modified without a new application that must be approved. |
|
277 |
|
|
278 |
11. **Creating and modifying projects with follow-up applications** |
|
279 |
|
|
280 |
Every application for a project can be followed up with another one. |
|
281 |
The new application points back to it with its ``precursor`` attribute. |
|
282 |
|
|
283 |
This means that an applicant can update their application |
|
284 |
before it has been approved. |
|
285 |
|
|
286 |
Apart from an applicant, whoever can approve the project, |
|
287 |
can also post a follow up application for it, modifying |
|
288 |
some aspects of the definition and approve that instead. |
|
289 |
For example, a user might request for 100 GB storage, |
|
290 |
but the Service may approve a project with only 80GB, |
|
291 |
via a follow up application. |
|
292 |
|
|
293 |
If the precursor of an application is not associated with a project |
|
294 |
(i.e. no project references it as its defining ``application``), |
|
295 |
then a new project entry is created and initialized. |
|
296 |
|
|
297 |
If the precursor of an application *is* associated with a valid project, |
|
298 |
then the same project entry is used and is re-initialized according |
|
299 |
to the new application's definition. |
|
300 |
The project is made alive (if terminated) and its previous state |
|
301 |
is maintained (mainly, the member set). |
|
302 |
If the new definition causes the project to exceed its limits, |
|
303 |
it will be suspended as required. |
|
304 |
|
|
305 |
|
|
306 |
|
|
307 |
Procedures |
|
308 |
---------- |
|
309 |
|
|
310 |
The following procedures are considered essential primitives |
|
311 |
for the function of the Projects feature, and should constitute |
|
312 |
a natural *internal* API to it. This is not a public API for users, |
|
313 |
although the public one should be thinly layered on top of it. |
|
314 |
|
|
315 |
For quotaholder interactions, a primitive to synchronize quotaholder |
|
316 |
with a user's resource quotas is assumed to be available. |
|
317 |
|
|
318 |
#. Submit an application |
|
319 |
|
|
320 |
Every user might submit an application to create or modify a project. |
|
321 |
There are no inherent constraints. |
|
322 |
However, policy may impose restrictions. |
|
323 |
|
|
324 |
#. Retrieve applications |
|
325 |
|
|
326 |
Applications should be retrievable by serial, by applicant, |
|
327 |
and by approval status. |
|
328 |
Because applications are immutable, some kind of extra state |
|
329 |
is needed in order to index by approval status. |
|
330 |
For example, one might instantiate a mutable object for approval state, |
|
331 |
with attributes (``approval_serial``, ``approval_state``, ``approval_data``) |
|
332 |
|
|
333 |
#. Approve an application (create or modify a Project) |
|
334 |
|
|
335 |
Application approval must atomically perform and commit all of the following: |
|
336 |
- create or modify the project at its specified definition |
|
337 |
- set the project state to be pending synchronization with quotaholder |
|
338 |
|
|
339 |
After committing, the procedure to synchronize the project (see below) |
|
340 |
should be called. |
|
341 |
|
|
342 |
#. Retrieve projects |
|
343 |
|
|
344 |
Projects should be retrievable by serial, by owner, |
|
345 |
by application, by life status, and by synchronization status. |
|
346 |
|
|
347 |
*By application* means that given an application, one must be able |
|
348 |
to retrieve the project that has it approved, if any. |
|
349 |
|
|
350 |
#. Add or remove a user to a project |
|
351 |
|
|
352 |
When a new membership is created for a project or |
|
353 |
an existing one is modified, then in the same |
|
354 |
transaction the project must be declared *unsynchronized*. |
|
355 |
|
|
356 |
#. Suspend a project |
|
357 |
|
|
358 |
A project is suspended by setting ``last_approval_date`` to None |
|
359 |
|
|
360 |
#. Terminate a project |
|
361 |
|
|
362 |
Project termination must atomically perform and commit all of the following: |
|
363 |
- set the project ``termination_start_date`` |
|
364 |
- set the ``termination_date`` to null (this is a redundant safeguard) |
|
365 |
in order to mark the project as pending termination synchronization. |
|
366 |
|
|
367 |
After committing, the procedure to synchronize the project (see below) |
|
368 |
should be called. |
|
369 |
|
|
370 |
#. Synchronize a membership with quotaholder |
|
371 |
|
|
372 |
This procedure is not required to be an independent procedure |
|
373 |
available for individual memberships. |
|
374 |
That is, if user synchronization takes care of all memberships, |
|
375 |
one can call user synchronization instead of membership synchronization. |
|
376 |
|
|
377 |
#. Synchronize a user with quotaholder |
|
378 |
|
|
379 |
User synchronization is equivalent to the synchronization of |
|
380 |
all the user's memberships. |
|
381 |
|
|
382 |
#. Synchronize a project with quotaholder |
|
383 |
|
|
384 |
Project synchronization is equivelent to the synchronization of |
|
385 |
either all its memberships, or all its members. |
|
386 |
|
|
387 |
|
|
388 |
|
|
389 |
View elements |
|
390 |
------------- |
|
391 |
In this context, view elements refer to (at best effort) self-contained |
|
392 |
elements that display information for and offer interaction with their |
|
393 |
underlying objects. A final view, such as a web page, or console command |
|
394 |
output, may include several elements. |
|
395 |
|
|
396 |
Interaction with the feature is going through several view elements. |
|
397 |
Each element has two pieces of input, |
|
398 |
the *objects being referenced*, and the *accessing user*, |
|
399 |
and its appearance and function is accordingly parametrized. |
|
400 |
|
|
401 |
Each *project element* may need to display information |
|
402 |
that internally belongs to its linked object, |
|
403 |
such as its *definition* or *memberships*. |
|
404 |
|
|
405 |
A proposed list of elements is following. |
|
406 |
The elements are only considered building blocks |
|
407 |
for views and not full views by themselves. |
|
408 |
More on views later on. |
|
409 |
|
|
410 |
#. Project list element |
|
411 |
|
|
412 |
This represents a list of *projects.* |
|
413 |
Technically, most of information about a project resides in its *application*. |
|
414 |
|
|
415 |
In the case of a *pending application*, |
|
416 |
one that has not been approved yet, |
|
417 |
then the row is filled with data from the |
|
418 |
current (approved and effective) application, |
|
419 |
or they are left blank if no such project exists yet. |
|
420 |
|
|
421 |
Additionally, the column that displays the pending status |
|
422 |
of the project (creation or modification), should be a link |
|
423 |
to the corresponding application detail element. |
|
424 |
|
|
425 |
#. Membership element |
|
426 |
|
|
427 |
A list of project members for a single (or maybe multiple) projects. |
|
428 |
The list must not display user emails if the viewer is not the owner |
|
429 |
of the group, or a service administrator. |
|
430 |
|
|
431 |
#. Application details element |
|
432 |
|
|
433 |
Displays all application details in full, |
|
434 |
with a link to the (alive) project it defines, if any, |
|
435 |
or a pending notice, |
|
436 |
or an obsolescence note if the project it defined was since modified, |
|
437 |
or a rejection notice. |
|
438 |
|
|
439 |
#. Project details element |
|
440 |
|
|
441 |
This element contains both details for the defining application |
|
442 |
and for the current state of the project. |
|
443 |
|
|
444 |
Details for the current state of the project may include |
|
445 |
statistics on membership and resource usage. |
|
446 |
|
|
447 |
#. Application form element |
|
448 |
|
|
449 |
It submits a new application. |
|
450 |
If the application is in reference |
|
451 |
to previous application (the ``precursor``) |
|
452 |
then the form should be initialized to be a copy of it. |
|
453 |
|
|
454 |
Otherwise, it may be blank, or initialized with defaults from a template. |
|
455 |
|
|
456 |
#. Project search element |
|
457 |
|
|
458 |
This is an entry point to a listing, with configurable filtering. |
|
459 |
|
|
460 |
#. History and statistics view |
|
461 |
|
|
462 |
No specification currently. |
|
463 |
|
Also available in: Unified diff