Finish the match key rename in the 51Did payload constants

pipeline.developer-examples/pipeline.developer-examples.fodid/src/main/java/pipeline/developerexamples/fodid/Main.java

@@ -109,8 +109,8 @@ private byte[] samplePayload() {
             payload[FodId.LICENSE_ID_OFFSET + 1] = 0x56;
             payload[FodId.LICENSE_ID_OFFSET + 2] = 0x34;
             payload[FodId.LICENSE_ID_OFFSET + 3] = 0x12;
-            for (int i = 0; i < FodId.HASH_LENGTH; i++) {
-                payload[FodId.HASH_OFFSET + i] = (byte) (0x20 + i);
+            for (int i = 0; i < FodId.MATCH_KEY_LENGTH; i++) {
+                payload[FodId.MATCH_KEY_OFFSET + i] = (byte) (0x20 + i);
             }
             return payload;
         }

pipeline.developer-examples/pipeline.developer-examples.fodid/src/test/java/pipeline/developerexamples/fodid/ExampleTests.java

@@ -249,8 +249,8 @@ private static byte[] samplePayload() {
         payload[FodId.LICENSE_ID_OFFSET + 1] = 0x56;
         payload[FodId.LICENSE_ID_OFFSET + 2] = 0x34;
         payload[FodId.LICENSE_ID_OFFSET + 3] = 0x12;
-        for (int i = 0; i < FodId.HASH_LENGTH; i++) {
-            payload[FodId.HASH_OFFSET + i] = (byte) (0x20 + i);
+        for (int i = 0; i < FodId.MATCH_KEY_LENGTH; i++) {
+            payload[FodId.MATCH_KEY_OFFSET + i] = (byte) (0x20 + i);
         }
         return payload;
     }

pipeline.did/README.md

@@ -198,6 +198,12 @@ Use `getMatchKey()` as the cache / dedup key. `getHash()` remains as a
 deprecated alias of `getMatchKey()`, returning the same bytes, and will be
 removed in a future release.
 
+The payload constants follow the same naming. `MATCH_KEY_OFFSET` and
+`MATCH_KEY_LENGTH` give the position and the size of the match key inside the
+payload, and `HASH_OFFSET` and `HASH_LENGTH` remain as deprecated aliases of
+the same two values so that code written against the earlier names keeps
+compiling. The aliases will be removed in a future release.
+
 ## Verifying on your server
 
 `DidClient` handles every manipulation of a 51Did a server needs against the

pipeline.did/src/main/java/fiftyone/pipeline/did/DidClient.java

@@ -487,7 +487,7 @@ public SignatureCheck verifySignatureDetailed(FodId fodId)
         }
         boolean isRandom = fodId.getType() == IdType.RANDOM;
         int baseLength = FodId.HEADER_LENGTH
-            + (isRandom ? FodId.GUID_LENGTH : FodId.HASH_LENGTH);
+            + (isRandom ? FodId.GUID_LENGTH : FodId.MATCH_KEY_LENGTH);
         if (fodId.getPayload().length < baseLength) {
             return SignatureCheck.MALFORMED_PAYLOAD;
         }

pipeline.did/src/main/java/fiftyone/pipeline/did/FodId.java

@@ -97,16 +97,38 @@ public final class FodId {
     public static final int LICENSE_ID_LENGTH = 4;
 
     /** Byte offset of the match key field within the payload. */
-    public static final int HASH_OFFSET = 5;
+    public static final int MATCH_KEY_OFFSET = 5;
 
     /** Byte length of the match key field (SHA-256). */
-    public static final int HASH_LENGTH = 32;
+    public static final int MATCH_KEY_LENGTH = 32;
+
+    /**
+     * Deprecated alias for {@link #MATCH_KEY_OFFSET}. The stable, comparable
+     * part of a 51Did is now called the match key, mirroring the Model Terms
+     * for Marketing vocabulary. This alias will be removed in a future
+     * release.
+     *
+     * @deprecated renamed to {@link #MATCH_KEY_OFFSET}
+     */
+    @Deprecated
+    public static final int HASH_OFFSET = MATCH_KEY_OFFSET;
+
+    /**
+     * Deprecated alias for {@link #MATCH_KEY_LENGTH}. The stable, comparable
+     * part of a 51Did is now called the match key, mirroring the Model Terms
+     * for Marketing vocabulary. This alias will be removed in a future
+     * release.
+     *
+     * @deprecated renamed to {@link #MATCH_KEY_LENGTH}
+     */
+    @Deprecated
+    public static final int HASH_LENGTH = MATCH_KEY_LENGTH;
 
     /**
      * Byte length of the payload header (Flags + License Id) common to every
      * identifier type.
      */
-    public static final int HEADER_LENGTH = HASH_OFFSET;
+    public static final int HEADER_LENGTH = MATCH_KEY_OFFSET;
 
     /** Byte length of the GUID match key carried by Random identifiers. */
     public static final int GUID_LENGTH = 16;
@@ -122,7 +144,8 @@ public final class FodId {
      * (Flags + License Id + match key). Random payloads are shorter - see
      * {@link #RANDOM_PAYLOAD_LENGTH}.
      */
-    public static final int PAYLOAD_LENGTH = HASH_OFFSET + HASH_LENGTH;
+    public static final int PAYLOAD_LENGTH =
+        MATCH_KEY_OFFSET + MATCH_KEY_LENGTH;
 
     /**
      * The origin the envelope's date counts from, 2020-01-01T00:00:00Z, as
@@ -227,7 +250,7 @@ private static FodIdParseResult read(Owid owid) {
                 matchKeyLength = payload.length - HEADER_LENGTH;
                 break;
             default:
-                matchKeyLength = HASH_LENGTH;
+                matchKeyLength = MATCH_KEY_LENGTH;
                 break;
         }
         if (payload.length < HEADER_LENGTH + matchKeyLength) {
@@ -245,7 +268,7 @@ private static FodIdParseResult read(Owid owid) {
         // gets back from getMatchKey() can never reach the envelope's own
         // bytes.
         byte[] matchKey = Arrays.copyOfRange(
-            payload, HASH_OFFSET, HASH_OFFSET + matchKeyLength);
+            payload, MATCH_KEY_OFFSET, MATCH_KEY_OFFSET + matchKeyLength);
         return FodIdParseResult.parsed(
             new FodId(owid, flags, licenseId, matchKey));
     }

pipeline.did/src/test/java/fiftyone/pipeline/did/FodIdTestFactory.java

@@ -74,7 +74,7 @@ final class FodIdTestFactory {
     }
 
     private static byte[] canonicalMatchKey() {
-        byte[] matchKey = new byte[FodId.HASH_LENGTH];
+        byte[] matchKey = new byte[FodId.MATCH_KEY_LENGTH];
         for (int i = 0; i < matchKey.length; i++) {
             matchKey[i] = (byte) (0x20 + i);
         }
@@ -87,7 +87,7 @@ static byte[] canonicalPayload() {
         writeCanonicalLicenseId(payload);
         System.arraycopy(
             CANONICAL_MATCH_KEY, 0, payload,
-            FodId.HASH_OFFSET, FodId.HASH_LENGTH);
+            FodId.MATCH_KEY_OFFSET, FodId.MATCH_KEY_LENGTH);
         return payload;
     }
 
@@ -96,7 +96,7 @@ static byte[] canonicalRandomPayload() {
         payload[FodId.FLAGS_OFFSET] = (byte) ((1 << 6) | 0b001);
         writeCanonicalLicenseId(payload);
         for (int i = 0; i < FodId.GUID_LENGTH; i++) {
-            payload[FodId.HASH_OFFSET + i] = (byte) (0x40 + i);
+            payload[FodId.MATCH_KEY_OFFSET + i] = (byte) (0x40 + i);
         }
         return payload;
     }

pipeline.did/src/test/java/fiftyone/pipeline/did/FodIdTests.java

@@ -66,9 +66,12 @@ public void init() throws OwidException {
 
     @Test
     public void constants_AreInternallyConsistent() {
-        assertEquals(FodId.PAYLOAD_LENGTH, FodId.HASH_OFFSET + FodId.HASH_LENGTH);
-        assertEquals(FodId.HASH_OFFSET, FodId.LICENSE_ID_OFFSET + FodId.LICENSE_ID_LENGTH);
-        assertEquals(FodId.RANDOM_PAYLOAD_LENGTH, FodId.HASH_OFFSET + FodId.GUID_LENGTH);
+        assertEquals(FodId.PAYLOAD_LENGTH,
+            FodId.MATCH_KEY_OFFSET + FodId.MATCH_KEY_LENGTH);
+        assertEquals(FodId.MATCH_KEY_OFFSET,
+            FodId.LICENSE_ID_OFFSET + FodId.LICENSE_ID_LENGTH);
+        assertEquals(FodId.RANDOM_PAYLOAD_LENGTH,
+            FodId.MATCH_KEY_OFFSET + FodId.GUID_LENGTH);
     }
 
     @Test
@@ -190,11 +193,11 @@ public void matchKey_IsDefensiveCopy() throws Exception {
 
         byte[] matchKey = fodId.getMatchKey();
         matchKey[0] = 0x00;
-        matchKey[FodId.HASH_LENGTH - 1] = 0x00;
+        matchKey[FodId.MATCH_KEY_LENGTH - 1] = 0x00;
 
         // Neither the underlying payload nor a fresh getMatchKey() is affected.
         assertEquals(
-            CANONICAL_MATCH_KEY[0], fodId.getPayload()[FodId.HASH_OFFSET]);
+            CANONICAL_MATCH_KEY[0], fodId.getPayload()[FodId.MATCH_KEY_OFFSET]);
         assertArrayEquals(CANONICAL_MATCH_KEY, fodId.getMatchKey());
     }
 
@@ -209,6 +212,16 @@ public void getHash_DeprecatedAlias_ReturnsMatchKey() throws Exception {
         assertArrayEquals(CANONICAL_MATCH_KEY, fodId.getHash());
     }
 
+    @Test
+    @SuppressWarnings("deprecation")
+    public void hashConstants_DeprecatedAliases_MatchNewNames() {
+        // HASH_OFFSET and HASH_LENGTH stay as deprecated aliases so that
+        // callers written against the earlier names keep compiling and read
+        // the same values as the match key constants they now point at.
+        assertEquals(FodId.MATCH_KEY_OFFSET, FodId.HASH_OFFSET);
+        assertEquals(FodId.MATCH_KEY_LENGTH, FodId.HASH_LENGTH);
+    }
+
     @Test
     public void constructor_PayloadOneByteShort_Throws() throws Exception {
         // 36 bytes - one short of the minimum 37 (flags 0 -> Probabilistic).
@@ -251,7 +264,7 @@ public void constructor_PayloadLargerThanSpec_UsesFirst37Bytes() throws Exceptio
         assertEquals(CANONICAL_FLAGS, fodId.getFlags());
         assertEquals(CANONICAL_LICENSE_ID, fodId.getLicenseId());
         assertArrayEquals(CANONICAL_MATCH_KEY, fodId.getMatchKey());
-        assertEquals(FodId.HASH_LENGTH, fodId.getMatchKey().length);
+        assertEquals(FodId.MATCH_KEY_LENGTH, fodId.getMatchKey().length);
     }
 
     @Test
@@ -366,7 +379,7 @@ public void constructor_HashedEmailPayloadOneByteShort_Throws() throws Exception
 
     @Test
     public void constructor_ReservedHeaderOnly_Parses() throws Exception {
-        byte[] payload = new byte[FodId.HASH_OFFSET];
+        byte[] payload = new byte[FodId.MATCH_KEY_OFFSET];
         payload[FodId.FLAGS_OFFSET] = (byte) 0b1100_0000;
 
         FodId fodId = FodId.fromBase64(factory.signedOwidBase64(payload));