Added first overhaul of states and messages. WIP

FraunhoferISST · Jul 2, 2024 · 16519d1 · 16519d1
1 parent c7c53de
commit 16519d1
Show file tree

Hide file tree

Showing 8 changed files with 180 additions and 58 deletions.
diff --git a/docs/developer/data-plane-signaling/data-plane-signaling-state-machine.png b/docs/developer/data-plane-signaling/data-plane-signaling-state-machine.png
diff --git a/docs/developer/data-plane-signaling/data-plane-signaling-state-machine.puml b/docs/developer/data-plane-signaling/data-plane-signaling-state-machine.puml
@@ -0,0 +1,64 @@
+'
+'  Copyright (c) 2024 Fraunhofer Institute for Software and Systems Engineering ISST
+'
+'  This program and the accompanying materials are made available under the
+'  terms of the Apache License, Version 2.0 which is available at
+'  https://www.apache.org/licenses/LICENSE-2.0
+'
+'  SPDX-License-Identifier: Apache-2.0
+'
+'  Contributors:
+'      Florian Zimmer - Initial Version
+'
+
+@startuml
+!define DscClr(x) <color:#7b839a>x</color>
+
+skinparam WrapWidth 270
+
+state "STARTED" as started_push #e6ebfa;line:blue
+started_push: DscClr(//trying to complete transfer process//)
+
+state "STARTED" as started_pull #e6ebfa;line:blue
+started_pull: DscClr(DataFlowStartMessage<PULL>)
+
+state "RECEIVED" as received #e6ebfa;line:blue
+received : DscClr(DataFlowStartMessage<PUSH>)
+
+state "COMPLETED" as completed #e6ebfa;line:blue
+completed: DscClr(//trying to send TransferProcessCompleteRequest to callback address (CP)//)
+
+state "NOTIFIED" as notified #e6ebfa;line:blue
+notified : DscClr(TransferProcessFailRequest //or// TransferProcessCompleteRequest)
+
+state "FAILED" as failed #e6ebfa;line:blue
+failed : DscClr(//trying to send TransferProcessFailRequest to callback address (CP)//)
+
+state "SUSPENDED / TERMINATED" as suspended #f5cccd;line:red
+suspended : DscClr(DataFlowSuspendMessage //or// DataFlowTerminateMessage)
+
+[*] --> received : CP
+received -[dashed]-> started_push
+
+started_push -[dashed]-> failed
+started_push -[dashed]-> completed
+
+failed --> failed
+failed --> notified : DP
+
+completed --> completed
+completed --> notified : DP
+
+notified --> [*]
+
+[*] --> started_pull : CP
+started_pull --> [*]
+
+received --> suspended : CP
+started_push --> suspended : CP
+started_pull --> suspended : CP
+failed --> suspended : CP
+completed --> suspended : CP
+notified --> suspended : CP
+suspended --> [*]
+@enduml
diff --git a/docs/developer/data-plane-signaling/data-plane-signaling.md b/docs/developer/data-plane-signaling/data-plane-signaling.md
@@ -51,14 +51,6 @@ For client pull transfers, the data plane will return a `DataAddress` and an acc
 
 If the data flow was previously `SUSPENDED`, the data plane may elect to return the same `DataAddress` or create a new one.
 
-##### 2. `SUSPEND` 
-
-During the transfer process `SUSPENDING` phase, the `DataFlowController` will send a `DataFlowSuspendMessage` to the data plane. The data plane will transition the data flow to the `SUSPENDED` state and invalidate the associated access token.
-
-##### 3. `TERMINATE`
-
-During the transfer process `TERMINATING` phase, the `DataFlowController` will send a `DataFlowTerminateMessage` to the data plane. The data plane will transition the data flow to the `TERMINATED` state and invalidate the associated access token.
-
 ### States
 
 The Data Plane Signaling protocol is represented by the following states:
@@ -75,83 +67,92 @@ The Data Plane Signaling protocol is represented by the following states:
 
 The Data Plane Signaling state machine can be seen in the following diagram:
 
+![](data-plane-signaling-state-machine.png)
+
 ### Message Types
 
+lorem ipsum
+
 #### DataFlowStartMessage
 
-| Message Type        | Start                                                          |
-|---------------------|----------------------------------------------------------------|
-| **Sent by**         | Control Plane                                                  |
-| **Resulting state** | `RECEIVED` or `STARTED` dependent on `FlowType` (Push or Pull) |
-| **Response**        | DataFlowResponseMessage                                        |
-| **Schema**          | JSON Schema                                                    |
-| **Example**         |                                                                |
-| **Diagram(s)**      |                                                                |
+| Message Type        | Start                                                              |
+|---------------------|--------------------------------------------------------------------|
+| **Sent by**         | Control Plane                                                      |
+| **Resulting state** | `RECEIVED` or `STARTED` dependent on the `FlowType` (Push or Pull) |
+| **Response**        | DataFlowResponseMessage                                            |
+| **Schema**          | JSON Schema                                                        |
+| **Example**         | [DataFlowStartMessage](./examples/DataFlowStartMessage.json)       |
+| **Diagram(s)**      |                                                                    |
 
-The lorem ipsum is sent to...
+Initiates the data flow by signaling the data plane to start the transfer process. Dependent on the `FlowType` the following things will happen:
+- `PUSH`: Data plane initiates transfer process and tries to complete it. Will notify Control Plane about the respective outcome after completion or failure.
+- `PULL`: Data plane returns callback address to pull the data from and an access token using a `DataFlowResponseMessage`.
 
 #### DataFlowSuspendMessage
 
-| Message Type        | Suspend       |
-|---------------------|---------------|
-| **Sent by**         | Control Plane |
-| **Resulting state** | `SUSPENDED`   |
-| **Response**        | -             |
-| **Schema**          | JSON Schema   |
-| **Example**         |               |
-| **Diagram(s)**      |               |
+| Message Type        | Suspend                                                          |
+|---------------------|------------------------------------------------------------------|
+| **Sent by**         | Control Plane                                                    |
+| **Resulting state** | `SUSPENDED`                                                      |
+| **Response**        | -                                                                |
+| **Schema**          | JSON Schema                                                      |
+| **Example**         | [DataFlowSuspendMessage](./examples/DataFlowSuspendMessage.json) |
+| **Diagram(s)**      |                                                                  |
 
-The lorem ipsum is sent to...
+Leads to the suspension of the data flow, thus stopping it and invalidating the associated access token. If the data flow was previously `SUSPENDED`, the data plane may elect to return the same `DataAddress` or create a new one.
 
 #### DataFlowTerminateMessage
 
-| Message Type        | Terminate     |
-|---------------------|---------------|
-| **Sent by**         | Control Plane |
-| **Resulting state** | `TERMINATED`  |
-| **Response**        | -             |
-| **Schema**          | JSON Schema   |
-| **Example**         |               |
-| **Diagram(s)**      |               |
+| Message Type        | Terminate                                                            |
+|---------------------|----------------------------------------------------------------------|
+| **Sent by**         | Control Plane                                                        |
+| **Resulting state** | `TERMINATED`                                                         |
+| **Response**        | -                                                                    |
+| **Schema**          | JSON Schema                                                          |
+| **Example**         | [DataFlowTerminateMessage](./examples/DataFlowTerminateMessage.json) |
+| **Diagram(s)**      |                                                                      |
 
-The lorem ipsum is sent to...
+Leads to the termination of the data flow, thus stopping it and invalidating the associated access token.
 
 ### Response Types
 
-lorem ipsum
+The response messages are either sent as a direct response to an incoming message or as an indirect response at a later stage during the transfer process.
 
 #### DataFlowResponseMessage
 
-| Message Type        | Response    |
-|---------------------|-------------|
-| **Sent by**         | Data Plane  |
-| **Schema**          | JSON Schema |
-| **Example**         |             |
-| **Diagram(s)**      |             |
+| Message Type        | Response                                                           |
+|---------------------|--------------------------------------------------------------------|
+| **Sent by**         | Data Plane                                                         |
+| **Resulting state** | `STARTED`                                                          |
+| **Schema**          | JSON Schema                                                        |
+| **Example**         | [DataFlowResponseMessage](./examples/DataFlowResponseMessage.json) |
+| **Diagram(s)**      |                                                                    |
 
-Gets sent by Data Plane to acknowledge a DataFlowStartMessage.
+This message is a direct response message to a DataFlowStartMessage and acknowledges receiving during a `PULL` transfer.
 
-#### TransferProcessComplete
+#### TransferProcessCompleteRequest
 
-| Message Type        | Response    |
-|---------------------|-------------|
-| **Sent by**         | Data Plane  |
-| **Schema**          | JSON Schema |
-| **Example**         |             |
-| **Diagram(s)**      |             |
+| Message Type        | Response                 |
+|---------------------|--------------------------|
+| **Sent by**         | Data Plane               |
+| **Resulting state** | `NOTIFIED`               |
+| **Schema**          | *None due to empty body* |
+| **Example**         | -                        |
+| **Diagram(s)**      | -                        |
 
-Gets sent by Data Plane in case transfer process is completed.
+This message is not a direct response to an incoming message. It rather gets sent by the Data Plane if the already started transfer process was successfully completed. Successfully sending this message leads to the transfer state machine to proceed to the state `NOTIFIED`.
 
 #### TransferProcessFailRequest
 
-| Message Type        | Response    |
-|---------------------|-------------|
-| **Sent by**         | Data Plane  |
-| **Schema**          | JSON Schema |
-| **Example**         |             |
-| **Diagram(s)**      |             |
+| Message Type        | Response                                                                 |
+|---------------------|--------------------------------------------------------------------------|
+| **Sent by**         | Data Plane                                                               |
+| **Resulting state** | `NOTIFIED`                                                               |
+| **Schema**          | JSON Schema                                                              |
+| **Example**         | [TransferProcessFailRequest](./examples/TransferProcessFailRequest.json) |
+| **Diagram(s)**      |                                                                          |
 
-Gets sent by Data Plane in case the transfer process could not be started or failed.
+This message is not a direct response to an incoming message. It rather gets sent by the Data Plane if the already started transfer process encountered an error, thus failed to be fulfilled. Successfully sending this message leads to the transfer state machine to proceed to the state `NOTIFIED`.
 
 ## II. Control Plane Refactoring
 

diff --git a/docs/developer/data-plane-signaling/examples/DataFlowResponseMessage.json b/docs/developer/data-plane-signaling/examples/DataFlowResponseMessage.json
@@ -0,0 +1,14 @@
+{
+  "@type": "https://w3id.org/edc/v0.0.1/ns/DataFlowResponseMessage",
+  "https://w3id.org/edc/v0.0.1/ns/dataAddress": {
+    "@type": "https://w3id.org/dspace/v0.8/DataAddress",
+    "https://w3id.org/dspace/v0.8/endpointType": "endpointType",
+    "https://w3id.org/dspace/v0.8/endpointProperties": [
+      {
+        "@type": "https://w3id.org/dspace/v0.8/EndpointProperty",
+        "https://w3id.org/dspace/v0.8/name": "name",
+        "https://w3id.org/dspace/v0.8/value": "value"
+      }
+    ]
+  }
+}
diff --git a/docs/developer/data-plane-signaling/examples/DataFlowStartMessage.json b/docs/developer/data-plane-signaling/examples/DataFlowStartMessage.json
@@ -0,0 +1,32 @@
+{
+  "@type": "https://w3id.org/edc/v0.0.1/ns/DataFlowStartMessage",
+  "https://w3id.org/edc/v0.0.1/ns/flowType": "PUSH",
+  "https://w3id.org/edc/v0.0.1/ns/agreementId": "agreementId",
+  "https://w3id.org/edc/v0.0.1/ns/processId": "processId",
+  "https://w3id.org/edc/v0.0.1/ns/datasetId": "datasetId",
+  "https://w3id.org/edc/v0.0.1/ns/properties": {},
+  "https://w3id.org/edc/v0.0.1/ns/callbackAddress": "http://localhost",
+  "https://w3id.org/edc/v0.0.1/ns/sourceDataAddress": {
+    "@type": "https://w3id.org/dspace/v0.8/DataAddress",
+    "https://w3id.org/dspace/v0.8/endpointType": "sourceType",
+    "https://w3id.org/dspace/v0.8/endpointProperties": [
+      {
+        "@type": "https://w3id.org/dspace/v0.8/EndpointProperty",
+        "https://w3id.org/dspace/v0.8/name": "name",
+        "https://w3id.org/dspace/v0.8/value": "value"
+      }
+    ]
+  },
+  "https://w3id.org/edc/v0.0.1/ns/participantId": "participantId",
+  "https://w3id.org/edc/v0.0.1/ns/destinationDataAddress": {
+    "@type": "https://w3id.org/dspace/v0.8/DataAddress",
+    "https://w3id.org/dspace/v0.8/endpointType": "endpointType",
+    "https://w3id.org/dspace/v0.8/endpointProperties": [
+      {
+        "@type": "https://w3id.org/dspace/v0.8/EndpointProperty",
+        "https://w3id.org/dspace/v0.8/name": "name",
+        "https://w3id.org/dspace/v0.8/value": "value"
+      }
+    ]
+  }
+}
diff --git a/docs/developer/data-plane-signaling/examples/DataFlowSuspendMessage.json b/docs/developer/data-plane-signaling/examples/DataFlowSuspendMessage.json
@@ -0,0 +1,4 @@
+{
+  "@type": "https://w3id.org/edc/v0.0.1/ns/DataFlowSuspendMessage",
+  "https://w3id.org/edc/v0.0.1/ns/reason": "reason"
+}
diff --git a/docs/developer/data-plane-signaling/examples/DataFlowTerminateMessage.json b/docs/developer/data-plane-signaling/examples/DataFlowTerminateMessage.json
@@ -0,0 +1,4 @@
+{
+  "@type": "https://w3id.org/edc/v0.0.1/ns/DataFlowTerminateMessage",
+  "https://w3id.org/edc/v0.0.1/ns/reason": "reason"
+}
diff --git a/docs/developer/data-plane-signaling/examples/TransferProcessFailRequest.json b/docs/developer/data-plane-signaling/examples/TransferProcessFailRequest.json
@@ -0,0 +1,3 @@
+{
+  "errorMessage": "errorMessage"
+}