Add UUID built-in convenience type to SpacetimeDB (#3538)

# Description of Changes

Closes
[#3290](#3290).

Adds a new "special" type to SATS, `UUID`, which is represented as the
product `{ __uuid__: u128 }`. Adds versions of this type to all of our
various languages' module bindings libraries and client SDKs, and
updates codegen to recognize it and output references to those named
library types. Adds methods for creating new UUIDs according to the V4
(all random) and V7 (timestamp, monotonic counter and random)
specifications.

# API and ABI breaking changes

We add a new type 

# Expected complexity level and risk

2

it impacts all over the code

# Testing

- [x] Extends the Rust and Unreal SDK tests, and the associated
`module-test` modules in Rust, C# and TypeScript, with uses of UUIDs.
- [x] Extends the C# SDK regression tests with uses of UUIDs.
- [x] Extends the TypeScript test suite with tests with uses of UUIDs.

---------

Signed-off-by: Mario Montoya <mamcx@elmalabarista.com>
Co-authored-by: Phoebe Goldman <phoebe@clockworklabs.io>
Co-authored-by: Jason Larabie <jason@clockworklabs.io>
Co-authored-by: John Detter <4099508+jdetter@users.noreply.github.com>

Author: 4 people

Cargo.lock

@@ -307,7 +307,7 @@ unicode-ident = "1.0.12"
 unicode-normalization = "0.1.23"
 url = "2.3.1"
 urlencoding = "2.1.2"
-uuid = { version = "1.18.1", features = ["v4"] }
+uuid = { version = "1.18.1", default-features = false }
 v8 = "140.2"
 walkdir = "2.2.5"
 wasmbin = "0.6"

Cargo.toml

@@ -1,6 +1,7 @@
 namespace SpacetimeDB;
 
 using System.Diagnostics.CodeAnalysis;
+using System.Security.Cryptography;
 using CsCheck;
 using SpacetimeDB.BSATN;
 using Xunit;
@@ -848,4 +849,126 @@ public static void GeneratedEnumEqualsWorks()
             iter: 10_000
         );
     }
+
+    [Fact]
+    public static void UUidRoundTrip()
+    {
+        var u1 = Uuid.NIL;
+        var s = u1.ToString();
+        var u2 = Uuid.Parse(s);
+        Assert.Equal(u1, u2);
+        Assert.Equal(u1.ToGuid(), u2.ToGuid());
+        Assert.Equal(s, u2.ToString());
+    }
+
+    [Fact]
+    public static void UuidToString()
+    {
+        foreach (
+            var uuid in new[]
+            {
+                Uuid.NIL,
+                new Uuid(new U128(0x0102030405060708UL, 0x090A0B0C0D0E0F10UL)),
+                Uuid.MAX,
+            }
+        )
+        {
+            var s = uuid.ToString();
+            var uuid2 = Uuid.Parse(s);
+            Assert.Equal(uuid, uuid2);
+            var g = new Guid(s);
+            Assert.Equal(s, g.ToString()); // same canonical form
+        }
+    }
+
+    [Fact]
+    public static void WrapAround()
+    {
+        // Check wraparound behavior
+        var counter = int.MaxValue;
+        var ts = Timestamp.UNIX_EPOCH;
+
+        _ = Uuid.FromCounterV7(ref counter, ts, new byte[4]);
+
+        Assert.Equal(0, counter);
+    }
+
+    [Fact]
+    public static void NegativeTimestampThrows()
+    {
+        var counter = 0;
+        var ts = new Timestamp(-1);
+
+        var ex = Assert.Throws<ArgumentException>(
+            () => Uuid.FromCounterV7(ref counter, ts, new byte[4])
+        );
+
+        Assert.Contains("timestamp", ex.Message, StringComparison.OrdinalIgnoreCase);
+    }
+
+    [Fact]
+    public static void UuidOrdered()
+    {
+        var u1 = new Uuid(new U128(1, 0));
+        var u2 = new Uuid(new U128(2, 0));
+
+        Assert.True(u1 < u2);
+        Assert.True(u2 > u1);
+        Assert.Equal(u1, u1);
+        Assert.NotEqual(u1, u2);
+
+        // Check we start from zero
+        var counter = 0;
+        var ts = Timestamp.UNIX_EPOCH;
+
+        var uStart = Uuid.FromCounterV7(ref counter, ts, new byte[4]);
+        Assert.Equal(0, uStart.GetCounter());
+
+        // Check ordering across many UUIDs
+        const int total = 10_000_000;
+        counter = int.MaxValue - total;
+
+        var uuids = Enumerable
+            .Range(0, 1000)
+            .Select(_ =>
+            {
+                var bytes = new byte[4];
+                RandomNumberGenerator.Fill(bytes);
+                return Uuid.FromCounterV7(ref counter, ts, bytes);
+            })
+            .ToList();
+
+        for (var i = 0; i < uuids.Count - 1; i++)
+        {
+            var a = uuids[i];
+            var b = uuids[i + 1];
+
+            Assert.Equal(Uuid.UuidVersion.V7, a.GetVersion());
+
+            Assert.True(a < b, $"UUIDs are not ordered at {i}: {a} !< {b}");
+            Assert.True(
+                a.GetCounter() < b.GetCounter(),
+                $"UUID counters are not ordered at {i}: {a.GetCounter()} !< {b.GetCounter()}"
+            );
+        }
+    }
+
+    [Fact]
+    public static void UuidVersion()
+    {
+        var u = Uuid.NIL;
+        Assert.Equal(Uuid.UuidVersion.Nil, u.GetVersion());
+
+        u = Uuid.MAX;
+        Assert.Equal(Uuid.UuidVersion.Max, u.GetVersion());
+
+        var randomBytes = new byte[16];
+        RandomNumberGenerator.Fill(randomBytes);
+        u = Uuid.FromRandomBytesV4(randomBytes);
+        Assert.Equal(Uuid.UuidVersion.V4, u.GetVersion());
+
+        var counter = 0;
+        u = Uuid.FromCounterV7(ref counter, Timestamp.UNIX_EPOCH, randomBytes.AsSpan()[..4]);
+        Assert.Equal(Uuid.UuidVersion.V7, u.GetVersion());
+    }
 }

crates/bindings-csharp/BSATN.Runtime.Tests/Tests.cs

@@ -3,6 +3,7 @@
 
 namespace SpacetimeDB;
 
+using System.Buffers.Binary;
 using System.Numerics;
 using System.Runtime.InteropServices;
 
@@ -33,6 +34,33 @@ public U128(ulong upper, ulong lower)
 
     internal ulong Upper => _upper;
 
+    /// Returns a <see cref="U128" /> from a big-endian byte array.
+    public static U128 FromBytesBigEndian(ReadOnlySpan<byte> bytes)
+    {
+        if (bytes.Length != Size)
+        {
+            throw new ArgumentException(
+                $"Byte array must be exactly {Size} bytes long.",
+                nameof(bytes)
+            );
+        }
+
+        var upper = BinaryPrimitives.ReadUInt64BigEndian(bytes.Slice(0, 8));
+        var lower = BinaryPrimitives.ReadUInt64BigEndian(bytes.Slice(8, 8));
+
+        return new U128(upper, lower);
+    }
+
+    public byte[] ToBytesBigEndian()
+    {
+        var bytes = new byte[Size];
+
+        BinaryPrimitives.WriteUInt64BigEndian(bytes.AsSpan(0, 8), _upper);
+        BinaryPrimitives.WriteUInt64BigEndian(bytes.AsSpan(8, 8), _lower);
+
+        return bytes;
+    }
+
     /// <inheritdoc cref="IComparable.CompareTo(object)" />
     public int CompareTo(object? value)
     {
@@ -90,4 +118,11 @@ private BigInteger AsBigInt() =>
 
     /// <inheritdoc cref="object.ToString()" />
     public override string ToString() => AsBigInt().ToString();
+
+    public static U128 FromGuid(Guid guid)
+    {
+        Span<byte> bytes = stackalloc byte[16];
+        guid.TryWriteBytes(bytes);
+        return FromBytesBigEndian(bytes);
+    }
 }