diff --git a/docs/developer/data-plane-signaling/data-plane-signaling.md b/docs/developer/data-plane-signaling/data-plane-signaling.md index e423bca4421..4eb1ccf01e7 100644 --- a/docs/developer/data-plane-signaling/data-plane-signaling.md +++ b/docs/developer/data-plane-signaling/data-plane-signaling.md @@ -41,7 +41,13 @@ The data plane access token may be renewable based on the capabilities of its as All requests must support idempotent behavior. Data planes must therefore perform request de-duplication. After a data plane commits a request, it will return an ack to the control plane, which will transition the `TransferProcess` to its next state (e.g., `STARTED`, `SUSPENDED`, `TERMINATED`). If a successful ack is not received, the control plane will resend the request during a subsequent tick period. -##### 1. `START` +#### Message Types + +The message primitives of the DPS which get usually get sent by the Control Plane (CP) are `START`, `SUSPEND` and `TERMINATE`, whereas the Data planes are sending `RESPONSE` and common HTTP `OK` messages to the CP while interacting. The respective message classes can be found under the [transfer package](../../../spi/common/core-spi/src/main/java/org/eclipse/edc/spi/types/domain/transfer) and are displayed in the following diagram. + +![](signaling_protocol_messages.png) + +###### 1. `START` During the transfer process `STARTING` phase, a data plane will be selected by the default push and pull `DataFlowControllers`, which will then send a `DataFlowStartMessage` (renamed from `DataFlowRequest`) to the data plane. @@ -51,14 +57,24 @@ 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` +###### 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` +###### 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. +###### 4. `RESPONSE` + +After receiving a `START` message by the CP using a `FlowType` of `PUSH`, the data plane acknowledges the received message by sending a `RESPONSE` message. + +#### Internal State Machine + +Receiving or sending messages as part of the DPS usually results in an update of the internal state machines of the respective interacting components. As using the EDC Data Plane Framework requires a deep understanding of how the internal state machine is updated in what way and what actions are triggered by an update, the following diagram illustrates that. + +![](signaling_protocol_states.png) + ## II. Control Plane Refactoring ### 1. DataAddress and Token Generation diff --git a/docs/developer/data-plane-signaling/signaling_protocol_messages.png b/docs/developer/data-plane-signaling/signaling_protocol_messages.png new file mode 100644 index 00000000000..6d6b1ce48c0 Binary files /dev/null and b/docs/developer/data-plane-signaling/signaling_protocol_messages.png differ diff --git a/docs/developer/data-plane-signaling/signaling_protocol_messages.puml b/docs/developer/data-plane-signaling/signaling_protocol_messages.puml new file mode 100644 index 00000000000..cd805dde84c --- /dev/null +++ b/docs/developer/data-plane-signaling/signaling_protocol_messages.puml @@ -0,0 +1,32 @@ +@startuml +!theme vibrant +top to bottom direction +skinparam linetype ortho + +class DataFlowResponseMessage { + dataAddress: DataAddress +} +class DataFlowStartMessage { + id: String + processId: String + assetId: String + participantId: String + agreementId: String + sourceDataAddress: DataAddress + destinationDataAddress: DataAddress + flowType: FlowType + callbackAddress: URI + properties: Map + traceContext: Map +} +class DataFlowSuspendMessage { + reason: String +} +class DataFlowTerminateMessage { + reason: String +} +enum FlowType { + PUSH + PULL +} +@enduml \ No newline at end of file diff --git a/docs/developer/data-plane-signaling/signaling_protocol_states.png b/docs/developer/data-plane-signaling/signaling_protocol_states.png new file mode 100644 index 00000000000..90f2c4659bb Binary files /dev/null and b/docs/developer/data-plane-signaling/signaling_protocol_states.png differ diff --git a/docs/developer/data-plane-signaling/signaling_protocol_states.puml b/docs/developer/data-plane-signaling/signaling_protocol_states.puml new file mode 100644 index 00000000000..2414528561b --- /dev/null +++ b/docs/developer/data-plane-signaling/signaling_protocol_states.puml @@ -0,0 +1,51 @@ +@startuml + +skinparam WrapWidth 270 + +state "STARTED" as started_push #e6ebfa;line:blue +started_push: sent DataFlowResponseMessage, \nto CP starting transfer + +state "STARTED" as started_pull #e6ebfa;line:blue +started_pull: received DataFlowStartMessage by CP, waiting for data to be requested + +state "RECEIVED" as received #e6ebfa;line:blue +received : received DataFlowStartMessage by CP + +state "COMPLETED" as completed #e6ebfa;line:blue +completed: completed transfer successfully, trying to send OK to callback address (CP) + +state "NOTIFIED" as notified #e6ebfa;line:blue +notified : notified callback address (CP) about outcome + +state "FAILED" as failed #e6ebfa;line:blue +failed : trying to send TransferProcessFailRequest to callback address (CP) + +state "SUSPENDED / TERMINATED" as suspended #f5cccd;line:red +suspended : received SUSPEND / TERMINATE by CP + +[*] --> received +received --> started_push + +started_push --> failed +started_push --> completed + +failed --> failed +failed --> notified + +completed --> completed +completed --> notified + +notified --> [*] + +[*] --> started_pull +started_pull --> [*] + +received --> suspended +started_push --> suspended +started_pull --> suspended +failed --> suspended +completed --> suspended +notified --> suspended +suspended --> [*] + +@enduml