Add UUID v4 and v7. Make v7 the default. Optimize UUID generation.

Add v4 and v7 UUIDs as per RFC9562 [1]

Use v7 as the new default instead of the previous `sequential`.

For v4 and v7 UUIDs add the `[uuids] format` setting to let users control the
encoding. These formats are supported:

  * `base_16` : (aka hex) encoding. This is the default and is the same as the
    previous (`sequential`) format.

  * `base_36` : Base 36 encoding using 0-9,a-z characters. This is the most
                compact encoding, only 25 characters long.

  * `rfc9562` : The standard RFC9562 UUID encoding, as a hex string with dashes.

The UUID v4, v7 along with the old `random` UUID types can skip calling the
`gen_server` since they do not need to keep any state. This should make the
system more robust and prevent clients from overwhelming the node with
concurrent requests to the `/_uuid` endpoint.

While at it, expand the test suite and add more coverage and also ensure to
test the sizes of the returned values.

[1] https://datatracker.ietf.org/doc/rfc9562

Author: nickva

rel/overlay/etc/default.ini

@@ -615,12 +615,23 @@ partitioned||* = true
 ;     First 14 characters are the time in hex. Last 18 are random.
 ;   utc_id - Time since Jan 1, 1970 UTC with microseconds, plus utc_id_suffix string
 ;     First 14 characters are the time in hex. uuids/utc_id_suffix string value is appended to these.
-;algorithm = sequential
+;   uuid_v7 - UUID v7. The returned format depends on the [uuids] format setting
+;   uuid_v4 - UUID v4. The returned format depends on the [uuids] format setting
+;algorithm = uuid_v7
 
 ; The utc_id_suffix value will be appended to uuids generated by the utc_id algorithm.
 ; Replicating instances should have unique utc_id_suffix values to ensure uniqueness of utc_id ids.
 ;utc_id_suffix =
 
+; Encoding format for UUID v4 and v7. The default is base_16 (aka hex). Other
+; accepted formats are "base_36" and ""rfc9562". Only v4 and v7 algorithm have
+; configurable formats, other algorithms only return base_16 encoded values.
+; Examples of the same UUID value encoded in all the supported formats:
+;   "base_16" : "0199df3759297032b402c3e61fbbf88f"
+;   "base_36" : "03eudcyamunnfraqdgmopx09b"
+;   "rfc9562" : "0199df37-5929-7032-b402-c3e61fbbf88f"
+;format = base_16
+
 ; Maximum number of UUIDs retrievable from /_uuids in a single request
 ;max_count = 1000
 

src/couch/src/couch_uuids.erl

@@ -17,13 +17,14 @@
 
 -export([start/0, stop/0]).
 -export([new/0, random/0]).
--export([v7_hex/0, v7_bin/0]).
+-export([v7_bin/0]).
 -export([init/1]).
 -export([handle_call/3, handle_cast/2, handle_info/2]).
 
 % config_listener api
 -export([handle_config_change/5, handle_config_terminate/3]).
 
+-define(DEFAULT_ALGORITHM, "uuid_v7").
 -define(RELISTEN_DELAY, 5000).
 
 start() ->
@@ -33,7 +34,13 @@ stop() ->
     gen_server:cast(?MODULE, stop).
 
 new() ->
-    gen_server:call(?MODULE, create).
+    % Some algorithms can bypass the gen_server
+    case config_algorithm() of
+        "random" -> random();
+        "uuid_v4" -> v4();
+        "uuid_v7" -> v7();
+        _ -> gen_server:call(?MODULE, create)
+    end.
 
 random() ->
     couch_util:to_hex_bin(crypto:strong_rand_bytes(16)).
@@ -42,16 +49,12 @@ init([]) ->
     ok = config:listen_for_changes(?MODULE, nil),
     {ok, state()}.
 
-handle_call(create, _From, random) ->
-    {reply, random(), random};
-handle_call(create, _From, uuid_v7) ->
-    {reply, v7_hex(), uuid_v7};
 handle_call(create, _From, {utc_random, ClockSeq}) ->
     {UtcRandom, NewClockSeq} = utc_random(ClockSeq),
     {reply, UtcRandom, {utc_random, NewClockSeq}};
 handle_call(create, _From, {utc_id, UtcIdSuffix, ClockSeq}) ->
-    Now = os:timestamp(),
-    {UtcId, NewClockSeq} = utc_suffix(UtcIdSuffix, ClockSeq, Now),
+    OsMicros = micros_since_epoch(),
+    {UtcId, NewClockSeq} = utc_suffix(UtcIdSuffix, ClockSeq, OsMicros),
     {reply, UtcId, {utc_id, UtcIdSuffix, NewClockSeq}};
 handle_call(create, _From, {sequential, Pref, Seq}) ->
     Result = ?l2b(Pref ++ io_lib:format("~6.16.0b", [Seq])),
@@ -109,10 +112,58 @@ v7_bin() ->
     <<RandA:12, RandB:62, _:6>> = crypto:strong_rand_bytes(10),
     <<MSec:48, 7:4, RandA:12, 2:2, RandB:62>>.
 
-v7_hex() ->
-    <<A:8/binary, B:4/binary, C:4/binary, D:4/binary, E:12/binary>> = couch_util:to_hex_bin(
-        v7_bin()
-    ),
+%% UUID Version 4
+%% https://www.rfc-editor.org/rfc/rfc9562#name-uuid-version-4
+%%
+%%  0                   1                   2                   3
+%%  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+%% +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+%% |                           random_a                            |
+%% +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+%% |          random_a             |  ver  |       random_b        |
+%% +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+%% |var|                       random_c                            |
+%% +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+%% |                           random_c                            |
+%% +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
+%%
+%% ver = 0100 = 4
+%% var = 10 = 2
+%%
+v4_bin() ->
+    <<A:48, B:12, C:62, _:6>> = crypto:strong_rand_bytes(16),
+    <<A:48, 4:4, B:12, 2:2, C:62>>.
+
+v7() ->
+    Bin = v7_bin(),
+    Format = config:get("uuids", "format", "base_16"),
+    uuid_format(Bin, Format).
+
+v4() ->
+    Bin = v4_bin(),
+    Format = config:get("uuids", "format", "base_16"),
+    uuid_format(Bin, Format).
+
+uuid_format(<<_:128>> = Bin, "rfc9562") ->
+    rfc9562_format(Bin);
+uuid_format(<<_:128>> = Bin, "base_36") ->
+    encode_base36(Bin);
+uuid_format(<<_:128>> = Bin, "base_16") ->
+    couch_util:to_hex_bin(Bin);
+uuid_format(<<_:128>>, Other) when is_list(Other) ->
+    error({unsupported_uuid_format, Other}).
+
+% Opt for a fixed width represention
+% 25 == length(integer_to_list(1 bsl 128 - 1, 36)).
+%
+encode_base36(<<Int:128>>) ->
+    String = integer_to_list(Int, 36),
+    Lower = string:to_lower(String),
+    iolist_to_binary(io_lib:format("~25..0s", [Lower])).
+
+rfc9562_format(<<_:128>> = Bin) ->
+    Hex = couch_util:to_hex_bin(Bin),
+    <<A:8/binary, B:4/binary, C:4/binary, D:4/binary, E:12/binary>> = Hex,
     <<A/binary, "-", B/binary, "-", C/binary, "-", D/binary, "-", E/binary>>.
 
 new_prefix() ->
@@ -122,37 +173,35 @@ inc() ->
     rand:uniform(16#ffd).
 
 state() ->
-    AlgoStr = config:get("uuids", "algorithm", "sequential"),
+    AlgoStr = config_algorithm(),
     case couch_util:to_existing_atom(AlgoStr) of
         random ->
             random;
         utc_random ->
-            ClockSeq = micros_since_epoch(os:timestamp()),
+            ClockSeq = micros_since_epoch(),
             {utc_random, ClockSeq};
         utc_id ->
-            ClockSeq = micros_since_epoch(os:timestamp()),
+            ClockSeq = micros_since_epoch(),
             UtcIdSuffix = config:get("uuids", "utc_id_suffix", ""),
             {utc_id, UtcIdSuffix, ClockSeq};
         sequential ->
             {sequential, new_prefix(), inc()};
         uuid_v7 ->
             uuid_v7;
+        uuid_v4 ->
+            uuid_v4;
         Unknown ->
             throw({unknown_uuid_algorithm, Unknown})
     end.
 
-micros_since_epoch({_, _, Micro} = Now) ->
-    Nowish = calendar:now_to_universal_time(Now),
-    Nowsecs = calendar:datetime_to_gregorian_seconds(Nowish),
-    Then = calendar:datetime_to_gregorian_seconds({{1970, 1, 1}, {0, 0, 0}}),
-    (Nowsecs - Then) * 1000000 + Micro.
+micros_since_epoch() ->
+    os:system_time(microsecond).
 
 utc_random(ClockSeq) ->
     Suffix = couch_util:to_hex(crypto:strong_rand_bytes(9)),
-    utc_suffix(Suffix, ClockSeq, os:timestamp()).
+    utc_suffix(Suffix, ClockSeq, micros_since_epoch()).
 
-utc_suffix(Suffix, ClockSeq, Now) ->
-    OsMicros = micros_since_epoch(Now),
+utc_suffix(Suffix, ClockSeq, OsMicros) when is_integer(OsMicros) ->
     NewClockSeq =
         if
             OsMicros =< ClockSeq ->
@@ -165,50 +214,70 @@ utc_suffix(Suffix, ClockSeq, Now) ->
     Prefix = io_lib:format("~14.16.0b", [NewClockSeq]),
     {list_to_binary(Prefix ++ Suffix), NewClockSeq}.
 
+config_algorithm() ->
+    config:get("uuids", "algorithm", ?DEFAULT_ALGORITHM).
+
 -ifdef(TEST).
 
 -include_lib("eunit/include/eunit.hrl").
 
 utc_id_time_does_not_advance_test() ->
     % Timestamp didn't advance but local clock sequence should and new UUIds
     % should be generated
-    Now = {0, 1, 2},
-    ClockSeq0 = micros_since_epoch({3, 4, 5}),
-    {UtcId0, ClockSeq1} = utc_suffix("", ClockSeq0, Now),
+    ClockSeq0 = 345,
+    {UtcId0, ClockSeq1} = utc_suffix("", ClockSeq0, 12),
     ?assert(is_binary(UtcId0)),
     ?assertEqual(ClockSeq0 + 1, ClockSeq1),
-    {UtcId1, ClockSeq2} = utc_suffix("", ClockSeq1, Now),
+    {UtcId1, ClockSeq2} = utc_suffix("", ClockSeq1, ClockSeq0),
     ?assertNotEqual(UtcId0, UtcId1),
     ?assertEqual(ClockSeq1 + 1, ClockSeq2).
 
 utc_id_time_advanced_test() ->
     % Timestamp advanced, a new UUID generated and also the last clock sequence
     % is updated to that timestamp.
-    Now0 = {0, 1, 2},
-    ClockSeq0 = micros_since_epoch({3, 4, 5}),
-    {UtcId0, ClockSeq1} = utc_suffix("", ClockSeq0, Now0),
+    ClockSeq0 = 345,
+    {UtcId0, ClockSeq1} = utc_suffix("", ClockSeq0, 12),
     ?assert(is_binary(UtcId0)),
     ?assertEqual(ClockSeq0 + 1, ClockSeq1),
-    Now1 = {9, 9, 9},
-    {UtcId1, ClockSeq2} = utc_suffix("", ClockSeq1, Now1),
+    ClockSeq2 = 999,
+    {UtcId1, ClockSeq3} = utc_suffix("", ClockSeq1, ClockSeq2),
     ?assert(is_binary(UtcId1)),
     ?assertNotEqual(UtcId0, UtcId1),
-    ?assertEqual(micros_since_epoch(Now1), ClockSeq2).
+    ?assertEqual(ClockSeq2, ClockSeq3).
 
 utc_random_test_time_does_not_advance_test() ->
-    {MSec, Sec, USec} = os:timestamp(),
-    Future = {MSec + 10, Sec, USec},
-    ClockSeqFuture = micros_since_epoch(Future),
+    OsMicros = os:system_time(microsecond),
+    ClockSeqFuture = OsMicros + 10_000_000,
     {UtcRandom, NextClockSeq} = utc_random(ClockSeqFuture),
     ?assert(is_binary(UtcRandom)),
     ?assertEqual(32, byte_size(UtcRandom)),
     ?assertEqual(ClockSeqFuture + 1, NextClockSeq).
 
 utc_random_test_time_advance_test() ->
-    ClockSeqPast = micros_since_epoch({1, 1, 1}),
+    ClockSeqPast = 111,
     {UtcRandom, NextClockSeq} = utc_random(ClockSeqPast),
     ?assert(is_binary(UtcRandom)),
     ?assertEqual(32, byte_size(UtcRandom)),
-    ?assert(NextClockSeq > micros_since_epoch({1000, 0, 0})).
+    ?assert(NextClockSeq > 1_000_000_000).
+
+uuid_v7_test() ->
+    Bin = v7_bin(),
+    ?assertEqual(36, byte_size(uuid_format(Bin, "rfc9562"))),
+    ?assertEqual(32, byte_size(uuid_format(Bin, "base_16"))),
+    ?assertEqual(25, byte_size(uuid_format(Bin, "base_36"))),
+    ?assertError({unsupported_uuid_format, "X"}, uuid_format(Bin, "X")),
+    Fun1 = fun(_, Acc) -> sets:add_element(v7_bin(), Acc) end,
+    Set1 = lists:foldl(Fun1, couch_util:new_set(), lists:seq(1, 10_000)),
+    ?assertEqual(10_000, sets:size(Set1)).
+
+uuid_v4_test() ->
+    Bin = v4_bin(),
+    ?assertEqual(36, byte_size(uuid_format(Bin, "rfc9562"))),
+    ?assertEqual(32, byte_size(uuid_format(Bin, "base_16"))),
+    ?assertEqual(25, byte_size(uuid_format(Bin, "base_36"))),
+    ?assertError({unsupported_uuid_format, "X"}, uuid_format(Bin, "X")),
+    Fun1 = fun(_, Acc) -> sets:add_element(v7_bin(), Acc) end,
+    Set1 = lists:foldl(Fun1, couch_util:new_set(), lists:seq(1, 10_000)),
+    ?assertEqual(10_000, sets:size(Set1)).
 
 -endif.