updating uuidv7 options

Author: ryanwinchester

lib/ecto/application.ex

@@ -3,6 +3,9 @@ defmodule Ecto.Application do
   use Application
 
   def start(_type, _args) do
+    :ok = :persistent_term.put({Ecto.UUID, :millisecond}, :atomics.new(1, signed: false))
+    :ok = :persistent_term.put({Ecto.UUID, :nanosecond}, :atomics.new(1, signed: false))
+
     children = [
       Ecto.Repo.Registry
     ]

lib/ecto/uuid.ex

@@ -34,23 +34,21 @@ defmodule Ecto.UUID do
   """
   @type option ::
           {:version, 4 | 7}
-          | {:monotonic_method, :millisecond | :increased_clock_precision}
+          | {:precision, :millisecond | :nanosecond}
+          | {:monotonic, boolean()}
 
   @type options :: [option]
 
   # The bits available for sub-millisecond fractions when using increased clock
-  # precision.
-  @sub_ms_bits 12
-
+  # precision based on nanoseconds.
+  @ns_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)
-
+  @ns_possible_values Bitwise.bsl(1, @ns_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)
+  # milliseconds based on nanoseconds.
+  @ns_minimal_step div(@ns_per_ms, @ns_possible_values)
 
   @doc false
   def type, do: :uuid
@@ -248,52 +246,53 @@ defmodule Ecto.UUID do
   end
 
   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)
+    time_unit = Keyword.get(opts, :precision, :millisecond)
+    monotonic = Keyword.get(opts, :monotonic, false)
+
+    case {time_unit, monotonic} do
+      {:millisecond, _monotonic = true} ->
+        unix_ts_ms = 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>>
+        <<unix_ts_ms::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)
+      {:millisecond, _monotonic = false} ->
+        unix_ts_ms = 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>>
+        <<unix_ts_ms::48, 7::4, rand_a::12, 2::2, rand_b::62>>
+
+      {:nanosecond, _monotonic = true} ->
+        unix_ts_ns = next_ascending(:nanosecond)
+        milliseconds = div(unix_ts_ns, @ns_per_ms)
 
-      # 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)
+        clock_precision =
+          (rem(unix_ts_ns, @ns_per_ms) * @ns_possible_values) |> div(@ns_per_ms)
+
+        <<rand_b::62, _::2>> = :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)}"
+      {:nanosecond, _monotonic = false} ->
+        unix_ts_ns = System.system_time(:nanosecond)
+        milliseconds = div(unix_ts_ns, @ns_per_ms)
+        nanoseconds = rem(unix_ts_ns, @ns_per_ms)
+
+        milliseconds =
+          if nanoseconds > @ns_possible_values, do: milliseconds + 1, else: milliseconds
+
+        <<rand_a::12, _::6, rand_b::62>> = :crypto.strong_rand_bytes(10)
+        <<milliseconds::48, 7::4, rand_a::12, 2::2, rand_b::62>>
+
+      {_time_unit, _monotonic} ->
+        raise ArgumentError, "unsupported options: #{inspect(opts)}"
     end
   end
 
   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
+    timestamp_ref = :persistent_term.get({__MODULE__, time_unit}, nil)
 
     step =
       case time_unit do
         :millisecond -> 1
-        :nanosecond -> @minimal_step_ns
+        :nanosecond -> @ns_minimal_step
       end
 
     previous_ts = :atomics.get(timestamp_ref, 1)