Add alternate version to UUIDv7 generator that uses random values on every call (not just for different timestamp) (#94)

Author: magdel

README.md

@@ -67,6 +67,7 @@ UUID uuid = Generators.nameBasedgenerator().generate("string to hash"); // Versi
 // With JUG 4.1+: support for https://github.com/uuid6/uuid6-ietf-draft versions 6 and 7:
 UUID uuid = Generators.timeBasedReorderedGenerator().generate(); // Version 6
 UUID uuid = Generators.timeBasedEpochGenerator().generate(); // Version 7
+UUID uuid = Generators.timeBasedEpochRandomGenerator().generate(); // Version 7 with per-call random values
 ```
 
 If you want customize generators, you may also just want to hold on to generator instance:

release-notes/VERSION

@@ -13,6 +13,9 @@ Releases
  (contributed by @magdel)
 #85: Fix `LazyRandom` for native code generation tools
  (contributed by @Maia-Everett)
+#94: Add alternate version to UUIDv7 generator that uses random values on every
+  call (not just for different timestamp)
+ (contributed by @magdel)
 
 4.3.0 (12-Sep-2023)
 

src/main/java/com/fasterxml/uuid/Generators.java

@@ -23,6 +23,7 @@
 import com.fasterxml.uuid.impl.NameBasedGenerator;
 import com.fasterxml.uuid.impl.RandomBasedGenerator;
 import com.fasterxml.uuid.impl.TimeBasedEpochGenerator;
+import com.fasterxml.uuid.impl.TimeBasedEpochRandomGenerator;
 import com.fasterxml.uuid.impl.TimeBasedReorderedGenerator;
 import com.fasterxml.uuid.impl.TimeBasedGenerator;
 
@@ -135,6 +136,10 @@ public static TimeBasedEpochGenerator timeBasedEpochGenerator()
      * Factory method for constructing UUID generator that generates UUID using
      * version 7 (Unix Epoch time+random based), using specified {@link Random}
      * number generator.
+     *<p>
+     * NOTE: calls within same millisecond produce very similar values; this may be
+     * unsafe in some environments.
+     *<p>
      * No additional external synchronization is used.
      */
     public static TimeBasedEpochGenerator timeBasedEpochGenerator(Random random)
@@ -145,9 +150,12 @@ public static TimeBasedEpochGenerator timeBasedEpochGenerator(Random random)
     /**
      * Factory method for constructing UUID generator that generates UUID using
      * version 7 (Unix Epoch time+random based), using specified {@link Random}
-     * number generato.
-     * Timestamp to use is accessed using specified {@link UUIDClock}
-     *
+     * number generator.
+     * Timestamp to use is accessed using specified {@link UUIDClock}.
+     *<p>
+     * NOTE: calls within same millisecond produce very similar values; this may be
+     * unsafe in some environments.
+     *<p>
      * No additional external synchronization is used.
      *
      * @since 4.3
@@ -158,6 +166,42 @@ public static TimeBasedEpochGenerator timeBasedEpochGenerator(Random random,
         return new TimeBasedEpochGenerator(random, clock);
     }
 
+    /**
+     * Factory method for constructing UUID generator that generates UUID using
+     * version 7 (Unix Epoch time+random based), using specified {@link Random}
+     * number generator.
+     *<p>
+     * Calls within same millisecond use additional per-call randomness to try to create
+     * more distinct values, compared to {@link #timeBasedEpochGenerator(Random)}
+     *<p>
+     * No additional external synchronization is used.
+     *
+     * @since 5.0
+     */
+    public static TimeBasedEpochRandomGenerator timeBasedEpochRandomGenerator(Random random)
+    {
+        return new TimeBasedEpochRandomGenerator(random);
+    }
+
+    /**
+     * Factory method for constructing UUID generator that generates UUID using
+     * version 7 (Unix Epoch time+random based), using specified {@link Random}
+     * number generator.
+     * Timestamp to use is accessed using specified {@link UUIDClock}
+     *<p>
+     * Calls within same millisecond use additional per-call randomness to try to create
+     * more distinct values, compared to {@link #timeBasedEpochGenerator(Random)}
+     *<p>
+     * No additional external synchronization is used.
+     *
+     * @since 5.0
+     */
+    public static TimeBasedEpochRandomGenerator timeBasedEpochRandomGenerator(Random random,
+            UUIDClock clock)
+    {
+        return new TimeBasedEpochRandomGenerator(random, clock);
+    }
+
     // // Time+location-based generation
 
     /**

src/main/java/com/fasterxml/uuid/Jug.java

@@ -33,6 +33,7 @@ public class Jug
         TYPES.put("name-based", "n");
         TYPES.put("reordered-time-based", "o"); // Version 6
         TYPES.put("epoch-time-based", "e"); // Version 7
+        TYPES.put("random-epoch-time-based", "m"); // Version 7 but more random
     }
 
     protected final static HashMap<String,String> OPTIONS = new HashMap<String,String>();
@@ -266,6 +267,16 @@ public static void main(String[] args)
                 noArgGenerator = Generators.timeBasedEpochGenerator(r);
             }
             break;
+        case 'm': // random-epoch-time-based
+            usesRnd = true;
+            {
+                SecureRandom r = new SecureRandom();
+                if (verbose) {
+                    System.out.print("(using secure random generator, info = '"+r.getProvider().getInfo()+"')");
+                }
+                noArgGenerator = Generators.timeBasedEpochRandomGenerator(r);
+            }
+            break;
         case 'n': // name-based
             if (nameSpace == null) {
                 System.err.println("--name-space (-s) - argument missing when using method that requires it, exiting.");

src/main/java/com/fasterxml/uuid/UUIDGenerator.java

@@ -46,4 +46,32 @@ protected UUIDGenerator() { }
      * generator instance will produce.
      */
     public abstract UUIDType getType();
+
+    /*
+    /**********************************************************
+    /* Helper methods for implementations
+    /**********************************************************
+     */
+
+    protected final static long _toLong(byte[] buffer, int offset)
+    {
+        long l1 = _toInt(buffer, offset);
+        long l2 = _toInt(buffer, offset+4);
+        long l = (l1 << 32) + ((l2 << 32) >>> 32);
+        return l;
+    }
+
+    protected final static long _toInt(byte[] buffer, int offset)
+    {
+        return (buffer[offset] << 24)
+            + ((buffer[++offset] & 0xFF) << 16)
+            + ((buffer[++offset] & 0xFF) << 8)
+            + (buffer[++offset] & 0xFF);
+    }
+
+    protected final static long _toShort(byte[] buffer, int offset)
+    {
+        return ((buffer[offset] & 0xFF) << 8)
+            + (buffer[++offset] & 0xFF);
+    }
 }

src/main/java/com/fasterxml/uuid/impl/NameBasedGenerator.java

@@ -116,7 +116,7 @@ public NameBasedGenerator(UUID namespace, MessageDigest digester, UUIDType type)
     @Override
     public UUID generate(String name)
     {
-        // !!! TODO: 14-Oct-2010, tatu: can repurpose faster UTF-8 encoding from Jackson
+        // !!! TODO: 14-Oct-2010, tatu: could re-purpose faster UTF-8 encoding from Jackson
         return generate(name.getBytes(_utf8));
     }
 

src/main/java/com/fasterxml/uuid/impl/RandomBasedGenerator.java

@@ -92,26 +92,4 @@ public UUID generate()
         }
         return UUIDUtil.constructUUID(UUIDType.RANDOM_BASED, r1, r2);
     }
-
-    /*
-    /**********************************************************************
-    /* Internal methods
-    /**********************************************************************
-     */
-
-    protected final static long _toLong(byte[] buffer, int offset)
-    {
-        long l1 = _toInt(buffer, offset);
-        long l2 = _toInt(buffer, offset+4);
-        long l = (l1 << 32) + ((l2 << 32) >>> 32);
-        return l;
-    }
-
-    private final static long _toInt(byte[] buffer, int offset)
-    {
-        return (buffer[offset] << 24)
-            + ((buffer[++offset] & 0xFF) << 16)
-            + ((buffer[++offset] & 0xFF) << 8)
-            + (buffer[++offset] & 0xFF);
-    }
 }

src/main/java/com/fasterxml/uuid/impl/TimeBasedEpochGenerator.java

@@ -144,32 +144,4 @@ public UUID construct(long rawTimestamp)
             lock.unlock();
         }
     }
-
-    /*
-    /**********************************************************************
-    /* Internal methods
-    /**********************************************************************
-     */
-
-    protected final static long _toLong(byte[] buffer, int offset)
-    {
-        long l1 = _toInt(buffer, offset);
-        long l2 = _toInt(buffer, offset+4);
-        long l = (l1 << 32) + ((l2 << 32) >>> 32);
-        return l;
-    }
-
-    private final static long _toInt(byte[] buffer, int offset)
-    {
-        return (buffer[offset] << 24)
-            + ((buffer[++offset] & 0xFF) << 16)
-            + ((buffer[++offset] & 0xFF) << 8)
-            + (buffer[++offset] & 0xFF);
-    }
-
-    private final static long _toShort(byte[] buffer, int offset)
-    {
-        return ((buffer[offset] & 0xFF) << 8)
-            + (buffer[++offset] & 0xFF);
-    }
 }

src/main/java/com/fasterxml/uuid/impl/TimeBasedEpochRandomGenerator.java

@@ -0,0 +1,129 @@
+package com.fasterxml.uuid.impl;
+
+import com.fasterxml.uuid.NoArgGenerator;
+import com.fasterxml.uuid.UUIDClock;
+import com.fasterxml.uuid.UUIDType;
+
+import java.security.SecureRandom;
+import java.util.Random;
+import java.util.UUID;
+import java.util.concurrent.locks.Lock;
+import java.util.concurrent.locks.ReentrantLock;
+
+/**
+ * Implementation of UUID generator that uses time/location based generation
+ * method field from the Unix Epoch timestamp source - the number of 
+ * milliseconds seconds since midnight 1 Jan 1970 UTC, leap seconds excluded.
+ * This is usually referred to as "Version 7".
+ * In addition to that random part is regenerated for every new UUID.
+ * This removes possibilities to have almost similar UUID, when calls
+ * to generate are made within same millisecond.
+ * <p>
+ * As all JUG provided implementations, this generator is fully thread-safe.
+ * Additionally it can also be made externally synchronized with other instances
+ * (even ones running on other JVMs); to do this, use
+ * {@link com.fasterxml.uuid.ext.FileBasedTimestampSynchronizer} (or
+ * equivalent).
+ *
+ * @since 5.0
+ */
+public class TimeBasedEpochRandomGenerator extends NoArgGenerator
+{
+    private static final int ENTROPY_BYTE_LENGTH = 10;
+
+    /*
+    /**********************************************************************
+    /* Configuration
+    /**********************************************************************
+     */
+
+    /**
+     * Random number generator that this generator uses.
+     */
+    protected final Random _random;
+
+    /**
+     * Underlying {@link UUIDClock} used for accessing current time, to use for
+     * generation.
+     */
+    protected final UUIDClock _clock;
+
+    private final byte[] _lastEntropy  = new byte[ENTROPY_BYTE_LENGTH];
+    private final Lock lock = new ReentrantLock();
+
+    /*
+    /**********************************************************************
+    /* Construction
+    /**********************************************************************
+     */
+
+    /**
+     * @param rnd Random number generator to use for generating UUIDs; if null,
+     *   shared default generator is used. Note that it is strongly recommend to
+     *   use a <b>good</b> (pseudo) random number generator; for example, JDK's
+     *   {@link SecureRandom}.
+     */
+    public TimeBasedEpochRandomGenerator(Random rnd) {
+        this(rnd, UUIDClock.systemTimeClock());
+    }
+
+    /**
+     * @param rnd Random number generator to use for generating UUIDs; if null,
+     *   shared default generator is used. Note that it is strongly recommend to
+     *   use a <b>good</b> (pseudo) random number generator; for example, JDK's
+     *   {@link SecureRandom}.
+     * @param clock clock Object used for accessing current time to use for generation
+     */
+    public TimeBasedEpochRandomGenerator(Random rnd, UUIDClock clock)
+    {
+        if (rnd == null) {
+            rnd = LazyRandom.sharedSecureRandom(); 
+        }
+        _random = rnd;
+        _clock = clock;
+    }
+
+    /*
+    /**********************************************************************
+    /* Access to config
+    /**********************************************************************
+     */
+
+    @Override
+    public UUIDType getType() { return UUIDType.TIME_BASED_EPOCH; }
+
+    /*
+    /**********************************************************************
+    /* UUID generation
+    /**********************************************************************
+     */
+
+    @Override
+    public UUID generate()
+    {
+        return construct(_clock.currentTimeMillis());
+    }
+
+    /**
+     * Method that will construct actual {@link UUID} instance for given
+     * unix epoch timestamp: called by {@link #generate()} but may alternatively be
+     * called directly to construct an instance with known timestamp.
+     * NOTE: calling this method directly produces somewhat distinct UUIDs as
+     * "entropy" value is still generated as necessary to avoid producing same
+     * {@link UUID} even if same timestamp is being passed.
+     *
+     * @param rawTimestamp unix epoch millis
+     *
+     * @return unix epoch time based UUID
+     */
+    public UUID construct(long rawTimestamp)
+    {
+        lock.lock();
+        try { 
+            _random.nextBytes(_lastEntropy);
+            return UUIDUtil.constructUUID(UUIDType.TIME_BASED_EPOCH, (rawTimestamp << 16) | _toShort(_lastEntropy, 0), _toLong(_lastEntropy, 2));
+        } finally {
+            lock.unlock();
+        }
+    }
+}

src/main/java/com/fasterxml/uuid/impl/UUIDUtil.java

@@ -362,7 +362,7 @@ private final static void _checkUUIDByteArray(byte[] bytes, int offset)
      *
      * @return timestamp in milliseconds (since Epoch), or 0 if type does not support timestamps
      *
-     * @since 5.0.0
+     * @since 5.0
      */
     public static long extractTimestamp(UUID uuid)
     {

src/test/java/com/fasterxml/uuid/UUIDComparatorTest.java

@@ -22,6 +22,7 @@
 
 import com.fasterxml.uuid.impl.TimeBasedEpochGenerator;
 
+import com.fasterxml.uuid.impl.TimeBasedEpochRandomGenerator;
 import junit.framework.TestCase;
 
 public class UUIDComparatorTest