hyperuuid 0.2.1 → 0.4.0

data/lib/hyperuuid.rb

@@ -1,49 +1,91 @@
-require "time"
-
+require_relative "hyperuuid/errors"
 require_relative "hyperuuid/uuid"
 require_relative "hyperuuid/namespaces"
 require_relative "hyperuuid/native_platform"
 require_relative "hyperuuid/runtime"
 
-# RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7 (time-sortable) generation, calling
-# directly into the native libhyperuuid shared library via Fiddle — no runtime bridge, no
-# extra gem dependency. Bundles a native build for every supported platform (see
-# HyperUuid::NativePlatform) and picks the right one at runtime, the same trick the Go/
-# Java bindings use since RubyGems has no per-platform native selection wired up here.
+# RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7 (time-sortable) generation from one
+# Rust core, reached through whichever of three backends this install can load: the core
+# linked straight into a Magnus native extension (shipped precompiled in the platform gems),
+# the native libhyperuuid shared library called through Fiddle (the universal gem bundles
+# one per supported platform, picked by HyperUuid::NativePlatform), or the same core as a
+# WebAssembly module inside the wasmtime gem. No runtime bridge in any of them, and nothing
+# compiled at install time. HyperUuid::BACKEND names the one that loaded; the selection logic
+# is at the bottom of this file.
+#
+# The doors below — with Uuid, Namespaces and the two exception classes — are the public
+# surface, and are shared by every backend, argument validation included: a caller bug raises
+# the same error whichever backend is live.
 module HyperUuid
   # This gem's own version — distinct from the RFC 9562 UUID *versions* (v4/v5/v6/v7) the
   # rest of this module generates.
-  VERSION = "0.2.1"
+  VERSION = "0.4.0"
+
+  # The widest batch count, and the longest v5 name in bytes, the native ABI carries (a u32).
+  # (The millisecond count is a u64; unix_millis_from refuses anything wider.)
+  U32_MAX = 0xFFFF_FFFF
+  private_constant :U32_MAX
 
   # Creates a random UUID version 4 (RFC 9562 §5.4).
   def self.new_v4
-    Uuid.new(Runtime.new_v4)
+    Uuid.new(Runtime.new_v4, true)
   end
 
   # Creates a deterministic UUID version 5 (RFC 9562 §5.5) from a namespace and a name. The
   # same (namespace, name) pair always produces the same UUID. `name` may be a text String
-  # (encoded as UTF-8) or already-raw ASCII-8BIT bytes, which are used as-is.
+  # (encoded as UTF-8) or already-raw ASCII-8BIT bytes, which are used as-is; it may be empty.
+  #
+  # @raise [TypeError] if +namespace+ isn't a HyperUuid::Uuid or +name+ isn't a String.
   def self.new_v5(namespace, name)
+    raise TypeError, "namespace must be a HyperUuid::Uuid; got #{namespace.class}" unless namespace.is_a?(Uuid)
+    raise TypeError, "name must be a String; got #{name.class}" unless name.is_a?(String)
+
     name_bytes =
       if name.encoding == Encoding::ASCII_8BIT
         name
       else
         name.encode(Encoding::UTF_8).dup.force_encoding(Encoding::BINARY)
       end
-    Uuid.new(Runtime.new_v5(namespace.bytes, name_bytes))
+    raise ArgumentError, "name must be at most #{U32_MAX} bytes" if name_bytes.bytesize > U32_MAX
+
+    Uuid.new(Runtime.new_v5(namespace.bytes, name_bytes), true)
   end
 
   # Converts +value+ to a Unix-epoch millisecond integer: +nil+ becomes the current time, a
   # +Time+ is converted exactly (via its own Rational seconds, avoiding float rounding), and
-  # anything else (an Integer millisecond count) passes through unchanged. Shared by every
+  # an Integer millisecond count passes through unchanged. Shared by every
   # `new_v6`/`new_v7`/batch door below so a caller can pass either a `Time` or a raw
   # millisecond count interchangeably.
-  private_class_method def self.unix_millis_from(value)
-    case value
-    when nil then Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond)
-    when Time then (value.to_r * 1000).to_i
-    else value
-    end
+  #
+  # This is also where a caller bug is caught once, for every backend: anything else is a
+  # TypeError, and a count that cannot cross the ABI as a u64 at all — negative (a `Time`
+  # before the epoch included) or past 64 bits — is the same TimestampOutOfRangeError, with
+  # the same +out_of_range+ message, the core raises for a value it can see but not embed.
+  # Left to the backends those cases diverged: a RangeError from the extension, a wrapped
+  # value from Fiddle, a silently truncated one from wasm.
+  #
+  # The two common arguments go first and cheapest: no argument is the clock, which needs no
+  # range check, and an Integer is checked by its bit length rather than against 2**64 - 1: a
+  # comparison with a number that size is a bignum comparison, and cost more than the mint.
+  private_class_method def self.unix_millis_from(value, out_of_range)
+    return Process.clock_gettime(Process::CLOCK_REALTIME, :millisecond) if value.nil?
+
+    millis =
+      if value.is_a?(Integer) then value
+      elsif value.is_a?(Time) then (value.to_r * 1000).floor
+      else raise TypeError, "unix_millis must be a Time, an Integer or nil; got #{value.class}"
+      end
+    raise TimestampOutOfRangeError, out_of_range unless millis >= 0 && millis.bit_length <= 64
+
+    millis
+  end
+
+  # Checks a batch +count+ once, for every backend: an Integer the ABI's u32 can carry.
+  private_class_method def self.batch_count(count)
+    raise TypeError, "count must be an Integer; got #{count.class}" unless count.is_a?(Integer)
+    raise ArgumentError, "count must be between 0 and #{U32_MAX}; got #{count}" unless count.between?(0, U32_MAX)
+
+    count
   end
 
   # Creates a time-sortable UUID version 6 (RFC 9562 §5.6), a field-compatible reordering of
@@ -51,49 +93,66 @@ module HyperUuid
   # `Time` or Unix-epoch millisecond integer to embed a specific time instead. `clock_seq` and
   # `node` are randomly generated on every call — unlike version 7, there is no monotonic
   # counter, so calls within the same millisecond are not guaranteed to sort in creation order.
+  #
+  # @raise [TimestampOutOfRangeError] if the time is negative or past the 60-bit v6 field.
+  # @raise [TypeError] if +unix_millis+ isn't a Time, an Integer or nil.
   def self.new_v6(unix_millis = nil)
-    Uuid.new(Runtime.new_v6(unix_millis_from(unix_millis)))
+    Uuid.new(Runtime.new_v6(unix_millis_from(unix_millis, Runtime::V6_TIMESTAMP_OUT_OF_RANGE)), true)
   end
 
   # Creates `count` time-sortable version 6 UUIDs sharing one timestamp capture — one FFI call
   # and one random-bytes fetch instead of `count` of each. Defaults to the current time; pass
   # an explicit `Time` or Unix-epoch millisecond integer to embed a specific time instead.
+  #
+  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and 2**32 - 1.
+  # @raise [TimestampOutOfRangeError] if the time is negative or past the 60-bit v6 field.
   def self.new_v6_batch(count, unix_millis = nil)
-    bytes = Runtime.new_v6_batch(count, unix_millis_from(unix_millis))
-    Array.new(count) { |i| Uuid.new(bytes[i * 16, 16]) }
+    bytes = new_v6_batch_bytes(count, unix_millis)
+    Array.new(count) { |i| Uuid.new(bytes[i * 16, 16], true) }
   end
 
   # Creates a time-sortable UUID version 7 (RFC 9562 §6.2). Defaults to the current time; pass
   # an explicit `Time` or Unix-epoch millisecond integer (non-negative, fitting in 48 bits) to
   # embed a specific time instead.
+  #
+  # @raise [TimestampOutOfRangeError] if the time is negative or past the 48-bit v7 field.
+  # @raise [TypeError] if +unix_millis+ isn't a Time, an Integer or nil.
   def self.new_v7(unix_millis = nil)
-    Uuid.new(Runtime.new_v7(unix_millis_from(unix_millis)))
+    Uuid.new(Runtime.new_v7(unix_millis_from(unix_millis, Runtime::V7_TIMESTAMP_OUT_OF_RANGE)), true)
   end
 
   # Creates `count` time-sortable version 7 UUIDs sharing one timestamp capture and one
   # contiguous block of the monotonic counter — one FFI call and one random-bytes fetch
   # instead of `count` of each. Defaults to the current time; pass an explicit `Time` or
   # Unix-epoch millisecond integer to embed a specific time instead.
+  #
+  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and 2**32 - 1.
+  # @raise [TimestampOutOfRangeError] if the time is negative or past the 48-bit v7 field.
   def self.new_v7_batch(count, unix_millis = nil)
-    bytes = Runtime.new_v7_batch(count, unix_millis_from(unix_millis))
-    Array.new(count) { |i| Uuid.new(bytes[i * 16, 16]) }
+    bytes = new_v7_batch_bytes(count, unix_millis)
+    Array.new(count) { |i| Uuid.new(bytes[i * 16, 16], true) }
   end
 
   # Returns `count` version 7 UUIDs as one binary String of raw RFC 9562-ordered bytes,
   # 16 per UUID, instead of an Array of Uuid objects.
   #
-  # Roughly 11x faster than #new_v7_batch for a 1000-UUID batch (about 35 us versus 400 us).
-  # The difference is not the native call — that is identical — it is that #new_v7_batch then
-  # allocates `count` Uuid objects and `count` String slices on top of it. This hands back the
-  # bytes the native core already produced, untouched.
+  # Far faster than #new_v7_batch for a large batch — the README's "Bulk generation into
+  # bytes" section carries the measured figures. The difference is not the native call —
+  # that is identical — it is that #new_v7_batch then allocates `count` Uuid objects and
+  # their byte Strings on top of it. This hands back the bytes the native core already
+  # produced, untouched.
   #
   # Use it when bytes are the destination: a BYTEA/uniqueidentifier bind parameter, a wire
   # format, a bulk COPY. If you need Uuid objects, keep using #new_v7_batch — slicing this
   # String into them yourself just moves the same allocations into your own code.
   #
   # Slice it with `bytes[i * 16, 16]`, which is what #new_v7_batch does internally.
+  #
+  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and 2**32 - 1.
+  # @raise [TimestampOutOfRangeError] if the time is negative or past the 48-bit v7 field.
   def self.new_v7_batch_bytes(count, unix_millis = nil)
-    Runtime.new_v7_batch(count, unix_millis_from(unix_millis))
+    count = batch_count(count)
+    Runtime.new_v7_batch(count, unix_millis_from(unix_millis, Runtime::V7_TIMESTAMP_OUT_OF_RANGE))
   end
 
   # Returns `count` version 6 UUIDs as one binary String of raw RFC 9562-ordered bytes,
@@ -103,8 +162,42 @@ module HyperUuid
   # clock_seq and node are independently random per item; unlike version 7 there is no
   # monotonic counter, so items minted in the same millisecond are not guaranteed to sort in
   # creation order.
+  #
+  # @raise [TypeError, ArgumentError] if +count+ isn't an Integer between 0 and 2**32 - 1.
+  # @raise [TimestampOutOfRangeError] if the time is negative or past the 60-bit v6 field.
   def self.new_v6_batch_bytes(count, unix_millis = nil)
-    Runtime.new_v6_batch(count, unix_millis_from(unix_millis))
+    count = batch_count(count)
+    Runtime.new_v6_batch(count, unix_millis_from(unix_millis, Runtime::V6_TIMESTAMP_OUT_OF_RANGE))
+  end
+
+  # The version of the native core actually loaded, as "major.minor.patch" — read from the
+  # library itself (its `hyperuuid_version` export), not from this gem, so a consumer can
+  # prove the core behind the doors is the one this binding was built against (and name the
+  # mismatch against HyperUuid::VERSION when it is not). The cheapest possible probe that the
+  # backend resolved at all: takes nothing, mints nothing, cannot fail once the backend loads.
+  #
+  # @raise [LoadError] if no backend could be loaded for this platform.
+  def self.native_version
+    word = Runtime.packed_version
+    "#{word >> 16}.#{(word >> 8) & 0xFF}.#{word & 0xFF}"
+  end
+
+  # Whether a backend actually loaded and exports the ABI this binding was built against —
+  # what a consumer with a fallback of its own (SecureRandom.uuid, say) checks before
+  # committing to these doors. Probed once (a native_version round trip), cached, and never
+  # raises: a missing shared library, an unsupported platform, an older core without the
+  # version export, or a wasm module the wasmtime gem cannot instantiate all answer false.
+  # The doors themselves keep their own behavior — the first call on an unavailable backend
+  # raises its precise error — and so does require-time selection under HYPERUUID_WASM=1
+  # without wasmtime; this only answers the question quietly.
+  def self.available?
+    return @available unless @available.nil?
+
+    @available = begin
+      native_version.is_a?(String)
+    rescue LoadError, StandardError
+      false
+    end
   end
 end
 
@@ -115,16 +208,39 @@ end
 # remain the universal zero-compile fallback; precompiled platform gems are how the
 # extension ships without ever making a consumer compile anything. Set HYPERUUID_PURE=1 to
 # force Fiddle.
+#
+# The third backend is WebAssembly (lib/hyperuuid/wasm_runtime.rb): the same core as a
+# wasm32-wasip1 module, run in-process by the `wasmtime` gem, which is deliberately not a
+# runtime dependency of this gem — a consumer who wants it installs it. HYPERUUID_WASM=1
+# forces it (and fails loudly if wasmtime is missing); otherwise it is only ever chosen when
+# there is no native library for this platform at all and wasmtime happens to be available,
+# so no supported platform's behavior changes by its existence.
+#
+# Both variables are read for presence, not value — set to anything at all, "0" and the
+# empty string included, they force their backend — and HYPERUUID_WASM wins when both are
+# set.
 HyperUuid::BACKEND =
-  if ENV["HYPERUUID_PURE"]
+  if ENV["HYPERUUID_WASM"]
+    begin
+      require "wasmtime"
+    rescue LoadError
+      raise LoadError,
+            "hyperuuid: HYPERUUID_WASM=1 needs the wasmtime gem — `gem install wasmtime` (or add it to your Gemfile)"
+    end
+    require_relative "hyperuuid/wasm_runtime"
+    :wasm
+  elsif ENV["HYPERUUID_PURE"]
     :fiddle
   else
     # Two layouts, and both have to work. A released platform gem is a "fat" gem carrying one
     # extension per supported Ruby ABI under lib/hyperuuid/<minor>/ (see the Rakefile's
     # native:gem task for why an ABI-per-file is unavoidable — Magnus has no `abi3`
-    # equivalent). CI's in-job staging and a local `cargo build --release --features ruby`
-    # instead drop a single extension flat at lib/. Trying the versioned path first and the
-    # flat one second means neither has to know the other exists.
+    # equivalent), and `rake native:dev` — the local dev loop — stages its own build at that
+    # same versioned path. CI's in-job staging additionally drops a single extension flat at
+    # lib/, which is also where a hand copy of `cargo ruby-ext`'s output goes (the alias only
+    # builds into rust/target/ruby/release/; nothing but that rake task copies it here).
+    # Trying the versioned path first and the flat one second means neither has to know the
+    # other exists.
     #
     # A miss on both is not an error: it means this Ruby/platform combination has no
     # precompiled extension, which is precisely what the Fiddle backend below is for.
@@ -136,7 +252,22 @@ HyperUuid::BACKEND =
         require "hyperuuid_native"
         :native
       rescue LoadError
-        :fiddle
+        if HyperUuid::Runtime.fiddle_library_available?
+          :fiddle
+        else
+          # No shared library for this platform either. wasmtime, if the consumer has it,
+          # is the only backend left that can run here; without it, stay on Fiddle so the
+          # first call raises its own precise error — a "not found" LoadError naming the
+          # path, or NativePlatform::UnsupportedPlatformError naming the platform — rather
+          # than a vaguer one from here. HyperUuid.available? is the quiet way to ask.
+          begin
+            require "wasmtime"
+            require_relative "hyperuuid/wasm_runtime"
+            :wasm
+          rescue LoadError
+            :fiddle
+          end
+        end
       end
     end
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperuuid
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Brian Buvinghausen
@@ -23,20 +23,6 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: benchmark-ips
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.15'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.15'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
@@ -66,9 +52,12 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.9'
 description: |
-  High-performance, allocation-free RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7
-  (time-sortable) generation, calling directly into the native libhyperuuid shared library
-  via Fiddle (Ruby's standard-library FFI) — no runtime bridge, no extra gem dependency.
+  RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7 (time-sortable) generation, with
+  batch and raw-bytes forms, from one native Rust core. Three backends behind one surface,
+  selected automatically and all shipped prebuilt: a Magnus extension where a precompiled
+  platform gem matches, stdlib Fiddle everywhere else, and the same core as a WebAssembly
+  module for anyone who installs the wasmtime gem. No runtime bridge, no dependencies
+  beyond Fiddle.
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -76,22 +65,30 @@ files:
 - LICENSE
 - README.md
 - lib/hyperuuid.rb
+- lib/hyperuuid/errors.rb
 - lib/hyperuuid/namespaces.rb
-- lib/hyperuuid/native/README.md
 - lib/hyperuuid/native/linux-arm64/libhyperuuid.so
+- lib/hyperuuid/native/linux-musl-arm64/libhyperuuid.so
+- lib/hyperuuid/native/linux-musl-x64/libhyperuuid.so
 - lib/hyperuuid/native/linux-x64/libhyperuuid.so
 - lib/hyperuuid/native/osx-arm64/libhyperuuid.dylib
 - lib/hyperuuid/native/osx-x64/libhyperuuid.dylib
+- lib/hyperuuid/native/wasm32-wasip1/hyperuuid.wasm
 - lib/hyperuuid/native/win-arm64/hyperuuid.dll
 - lib/hyperuuid/native/win-x64/hyperuuid.dll
 - lib/hyperuuid/native_platform.rb
 - lib/hyperuuid/runtime.rb
 - lib/hyperuuid/uuid.rb
+- lib/hyperuuid/wasm_runtime.rb
 homepage: https://github.com/SkunkWerkx/HyperUuid
 licenses:
 - MIT
 metadata:
   source_code_uri: https://github.com/SkunkWerkx/HyperUuid
+  changelog_uri: https://github.com/SkunkWerkx/HyperUuid/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/SkunkWerkx/HyperUuid/issues
+  documentation_uri: https://github.com/SkunkWerkx/HyperUuid/tree/master/ruby#readme
+  rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
 - lib
@@ -99,15 +96,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.16
+rubygems_version: 4.0.20
 specification_version: 4
-summary: RFC 9562 UUID v4/v5/v6/v7 generation — direct native FFI into a Rust core,
-  no runtime bridge.
+summary: RFC 9562 UUID v4/v5/v6/v7 generation over a native Rust core, shipped prebuilt
 test_files: []

data/lib/hyperuuid/native/README.md

@@ -1,6 +0,0 @@
-# native/
-
-Populated per-RID with the platform's native `libhyperuuid` build (`native/{rid}/{lib}`) by CI
-and by `cargo build --release` for local dev — see `../../../.gitignore`. This file exists so
-the directory has at least one tracked file on a fresh checkout, matching the Go/Swift
-bindings' `native/`/`NativeLibs/` placeholder convention.