uuidv7 monotonicity

Author: ryanwinchester

lib/ecto/uuid.ex

@@ -32,7 +32,25 @@ defmodule Ecto.UUID do
   @typedoc """
   currently supported option is version, it accepts 4 or 7.
   """
-  @type options :: [version: 4 | 7]
+  @type option ::
+          {:version, 4 | 7}
+          | {:monotonic_method, :millisecond | :increased_clock_precision}
+
+  @type options :: [option]
+
+  # The bits available for sub-millisecond fractions when using increased clock
+  # precision.
+  @sub_ms_bits 12
+
+  # The number of values that can be represented in the bit space (2^12).
+  @possible_values Bitwise.bsl(1, @sub_ms_bits)
+
+  # The number of nanoseconds in a millisecond.
+  @ns_per_ms 1_000_000
+
+  # The minimum step when using increased clock precision with fractional
+  # milliseconds.
+  @minimal_step_ns div(@ns_per_ms, @possible_values)
 
   @doc false
   def type, do: :uuid
@@ -217,10 +235,10 @@ defmodule Ecto.UUID do
   """
   @spec bingenerate(options) :: raw
   def bingenerate(opts \\ []) do
-    case Keyword.get(opts, :version, @default_version) do
-      4 -> bingenerate_v4()
-      7 -> bingenerate_v7()
-      version -> raise ArgumentError, "unknown UUID version: #{inspect(version)}"
+    case Keyword.pop(opts, :version, @default_version) do
+      {4, _opts} -> bingenerate_v4()
+      {7, opts} -> bingenerate_v7(opts)
+      {version, _} -> raise ArgumentError, "unsupported UUID version: #{inspect(version)}"
     end
   end
 
@@ -229,11 +247,79 @@ defmodule Ecto.UUID do
     <<u0::48, 4::4, u1::12, 2::2, u2::62>>
   end
 
-  defp bingenerate_v7 do
-    milliseconds = System.system_time(:millisecond)
-    <<u0::12, u1::62, _::6>> = :crypto.strong_rand_bytes(10)
+  defp bingenerate_v7(opts) do
+    # From RFC 9562:
+    # Monotonicity (each subsequent value being greater than the last) is the
+    # backbone of time-based sortable UUIDs. Normally, time-based UUIDs will be
+    # monotonic due to an embedded timestamp; however, implementations can
+    # guarantee additional monotonicity via the concepts covered in section 6.2.
+    case Keyword.get(opts, :monotonic_method) do
+      # Millisecond granularity only. No monotonic guarantee.
+      nil ->
+        milliseconds = System.system_time(:millisecond)
+        <<rand_a::12, _::6, rand_b::62>> = :crypto.strong_rand_bytes(10)
+        <<milliseconds::48, 7::4, rand_a::12, 2::2, rand_b::62>>
+
+      # For single-node UUID implementations that do not need to create
+      # batches of UUIDs, the embedded timestamp within UUIDv7 can provide
+      # sufficient monotonicity guarantees by simply ensuring that timestamp
+      # increments before creating a new UUID. (RFC9562§6.2)
+      :millisecond ->
+        milliseconds = next_ascending(:millisecond)
+        <<rand_a::12, _::6, rand_b::62>> = :crypto.strong_rand_bytes(10)
+        <<milliseconds::48, 7::4, rand_a::12, 2::2, rand_b::62>>
+
+      # Replace Leftmost Random Bits with Increased Clock Precision (RFC9562§6.2, Method 3):
+      :increased_clock_precision ->
+        nanoseconds = next_ascending(:nanosecond)
+        milliseconds = div(nanoseconds, @ns_per_ms)
+        clock_precision = (rem(nanoseconds, @ns_per_ms) * @possible_values) |> div(@ns_per_ms)
+        <<_rand_a::2, rand_b::62>> = :crypto.strong_rand_bytes(8)
+        <<milliseconds::48, 7::4, clock_precision::12, 2::2, rand_b::62>>
+
+      method ->
+        raise ArgumentError, "invalid monotonic method: #{inspect(method)}"
+    end
+  end
 
-    <<milliseconds::48, 7::4, u0::12, 2::2, u1::62>>
+  defp next_ascending(time_unit) when time_unit in [:millisecond, :nanosecond] do
+    timestamp_ref =
+      with nil <- :persistent_term.get({__MODULE__, time_unit}, nil) do
+        timestamp_ref = :atomics.new(1, signed: false)
+        :ok = :persistent_term.put({__MODULE__, time_unit}, timestamp_ref)
+        timestamp_ref
+      end
+
+    step =
+      case time_unit do
+        :millisecond -> 1
+        :nanosecond -> @minimal_step_ns
+      end
+
+    previous_ts = :atomics.get(timestamp_ref, 1)
+    min_step_ts = previous_ts + step
+    current_ts = System.system_time(time_unit)
+
+    # If the current timestamp is not at least the minimal step greater than the
+    # previous step, then we make it so.
+    new_ts =
+      if current_ts > min_step_ts do
+        current_ts
+      else
+        min_step_ts
+      end
+
+    compare_exchange(timestamp_ref, previous_ts, new_ts, step)
+  end
+
+  defp compare_exchange(timestamp_ref, previous_ts, new_ts, step) do
+    case :atomics.compare_exchange(timestamp_ref, 1, previous_ts, new_ts) do
+      # If the new value was written, then we return it.
+      :ok -> new_ts
+      # If the atomic value has changed in the meantime, we add the minimal step
+      # nanoseconds value to that and try again.
+      updated_ts -> compare_exchange(timestamp_ref, updated_ts, updated_ts + step, step)
+    end
   end
 
   # Callback invoked by autogenerate fields.