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