generateV7NonMonotonicAt

Версия Kotlin: 2.4

@ExperimentalUuidApi
fun generateV7NonMonotonicAt(timestamp: Instant): Uuid

Генерирует новый случайный экземпляр Uuid версии 7 для указанного момента времени.

Возвращаемый UUID — это сортируемый UUID, основанный на времени и соответствующий варианту IETF (вариант 2) и версии 7. В качестве префикса используется временная метка UNIX в миллисекундах, извлечённая из временной метки, а в качестве суффикса — случайное значение.

В отличие от generateV7, эта функция не гарантирует монотонность. Это означает, что порядок UUID, созданных двумя или более вызовами этой функции с одной и той же временной меткой, не гарантируется. Если нужны несколько UUID, соответствующих одной временной метке, рассмотрите возможность сгенерировать их с помощью этой функции, а затем отсортировать результат, прежде чем использовать его, чтобы обеспечить монотонность.

Эта функция предназначена для генерации UUID версии 7, соответствующих прошлому (или будущему). Если нужен UUID, соответствующий текущему моменту времени, всегда используйте generateV7.

Эта функция никак не влияет на состояние и гарантии монотонности generateV7. Поэтому даже если вызвать её с временной меткой из далёкого будущего, generateV7 продолжит возвращать UUID с временной меткой, соответствующей текущему моменту времени.

Случайная часть UUID генерируется с помощью доступного на платформе криптографически стойкого генератора псевдослучайных чисел (CSPRNG). Если базовая система собрала недостаточно энтропии, эта функция может заблокироваться до тех пор, пока не будет собрано достаточно энтропии и CSPRNG не будет полностью инициализирован. Стоит отметить, что используемый в целевой платформе Kotlin/WasmWasi генератор псевдослучайных чисел не гарантированно является криптографически стойким. Сведения об API, используемом для генерации случайного UUID в каждой из поддерживаемых целевых платформ, приведены ниже.

Обратите внимание, что возвращаемый UUID не рекомендуется использовать в криптографических целях. UUID версии 7 имеет частично предсказуемый битовый шаблон и использует не более 74 бит энтропии независимо от платформы.

Для генерации случайного UUID в каждой из поддерживаемых целевых платформ используются следующие API:

• Kotlin/JVM — java.security.SecureRandom

• Kotlin/JS — Crypto.getRandomValues()

• Kotlin/WasmJs — Crypto.getRandomValues()

• Kotlin/WasmWasi — random_get

• Kotlin/Native: — целевые платформы Linux — getrandom — целевые платформы Apple и Android Native — arc4random_buf — целевые платформы Windows — BCryptGenRandom

Обратите внимание, что базовый API, используемый для генерации случайных UUID, может измениться в будущем.

Исключения

Примеры

import kotlin.test.*
import kotlin.time.Instant
import kotlin.uuid.*

fun main() { 
   //sampleStart 
   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.
println("uuid1.toHexDashString().startsWith(\"01992f9f-2558-\") is ${uuid1.toHexDashString().startsWith("01992f9f-2558-")}") // true
println(uuid1.toHexDashString())

println("uuid2.toHexDashString().startsWith(\"01992f9f-2558-\") is ${uuid2.toHexDashString().startsWith("01992f9f-2558-")}") // true
println(uuid2.toHexDashString())

assertNotEquals(uuid1, uuid2) 
   //sampleEnd
}

import kotlin.test.*
import kotlin.time.Instant
import kotlin.uuid.*

fun main() { 
   //sampleStart 
   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) {
    println("uuids[idx - 1] < uuids[idx] is ${uuids[idx - 1] < uuids[idx]}") // true
} 
   //sampleEnd
}