The EDC will be upgraded to implement and be fully compliant to the Dataspace Protocol Contract Negotiation Protocol. This document details the architectural approach that will be taken to support that protocol.
It is NOT a goal of the EDC project to provide backward compatibility to the previous IDS implementation. At a declared milestone, once the Dataspace Protocol implementation has reached a sufficient maturity level, the EDC will switch to the new protocol and remove the old protocol implementation. Users will be responsible for migrating existing EDC installations as no automated migration facilities will be provided.
The goals of the Dataspace Protocol support are:
- To be compliant with the Dataspace Protocol Contract Negotiation Protocol. This will involve passing all mandatory tests of the to-be-released IDS Test Compatibility Kit (IDS-TCK).
- To support a range of requirements involving externally assisted contract negotiation decisions. These include manual negotiation approval and integration with external systems to determine state transitions.
- To support integration with facilities for producing digital contract signatures and contract non-repudiation.
The IDS Specification Contract Negotiation states are:
- INITIALIZED,
- REQUESTED,
- OFFERED,
- ACCEPTED,
- AGREED,
- VERIFIED,
- FINALIZED,
- TERMINATED
The following table defines the mapping between existing EDC states, the corresponding new EDC states, and the IDS specification states.
EDC Existing | EDC New | IDS | Transition Function | Notes |
---|---|---|---|---|
UNSAVED | (remove) | N/A | This state is not needed | |
INITIAL | INITIAL | N/A | ||
REQUESTING | REQUESTING | N/A | ||
REQUESTED | REQUESTED | REQUESTED | Provider (new & counter) | |
PROVIDER_OFFERING | OFFERING | N/A | ||
PROVIDER_OFFERED | OFFERED | OFFERED | Consumer | |
CONSUMER_OFFERING | (REQUESTING) | |||
CONSUMER_OFFERED | (REQUESTED) | |||
CONSUMER_APPROVING | ACCEPTING | N/A | ||
CONSUMER_APPROVED | ACCEPTED | ACCEPTED | Provider | |
DECLINING | (TERMINATING) | |||
DECLINED | (TERMINATED) | |||
CONFIRMING | AGREEING | N/A | ||
CONFIRMED | AGREED | AGREED | Consumer | |
VERIFYING | N/A | |||
VERIFIED | VERIFIED | Provider | ||
FINALIZING | N/A | |||
FINALIZED | FINALIZED | Consumer | ||
TERMINATING | N/A | |||
TERMINATED | TERMINATED | P & C | ||
ERROR | (TERMINATED) |
State transition functions (StateTransitionFunction
) can be registered at specific callback points which are responsible for transitioning the Contract Negotiation State Machine
(CNSM) to a new state. These functions can be used to implement custom workflows. In runtime configurations that support it, transition functions will be called transactionally as
part of the ContractNegotiationManager
process loop. This will ensure state transitions are atomic.
StateTransitionFunction
will operate on ContractNegotiation
instances.
@FunctionalInterface
public interface StateTransitionFunction {
Result<Boolean> process(ContractNegotiation negotiation);
}
Note this does not follow immutability principles but has the advantage of simplicity and the ability to enforce proper state transitions in the ContractNegotiation
instance.
The Result<Boolean>
response indicates if the ContractNegotiation
has been updated (true) or not (false), or if processing failed. This can be used to avoid
re-persisting ContractNegotiation
instances if they have not changed.
End users will be able to register their own StateTransitionFunction
implementations to provide custom contract negotiation workflows. For example, a StateTransitionFunction
implementation can be registered to be invoked when a consumer request is received (REQUESTED) to support manual approval. The function will be called by
the ConsumerContractNegotiationManager
during its processing loop. If the request initiates a new negotiation, the function implementation could trigger a process in an external
approval system. In a subsequent processing loop, the StateTransitionFunction
could check for the completion of the external approval process (e.g. by querying a column in a
table) and updating the ContractNegotition
.
The following tabled define the default StateTransitionFunction
s to use if one is not registered for the specified state transition.
State | Default StateTransitionFunction |
---|---|
OFFERED | Transition to ACCEPTING if offer matches the original requested |
AGREED | Transition to VERIFYING |
FINALIZED | No-op |
State | Default StateTransitionFunction |
---|---|
REQUESTED | For the initial request transition to AGREED if the offer corresponds to a |
provider offer and the consumer evaluates successfully against the offer policy. | |
ACCEPTED | Transition to AGREEING |
VERIFIED | Transition to FINALIZING |
TERMINATED | No-op |
The EDC provides the ability to extend the runtime via HTTP endpoints, for example, HTTP provisioning. A similar method should be added for state transitions where an HTTP endpoint
can implement processing logic for one of the defined StateTransitionFunction
extension points. In addition to invoking an external endpoint, the EDC runtime will need to provide
an HTTP REST controller to serve as a callback for receiving updated ContractNegotiation
instances.
The controller may use the command infrastructure to update a received ContractNegotiation
. However, since the command infrastructure relies on an in-memory queue, updates will
not be reliable. Three options for addressing this are:
- Make the in-memory queue reliable and persistent. This option is likely to be the most complicated and difficult to achieve as it will require persistence and the ability to perform message ordering.
- Introduce a persistence mechanism for storing intermediate state machine results including
ContractNegotiation
andTransferProcess,
and updates them using the command infrastructure in a reliable way (e.g. removing entries once the command processing has been completed). This is still a complicated solution but has the advantage of using the command infrastructure as a single point for external state machine updates. - Introduce a lock-based synchronous update mechanism for state machine instances including
ContractNegotiation
andTransferProcess
instances that bypasses the command queue. This approach has the advantage of relative simplicity but introduces an additional code path for external state machine updates.
A generic solution should be designed which can be used by other extensions such as the HTTP provisioner to provide reliability guarantees.
Note that this feature will also be required for supporting reliable callbacks when a transfer is complete and when a transfer has been suspended.