ARSN-392 Fix processVersionSpecificPut

- For backward compatibility (if isNull is undefined), add the nullVersionId field to the master update. The nullVersionId is needed for listing, retrieving, and deleting null versions.

- For the new null key implementation (if isNull is defined): add the isNull2 field and set it to true to specify that the new version is null AND has been put with a Cloudserver handling null keys (i.e., supporting S3C-7352).

- Manage scenarios in which a version is marked with the isNull attribute set to true, but without a version ID. This happens after BackbeatClient.putMetadata() is applied to a standalone null master.

(cherry picked from commit 6820444)

lib/versioning/Version.ts

@@ -3,7 +3,7 @@ import { VersioningConstants } from './constants';
 const VID_SEP = VersioningConstants.VersionId.Separator;
 /**
  * Class for manipulating an object version.
- * The format of a version: { isNull, isDeleteMarker, versionId, otherInfo }
+ * The format of a version: { isNull, isNull2, isDeleteMarker, versionId, otherInfo }
  *
  * @note Some of these functions are optimized based on string search
  * prior to a full JSON parse/stringify. (Vinh: 18K op/s are achieved
@@ -13,24 +13,31 @@ const VID_SEP = VersioningConstants.VersionId.Separator;
 export class Version {
     version: {
         isNull?: boolean;
+        isNull2?: boolean;
         isDeleteMarker?: boolean;
         versionId?: string;
         isPHD?: boolean;
+        nullVersionId?: string;
     };
 
     /**
      * Create a new version instantiation from its data object.
      * @param version - the data object to instantiate
      * @param version.isNull - is a null version
+     * @param version.isNull2 - Whether new version is null or not AND has
+     * been put with a Cloudserver handling null keys (i.e. supporting
+     * S3C-7352)
      * @param version.isDeleteMarker - is a delete marker
      * @param version.versionId - the version id
      * @constructor
      */
     constructor(version?: {
         isNull?: boolean;
+        isNull2?: boolean;
         isDeleteMarker?: boolean;
         versionId?: string;
         isPHD?: boolean;
+        nullVersionId?: string;
     }) {
         this.version = version || {};
     }
@@ -121,6 +128,19 @@ export class Version {
         return this.version.isNull ?? false;
     }
 
+    /**
+     * Check if a version is a null version and has
+     * been put with a Cloudserver handling null keys (i.e. supporting
+     * S3C-7352).
+     *
+     * @return - stating if the value is a null version and has
+     * been put with a Cloudserver handling null keys (i.e. supporting
+     * S3C-7352).
+     */
+    isNull2Version(): boolean {
+        return this.version.isNull2 ?? false;
+    }
+
     /**
      * Check if a stringified object is a delete marker.
      *
@@ -170,6 +190,15 @@ export class Version {
         return this;
     }
 
+    /**
+     * Get the nullVersionId of the version.
+     *
+     * @return - the nullVersionId
+     */
+    getNullVersionId(): string | undefined {
+        return this.version.nullVersionId;
+    }
+
     /**
      * Mark a version as a delete marker.
      *
@@ -190,6 +219,19 @@ export class Version {
         return this;
     }
 
+    /**
+     * Mark that the null version has been put with a Cloudserver handling null keys (i.e. supporting S3C-7352)
+     * 
+     * If `isNull2` is set, `isNull` is also set to maintain consistency.
+     * Explicitly setting both avoids misunderstandings and mistakes in future updates or fixes.
+     * @return - the updated version
+     */
+    setNull2Version() {
+        this.version.isNull2 = true;
+        this.version.isNull = true;
+        return this;
+    }
+
     /**
      * Serialize the version.
      *

lib/versioning/VersioningRequestProcessor.ts

@@ -496,7 +496,26 @@ export default class VersioningRequestProcessor {
                 const versionIdFromMaster = masterVersion.getVersionId();
                 if (versionIdFromMaster === undefined ||
                     versionIdFromMaster >= versionId) {
+                    let value = request.value;
                     logger.debug('version to put is not older than master');
+                    // Delete the deprecated, null key for backward compatibility
+                    // to avoid storing both deprecated and new null keys.
+                    // If master null version was put with an older Cloudserver (or in compat mode),
+                    // there is a possibility that it also has a null versioned key
+                    // associated, so we need to delete it as we write the null key.
+                    // Deprecated null key gets deleted when the new CloudServer:
+                    // - updates metadata of a null master (options.isNull=true)
+                    // - puts metadata on top of a master null key (options.isNull=false)
+                    if (request.options.isNull !== undefined && // new null key behavior when isNull is defined.
+                        masterVersion.isNullVersion() && // master is null
+                        !masterVersion.isNull2Version()) { // master does not support the new null key behavior yet.
+                        const masterNullVersionId = masterVersion.getNullVersionId();
+                        // The deprecated null key is referenced in the "nullVersionId" property of the master key.
+                        if (masterNullVersionId) {
+                            const oldNullVersionKey = formatVersionKey(key, masterNullVersionId);
+                            ops.push({ key: oldNullVersionKey, type: 'del' });
+                        }
+                    }
                     // new behavior when isNull is defined is to only
                     // update the master key if it is the latest
                     // version, old behavior needs to copy master to
@@ -509,7 +528,7 @@ export default class VersioningRequestProcessor {
                         request.options.isNull === undefined) {
                         // master key is strictly older than the put version
                         let masterVersionId;
-                        if (masterVersion.isNullVersion()) {
+                        if (masterVersion.isNullVersion() && versionIdFromMaster) {
                             logger.debug('master key is a null version');
                             masterVersionId = versionIdFromMaster;
                         } else if (versionIdFromMaster === undefined) {
@@ -537,13 +556,22 @@ export default class VersioningRequestProcessor {
                                   '' : masterVersionId;
                             const masterVersionKey = formatVersionKey(key, masterKeyVersionId);
                             masterVersion.setNullVersion();
+                            // isNull === false means Cloudserver supports null keys,
+                            // so create a null key with the isNull2 flag
+                            if (request.options.isNull === false) {
+                                masterVersion.setNull2Version();
+                            // else isNull === undefined means Cloudserver does not support null keys,
+                            // hence set/update the new master nullVersionId for backward compatibility
+                            } else {
+                                value = Version.updateOrAppendNullVersionId(request.value, masterVersionId);
+                            }
                             ops.push({ key: masterVersionKey,
                                        value: masterVersion.toString() });
                         }
                     } else {
                         logger.debug('version to put is the master');
                     }
-                    ops.push({ key, value: request.value });
+                    ops.push({ key, value: value });
                 } else {
                     logger.debug('version to put is older than master');
                     if (request.options.isNull === true && !masterVersion.isNullVersion()) {