root / snf-astakos-app / docs / projects_specs.rst @ dfbf5c50
History | View | Annotate | Download (15.3 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 |
|
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 declared 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 parameterized. |
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 |
|