refactor: reflect implementation choices in AEP3 (#41)

AEP/aep-00003.md

@@ -33,116 +33,50 @@ Deleting all the data at the right time is crucial for the effective usage of re
 
 1. The session is created with the status Open. Results can be added to the session and tasks can be submitted to the session.
 2. The session can be paused and resumed. When the session is paused, running tasks continue to run until completion but submitted tasks are removed from the queue and are not executed. Running tasks can still submit subtasks but they will not be inserted into the queue thus not being executed. When the session is resumed, tasks that can be submitted (dependencies resolved) are inserted into the queue. Tasks execution will resume.
-3. Terminating a session means that no new tasks will be submitted from the client side of the application. Tasks are still able to submit new tasks that will be executed.
-4. Pausing the termination of a session has one additional consequence relatively to terminating a session: in addition to preventing the client from submission, running tasks are not able to submit new tasks and submitted tasks are removed from the queue.
-5. Unpausing the termination of a session means that we will allow again running tasks to submit new tasks and readd them to the queue. But the client is always unable to submit. So these two actions of pause/unpause the termination of a session does not affect the prevention of submission from the client.
-6. Closing session will prevent task submission from client and tasks. Running tasks can finish and produce results but not submit new tasks. An option is available to cancel running tasks; these tasks will not run up to completion and will not be able to produce results.
-7. Delete a session will trigger lazy removing of data related to a session such as tasks payloads, data dependencies and outputs in the case where these data are still here. What we mean by lazy is that when a session is deleted, data is not necessarily removed instantly, but soon (in a reasonably short time). Tasks, Data and Sessions metadata will not be removed at this step for accounting purposes: we may need to take advantage from the metrics in the metadata so we may need to keep them for some additional time.
-8. Metadata are removed when they exceed their configured Time To Live.
+3. In a session, tasks submission from the client and/or the worker can be disabled. In which, case errors will be produced during task submission.
+4. Closing session will prevent task submission from client and tasks. Running tasks can finish and produce results but not submit new tasks.
+5. A session can be cancelled. It will also cancel running tasks; these tasks will not run up to completion and will not be able to produce results.
+6. Purge a session will trigger removing of data related to a session such as tasks payloads, data dependencies and outputs in the case where these data are still here. Tasks, Data and Sessions metadata will not be removed at this step for accounting purposes: we may need to take advantage from the metrics in the metadata so we may need to keep them for some additional time.
+7. Delete a session remove all metadata related to session including Sessions, Tasks and Result metadata.
 
 The following state diagram summarizes the worflow of a session.
 
 ```mermaid
 stateDiagram-v2
-    EOS: End of Submission
-    PEOS: Pause End of Submission
     [*] --> Open : create
     Open --> Pause : pause
     Pause --> Open : resume
-    Open --> EOS : terminate
+    Pause --> Cancelled : resume
     Open --> Closed : close
+    Open --> Cancelled : cancel
     Pause --> Closed : close
-    Pause --> PEOS : terminate
-    EOS --> PEOS : pause
-    PEOS --> EOS : unpause
-    PEOS --> Closed : close
-    EOS --> Closed : close
-    Closed --> Deleted : delete data
-    Deleted --> [*] : delete metadata
+    Closed --> Purged : purge data
+    Cancelled --> Purged : purge data
+    Purged --> Deleted : delete metadata
 ```
 
 Note: If we pause a session, submitted tasks are removed from the queue. If after a short time from when we paused the session, we resume it, removing submitted tasks from the queue may not be finished yet, and resuming the session will cause insert the submitted tasks(that were supposed to be removed from the queue) into the queue. The consequence of pausing/resuming a session in a short time is to have duplicated messages in the queue. This may have an important impact on the performance of the system. Accordingly, this should be done with precaution. Or maybe we should handle it in the implementation of resume, if possible.
 
-## Statuses of a session
-
-A session can be found in one of the following statuses:
-
-1. Open
-2. Paused
-3. Terminated
-4. Closed
-5. Deleted
-
-As you may notice, pausing/unpausing the termination of a session does not figure in the above list of statuses. One suggestion is to have a flag called `enableSubTaskingInSessionTermination` associated with the status `Terminated` where:
-
-- `Session Status = Terminated` and `enableSubTaskingInSessionTermination = true` : when the termination of a session in unpaused, the default behavior of `Terminated` status.
-- `Session Status = Terminated` and `enableSubTaskingInSessionTermination = false` : when the termination of a session is paused.
-
-This flag is set to `false` when we want to pause the termination of a session and reset to `true` when we unpause it.
-
-The first clear drawback of this suggestion is that the flag name is too long, but it is difficult to have a name that represents the meaning this flag should carry without being so long.
-
-Instead of this suggestion, we may have another statuses to desribe the case when the termination is paused. Here is the full list of suggested statuses:
-
-1. Open
-2. Paused
-3. Terminated
-4. TerminationPaused
-5. Closed
-6. Deleted
-
-The drawbacks of this suggestion are:
-
-- the name is not very suitable: we can not say "a session is TerminationPaused".
-- the meaning of the status is not clear enough.
-
-The following sections will be based on the first suggestion : using a flag along with the five sessions statuses.
-
-The table below shows what impact will have each session status on the different parts:
-
-| Session Status                                                       | Task Submission by the client | Task Submission by the running tasks(subtasking)    |
-|----------------------------------------------------------------------|-------------------------------|-----------------------------------------------------|
-| Open                                                                 | Allowed                       | Allowed                                             |
-| Paused                                                               | Allowed but not submitted     | Allowed                                             |
-| Terminated with `enableSubTaskingInSessionTermination = true`        | Forbidden                     | Allowed                                             |
-| Terminated with `enableSubTaskingInSessionTermination = false`       | Forbidden                     | Forbidden                                           |
-| Closed                                                               | Forbidden                     | Forbidden                                           |
-| Deleted                                                              | Forbidden                     | Forbidden                                           |
-
 ## Proposed APIs
 
 ### Session services API
 
-```protobuf
-service SessionService {
-  rpc ListSessions(ListSessionsRequest) returns (ListSessionsResponse);
-  rpc GetSession(GetSessionRequest) returns (GetSessionResponse); 
-  rpc CreateSession(CreateSessionRequest) returns (CreateSessionResponse);
-  rpc TerminateSession(TerminateSessionRequest) returns (TerminateSessionResponse);
-  rpc PauseSession(PauseSessionRequest) returns (PauseSessionResponse);
-  rpc ResumeSession(ResumeSessionRequest) returns (ResumeSessionRequest);
-  rpc SetSubTaskingInTerminationFlag(SetSubTaskingInTerminationFlagRequest) returns (SetSubTaskingInTerminationFlagResponse);
-  rpc CloseSession(CloseSessionRequest) returns (CloseSessionResponse) ;
-  rpc DeleteSession(DeleteSessionRequest) returns (DeleteSessionResponse) ; 
-}
-```
-
-The first three methods are already available in the current services API, with the difference that `CreateSessionReply` will be renamed to  `CreateSessionResponse`. The current CancelSession method will be removed because it is more related to tasks than to sessions.
-
-The proposed service contains 9 RPC methods, each of them has a request message and a response message. In addition, each of the 9 services should have an error message that will be sent as response metadata when an error happened during the call. In total, we have 27 messages to define.
-
-Another solution could be to have one method that updates the state of a session:
-
 ```protobuf
 service SessionService {
   rpc ListSessions(ListSessionsRequest) returns (ListSessionsResponse);
   rpc GetSession(GetSessionRequest) returns (GetSessionResponse);
-  rpc CreateSession(CreateSessionRequest) returns (CreateSessionResponse);
-  rpc UpdateSessionStatus(UpdateSessionStatusRequest) returns (UpdateSessionStatusResponse);
+  rpc CancelSession(CancelSessionRequest) returns (CancelSessionResponse);
+  rpc CreateSession(CreateSessionRequest) returns (CreateSessionReply);
+  rpc PauseSession(PauseSessionRequest) returns (PauseSessionResponse);
+  rpc ResumeSession(ResumeSessionRequest) returns (ResumeSessionResponse);
+  rpc CloseSession(CloseSessionRequest) returns (CloseSessionResponse);
+  rpc PurgeSession(PurgeSessionRequest) returns (PurgeSessionResponse);
+  rpc DeleteSession(DeleteSessionRequest) returns (DeleteSessionResponse);
+  rpc StopSubmission(StopSubmissionRequest) returns (StopSubmissionResponse);
 }
 ```
 
-In this case, we will have 12 messages to define. But the implementation of this RPC method will be much more complex.
+The first three methods are already available in the current services API, with the difference that `CreateSessionReply` will be renamed to  `CreateSessionResponse`.
 
 ### Session messages API
 
@@ -160,22 +94,6 @@ message PauseSessionRequest {
 }
 ```
 
-We can have the same for the rest of new methods messages except the messages of `SetSubTaskingInTerminationFlag` method. Thus, it follows that with the first proposition of services API with 9 methods, there will be redundancy in the definitions of the messages.
-
-The `SetSubTaskingInTerminationFlagRequest` and `SetSubTaskingInTerminationFlagResponse` can be defined as follows:
-
-```protobuf
-message SetSubTaskingInTerminationFlagRequest{
-  string session_id = 1;
-  bool enable_subtasking_in_session_termination = 2;
-}
-message SetSubTaskingInTerminationFlagResponse {
-  SessionRawField session_field = 1; 
-}
-```
-
-The redundancy in the messages is avoided in the second suggestion where all the redundant messages definitions will be resumed to `UpdateSessionStatusRequest`  and `UpdateSessionStatusResponse`.
-
 An example of an error message:
 
 ```protobuf