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