CPS Delta Feature

Note: The feature is still in planning phase. The following page will evolve over time. Might add subpages as well.

Decisions Table

Introduction

The CPS Delta feature is proposed as a new feature to the existing functionalities of CPS. The main idea behind it being is to have the ability to find the delta between two configurations stored in CPS DB.

The Delta feature focuses on two main functionalities:

• • Compare the delta between the configurations stored in two anchors within the same dataspace.
  • Compare the configuration stored under an anchor against an incoming payload.
• The primary focus of the feature is to calculate the difference between the JSON configurations, irrespective of the schema set. 
• So, the feature will technically allow the user to find the delta between two configurations that belong to two different schema sets.
• The calculated differences can then be used to generate a delta report which can be sent over the Kafka Notification Service to the user.

Implementation Ideas

The design of the proposed feature is yet to be finalized. But here are a few ideas to start with:

• The feature can be developed as a microservice that sits alongside CPS 
• We can expose new endpoints for the feature, wherein the new endpoints can:
  • accept two anchor names (irrespective of their schema) and generate a delta report of the JSON data stored in both the anchors
  • for comparing an anchor to a payload, we can expose a second endpoint that takes one anchor and raw jSON data as input to generate the delta report or the first endpoint can be used to send the JSON as payload
    • in order to to achieve this the second anchor can be defined as an optional parameter in the request
• the possibility of including the delta feature as a part of existing API's can also be explored. 
• The feature will only support generating the delta for anchors within the same dataspace.

Use cases

There can be many use cases for the Delta feature. Some of which are discussed below:

• The delta feature can be used to compare the configuration of two nodes on a network over time (for example configuration changes over days). This can then be used
  • to identify the cause of configuration change
  • and if the configuration change causes any problems, the delta report can help identify the issue.
• A reference configuration can be stored in an anchor, and a copy/snapshot of this reference configuration can then be further modified by other users. Hence the user will always have a reference configuration which they can be sure of is free of any known issues.
  The delta of the reference configuration and modified configuration can then be used to rectify problems with a node configuration.
  
  • If the changes to the configuration lead to any problems, the users can generate the delta to identify the problems and if required the users can fix the issues with configuration changes or rollback the changes to the reference configuration.
• It can even be used to monitor unwanted deviations in some configuration values. 
• Configuration from one node can be used to deploy other nodes. Or as stated above a reference configuration can be used to deploy multiple different nodes.

API Implementation

RESTful API implementation proposed as below to find out delta configuration between two anchors for a given dataspace, cps-path and descendants. 

API : GET http://localhost:8080/v2/{dataspace-name}/anchors/{anchor-name}/delta?xpath={xpath}&descendants={descendants}?compareWithAnchor={anchor-name}

Request parameters:

Response Body: Response body should contain anchors delta report (added/deleted/modified configuration) as below.

[
{"action": "ADD", "xpath":"/bookstore/categories/[@code=3]", "payload":{"code":3,"name":"kidz"}},
{"action": "DELETE", "xpath":"/bookstore/categories/[@code=1]", "payload":{"code":1,"name":"Fiction"}},
{"action": "UPDATE", "xpath":"/bookstore/categories/[@code=2]", "payload":{"name":"Comic"}}
]

Points from initial discussion

• the feature sounds similar to the functionality for Temporal.
  • but temporal receives the full configuration of the anchor after an update, instead of the delta of two configurations.

Open Questions

• Can the functionality be expanded to anchors within different dataspaces?
• will the delta report be generated only between the latest configuration change and the reference configuration?
  • or should the delta report be generated automatically for all the configuration changes between time T₀ and Tn?
    • this would require an automated mechanism that would trigger the delta report generation every time there is a configuration change.