SECENG-3602: add UUIDv7 methods, deprecate prefixComb methods (#56)

* SECENG-3602: add UUIDv7 methods, depcreate `prefixComb` methods

* Add support for deterministic UUIDs

* Fix helper functon visibility and Javadoc line length

* Update adding constant ordering tests

* Clarify long-term intentions WRT UUIDv7 generation code

Author: bh-wise

CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.14.0] - 2025-07-10
+
+### Changed
+- Added support for generating [UUIDv7](https://uuid7.com/)s (`generateTimePrefixedUuid`).
+- Added support for generating UUIDv8s. This implementation (`generateDeterministicTimePrefixedUuid`) is a combination of UUIDv7's time-prefixing and UUIDv3's seeding.
+- Deprecated prefix combined UUIDv4s in favour of UUIDv7s or UUIDv8s (as appropriate).
+
 ## [1.13.4] - 2025-06-17
 
 ### Changed

gradle.properties

@@ -1 +1 @@
-version=1.13.4
+version=1.14.0

tw-base-utils/src/main/java/com/transferwise/common/baseutils/UuidUtils.java

@@ -27,13 +27,75 @@ public static UUID generateSecureUuid() {
     return new UUID(applyVersionBits(numberGenerator.nextLong(), V4_VERSION_BITS), numberGenerator.nextLong());
   }
 
+  /**
+   * Timestamp-prefixed UUID for where UUIDs should be time-sortable, see <a href="https://uuid7.com/">uuid7.com</a> for details.
+   *
+   * <p>This UUID is not suitable for things like session and authentication tokens.
+   *
+   * <p>This method is likely to be deprecated once <a href="https://bugs.openjdk.org/browse/JDK-8334015">JDK-8334015</a> has been released, in favour of the built-in UUIDv7 implementation.
+   */
+  public static UUID generateTimePrefixedUuid() {
+    long timestamp = ClockHolder.getClock().millis();
+    return generateTimePrefixedUuid(timestamp);
+  }
+
+  /**
+   * Timestamp-prefixed UUID for where UUIDs should be time-sortable, see <a href="https://uuid7.com/">uuid7.com</a> for details.
+   *
+   * <p>This UUID is not suitable for things like session and authentication tokens.
+   *
+   * <p>This method is likely to be deprecated once <a href="https://bugs.openjdk.org/browse/JDK-8334015">JDK-8334015</a> has been released, in favour of the built-in UUIDv7 implementation.
+   *
+   * @param timestamp provided timestamp milliseconds from epoch.
+   */
+  public static UUID generateTimePrefixedUuid(long timestamp) {
+    // use built-in implementation once https://bugs.openjdk.org/browse/JDK-8334015 is done and released
+    byte[] bytes = new byte[16];
+    numberGenerator.nextBytes(bytes);
+    applyV7StyleTimestampBits(timestamp, bytes);
+    applyVersionBits(7, bytes);
+    applyIetfVariantBits(bytes);
+    return toUuid(bytes);
+  }
+
+  /**
+   * Deterministic timestamp-prefixed UUID. This may be useful if <a href="https://transferwise.atlassian.net/wiki/spaces/EKB/pages/3184789016/Consistent+and+idempotent+processing+in+multi-step+flows#Branching-UUIDs">branching UUIDs</a> aren't a viable option.
+   *
+   * <p>This UUID is not suitable for things like session and authentication tokens.
+   *
+   * @param data a byte array that will be used to generate the UUID.
+   */
+  public static UUID generateDeterministicTimePrefixedUuid(byte[] data) {
+    long timestamp = ClockHolder.getClock().millis();
+    return generateDeterministicTimePrefixedUuid(timestamp, data);
+  }
+
+  /**
+   * Deterministic timestamp-prefixed UUID. This may be useful if <a href="https://transferwise.atlassian.net/wiki/spaces/EKB/pages/3184789016/Consistent+and+idempotent+processing+in+multi-step+flows#Branching-UUIDs">branching UUIDs</a> aren't a viable option.
+   *
+   * <p>This UUID is not suitable for things like session and authentication tokens.
+   *
+   * @param timestamp provided timestamp milliseconds from epoch.
+   * @param data a byte array that will be used to generate the UUID.
+   */
+  public static UUID generateDeterministicTimePrefixedUuid(long timestamp, byte[] data) {
+    byte[] bytes = toBytes(UUID.nameUUIDFromBytes(data));
+    applyV7StyleTimestampBits(timestamp, bytes);
+    applyVersionBits(8, bytes);
+    applyIetfVariantBits(bytes);
+    return toUuid(bytes);
+  }
+
   /**
    * Random UUID with 38 bit prefix based on current milliseconds from epoch.
    *
    * <p>Giving about 3181 days roll-over.
    *
    * <p>This UUID is not suitable for things like session and authentication tokens.
+   *
+   * @deprecated in a favour of {@link #generateTimePrefixedUuid()}.
    */
+  @Deprecated(forRemoval = false)
   public static UUID generatePrefixCombUuid() {
     return generatePrefixCombUuid(38);
   }
@@ -44,7 +106,10 @@ public static UUID generatePrefixCombUuid() {
    * <p>Giving about 3181 days roll-over.
    *
    * <p>This UUID is not suitable for things like session and authentication tokens.
+   *
+   * @deprecated in a favour of {@link #generateDeterministicTimePrefixedUuid(long timestamp, byte[] data)}.
    */
+  @Deprecated(forRemoval = false)
   public static UUID generatePrefixCombUuid(long timestamp, UUID uuid) {
     return generatePrefixCombUuid(timestamp, uuid, 38);
   }
@@ -61,7 +126,11 @@ public static UUID generatePrefixCombUuid(long timestamp, UUID uuid) {
    * @param timestamp provided timestamp milliseconds from epoch.
    * @param uuid provided uuid.
    * @param timePrefixLengthBits technically we left-shift the current time-millis by that amount.
+   *
+   * @deprecated in a favour of {@link #generateDeterministicTimePrefixedUuid(long timestamp, byte[] data)}.
+   *     Note that the replacement method has a fixed 48-bit timestamp prefix.
    */
+  @Deprecated(forRemoval = false)
   public static UUID generatePrefixCombUuid(long timestamp, UUID uuid, int timePrefixLengthBits) {
     if (timePrefixLengthBits < 1 || timePrefixLengthBits > 63) {
       throw new IllegalArgumentException("Prefix length " + timePrefixLengthBits + " has to be between 1 and 63, inclusively.");
@@ -82,7 +151,10 @@ public static UUID generatePrefixCombUuid(long timestamp, UUID uuid, int timePre
    * <p>This UUID is not suitable for things like session and authentication tokens.
    *
    * @param timePrefixLengthBits technically we left-shift the current time-millis by that amount.
+   *
+   * @deprecated in a favour of {@link #generateTimePrefixedUuid()}. Note that UUIDv7s have a fixed 48-bit timestamp prefix.
    */
+  @Deprecated(forRemoval = false)
   public static UUID generatePrefixCombUuid(int timePrefixLengthBits) {
     if (timePrefixLengthBits < 1 || timePrefixLengthBits > 63) {
       throw new IllegalArgumentException("Prefix length " + timePrefixLengthBits + " has to be between 1 and 63, inclusively.");
@@ -135,8 +207,29 @@ public static UUID add(UUID uuid, long constant) {
     return new UUID(uuid.getMostSignificantBits(), uuid.getLeastSignificantBits() + constant);
   }
 
-  protected static long applyVersionBits(final long msb, int versionBits) {
+  private static void applyV7StyleTimestampBits(long timestamp, byte[] bytes) {
+    bytes[0] = (byte)(timestamp >>> 40);
+    bytes[1] = (byte)(timestamp >>> 32);
+    bytes[2] = (byte)(timestamp >>> 24);
+    bytes[3] = (byte)(timestamp >>> 16);
+    bytes[4] = (byte)(timestamp >>> 8);
+    bytes[5] = (byte)(timestamp);
+  }
+
+  private static long applyVersionBits(final long msb, int versionBits) {
     return (msb & 0xffffffffffff0fffL) | versionBits;
   }
 
+  private static void applyVersionBits(int version, byte[] bytes) {
+    // Set version bits
+    bytes[6] &= 0x0f;
+    bytes[6] |= (byte) (version << 4);
+  }
+
+  private static void applyIetfVariantBits(byte[] bytes) {
+    // Set variant to IETF
+    bytes[8] &= 0x3f;
+    bytes[8] |= (byte) 0x80;
+  }
+
 }

tw-base-utils/src/test/java/com/transferwise/common/baseutils/UuidUtilsTest.java

@@ -9,6 +9,7 @@
 
 import com.google.common.collect.Ordering;
 import com.transferwise.common.baseutils.clock.TestClock;
+import java.nio.charset.StandardCharsets;
 import java.time.Duration;
 import java.time.Instant;
 import java.util.Arrays;
@@ -34,24 +35,107 @@ void defaultPrefixCombUuidIsGrowingOverTime() {
 
     long previousTime = -1;
     for (int i = 0; i < n; i++) {
+      System.out.println("Testing " + uuids[i]);
+      assertEquals(4, uuids[i].version());
       long time = uuids[i].getMostSignificantBits() >>> (64 - 38);
 
       if (previousTime != -1) {
         assertTrue(previousTime < time);
       }
       previousTime = time;
+    }
 
-      System.out.println(uuids[i]);
-      assertEquals(4, uuids[i].version());
+    assertTrue(Ordering.natural().isOrdered(Arrays.asList(uuids)));
+    assertEquals(n, Set.of(uuids).size());
+  }
+
+  @Test
+  void timePrefixedUuidIsVersion7() {
+    UUID uuid = UuidUtils.generateTimePrefixedUuid();
+    assertEquals(7, uuid.version());
+  }
+
+  @Test
+  void timePrefixedUuidIsGrowingOverTime() {
+    TestClock clock = TestClock.createAndRegister();
+
+    int n = 100;
+
+    UUID[] uuids = new UUID[n];
+    for (int i = 0; i < n; i++) {
+      uuids[i] = UuidUtils.generateTimePrefixedUuid();
+      clock.tick(Duration.ofMillis(2));
+    }
+
+    long previousTime = -1;
+    for (int i = 0; i < n; i++) {
+      System.out.println("Testing " + uuids[i]);
+      long time = uuids[i].getMostSignificantBits() >>> (64 - 48);
+
+      if (previousTime != -1) {
+        assertTrue(previousTime < time);
+      }
+      previousTime = time;
+    }
+
+    assertTrue(Ordering.natural().isOrdered(Arrays.asList(uuids)));
+    assertEquals(n, Set.of(uuids).size());
+  }
+
+  @Test
+  void deterministicTimePrefixedUuidIsVersion8() {
+    UUID uuid = UuidUtils.generateDeterministicTimePrefixedUuid(new byte[0]);
+    System.out.println(uuid);
+    assertEquals(8, uuid.version());
+  }
+
+  @Test
+  void deterministicTimePrefixedUuidIsGrowingOverTime() {
+    TestClock clock = TestClock.createAndRegister();
+
+    int n = 100;
+
+    UUID[] uuids = new UUID[n];
+    for (int i = 0; i < n; i++) {
+      uuids[i] = UuidUtils.generateDeterministicTimePrefixedUuid(new byte[0]);
+      clock.tick(Duration.ofMillis(2));
+    }
+
+    long previousTime = -1;
+    for (int i = 0; i < n; i++) {
+      System.out.println("Testing " + uuids[i]);
+      long time = uuids[i].getMostSignificantBits() >>> (64 - 48);
+
+      if (previousTime != -1) {
+        assertTrue(previousTime < time);
+      }
+      previousTime = time;
     }
 
     assertTrue(Ordering.natural().isOrdered(Arrays.asList(uuids)));
     assertEquals(n, Set.of(uuids).size());
   }
 
+  @Test
+  void deterministicTimePrefixedUuidIsFullyDeterministic() {
+    long timestamp = System.currentTimeMillis();
+    byte[] seed = "Ben was here".getBytes(StandardCharsets.UTF_8);
+    UUID uuid1 = UuidUtils.generateDeterministicTimePrefixedUuid(timestamp, seed);
+    UUID uuid2 = UuidUtils.generateDeterministicTimePrefixedUuid(timestamp, seed);
+    assertEquals(uuid1, uuid2);
+  }
+
+  @Test
+  void deterministicTimePrefixedUuidChangesWithDifferentData() {
+    long timestamp = System.currentTimeMillis();
+    UUID uuid1 = UuidUtils.generateDeterministicTimePrefixedUuid(timestamp, "Ben was here".getBytes(StandardCharsets.UTF_8));
+    UUID uuid2 = UuidUtils.generateDeterministicTimePrefixedUuid(timestamp, "Ben was not here".getBytes(StandardCharsets.UTF_8));
+    assertNotEquals(uuid1, uuid2);
+  }
+
   @Test
   void constantCanBeAddedToUuid() {
-    var uuid = UuidUtils.generatePrefixCombUuid();
+    var uuid = UuidUtils.generateTimePrefixedUuid();
     var uuidWithConstant = UuidUtils.add(uuid, 11111);
 
     assertNotEquals(uuidWithConstant, uuid);
@@ -60,7 +144,7 @@ void constantCanBeAddedToUuid() {
   }
 
   @Test
-  void addingConstantDoesNotChangeOrdering() {
+  void addingConstantDoesNotChangeOrderingOfPrefixCombUuid() {
     TestClock clock = TestClock.createAndRegister();
 
     int n = 100;
@@ -73,7 +157,7 @@ void addingConstantDoesNotChangeOrdering() {
 
     long previousTime = -1;
     for (int i = 0; i < n; i++) {
-      long time = uuids[i].getMostSignificantBits() >>> (64 - 38);
+      long time = uuids[i].getMostSignificantBits() >>> (64 - 48);
 
       if (previousTime != -1) {
         assertTrue(previousTime < time);
@@ -88,6 +172,35 @@ void addingConstantDoesNotChangeOrdering() {
     assertEquals(n, Set.of(uuids).size());
   }
 
+  @Test
+  void addingConstantDoesNotChangeOrderingOfTimePrefixedUuid() {
+    TestClock clock = TestClock.createAndRegister();
+
+    int n = 100;
+
+    UUID[] uuids = new UUID[n];
+    for (int i = 0; i < n; i++) {
+      uuids[i] = UuidUtils.add(UuidUtils.generateTimePrefixedUuid(), ThreadLocalRandom.current().nextInt());
+      clock.tick(Duration.ofMillis(2));
+    }
+
+    long previousTime = -1;
+    for (int i = 0; i < n; i++) {
+      long time = uuids[i].getMostSignificantBits() >>> (64 - 48);
+
+      if (previousTime != -1) {
+        assertTrue(previousTime < time);
+      }
+      previousTime = time;
+
+      System.out.println(uuids[i]);
+      assertEquals(7, uuids[i].version());
+    }
+
+    assertTrue(Ordering.natural().isOrdered(Arrays.asList(uuids)));
+    assertEquals(n, Set.of(uuids).size());
+  }
+
   @Test
   void convertingFromUuidAndBackToBytesEndWithTheSameResult() {
     UUID expected = UUID.randomUUID();