Provide information about desired property changes which could not be applied

[thjaeckle]

As an enhancement of #696 for the case that a device could not apply the "desiredProperties" state of a property to its actual state, the device shall send that "unable to apply desired state" information back to Ditto.

• sync-state revision number of desired property information is "piggy backed" as part of a normal command as "put-metadata": {"key": "/desiredSyncRevision", "value": 42}
• sync-state metadata information is "piggy backed" as part of a normal command as "put-metadata": {"key": "/desiredSyncState", "value": "applied"}
  • 1st option: the desired change could be "applied"
  • 2nd option: it is still trying to apply the desired state: "pending-application"
  • 3rd option: it is impossible as the desired property is not processable "not-applicable"
  • in addition, e.g. for the 3rd option, a metadata "desiredSyncStateDetails" is optionally provided
    • should be filled by the device itself
• persist that information as part of the _metadata section introduced in Support for adding arbitrary _metadata for features / properties #680
• emit as part of a "normal" change event so that a backend application which set that "desired" property may react on that

Implementation details

As suggested in #680 this sync-state metadata information is "piggy backed" as part of a normal command, e.g.:

{
  "topic": "org.eclipse.ditto/my-thermostat-1/things/twin/commands/modify",
  "headers": {
    "put-metadata": [
      {
        "key": "/desiredSyncRevision",
        "value":  42
      },
      {
        "key": "/desiredSyncState",
        "value":  "not-applicable"
      },
      {
        "key": "/desiredSyncStateDetails",
        "value":  "invalid target range"
      },
    ]
  },
  "path": "/features/Thermostat/properties/configuration/target-temperature",
  "value": 20.0
}

The _metadata structure would look like:

{
  "thingId": "org.eclipse.ditto:my-thermostat-1",
  "policyId": "...",
  "features": {
    "Thermostat": {
      "properties": {
        "configuration": {
          "target-temperature": 20.0
        }
      },
      "desiredProperties": {
        "configuration": {
          "target-temperature": 50.0
        }
      }
    }
  },
  "_modified": "2020-06-09T14:30:00Z",
  "_revision": 44,
  "_metadata": {
    "policyId": {
      "_modified": "2020-06-09T14:00:00Z",
      "_revision": 1
    },
    "features": {
      "Thermostat": {
        "properties": {
          "configuration": {
            "target-temperature": {
              "_modified": "2020-06-09T14:35:00Z",
              "_revision": 44,
              "desiredSyncRevision": 42,
              "desiredSyncState": "not-applicable",
              "desiredSyncStateDetails": "invalid target range"
            }
          }
        },
        "desiredProperties": {
          "configuration": {
            "target-temperature": {
              "_modified": "2020-06-09T14:30:00Z",
              "_revision": 42
            }
          }
        }
      }
    }
  }
}