From 48ae4dc1188ef4c2ac73df68496e148791b5444b Mon Sep 17 00:00:00 2001 From: Cristian Recoseanu Date: Tue, 21 Jan 2025 14:06:39 +0000 Subject: [PATCH] Update Backup & restore.md And add clarifications and tweaks to the conformance language --- docs/Backup & restore.md | 120 +++++++++++++++++++-------------------- 1 file changed, 57 insertions(+), 63 deletions(-) diff --git a/docs/Backup & restore.md b/docs/Backup & restore.md index 2fba645..ddcc023 100644 --- a/docs/Backup & restore.md +++ b/docs/Backup & restore.md @@ -11,8 +11,8 @@ The [Configuration API](https://specs.amwa.tv/is-14/branches/v1.0-dev/APIs/Confi These mechanisms are used for enabling backup and restore functionality and this section of the specification aims to cover the expectations, behaviour and requirements for the following scenarios: - [Performing a backup](#performing-a-backup) -- Restoring a full backup data set to a [dynamic device after a faulty unit is replaced with an identical spare](#restoring-a-full-backup-data-set-to-a-dynamic-device-after-a-faulty-unit-is-replaced-with-an-identical-spare) -- Restoring a full backup data set to a [fixed device after a faulty unit is replaced with an identical spare](#restoring-a-full-backup-data-set-to-a-fixed-device-after-a-faulty-unit-is-replaced-with-an-identical-spare) +- Performing a [Modify restore](#performing-a-modify-restore) +- Performing a [Rebuild restore](#performing-a-rebuild-restore) `Note`: This does not mean that the backup & restore functionality can only be used in these scenarios. @@ -42,11 +42,19 @@ A `modified backup` is a `full backup` or `partial backup` where the backup data ## General concepts -Role path objects within a backup data set contain a boolean property called `isRebuildable`. If the object is a non-block object `isRebuildable` means the object can be reconstructed (constructing a fresh object which can accept changes even to its readonly properties). If the object is a block, `isRebuildable` depicts it can be reconstructed as mentioned in the statement before but also that its members can be added or removed. When a parent block object is not rebuildable but a member child is rebuildable the implication is that the child cannot change its role within that block when being rebuilt through a restore. +Role path objects within a backup data set contain a boolean property called `isRebuildable`. +If the object is a non-block object `isRebuildable` means the object's readonly properties can be modified. +If the object is a block, `isRebuildable` depicts it can be modified as mentioned before but also that its members can be added or removed (new instances of rebuildable objects can be created in a rebuildable parent block). +When a parent block object is not rebuildable but a member child is rebuildable the implication is that the child cannot change its role within that block when being rebuilt through a restore. +Members of a rebuildable block which are not rebuildable cannot be removed. + +and new instances of that object can be created in a rebuildable parent block. The restore mechanism achieved by [Setting bulk properties for a role path](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#setting-bulk-properties-for-a-role-path) affects the device model by either rebuilding it or modifying it. -A restore with the restore mode set to `Modify` MUST only be allowed to make changes to existing writeable properties of existing device model objects and MUST NOT modify the device model in a structural way (cannot cause the addition or removal of objects from blocks). +Validating a restore operation before applying it is achieved by [Validating bulk properties for a role path](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#validating-bulk-properties-for-a-role-path). Implementations MUST perform the same checks and offer the same response as if the restore was being applied without actually performing changes to the device model objects. + +A restore with the restore mode set to `Modify` MUST only be allowed to make changes to existing writeable properties of existing device model objects and MUST NOT modify the device model in a structural way (cannot cause the addition or removal of objects from blocks). Furthermore, devices are RECOMMENDED to evaluate a `Modify` restore (validate if the restore can happen) even when the backup data set contains readonly properties since writeable properties might result in the desired changes being applied and the readonly properties will result in notices in the response returned. A restore with the restore mode set to `Rebuild` MUST allow the following actions: @@ -55,20 +63,28 @@ A restore with the restore mode set to `Rebuild` MUST allow the following action - remove existing members from rebuildable block objects by deconstructing the member objects (structural changes) - reconstruct existing rebuildable objects (constructing fresh objects which can accept changes even to its readonly properties) -In the interest of interoperability even devices with no `rebuildable` device model objects MUST accept `Rebuild` restores but only perform the changes in scope for a `Modify` restore whilst including notices for any changes to readonly properties. Furthermore, performing a `Modify` restore MUST be possible even when the backup data set contains readonly properties since writeable properties will results in the desired changes being applied and the readonly properties will result in notices in the response returned. +`Rebuild` restores can perform structural changes against rebuildable device models in the following ways: + +- an object can be removed from a rebuildable block when the backup data set used in the restore offers a collection of members for the block which does not include the object (the success of this operation MAY depend on the internal constraints of the device - some devices might have have some members which cannot be removed or a minimum number of members). +- an object can be added to a rebuildable block when the backup data set used in the restore offers a collection of members for the block which includes the new object and also includes a new entry for the role path of the new object with its properties (the success of this operation MAY depend on the internal constraints of the device - devices are likely to check whether the new object class and role can be added to the block, whether they have all the necessary information to construct the new object, and might even check against a maximum number of members). -The general pattern for how devices interpret the restore workflow can be explained as follows: +In the interest of interoperability even devices with no `rebuildable` device model objects MUST accept `Rebuild` restores but only perform changes to writeable properties of device model objects whilst including notices for any other changes not supported by the device. -- devices MUST always offer healthy objects in the device model after a restore -- devices MUST attempt to use the backup data set provided first as a pool of information for changing/constructing/deconstructing/reconstructing a particular role path object and if they have all the necessary data they MUST report the restore status as `Ok`. -- if the backup data set provided doesn't have the information required for changing/constructing/deconstructing/reconstructing a particular role path object, but the device can fill in the necessary gaps from an internal knowledge store, then they MUST report the restore status as `Ok` and include properties which have benefited from internal knowledge store data in the [notices](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncpropertyrestorenotice) property as `Warning` notices. -- if devices cannot find the required information for changing/constructing/deconstructing/reconstructing a particular role path object in either the backup data set provided or an internal knowledge store then they MUST return `Failed` as the restore status. +The rules for devices implementing the restore workflow are: + +- after a restore operation devices MUST always contain valid objects (objects which have suitable values for each property within the current operating context) in their device models +- a restore operation modifying/rebuilding an object can use information from the backup data set provided or from an internal knowledge store +- a restore operation modifying/rebuilding an object which uses only the backup data set information MUST report the role path restore status as `Ok` +- a restore operation modifying/rebuilding an object which uses internal knowledge store information MUST report the role path restore status as `Ok` and list properties which have benefited from internal knowledge store data in the [notices](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncpropertyrestorenotice) property as `Warning` notices +- if devices cannot find the required information for modifying/rebuilding a particular object in either the backup data set provided or an internal knowledge store, then they MUST report the role path restore status as `Failed` and also MUST populate the `statusMessage` property with details of why the operation failed. Devices MAY also populate [notices](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncpropertyrestorenotice) for the object properties which have contributed to the operation failing. +- a restore operation modifying/rebuilding an object resulting in at least one error [notice](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncpropertyrestorenotice) MUST report the role path restore status as `Failed` +- a restore operation modifying/rebuilding an object resulting only in warning [notices](https://specs.amwa.tv/nmos-control-feature-sets/branches/publish-device-configuration/device-configuration/#ncpropertyrestorenotice) MUST report the role path restore status as `Ok` ## Performing a backup Creating a backup is performed by using the `bulkProperties` endpoint of a device alongside the [Get verb](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#getting-all-the-properties-of-a-role-path). -In order to retrieve the whole device model (full backup), requests MUST use `root` as the `rolePath`. The response contains a `validationFingerprint` and the `values` of all the role paths in the device model. +In order to retrieve the whole device model (full backup), requests MUST use `root` as the `rolePath` and a `recurse` parameter with a value of `true`. The response contains a `validationFingerprint` and the `values` of all the role paths in the device model. | ![Performing a full backup](images/performing-full-backup.png) | |:--:| @@ -76,92 +92,70 @@ In order to retrieve the whole device model (full backup), requests MUST use `ro Partial backups can be created by choosing other role paths. The scope of backups can further be restricted by using a query parameter of `recurse=false` which will only include the properties of the targeted role path. -It is RECOMMENDED to store the backup file in its entirety and not remove elements from the data set as they might contain dependencies required by some of the role paths. - -## Restoring a full backup data set to a dynamic device after a faulty unit is replaced with an identical spare +`Note`: In some cases objects in a device model might have dependencies to other objects in the device model which could influence restore behaviour. -The following assumptions are made: +## Performing a Modify restore -- the spare device replacing the faulty unit is the same product type from the same vendor -- a [full backup](#performing-a-backup) has been created of the faulty unit when it was healthy -- the devices are dynamic containing rebuildable blocks and objects +The following sections describe how a `Modify` restore can be performed using a backup data set as detailed in [performing a backup](#performing-a-backup). -The first step is to perform a [Validation request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#validating-bulk-properties-for-a-role-path) to check if the backup data set can be successfully restored. +Clients are RECOMMENDED to [Validate the restore operation](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#validating-bulk-properties-for-a-role-path) before attempting to apply the changes. -In order to validate applying the whole backup data set against the device model, requests MUST use `root` as the `rolePath`. +In order to validate applying the full backup data set against the device model, requests MUST use `root` as the `rolePath`. The request body MUST include: - the backup dataSet -- a boolean `recurse` argument (set to `true` for validating the whole device model) -- the `restoreMode` argument (set to `Rebuild` in order to allow blocks to be repopulated with the same members as per the original device) - -| ![Validating a full backup](images/validating-full-backup.png) | -|:--:| -| _**Validating a full backup**_ | - -The response MUST include a collection of all target device model role paths with a validation `status` property and a `notices` array of property notices. For role paths which have a `status` which is not a 2XX value the response MUST also include a `statusMessage` with details of why the validation failed. When there are properties of role path objects which cannot be validated from the values provided in the dataset, these MUST be reported in the `notices` property as `Warning` notices. +- a boolean `recurse` argument (set to `true` for validating the entire device model) +- the `restoreMode` argument (set to `Modify` in order to only allow changes to writeable properties) -The backup can be restored by performing a [Set request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#setting-bulk-properties-for-a-role-path) to restore the backup. +A restore operation is performed through a [Set request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#setting-bulk-properties-for-a-role-path) to restore a backup data set. -In order to use the whole backup data set to restore against the device model, requests MUST use `root` as the `rolePath`. +In order to restore the full backup data set to the device model, the request MUST use `root` as the `rolePath`. The request body MUST include: - the backup dataSet -- a boolean `recurse` argument (set to `true` for validating the whole device model) -- the `restoreMode` argument (set to `Rebuild` in order to allow blocks to be repopulated with the same members as per the original device) - -| ![Restoring a full backup](images/restoring-full-backup.png) | -|:--:| -| _**Restoring a full backup**_ | - -The response MUST include a collection of all target device model role paths with a validation `status` property and a `notices` array of property notices. For role paths which have a `status` which is not a 2XX value the response MUST also include a `statusMessage` with details of why the restore failed. When there are properties of role path objects which cannot be restored from the values provided in the dataset, these MUST be reported in the `notices` property as `Warning` notices. +- a boolean `recurse` argument (set to `true` for validating the entire device model) +- the `restoreMode` argument (set to `Modify` in order to only allow changes to writeable properties) -If devices require a system reboot in order to apply the restore then they MUST perform this immediately after responding to the restore request. +If a device requires a system reboot in order to apply the restore then it MUST perform this immediately after responding to the restore request. -The diagram below captures how the `Rebuild` restore uses the backup data set to transition the spare device from its out of the box device model to a state of functionality identical to the original faulty device. +The diagram below captures how the `Modify` restore uses the backup data set to transition the device from its current device model to a changed state. -| ![Rebuild restore of spare](images/restoring_on_dynamic_spare.png) | +| ![Modify restore](images/modify-restore.png) | |:--:| -| _**Rebuild restore of spare**_ | +| _**Modify restore**_ | -## Restoring a full backup data set to a fixed device after a faulty unit is replaced with an identical spare +## Performing a Rebuild restore -The following assumptions are made: +Rebuild restores are the only way to make structural changes to a device model. Structural changes are only allowed for rebuildable blocks. -- the spare device replacing the faulty unit is the same product type from the same vendor -- a [full backup](#performing-a-backup) has been created of the faulty unit when it was healthy -- the devices are fixed containing no rebuildable blocks or objects +The following sections describe how a `Rebuild` restore can be performed using a backup data set as detailed in [performing a backup](#performing-a-backup). -The first step is to perform a [Validation request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#validating-bulk-properties-for-a-role-path) to check if the backup data set can be successfully restored. +Clients are RECOMMENDED to [Validate the restore operation](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#validating-bulk-properties-for-a-role-path) before attempting to apply the changes. -In order to validate applying the whole backup data set against the device model, requests MUST use `root` as the `rolePath`. +In order to validate applying the full backup data set against the device model, the request MUST use `root` as the `rolePath`. The request body MUST include: - the backup dataSet -- a boolean `recurse` argument (set to `true` for validating the whole device model) -- the `restoreMode` argument (set to `Modify` in order to only allow changes to writeable properties) - -The response MUST include a collection of all target device model role paths with a validation `status` property and a `notices` array of property notices. For role paths which have a `status` which is not a 2XX value the response MUST also include a `statusMessage` with details of why the validation failed. When there are properties of role path objects which cannot be validated from the values provided in the dataset, these MUST be reported in the `notices` property as `Warning` notices. +- a boolean `recurse` argument (set to `true` for validating the entire device model) +- the `restoreMode` argument (set to `Rebuild` in order to allow blocks to be repopulated with the same members as per the original device) -The backup can be restored by performing a [Set request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#setting-bulk-properties-for-a-role-path) to restore the backup. +A restore operation is performed through a [Set request](https://specs.amwa.tv/is-14/branches/v1.0-dev/docs/API_requests.html#setting-bulk-properties-for-a-role-path) to restore a backup data set. -In order to use the whole backup data set to restore against the device model, requests MUST use `root` as the `rolePath`. +In order to restore the full backup data set to the device model, requests MUST use `root` as the `rolePath`. The request body MUST include: - the backup dataSet -- a boolean `recurse` argument (set to `true` for validating the whole device model) -- the `restoreMode` argument (set to `Modify` in order to only allow changes to writeable properties) - -The response MUST include a collection of all target device model role paths with a validation `status` property and a `notices` array of property notices. For role paths which have a `status` which is not a 2XX value the response MUST also include a `statusMessage` with details of why the restore failed. When there are properties of role path objects which cannot be restored from the values provided in the dataset, these MUST be reported in the `notices` property as `Warning` notices. +- a boolean `recurse` argument (set to `true` for validating the entire device model) +- the `restoreMode` argument (set to `Rebuild` in order to allow blocks to be repopulated with the same members as per the original device) -If devices require a system reboot in order to apply the restore then they MUST perform this immediately after responding to the restore request. +If a device requires a system reboot in order to apply the restore then it MUST perform this immediately after responding to the restore request. -The diagram below captures how the `Rebuild` restore uses the backup data set to transition the spare device from its out of the box device model to a state of functionality identical to the original faulty device. +The diagram below captures how the `Rebuild` restore uses the backup data set to transition the device from its current device model to a changed state. In this case the operation makes a structural change to the device model. -| ![Modify restore of spare](images/restoring_on_fixed_spare.png) | +| ![Rebuild restore](images/rebuild-restore.png) | |:--:| -| _**Modify restore of spare**_ | +| _**Rebuild restore**_ |