KT-81092 Add a function to generate V7 Uuids for a given timestamp

^KT-81092 Fixed

Merge-request: KT-MR-23496
Merged-by: Filipp Zhinkin <[email protected]>

Author: fzhinkin

libraries/stdlib/samples/test/samples/uuid/uuid.kt

@@ -7,6 +7,7 @@ package samples.uuid
 
 import samples.*
 import kotlin.test.*
+import kotlin.time.Instant
 import kotlin.uuid.*
 
 @OptIn(ExperimentalUuidApi::class)
@@ -256,6 +257,36 @@ class Uuids {
         assertPrints(uuid2 < uuid3, "true")
     }
 
+    @Sample
+    fun v7NonMonotonicAt() {
+        val timestamp = Instant.fromEpochMilliseconds(1757440583000L)
+
+        val uuid1 = Uuid.generateV7NonMonotonicAt(timestamp)
+        val uuid2 = Uuid.generateV7NonMonotonicAt(timestamp)
+
+        // Uuids have the same timestamp prefix (01992f9f-2558-, which corresponds to 1757440583000 in hex),
+        // but other bytes are different.
+        assertTrue(uuid1.toHexDashString().startsWith("01992f9f-2558-"))
+        println(uuid1.toHexDashString())
+
+        assertTrue(uuid2.toHexDashString().startsWith("01992f9f-2558-"))
+        println(uuid2.toHexDashString())
+
+        assertNotEquals(uuid1, uuid2)
+    }
+
+    @Sample
+    fun v7ForTimestampSorted() {
+        val timestamp = Instant.fromEpochMilliseconds(1757440583000L)
+
+        // Generate 5 uuids for the same timestamp, and them explicitly sort them to ensure monotonicity
+        val uuids = sequence<Uuid> { Uuid.generateV7NonMonotonicAt(timestamp) }.take(5).sorted().toList()
+
+        for (idx in 1..<uuids.size) {
+            assertTrue(uuids[idx - 1] < uuids[idx])
+        }
+    }
+
     @Sample
     fun compareTo() {
         val uuid1 = Uuid.parse("49d6d991-c780-4eb5-8585-5169c25af912")

libraries/stdlib/src/kotlin/uuid/Uuid.kt

@@ -19,6 +19,7 @@ import kotlin.internal.ReadObjectParameterType
 import kotlin.internal.throwReadObjectNotSupported
 import kotlin.time.Clock
 import kotlin.time.ExperimentalTime
+import kotlin.time.Instant
 
 /**
  * Represents a Universally Unique Identifier (UUID), also known as a Globally Unique Identifier (GUID).
@@ -669,6 +670,77 @@ public class Uuid private constructor(
         @OptIn(ExperimentalTime::class)
         public fun generateV7(): Uuid = generateV7(Clock.System)
 
+        /**
+         * Generates a new random [Uuid] Version 7 instance for a specified [moment in time][timestamp].
+         *
+         * The returned uuid is a time-based sortable UUID that conforms to the
+         * [IETF variant (variant 2)](https://www.rfc-editor.org/rfc/rfc9562.html#section-4.1)
+         * and [version 7](https://www.rfc-editor.org/rfc/rfc9562.html#section-4.2),
+         * uses UNIX timestamp in milliseconds extracted from [timestamp] as a prefix and a randomly generated suffix.
+         *
+         * Unlike [generateV7], this function does not provide any monotonicity guarantees, meaning that there will be no guaranteed order
+         * for uuids created by calling this function two or more times with exactly the same [timestamp].
+         * If multiple uuids corresponding to the same timestamp are needed, consider generating them using this function,
+         * then sorting the result before using it to achieve the monotonicity.
+         *
+         * This function is aimed for generating v7 uuids corresponding to the past (or the future).
+         * Always consider using [generateV7] if an uuid corresponding to a current moment in time in needed.
+         *
+         * This function does not affect the state and monotonicity guarantees of [generateV7] in any way,
+         * so even if it is invoked with a timestamp from a distant future,
+         * [generateV7] will continue returning uuids with a timestamp corresponding to a current moment in time.
+         *
+         * The random part of the uuid is produced using a cryptographically secure pseudorandom number generator (CSPRNG)
+         * available on the platform.
+         * If the underlying system has not collected enough entropy, this function
+         * may block until sufficient entropy is collected, and the CSPRNG is fully initialized.
+         * It is worth mentioning
+         * that the PRNG used in the Kotlin/WasmWasi target is not guaranteed to be cryptographically secure.
+         * See the list below for details about the API used for producing the random uuid in each supported target.
+         *
+         * Note that the returned uuid is not recommended for use for cryptographic purposes.
+         * Because version 7 uuid has a partially predictable bit pattern, and utilizes at most
+         * 74 bits of entropy, regardless of platform.
+         *
+         * The following APIs are used for producing the random uuid in each of the supported targets:
+         *   - Kotlin/JVM - [java.security.SecureRandom](https://docs.oracle.com/javase/8/docs/api/java/security/SecureRandom.html)
+         *   - Kotlin/JS - [Crypto.getRandomValues()](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues)
+         *   - Kotlin/WasmJs - [Crypto.getRandomValues()](https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues)
+         *   - Kotlin/WasmWasi - [random_get](https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/docs.md#random_get)
+         *   - Kotlin/Native:
+         *       - Linux targets - [getrandom](https://www.man7.org/linux/man-pages/man2/getrandom.2.html)
+         *       - Apple and Android Native targets - [arc4random_buf](https://man7.org/linux/man-pages/man3/arc4random_buf.3.html)
+         *       - Windows targets - [BCryptGenRandom](https://learn.microsoft.com/en-us/windows/win32/api/bcrypt/nf-bcrypt-bcryptgenrandom)
+         *
+         * Note that the underlying API used to produce random uuids may change in the future.
+         *
+         * @return A randomly generated uuid.
+         * @throws RuntimeException if the underlying API fails. Refer to the corresponding underlying API
+         *   documentation for possible reasons for failure and guidance on how to handle them.
+         *
+         * @sample samples.uuid.Uuids.v7NonMonotonicAt
+         * @sample samples.uuid.Uuids.v7ForTimestampSorted
+         */
+        @SinceKotlin("2.3")
+        @ExperimentalTime
+        public fun generateV7NonMonotonicAt(timestamp: Instant): Uuid {
+            val randomBytes = ByteArray(10).also {
+                secureRandomBytes(it)
+            }
+
+            val verAndRandA = randomBytes[8].toInt().and(0x0F).or(0x70).shl(8)
+                .or(randomBytes[9].toInt().and(0xFF))
+
+            val tsVerAndRandA = timestamp.toEpochMilliseconds().shl(16).or(verAndRandA.toLong())
+
+            randomBytes[0] = randomBytes[0]
+                .and(0x3F) // clear two MSBs
+                .or(0x80.toByte()) // set then to 0b10
+            val varAndRandB = randomBytes.getLongAt(0)
+
+            return fromLongs(tsVerAndRandA, varAndRandB)
+        }
+
         @OptIn(ExperimentalTime::class)
         internal fun generateV7(clock: Clock): Uuid = UuidV7Generator.generate(clock)
 

libraries/stdlib/test/uuid/UuidTest.kt

@@ -461,6 +461,26 @@ class UuidTest {
         }
     }
 
+    @Test
+    fun testV7GenerateUnordered() {
+        val uuid = Uuid.generateV7NonMonotonicAt(Instant.fromEpochMilliseconds(0L))
+
+        assertEquals(7, uuid.version, "Generated Uuid has a wrong version: ${uuid.toHexDashString()}")
+        assertTrue(uuid.isIetfVariant, "Generated Uuid has a wrong variant: ${uuid.toHexDashString()}")
+        uuid.toLongs { msb, _ ->
+            assertEquals(msb.shr(16), 0L, "Timestamp field has a wrong value")
+        }
+
+        val anotherUuid = Uuid.generateV7NonMonotonicAt(Instant.fromEpochMilliseconds(0L))
+        assertNotEquals(uuid, anotherUuid, "Two uuids generated for the same timestamp should not be equal")
+
+        val tsValue = 1757440583123L
+        val nonZeroTs = Uuid.generateV7NonMonotonicAt(Instant.fromEpochMilliseconds(tsValue))
+        nonZeroTs.toLongs { msb, _ ->
+            assertEquals(msb.shr(16), tsValue, "Timestamp field has a wrong value")
+        }
+    }
+
     private class NonMonotonicClock : Clock {
         private var currentTime = Clock.System.now()
 

libraries/tools/binary-compatibility-validator/klib-public-api/kotlin-stdlib.api

@@ -2112,6 +2112,7 @@ final class kotlin.uuid/Uuid : kotlin.io/Serializable, kotlin/Comparable<kotlin.
         final fun fromULongs(kotlin/ULong, kotlin/ULong): kotlin.uuid/Uuid // kotlin.uuid/Uuid.Companion.fromULongs|fromULongs(kotlin.ULong;kotlin.ULong){}[0]
         final fun generateV4(): kotlin.uuid/Uuid // kotlin.uuid/Uuid.Companion.generateV4|generateV4(){}[0]
         final fun generateV7(): kotlin.uuid/Uuid // kotlin.uuid/Uuid.Companion.generateV7|generateV7(){}[0]
+        final fun generateV7NonMonotonicAt(kotlin.time/Instant): kotlin.uuid/Uuid // kotlin.uuid/Uuid.Companion.generateV7NonMonotonicAt|generateV7NonMonotonicAt(kotlin.time.Instant){}[0]
         final fun parse(kotlin/String): kotlin.uuid/Uuid // kotlin.uuid/Uuid.Companion.parse|parse(kotlin.String){}[0]
         final fun parseHex(kotlin/String): kotlin.uuid/Uuid // kotlin.uuid/Uuid.Companion.parseHex|parseHex(kotlin.String){}[0]
         final fun parseHexDash(kotlin/String): kotlin.uuid/Uuid // kotlin.uuid/Uuid.Companion.parseHexDash|parseHexDash(kotlin.String){}[0]

libraries/tools/binary-compatibility-validator/reference-public-api/kotlin-stdlib-runtime-merged.txt

@@ -6496,6 +6496,7 @@ public final class kotlin/uuid/Uuid$Companion {
 	public final fun fromULongs-eb3DHEI (JJ)Lkotlin/uuid/Uuid;
 	public final fun generateV4 ()Lkotlin/uuid/Uuid;
 	public final fun generateV7 ()Lkotlin/uuid/Uuid;
+	public final fun generateV7NonMonotonicAt (Lkotlin/time/Instant;)Lkotlin/uuid/Uuid;
 	public final fun getLEXICAL_ORDER ()Ljava/util/Comparator;
 	public final fun getNIL ()Lkotlin/uuid/Uuid;
 	public final fun parse (Ljava/lang/String;)Lkotlin/uuid/Uuid;