hyperuuid 0.2.1 → 0.4.0

data/lib/hyperuuid/runtime.rb

@@ -12,8 +12,18 @@ module HyperUuid
   # files are already plain files on disk once installed — native/{rid}/{lib} can be
   # dlopen'd directly, no extraction step needed.
   module Runtime
-    class RandomSourceError < StandardError; end
-    class TimestampOutOfRangeError < StandardError; end
+    # The package's two exceptions live on HyperUuid itself (errors.rb). These are the names
+    # they had through 0.3.0, kept as aliases of the very same classes so a
+    # `rescue HyperUuid::Runtime::TimestampOutOfRangeError` written against an earlier
+    # release still catches.
+    RandomSourceError = HyperUuid::RandomSourceError
+    TimestampOutOfRangeError = HyperUuid::TimestampOutOfRangeError
+
+    # One copy of each out-of-range message for the Fiddle and wasm backends and for the
+    # doors' own range check in hyperuuid.rb; the Magnus extension (rust/src/ruby_ext.rs)
+    # carries the same text, and spec/native_backend_spec.rb pins that the two agree.
+    V6_TIMESTAMP_OUT_OF_RANGE = "unix_millis does not fit the 60-bit v6 timestamp field"
+    V7_TIMESTAMP_OUT_OF_RANGE = "unix_millis must fit within the RFC 9562 48-bit field"
 
     NATIVE_DIR = File.join(__dir__, "native")
 
@@ -24,17 +34,18 @@ module HyperUuid
       def new_v4
         out = scratch
         rc = functions[:new_v4].call(out)
-        raise RandomSourceError, "uuid_new_v4 failed with code #{rc}" unless rc.zero?
+        raise random_source_failure("uuid_new_v4") unless rc.zero?
         out[0, 16]
       end
 
       def new_v5(namespace_bytes, name_bytes)
         out = scratch
-        # Fiddle passes a String's bytes for void* directly (read-only) — no Pointer
-        # wrapper, no copy — the same zero-copy crossing every other input here uses.
-        name = name_bytes.empty? ? nil : name_bytes
-        rc = functions[:new_v5].call(namespace_bytes, name, name_bytes.bytesize, out)
-        raise RandomSourceError, "uuid_new_v5 failed with code #{rc}" unless rc.zero?
+        # Fiddle passes a String's own bytes for void* (read-only, no copy of them) — the
+        # same crossing every other input here uses. An empty name crosses as it is, a
+        # valid pointer with length 0, never as nil: NULL is not part of this export's
+        # contract.
+        rc = functions[:new_v5].call(namespace_bytes, name_bytes, name_bytes.bytesize, out)
+        raise random_source_failure("uuid_new_v5") unless rc.zero?
         out[0, 16]
       end
 
@@ -43,8 +54,8 @@ module HyperUuid
         rc = functions[:new_v6].call(unix_millis, out)
         case rc
         when 0 then out[0, 16]
-        when 2 then raise TimestampOutOfRangeError, "unix_millis does not fit the 60-bit v6 timestamp field"
-        else raise RandomSourceError, "uuid_new_v6 failed with code #{rc}"
+        when 2 then raise TimestampOutOfRangeError, V6_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v6")
         end
       end
 
@@ -58,8 +69,8 @@ module HyperUuid
         rc = functions[:new_v6_batch].call(unix_millis, count, out)
         case rc
         when 0 then out[0, count * 16]
-        when 2 then raise TimestampOutOfRangeError, "unix_millis does not fit the 60-bit v6 timestamp field"
-        else raise RandomSourceError, "uuid_new_v6_batch failed with code #{rc}"
+        when 2 then raise TimestampOutOfRangeError, V6_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v6_batch")
         end
       end
 
@@ -68,8 +79,8 @@ module HyperUuid
         rc = functions[:new_v7].call(unix_millis, out)
         case rc
         when 0 then out[0, 16]
-        when 2 then raise TimestampOutOfRangeError, "unix_millis must fit within the RFC 9562 48-bit field"
-        else raise RandomSourceError, "uuid_new_v7 failed with code #{rc}"
+        when 2 then raise TimestampOutOfRangeError, V7_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v7")
         end
       end
 
@@ -83,8 +94,8 @@ module HyperUuid
         rc = functions[:new_v7_batch].call(unix_millis, count, out)
         case rc
         when 0 then out[0, count * 16]
-        when 2 then raise TimestampOutOfRangeError, "unix_millis must fit within the RFC 9562 48-bit field"
-        else raise RandomSourceError, "uuid_new_v7_batch failed with code #{rc}"
+        when 2 then raise TimestampOutOfRangeError, V7_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v7_batch")
         end
       end
 
@@ -104,8 +115,44 @@ module HyperUuid
         rewrite(:v6_to_rfc_order, bytes)
       end
 
+      # The loaded core's version word, major << 16 | minor << 8 | patch, straight from the
+      # library's zero-argument hyperuuid_version export. HyperUuid.native_version unpacks
+      # it; like every method here, each backend replaces this one in place.
+      def packed_version
+        functions[:version].call
+      end
+
+      # The one failure every generating export shares, with the one message every backend
+      # raises for it: the export's name, and that the system's random source failed.
+      def random_source_failure(export)
+        RandomSourceError.new("#{export}: the system random source failed")
+      end
+
+      # Whether this platform has a shared library for Fiddle to dlopen at all: a known RID
+      # and the file actually present — in this install, or in the in-repo cargo build the
+      # dev loop falls back to. Backend selection (hyperuuid.rb) asks this before falling
+      # back to the WebAssembly backend, which needs neither.
+      def fiddle_library_available?
+        !library_path.nil?
+      rescue NativePlatform::UnsupportedPlatformError
+        false
+      end
+
       private
 
+      # The shared library to dlopen: this install's native/{rid}/{lib}, or — the
+      # development loop — the in-repo cargo build, exactly what the other bindings' local
+      # staging does (HyperCast's runtime has had this since its first release). Nil when
+      # neither exists.
+      def library_path
+        rid, lib_name = NativePlatform.rid_and_library_name
+        path = File.join(NATIVE_DIR, rid, lib_name)
+        return path if File.exist?(path)
+
+        repo_build = File.expand_path(File.join(__dir__, "../../../rust/target/release", lib_name))
+        File.exist?(repo_build) ? repo_build : nil
+      end
+
       # One 16-byte scratch allocation per thread, reused by every single-item call —
       # Fiddle::Pointer.malloc(..., RUBY_FREE) registers a GC finalizer per call, measured
       # (in HyperCast, same mechanism) as the dominant per-call cost by an order of
@@ -132,11 +179,12 @@ module HyperUuid
       end
 
       def load_functions
-        rid, lib_name = NativePlatform.rid_and_library_name
-        path = File.join(NATIVE_DIR, rid, lib_name)
-        unless File.exist?(path)
+        path = library_path
+        if path.nil?
+          rid, lib_name = NativePlatform.rid_and_library_name
           raise LoadError,
-                "hyperuuid: #{path} not found (unsupported platform, or this gem was built without a native library for it)"
+                "hyperuuid: #{File.join(NATIVE_DIR, rid, lib_name)} not found (unsupported " \
+                "platform, or this gem was built without a native library for it)"
         end
 
         handle = Fiddle.dlopen(path)
@@ -197,6 +245,8 @@ module HyperUuid
             [Fiddle::TYPE_VOIDP],
             Fiddle::TYPE_VOID
           ),
+          # The one export that mints nothing: the zero-argument version probe.
+          version: Fiddle::Function.new(handle["hyperuuid_version"], [], Fiddle::TYPE_UINT32_T),
         }
       end
     end

data/lib/hyperuuid/uuid.rb

@@ -9,12 +9,22 @@ module HyperUuid
     # The UUID's 16 raw bytes in RFC 9562 (big-endian) order.
     attr_reader :bytes
 
-    # Wraps a raw 16-byte RFC 9562 (big-endian) UUID value.
+    # Wraps a raw 16-byte RFC 9562 (big-endian) UUID value. The bytes are copied, so the
+    # String passed in stays the caller's.
+    #
+    # +owned+ is for this gem's own use: it says +bytes+ is a String the native core has
+    # just produced — sixteen bytes, already ASCII-8BIT, held by nothing else — so there is
+    # nothing to check, copy or re-tag, and that copy is most of what constructing one costs.
     #
     # @raise [ArgumentError] if +bytes+ isn't exactly 16 bytes.
-    def initialize(bytes)
-      raise ArgumentError, "bytes must be exactly 16 bytes" unless bytes.bytesize == 16
-      @bytes = bytes.dup.force_encoding(Encoding::BINARY).freeze
+    def initialize(bytes, owned = false)
+      if owned
+        @bytes = bytes.freeze
+      else
+        raise ArgumentError, "bytes must be exactly 16 bytes" unless bytes.bytesize == 16
+
+        @bytes = bytes.dup.force_encoding(Encoding::BINARY).freeze
+      end
     end
 
     # The RFC 9562 §5.9 Nil UUID — all 128 bits zero.
@@ -23,13 +33,22 @@ module HyperUuid
     # The RFC 9562 §5.10 Max UUID — all 128 bits one.
     MAX = new(("\xFF" * 16).b).freeze
 
-    # Parses an 8-4-4-4-12 hyphenated hex UUID string.
+    # The one text shape .parse accepts: 8-4-4-4-12 hex digits, either case, the four hyphens
+    # exactly where #to_s puts them.
+    HYPHENATED = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/
+    private_constant :HYPHENATED
+
+    # Parses an 8-4-4-4-12 hyphenated hex UUID string — exactly the shape #to_s produces, in
+    # either case. Nothing else parses: not the bare 32 hex digits, not hyphens anywhere but
+    # those four positions, not braces or a `urn:uuid:` prefix.
     #
-    # @raise [ArgumentError] if +string+ isn't a valid UUID string.
+    # @raise [ArgumentError] if +string+ isn't a String in that shape.
     def self.parse(string)
-      hex = string.delete("-")
-      raise ArgumentError, "invalid UUID string: #{string.inspect}" unless hex.match?(/\A[0-9a-fA-F]{32}\z/)
-      new([hex].pack("H*"))
+      unless string.is_a?(String) && string.match?(HYPHENATED)
+        raise ArgumentError, "invalid UUID string: #{string.inspect}"
+      end
+
+      new([string.delete("-")].pack("H*"))
     end
 
     # The RFC 9562 version nibble (bits 48-51, the high nibble of octet 6).
@@ -100,8 +119,8 @@ module HyperUuid
     # Meaningful only for a genuine version 6 or 7 UUID.
     def to_sql_order
       case version
-      when 7 then self.class.new(Runtime.v7_to_sql_order(bytes))
-      when 6 then self.class.new(Runtime.v6_to_sql_order(bytes))
+      when 7 then self.class.new(Runtime.v7_to_sql_order(bytes), true)
+      when 6 then self.class.new(Runtime.v6_to_sql_order(bytes), true)
       else raise ArgumentError, "to_sql_order is only defined for version 6 or 7 UUIDs, got version #{version}"
       end
     end
@@ -127,9 +146,9 @@ module HyperUuid
       octet8_version = (bytes.getbyte(8) >> 4) & 0x0F
       octet7_version = (bytes.getbyte(7) >> 4) & 0x0F
       if octet8_version == 6
-        self.class.new(Runtime.v6_to_rfc_order(bytes))
+        self.class.new(Runtime.v6_to_rfc_order(bytes), true)
       elsif octet7_version == 7
-        self.class.new(Runtime.v7_to_rfc_order(bytes))
+        self.class.new(Runtime.v7_to_rfc_order(bytes), true)
       else
         raise ArgumentError, "from_sql_order: not a recognized version 6 or 7 SQL-ordered UUID"
       end

data/lib/hyperuuid/wasm_runtime.rb

@@ -0,0 +1,259 @@
+require "wasmtime"
+
+module HyperUuid
+  # The WebAssembly backend: the same Rust core, compiled once to a `wasm32-wasip1` module
+  # (lib/hyperuuid/native/wasm32-wasip1/hyperuuid.wasm) and run inside this process by the
+  # `wasmtime` gem — no per-platform shared library needed, and nothing dlopen'd. This is the
+  # inverse of ruby.wasm: not Ruby running inside a wasm sandbox, but a wasm module running
+  # inside Ruby.
+  #
+  # Same integration shape as the Magnus extension: on require (after runtime.rb has defined
+  # the Fiddle backend) this redefines the `HyperUuid::Runtime` singleton methods **in place**
+  # — no delegation layer, no second surface. Everything above Runtime (the `Uuid` class, the
+  # module doors and their argument checks, batch slicing) stays shared byte-for-byte across
+  # all three backends, and the same `HyperUuid::RandomSourceError` /
+  # `HyperUuid::TimestampOutOfRangeError` classes carry the same messages — literally the
+  # same constants and helper runtime.rb defines for the Fiddle backend.
+  #
+  # Two things differ from the native backends, both forced by the sandbox:
+  #
+  # * A wasm guest only sees its own linear memory, so no Fiddle::Pointer can cross. Every
+  #   buffer the core writes into is obtained from the module's own exported `malloc` (the
+  #   wasi-libc allocator Rust's std already uses on this target) and read back with
+  #   `Memory#read`. Using the guest's allocator rather than a host-picked offset is
+  #   load-bearing: dlmalloc claims the tail of the initial memory on first use, and a batch
+  #   written at a guessed offset was observed corrupted by the guest's next allocation.
+  # * A `Wasmtime::Store` is single-threaded, so every call is serialized under one Mutex.
+  #   One shared instance per process is also what keeps the core's v7 counter — which lives
+  #   inside the instance — monotonic across threads and batches, exactly as the one dlopen'd
+  #   library does natively.
+  module Runtime
+    WASM_MODULE_PATH = File.join(NATIVE_DIR, "wasm32-wasip1", "hyperuuid.wasm")
+    # Development loop: the in-repo cargo build, the same fallback runtime.rb takes for the
+    # native library, so `HYPERUUID_WASM=1 bundle exec rspec` needs nothing staged by hand.
+    WASM_REPO_BUILD_PATH = File.expand_path(
+      File.join(__dir__, "../../../rust/target/wasm32-wasip1/release/hyperuuid.wasm")
+    )
+
+    # One instantiated module: the exported functions, the exported memory, and the two
+    # 16-byte scratch buffers (one in, one out) the single-item doors reuse for the life of
+    # the process. Batches and v5 names get a `malloc`/`free` pair per call instead — one
+    # allocation amortized over `count` IDs, the same shape as the Fiddle backend's per-batch
+    # Pointer.malloc.
+    class WasmInstance
+      attr_reader :memory, :in, :out
+
+      EXPORTS = %i[
+        malloc free
+        uuid_new_v4 uuid_new_v5 uuid_new_v6 uuid_v6_unix_millis uuid_new_v6_batch
+        uuid_new_v7 uuid_v7_unix_millis uuid_new_v7_batch
+        uuid_v7_to_sql_order uuid_v7_to_rfc_order uuid_v6_to_sql_order uuid_v6_to_rfc_order
+        hyperuuid_version
+      ].freeze
+
+      def initialize(path)
+        path = WASM_REPO_BUILD_PATH if !File.exist?(path) && File.exist?(WASM_REPO_BUILD_PATH)
+        unless File.exist?(path)
+          raise LoadError,
+                "hyperuuid: #{path} not found (this gem was built without its WebAssembly module)"
+        end
+
+        engine = Wasmtime::Engine.new
+        mod = Wasmtime::Module.from_file(engine, path)
+        linker = Wasmtime::Linker.new(engine)
+        # The module imports five WASI preview1 functions (random_get is the one that
+        # matters: it is the core's only entropy source; the rest are wasi-libc's startup
+        # plumbing). A default WasiConfig — no stdio, no filesystem, no environment — is all
+        # any of them need.
+        Wasmtime::WASI::P1.add_to_linker_sync(linker)
+        store = Wasmtime::Store.new(engine, wasi_p1_config: Wasmtime::WasiConfig.new)
+        instance = linker.instantiate(store, mod)
+
+        @memory = instance.export("memory").to_memory
+        @fn = EXPORTS.to_h do |name|
+          export = instance.export(name.to_s) or
+            raise LoadError, "hyperuuid: #{path} does not export #{name} (a module older than this binding)"
+          [name, export.to_func]
+        end
+        @in = malloc(16)
+        @out = malloc(16)
+      end
+
+      def fn(name)
+        @fn.fetch(name)
+      end
+
+      def malloc(size)
+        ptr = @fn[:malloc].call(size)
+        raise NoMemoryError, "hyperuuid: wasm malloc(#{size}) failed" if ptr.zero?
+        ptr
+      end
+
+      def free(ptr)
+        @fn[:free].call(ptr)
+      end
+
+      # Runs `block` with a `size`-byte guest buffer, freeing it afterwards even on error.
+      def with_buffer(size)
+        ptr = malloc(size)
+        begin
+          yield ptr
+        ensure
+          free(ptr)
+        end
+      end
+    end
+
+    @wasm_mutex = Mutex.new
+    @wasm = nil
+
+    class << self
+      def new_v4
+        wasm do |w|
+          rc = w.fn(:uuid_new_v4).call(w.out)
+          raise random_source_failure("uuid_new_v4") unless rc.zero?
+          w.memory.read(w.out, 16)
+        end
+      end
+
+      def new_v5(namespace_bytes, name_bytes)
+        wasm do |w|
+          w.memory.write(w.in, namespace_bytes)
+          # A zero-length name still needs a valid (non-null) pointer inside the guest —
+          # the `in` scratch, already holding the namespace, serves; nothing reads past
+          # a zero length.
+          rc =
+            if name_bytes.empty?
+              w.fn(:uuid_new_v5).call(w.in, w.in, 0, w.out)
+            else
+              w.with_buffer(name_bytes.bytesize) do |name|
+                w.memory.write(name, name_bytes)
+                w.fn(:uuid_new_v5).call(w.in, name, name_bytes.bytesize, w.out)
+              end
+            end
+          raise random_source_failure("uuid_new_v5") unless rc.zero?
+          w.memory.read(w.out, 16)
+        end
+      end
+
+      def new_v6(unix_millis)
+        wasm do |w|
+          rc = w.fn(:uuid_new_v6).call(i64(unix_millis), w.out)
+          case rc
+          when 0 then w.memory.read(w.out, 16)
+          when 2 then raise TimestampOutOfRangeError, V6_TIMESTAMP_OUT_OF_RANGE
+          else raise random_source_failure("uuid_new_v6")
+          end
+        end
+      end
+
+      def v6_unix_millis(bytes)
+        wasm do |w|
+          w.memory.write(w.in, bytes)
+          u64(w.fn(:uuid_v6_unix_millis).call(w.in))
+        end
+      end
+
+      def new_v6_batch(count, unix_millis)
+        return "" if count.zero?
+        wasm do |w|
+          w.with_buffer(count * 16) do |out|
+            rc = w.fn(:uuid_new_v6_batch).call(i64(unix_millis), count, out)
+            case rc
+            when 0 then w.memory.read(out, count * 16)
+            when 2 then raise TimestampOutOfRangeError, V6_TIMESTAMP_OUT_OF_RANGE
+            else raise random_source_failure("uuid_new_v6_batch")
+            end
+          end
+        end
+      end
+
+      def new_v7(unix_millis)
+        wasm do |w|
+          rc = w.fn(:uuid_new_v7).call(i64(unix_millis), w.out)
+          case rc
+          when 0 then w.memory.read(w.out, 16)
+          when 2 then raise TimestampOutOfRangeError, V7_TIMESTAMP_OUT_OF_RANGE
+          else raise random_source_failure("uuid_new_v7")
+          end
+        end
+      end
+
+      def v7_unix_millis(bytes)
+        wasm do |w|
+          w.memory.write(w.in, bytes)
+          u64(w.fn(:uuid_v7_unix_millis).call(w.in))
+        end
+      end
+
+      def new_v7_batch(count, unix_millis)
+        return "" if count.zero?
+        wasm do |w|
+          w.with_buffer(count * 16) do |out|
+            rc = w.fn(:uuid_new_v7_batch).call(i64(unix_millis), count, out)
+            case rc
+            when 0 then w.memory.read(out, count * 16)
+            when 2 then raise TimestampOutOfRangeError, V7_TIMESTAMP_OUT_OF_RANGE
+            else raise random_source_failure("uuid_new_v7_batch")
+            end
+          end
+        end
+      end
+
+      def v7_to_sql_order(bytes)
+        rewrite(:uuid_v7_to_sql_order, bytes)
+      end
+
+      def v7_to_rfc_order(bytes)
+        rewrite(:uuid_v7_to_rfc_order, bytes)
+      end
+
+      def v6_to_sql_order(bytes)
+        rewrite(:uuid_v6_to_sql_order, bytes)
+      end
+
+      def v6_to_rfc_order(bytes)
+        rewrite(:uuid_v6_to_rfc_order, bytes)
+      end
+
+      def packed_version
+        wasm { |w| w.fn(:hyperuuid_version).call }
+      end
+
+      private
+
+      # The in-place byte-order rewrites: copy the caller's frozen bytes into the guest,
+      # let the core rewrite them there, read the result back.
+      def rewrite(export, bytes)
+        wasm do |w|
+          w.memory.write(w.in, bytes)
+          w.fn(export).call(w.in)
+          w.memory.read(w.in, 16)
+        end
+      end
+
+      # Every call holds the one lock: the Store is single-threaded, and the lazily created
+      # instance is shared by every thread for the life of the process (never torn down,
+      # same as the dlopen'd library natively).
+      def wasm
+        @wasm_mutex.synchronize do
+          @wasm ||= WasmInstance.new(WASM_MODULE_PATH)
+          yield @wasm
+        end
+      end
+
+      # wasm has no unsigned integers: a u64 crosses as an i64. The core's own range checks
+      # (48-bit v7, 60-bit v6) still see the exact value the caller passed, they just see
+      # it through a two's-complement reinterpretation on the way in and back. Exact only
+      # for a value that is a u64 to begin with, which the doors in hyperuuid.rb guarantee
+      # before any backend is called.
+      def i64(value)
+        value >= 2**63 ? value - 2**64 : value
+      end
+
+      def u64(value)
+        value.negative? ? value + 2**64 : value
+      end
+    end
+  end
+end