Upgrade microVersionId to timestamp-ordered format and add isReplica

Replace the random 8-byte hex microVersionId the
timestamp-ordered identifier matching the versionId scheme, and add
helpers for the crr cascade feature.
Add an optional isReplica flag to ReplicationInfo to distinguish replica
writes from user writes, enabling cascaded CRR.

Issue: ARSN-578

Author: maeldonn

lib/models/ObjectMD.ts

@@ -1,4 +1,3 @@
-import * as crypto from 'crypto';
 import * as constants from '../constants';
 import * as VersionIDUtils from '../versioning/VersionID';
 import { VersioningConstants } from '../versioning/constants';
@@ -49,6 +48,7 @@ export type ReplicationInfo = {
     /** @deprecated in favor of per-backend dataStoreVersionId for multi-destination. */
     dataStoreVersionId?: string;
     isNFS?: boolean;
+    isReplica?: boolean;
 };
 
 export type ObjectMDTag = {
@@ -260,6 +260,7 @@ export default class ObjectMD {
                 storageType: undefined,
                 dataStoreVersionId: undefined,
                 isNFS: undefined,
+                isReplica: undefined,
             },
             dataStoreName: '',
             originOp: '',
@@ -1168,6 +1169,27 @@ export default class ObjectMD {
         return this;
     }
 
+    /**
+     * Mark this object as the result of a replication write (replica),
+     * as opposed to a write originating from a user request.
+     *
+     * @param isReplica - true if this object was written by replication
+     * @return itself
+     */
+    setReplicationIsReplica(isReplica: boolean) {
+        this._data.replicationInfo.isReplica = isReplica;
+        return this;
+    }
+
+    /**
+     * Get whether this object was written by replication (replica).
+     * @return true if this object is a replica
+     */
+    getReplicationIsReplica(): boolean {
+        return this._data.replicationInfo.isReplica === true
+            || this._data.replicationInfo.status === 'REPLICA';
+    }
+
     getReplicationSiteStatus(key: BackendKey): string | undefined {
         return this._findBackend(key)?.status;
     }
@@ -1348,35 +1370,28 @@ export default class ObjectMD {
     }
 
     /**
-     * Create or update the microVersionId field
-     *
-     * This field can be used to force an update in MongoDB. This can
-     * be needed in the following cases:
-     *
-     * - in case no other metadata field changes
-     *
-     * - to detect a change when fields change but object version does
-     *   not change e.g. when ingesting a putObjectTagging coming from
-     *   S3C to Zenko
-     *
-     * - to manage conflicts during concurrent updates, using
-     *   conditions on the microVersionId field.
-     *
-     * It's a field of 16 hexadecimal characters randomly generated
-     *
+     * Update the microVersionId
+     * 
+     * This field can be used to force an update in MongoDB when no other
+     * metadata field changes, to detect a change for CRR,
+     * and to manage conflicts during concurrent updates using conditions on this field. 
+     * 
+     * @param instanceId - instance identifier (e.g. config.instanceId)
+     * @param replicationGroupId - replication group ID (e.g. config.replicationGroupId)
      * @return itself
      */
-    updateMicroVersionId() {
-        this._data.microVersionId = crypto.randomBytes(8).toString('hex');
+    updateMicroVersionId(instanceId: string, replicationGroupId: string) {
+        this._data.microVersionId = VersionIDUtils.generateVersionId(instanceId, replicationGroupId);
+        return this;
     }
 
     /**
-     * Get the microVersionId field, or null if not set
+     * Get the microVersionId field, or undefined if not set
      *
-     * @return the microVersionId field if exists, or {null} if it does not exist
+     * @return the microVersionId field if set, or undefined if not
      */
     getMicroVersionId() {
-        return this._data.microVersionId || null;
+        return this._data.microVersionId || undefined;
     }
 
     /**

lib/versioning/VersionID.ts

@@ -369,3 +369,34 @@ export function decode(str: string): string | Error {
     }
     return new Error(`cannot decode str ${str.length}`);
 }
+
+export enum Ordering {
+    OLDER          = 'older',
+    YOUNGER        = 'younger',
+    EQUAL          = 'equal',
+    NOT_COMPARABLE = 'notComparable',
+}
+
+/**
+ * Compare two raw (decoded) version IDs.
+ *
+ * Returns NOT_COMPARABLE when either value is absent or shorter than
+ * LEGACY_BASE62_DECODED_LENGTH (rejects the old 16-char random-hex format.
+ * Callers are responsible for deciding how to handle NOT_COMPARABLE.
+ */
+export function compare(
+    v1: string | null | undefined,
+    v2: string | null | undefined,
+): Ordering {
+    if (
+        typeof v1 !== 'string' || v1.length < LEGACY_BASE62_DECODED_LENGTH ||
+        typeof v2 !== 'string' || v2.length < LEGACY_BASE62_DECODED_LENGTH
+    ) {
+        return Ordering.NOT_COMPARABLE;
+    }
+    if (v1 === v2) {
+        return Ordering.EQUAL;
+    }
+
+    return v1 > v2 ? Ordering.OLDER : Ordering.YOUNGER;
+}

tests/unit/models/ObjectMD.spec.js

@@ -112,6 +112,7 @@ describe('ObjectMD class setters/getters', () => {
                 storageType: undefined,
                 dataStoreVersionId: undefined,
                 isNFS: undefined,
+                isReplica: undefined,
             },
         ],
         [
@@ -132,6 +133,7 @@ describe('ObjectMD class setters/getters', () => {
                 storageType: 'aws_s3',
                 dataStoreVersionId: '',
                 isNFS: undefined,
+                isReplica: undefined,
             },
         ],
         ['DataStoreName', null, ''],
@@ -183,6 +185,26 @@ describe('ObjectMD class setters/getters', () => {
         });
     });
 
+    it('getReplicationIsReplica: returns true when status is REPLICA', () => {
+        md.setReplicationStatus('REPLICA');
+        assert.strictEqual(md.getReplicationIsReplica(), true,
+            'status REPLICA alone can be used to determine isReplica');
+    });
+
+    it('getReplicationIsReplica: survives status transition to PENDING (cascade)', () => {
+        md.setReplicationInfo({
+            status: 'REPLICA',
+            isReplica: true,
+            backends: [],
+            content: [],
+            destination: '',
+            role: '',
+        });
+        md.setReplicationStatus('PENDING');
+        assert.strictEqual(md.getReplicationIsReplica(), true,
+            'isReplica must survive status changes');
+    });
+
     it('ObjectMD::setReplicationSiteStatus', () => {
         md.setReplicationInfo({
             backends: [
@@ -386,22 +408,22 @@ describe('ObjectMD class setters/getters', () => {
     });
 
     it('ObjectMD::microVersionId unset', () => {
-        assert.strictEqual(md.getMicroVersionId(), null);
+        assert.strictEqual(md.getMicroVersionId(), undefined);
     });
 
     it('ObjectMD::microVersionId set', () => {
-        const generatedIds = new Set();
+        const generatedIds = [];
         for (let i = 0; i < 100; ++i) {
-            md.updateMicroVersionId();
-            generatedIds.add(md.getMicroVersionId());
+            md.updateMicroVersionId('instance', 'RG001');
+            generatedIds.push(md.getMicroVersionId());
         }
         // all generated IDs should be different
-        assert.strictEqual(generatedIds.size, 100);
-        generatedIds.forEach(key => {
-            // length is always 16 in hex because leading 0s are
-            // also encoded in the 8-byte random buffer.
-            assert.strictEqual(key.length, 16);
-        });
+        assert.strictEqual(new Set(generatedIds).size, 100);
+        // microVersionIds use the versionId format (reversed time ordered):
+        // newer values sort before older ones lexicographically.
+        for (let i = 1; i < generatedIds.length; ++i) {
+            assert(generatedIds[i] < generatedIds[i - 1]);
+        }
     });
 
     it('ObjectMD::set/getRetentionMode', () => {

tests/unit/versioning/VersionID.spec.js

@@ -1,3 +1,4 @@
+const crypto = require('crypto');
 const VID = require('../../../lib/versioning/VersionID');
 const VersioningConstants = require('../../../lib/versioning/constants').VersioningConstants;
 const assert = require('assert');
@@ -188,3 +189,49 @@ describe('test generating versionIds', () => {
         });
     });
 });
+
+describe('compare', () => {
+    const { compare, Ordering, generateVersionId } = VID;
+
+    it('should return NOT_COMPARABLE when existing is null', () => {
+        assert.strictEqual(compare(generateVersionId('test', 'RG001'), null), Ordering.NOT_COMPARABLE);
+    });
+
+    it('should return NOT_COMPARABLE when existing is undefined', () => {
+        assert.strictEqual(compare(generateVersionId('test', 'RG001'), undefined), Ordering.NOT_COMPARABLE);
+    });
+
+    it('should return NOT_COMPARABLE when existing is a legacy 16-char hex microVersionId', () => {
+        const legacyHex = crypto.randomBytes(8).toString('hex');
+        assert.strictEqual(legacyHex.length, 16);
+        assert.strictEqual(compare(generateVersionId('test', 'RG001'), legacyHex), Ordering.NOT_COMPARABLE);
+    });
+
+    it('should return NOT_COMPARABLE when incoming is a legacy 16-char hex microVersionId', () => {
+        const legacyHex = crypto.randomBytes(8).toString('hex');
+        assert.strictEqual(compare(legacyHex, generateVersionId('test', 'RG001')), Ordering.NOT_COMPARABLE);
+    });
+
+    it('should return NOT_COMPARABLE for a string shorter than 27 chars', () => {
+        assert.strictEqual(compare('tooshort', generateVersionId('test', 'RG001')), Ordering.NOT_COMPARABLE);
+    });
+
+    it('should return EQUAL when incoming equals existing', () => {
+        const raw = generateVersionId('test', 'RG001');
+        assert.strictEqual(compare(raw, raw), Ordering.EQUAL);
+    });
+
+    it('should return OLDER when incoming is older than existing', () => {
+        const older = generateVersionId('test', 'RG001');
+        const newer = generateVersionId('test', 'RG001');
+        assert.ok(older > newer, 'test requires two distinct versionIds in order');
+        assert.strictEqual(compare(older, newer), Ordering.OLDER);
+    });
+
+    it('should return YOUNGER when incoming is newer than existing', () => {
+        const older = generateVersionId('test', 'RG001');
+        const newer = generateVersionId('test', 'RG001');
+        assert.ok(older > newer, 'test requires two distinct versionIds in order');
+        assert.strictEqual(compare(newer, older), Ordering.YOUNGER);
+    });
+});