hyperuuid-wasm 0.6.1

data/lib/hyperuuid/runtime.rb

@@ -0,0 +1,279 @@
+# Autoloaded, not required: the platform gems carry no library for Fiddle to open and do not
+# declare fiddle, so loading it eagerly would make `require "hyperuuid"` fail under Bundler
+# wherever fiddle is a bundled rather than a default gem (Ruby 4.0). It loads the first time
+# the Fiddle backend runs, and every path there goes through `functions` first, so a platform
+# gem forced onto Fiddle still gets missing_library_message rather than a bare LoadError.
+autoload :Fiddle, "fiddle"
+
+module HyperUuid
+  # Fiddle plumbing for the native libhyperuuid shared library — dlopen/dlsym plus a raw
+  # C-ABI call, no runtime bridge (the same "no shim" positioning as the PHP binding's
+  # FFI and C#'s P/Invoke). Fiddle ships with every Ruby install; it's a plain gem dependency of the
+  # universal gem (see hyperuuid.gemspec) rather than a third-party one — mirroring Python's
+  # zero-dependency PyO3 wheels.
+  #
+  # A Ruby gem's files are plain files on disk once installed, so native/{rid}/{lib} can be
+  # dlopen'd directly, with no extraction step.
+  module Runtime
+    # 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 backend 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")
+
+    @mutex = Mutex.new
+    @functions = nil
+
+    class << self
+      def new_v4
+        out = scratch
+        rc = functions[:new_v4].call(out)
+        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 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
+
+      def new_v6(unix_millis)
+        out = scratch
+        rc = functions[:new_v6].call(unix_millis, out)
+        case rc
+        when 0 then out[0, 16]
+        when 2 then raise TimestampOutOfRangeError, V6_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v6")
+        end
+      end
+
+      def v6_unix_millis(bytes)
+        functions[:v6_unix_millis].call(bytes)
+      end
+
+      def new_v6_batch(count, unix_millis)
+        return "" if count.zero?
+        out = buffer(count * 16)
+        rc = functions[:new_v6_batch].call(unix_millis, count, out)
+        case rc
+        when 0 then out[0, count * 16]
+        when 2 then raise TimestampOutOfRangeError, V6_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v6_batch")
+        end
+      end
+
+      def new_v7(unix_millis)
+        out = scratch
+        rc = functions[:new_v7].call(unix_millis, out)
+        case rc
+        when 0 then out[0, 16]
+        when 2 then raise TimestampOutOfRangeError, V7_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v7")
+        end
+      end
+
+      def v7_unix_millis(bytes)
+        functions[:v7_unix_millis].call(bytes)
+      end
+
+      def new_v7_batch(count, unix_millis)
+        return "" if count.zero?
+        out = buffer(count * 16)
+        rc = functions[:new_v7_batch].call(unix_millis, count, out)
+        case rc
+        when 0 then out[0, count * 16]
+        when 2 then raise TimestampOutOfRangeError, V7_TIMESTAMP_OUT_OF_RANGE
+        else raise random_source_failure("uuid_new_v7_batch")
+        end
+      end
+
+      def v7_to_sql_order(bytes)
+        rewrite(:v7_to_sql_order, bytes)
+      end
+
+      def v7_to_rfc_order(bytes)
+        rewrite(:v7_to_rfc_order, bytes)
+      end
+
+      def v6_to_sql_order(bytes)
+        rewrite(:v6_to_sql_order, bytes)
+      end
+
+      def v6_to_rfc_order(bytes)
+        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
+
+      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
+
+      # Why Fiddle found nothing to load. A precompiled platform gem is the one install where
+      # that is by design rather than a gap: it carries only its Magnus extensions, and the
+      # Fiddle backend is reached there only by forcing it (HYPERUUID_PURE) or because none
+      # of its extensions loaded — a gem RubyGems matched to a Ruby it was not built for,
+      # such as the glibc Linux gem that `gem install` on RubyGems 3.x picks on Alpine. So
+      # that case names its fix, the universal gem, which carries every platform's library,
+      # instead of a missing path that reads like a packaging bug. Both arguments are
+      # parameters only so the specs can ask for every wording.
+      def missing_library_message(gem_platform = Gem.loaded_specs["hyperuuid"]&.platform,
+                                  forced = ENV.key?("HYPERUUID_PURE"))
+        rid, lib_name = NativePlatform.rid_and_library_name
+        missing = File.join(NATIVE_DIR, rid, lib_name)
+        if gem_platform && gem_platform.to_s != Gem::Platform::RUBY
+          reason =
+            if forced
+              "HYPERUUID_PURE forces the Fiddle backend (unset it to use the extension)"
+            else
+              "none of its extensions loads on this Ruby (#{RUBY_VERSION}, #{RUBY_PLATFORM})"
+            end
+          "hyperuuid: this #{gem_platform} platform gem carries only Magnus extensions, no " \
+            "Fiddle library, and #{reason}. The universal gem has the Fiddle backend for every " \
+            "platform: `gem install hyperuuid --platform ruby`, or Bundler's force_ruby_platform " \
+            "(#{missing} not found)"
+        else
+          "hyperuuid: #{missing} not found (unsupported platform, or this gem was built " \
+            "without a native library for it)"
+        end
+      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
+      # magnitude. Batches keep a per-call buffer: one malloc amortized over `count` IDs.
+      def scratch
+        Thread.current[:hyperuuid_scratch] ||= buffer(16)
+      end
+
+      # Every Fiddle allocation goes through here, and loads the library first: that is what
+      # keeps a missing library reported as missing_library_message instead of as whatever
+      # touching Fiddle raises first. The scratch buffer pays for it once per thread.
+      def buffer(size)
+        functions
+        Fiddle::Pointer.malloc(size, Fiddle::RUBY_FREE)
+      end
+
+      # The in-place byte-order rewrites are the one shape that must copy in: the native
+      # call genuinely mutates the buffer, and the input String is frozen.
+      def rewrite(symbol, bytes)
+        buf = scratch
+        buf[0, 16] = bytes
+        functions[symbol].call(buf)
+        buf[0, 16]
+      end
+
+      # Loaded lazily and exactly once, mirroring Java's class initializer / Swift's lazy
+      # static let — the native library and its function pointers live for the process's
+      # lifetime, same as every other binding (never dlclose'd). The unsynchronized read is
+      # the hot path; the mutex only guards the one-time load (a benign race — idempotent).
+      def functions
+        @functions || @mutex.synchronize { @functions ||= load_functions }
+      end
+
+      def load_functions
+        path = library_path
+        raise LoadError, missing_library_message if path.nil?
+
+        handle = Fiddle.dlopen(path)
+        {
+          new_v4: Fiddle::Function.new(handle["uuid_new_v4"], [Fiddle::TYPE_VOIDP], Fiddle::TYPE_INT),
+          new_v5: Fiddle::Function.new(
+            handle["uuid_new_v5"],
+            [Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_INT
+          ),
+          new_v6: Fiddle::Function.new(
+            handle["uuid_new_v6"],
+            [Fiddle::TYPE_UINT64_T, Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_INT
+          ),
+          v6_unix_millis: Fiddle::Function.new(
+            handle["uuid_v6_unix_millis"],
+            [Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_UINT64_T
+          ),
+          new_v6_batch: Fiddle::Function.new(
+            handle["uuid_new_v6_batch"],
+            [Fiddle::TYPE_UINT64_T, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_INT
+          ),
+          new_v7: Fiddle::Function.new(
+            handle["uuid_new_v7"],
+            [Fiddle::TYPE_UINT64_T, Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_INT
+          ),
+          v7_unix_millis: Fiddle::Function.new(
+            handle["uuid_v7_unix_millis"],
+            [Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_UINT64_T
+          ),
+          new_v7_batch: Fiddle::Function.new(
+            handle["uuid_new_v7_batch"],
+            [Fiddle::TYPE_UINT64_T, Fiddle::TYPE_UINT32_T, Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_INT
+          ),
+          v7_to_sql_order: Fiddle::Function.new(
+            handle["uuid_v7_to_sql_order"],
+            [Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_VOID
+          ),
+          v7_to_rfc_order: Fiddle::Function.new(
+            handle["uuid_v7_to_rfc_order"],
+            [Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_VOID
+          ),
+          v6_to_sql_order: Fiddle::Function.new(
+            handle["uuid_v6_to_sql_order"],
+            [Fiddle::TYPE_VOIDP],
+            Fiddle::TYPE_VOID
+          ),
+          v6_to_rfc_order: Fiddle::Function.new(
+            handle["uuid_v6_to_rfc_order"],
+            [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
+  end
+end

data/lib/hyperuuid/uuid.rb

@@ -0,0 +1,179 @@
+module HyperUuid
+  # A parsed 16-byte RFC 9562 UUID value. Minimal by design — this gem has no runtime
+  # dependency on the `uuid` gem, the same "no extra dependency" positioning as the Go
+  # binding's lone google/uuid requirement and the Python binding's dependency-free PyO3
+  # wheels.
+  class Uuid
+    include Comparable
+
+    # 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. 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, 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.
+    NIL = new(("\x00" * 16).b).freeze
+
+    # The RFC 9562 §5.10 Max UUID — all 128 bits one.
+    MAX = new(("\xFF" * 16).b).freeze
+
+    # 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 String in that shape.
+    def self.parse(string)
+      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).
+    def version
+      (bytes.getbyte(6) >> 4) & 0x0F
+    end
+
+    # The RFC 9562 variant bits (top two bits of octet 8). +0b10+ means RFC 9562/4122.
+    def variant
+      (bytes.getbyte(8) >> 6) & 0b11
+    end
+
+    # The 8-4-4-4-12 hyphenated hex string representation.
+    def to_s
+      hex = bytes.unpack1("H*")
+      "#{hex[0, 8]}-#{hex[8, 4]}-#{hex[12, 4]}-#{hex[16, 4]}-#{hex[20, 12]}"
+    end
+    alias_method :to_str, :to_s
+
+    # The UTC timestamp embedded in a version 6 or 7 UUID's timestamp field. Only meaningful
+    # when `version` is 6 or 7 — the RFC 9562 bit layout doesn't distinguish "not a time-based
+    # UUID" from "time-based UUID with a very early timestamp", so the caller is responsible
+    # for checking `version` first if that matters.
+    #
+    # Raises by default for any other version; pass `raise_on_mismatch: false` to get `nil`
+    # back instead — for a caller that doesn't already know (or want to separately check)
+    # whether this UUID is time-based.
+    def timestamp(raise_on_mismatch: true)
+      millis =
+        case version
+        when 6 then Runtime.v6_unix_millis(bytes)
+        when 7 then Runtime.v7_unix_millis(bytes)
+        else
+          raise ArgumentError, "timestamp is only defined for version 6 or 7 UUIDs, got version #{version}" if raise_on_mismatch
+          return nil
+        end
+      Time.at(millis / 1000, millis % 1000, :millisecond).utc
+    end
+
+    # Converts an RFC 9562-ordered version 6 or 7 UUID to the byte order SQL Server's
+    # `uniqueidentifier` needs on the wire to sort by creation order. Dispatches on `version`
+    # the same way #timestamp does.
+    #
+    # `System.Data.SqlTypes.SqlGuid` comparison — and therefore T-SQL `ORDER BY` on a
+    # `uniqueidentifier` column — doesn't compare a GUID's 16 bytes left to right; it uses a
+    # fixed, non-sequential byte significance order (octets 10,11,12,13,14,15,8,9,6,7,4,5,
+    # 0,1,2,3, most significant first). Computed once in the native Rust core and verified
+    # there (and independently, against the real SqlGuid comparator, in this project's C#
+    # test suite); this binding calls the same native functions rather than reimplementing
+    # the byte math.
+    #
+    # For v7, this moves the timestamp and counter — the two fields that determine creation
+    # order — into that comparison's most-significant bytes, and moves the trailing entropy,
+    # which carries no ordering information, into the least-significant ones as one intact
+    # block. For v6, which has no monotonic counter the way v7 does, the only field that
+    # determines creation order is the 60-bit timestamp itself, so that moves into the most
+    # significant bytes instead, with `clock_seq`/`node` (independently random per call, not
+    # a counter, so no ordering value either way) relocated into the rest. v6's much simpler
+    # byte layout needs no bit-level repacking to do this — just whole-octet-group
+    # relocation — unlike v7's, and its version/variant land at different sql-order offsets
+    # as a result (octet 8's top nibble / octet 6's top two bits, not 7/8).
+    #
+    # **v6-specific caveat, unlike v7:** two version 6 UUIDs minted at the same millisecond
+    # have identical timestamp bits, so they aren't guaranteed to sort in creation order any
+    # more than plain RFC order already does — a pre-existing RFC 9562 v6 limitation, not one
+    # this transform introduces.
+    #
+    # 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), 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
+
+    # Inverse of #to_sql_order — converts a SQL-Server-ordered version 6 or 7 UUID back to
+    # RFC 9562 order.
+    #
+    # A SQL-ordered value's version nibble sits at a different octet depending on which
+    # version produced it (octet 7's top nibble = 7 for v7-sql-order, octet 8's top nibble =
+    # 6 for v6-sql-order — #version itself assumes RFC order's octet 6 and can't tell these
+    # apart), so this checks both fixed positions directly rather than calling #version.
+    #
+    # Order matters here and isn't arbitrary: octet 8 must be checked *first*. For v6-sql-order
+    # it's deterministic (top nibble always 0x6, by construction), and for v7-sql-order it's
+    # also deterministic but structurally excluded from ever reading 0x6 (its top two bits are
+    # the fixed variant `10`, so the nibble only ever lands in 0x8-0xB) — no collision either
+    # way. Octet 7, by contrast, is *not* safe to check first: for v7-sql-order it's
+    # deterministically 0x7, but for v6-sql-order it holds `clock_seq`'s fully random low
+    # byte, which has a real (~1-in-16) chance of a top nibble that also happens to read 0x7 —
+    # confirmed by an actual test failure during development, not a hypothetical. Checking
+    # octet 8 first rules v6 in or out unambiguously before octet 7's reading can matter.
+    def from_sql_order
+      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), true)
+      elsif octet7_version == 7
+        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
+    end
+
+    # Whether +other+ wraps the same 16 raw bytes.
+    def ==(other)
+      other.is_a?(Uuid) && bytes == other.bytes
+    end
+    alias_method :eql?, :==
+
+    # Hash code consistent with #==, based on the raw bytes.
+    def hash
+      bytes.hash
+    end
+
+    # Byte-order comparison against +other+, or +nil+ if +other+ isn't a Uuid.
+    def <=>(other)
+      return nil unless other.is_a?(Uuid)
+      bytes <=> other.bytes
+    end
+
+    # Debug representation, e.g. <tt>#<HyperUuid::Uuid ...></tt>.
+    def inspect
+      "#<HyperUuid::Uuid #{self}>"
+    end
+  end
+end