hyperuuid 0.2.1-aarch64-linux → 0.3.0-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b849ff1768c8be95682aca3a919293c35e41544021e32cabb16af7eaea47a75f
-  data.tar.gz: d146d988512e41065a80fa628cfd64a270add25b7ecbdba731f3bf3b9da091c1
+  metadata.gz: f236489589d106e3922b7ea6afc388da14ee34b7eeae2398d13a26e6de842ba8
+  data.tar.gz: ebadf7adf1ff518f468fcb00d28abe9004e26e29013c9f393063752ea07fdd31
 SHA512:
-  metadata.gz: 4b1aee8bf3925edfaf5c62fd812abc81ca945d01bfffab1354a16fdca414581f0e5349a29aee2ec36a01d84d10a36d16c0231c5ed87f1405141eed53706785ac
-  data.tar.gz: 66d93d8cfc927384f81694200dbbd6f048c3df9d3088f6e4f5b821cdbd729fba2b5b238ab6d54d161bb68e922e40713ee0ceb9af65721b684590ac940332e2dd
+  metadata.gz: c83e2025e8f493d5762607b0ef5acc1238252dd7b7998a9afe4462f4a2bb382af52298713abce4b79830e274b6da317e51ff14db21146d6ae7f8cfc1e1e74d72
+  data.tar.gz: b57eca92e941b4ec157457d5610d3db7ed36af4057f0f91e053c461681f36228714344e8a177985659ed5af0545a7f3f93a7de6eb91bcc743e2a4c5d859da8b8

data/README.md

@@ -6,7 +6,7 @@
 **Ruby's own stdlib stops at `SecureRandom.uuid` — random v4, full stop. No v5, no v6, no v7. This gem is the whole RFC, with zero gem dependency beyond `Fiddle` (which ships with every Ruby install) — and it's faster than `SecureRandom.uuid` too.**
 
 RFC 9562 UUID v4 (random), v5 (deterministic), v6 and v7 (time-sortable) generation, with
-two backends sharing one public surface. The fast path is a native extension built with
+three backends sharing one public surface. The fast path is a native extension built with
 [Magnus](https://github.com/matsadler/magnus) — the Rust core linked directly into the Ruby
 VM, auto-selected when loadable — which redefines the low-level `Runtime` methods in place
 on require; everything above them (`Uuid`, the module doors, batch slicing) is shared
@@ -15,7 +15,10 @@ shared library via [`Fiddle`](https://docs.ruby-lang.org/en/master/Fiddle.html)
 dlopen/dlsym plus a raw C-ABI call, no runtime bridge, nothing to compile on
 `bundle install`. Set `HYPERUUID_PURE=1` to force the Fiddle backend;
 `HyperUuid::BACKEND` reports which one is live. Bundles a native build for every supported
-platform (linux/darwin/windows × x64/arm64) and picks the right one at runtime.
+platform (linux/darwin/windows × x64/arm64) and picks the right one at runtime. A third
+backend runs the same core as a WebAssembly module inside the
+[`wasmtime`](https://rubygems.org/gems/wasmtime) gem, for any platform with no native build
+at all — see [WebAssembly (wasmtime)](#webassembly-wasmtime).
 
 ```ruby
 require "hyperuuid"
@@ -109,6 +112,77 @@ Batch generation still amortizes per-call cost on both backends — one native c
 
 The batch multiplier shrank from 11x to ~3.8x for the best reason available: the individual calls got 3x faster, so there's less waste left to amortize. If you need v5/v6/v7, need many at once, or need this Ruby service's IDs to agree byte-for-byte with a Go or Python service's, that's what this gem is for — and now it's the fast option too, not just the capable one.
 
+## WebAssembly (wasmtime)
+
+The Rust core also ships inside this gem as a `wasm32-wasip1` module
+(`lib/hyperuuid/native/wasm32-wasip1/hyperuuid.wasm`), and the
+[`wasmtime`](https://rubygems.org/gems/wasmtime) gem can run it in-process. This is the
+inverse of ruby.wasm — not Ruby inside a wasm sandbox, but a wasm module inside Ruby — and
+it is the one backend that needs no shared library for the platform it runs on: no
+`dlopen`, no Magnus extension, nothing compiled against this Ruby's ABI. Everything above
+`Runtime` (`Uuid`, the module doors, batch slicing) is the same code the other two backends
+run, and `spec/wasm_backend_spec.rb` pins that the outputs agree with the Fiddle backend
+byte for byte.
+
+`wasmtime` is deliberately **not** a dependency of this gem; a consumer who wants this path
+installs it:
+
+```sh
+gem install wasmtime
+HYPERUUID_WASM=1 ruby -rhyperuuid -e 'p HyperUuid::BACKEND'   # => :wasm
+```
+
+`HYPERUUID_WASM=1` forces the backend (and raises a `LoadError` naming the gem if it is
+missing). Without it, the wasm backend is only ever chosen automatically when there is no
+native library for this platform at all — no Magnus extension and no `libhyperuuid` for the
+RID — and `wasmtime` happens to be installed. No supported platform's behavior changes just
+because this backend exists.
+
+Two things are different under the sandbox, both by necessity. A wasm guest only sees its own
+linear memory, so every buffer the core fills comes from the module's own exported `malloc`
+(the same wasi-libc allocator Rust's std uses on that target) and is read back with
+`Memory#read` — using the guest's allocator rather than a host-picked offset is what keeps a
+batch from being clobbered by the guest's next allocation. And a `Wasmtime::Store` is
+single-threaded, so every call is serialized under one Mutex around one shared instance,
+which is also what keeps the core's v7 counter (it lives inside the instance) monotonic
+across threads and batches, exactly as the one dlopen'd library does natively.
+
+Measured, same box as the benchmarks above (Ruby 4.0.6, linux-arm64, wasmtime 47.0.3):
+
+| Call | wasmtime | native (Magnus) |
+|---|---:|---:|
+| `uuid_new_v7`, single, per call | 867 ns | ~450 ns |
+| `uuid_new_v7_batch(1000)`, per call | 40.6 µs (50.6 µs with the 16 KB read back into Ruby) | 24 µs |
+
+So roughly 2x the native cost per call, and the batch doors amortize it the same way they do
+for Fiddle. The guest's own work is not where the time goes — the identical module runs at
+14 µs per thousand under a JIT-compiled host — it is the crossing, and Ruby's is one of the
+cheaper ones.
+
+## Verifying provenance
+
+Every gem RubyGems.org serves — the universal fallback and each of the six precompiled
+platform gems — carries its own GitHub build-provenance attestation, signed directly by
+this repo's own `release.yml` (the `rubygems-publish` job attests `ruby/pkg/*.gem` right
+before the push), so plain `--repo` verifies any of them:
+
+```sh
+gem fetch hyperuuid -v X.Y.Z --platform <platform>   # or omit --platform for the universal gem
+gh attestation verify hyperuuid-X.Y.Z-<platform>.gem --repo SkunkWerkx/HyperUuid
+```
+
+That's the release's second layer of checking, not the only one: before any gem gets built,
+the same job verifies all ten native binaries it packs (six FFI libs, four Magnus
+extensions) against *their own* attestations — those are signed from `SkunkWerkx/.github`
+by `hyper-build-native.yml`, so that check needs `--signer-repo SkunkWerkx/.github` added —
+and refuses to proceed on an unverified one. RubyGems.org has no unpublish and no
+duplicate-version overwrite, so this all happens while a bad artifact is still reversible.
+The release run's job summary then re-fetches every gem from the CDN and records
+attested-vs-served digests, turning "rubygems.org stores an upload verbatim" into a
+per-release measurement rather than an assumption — see
+[csharp/README.md's provenance section](../csharp/README.md#native-binary-provenance) for
+more on why `--signer-repo` is needed for some artifacts here and not others.
+
 ## Install
 
 ```sh

data/lib/hyperuuid/native/README.md

@@ -1,6 +1,9 @@
 # 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
+and by `cargo build --release` for local dev — see `../../../.gitignore` — plus
+`wasm32-wasip1/hyperuuid.wasm`, the same core as a WebAssembly module for the `wasmtime`
+backend (`../wasm_runtime.rb`), staged the same way from
+`cargo build --release --target wasm32-wasip1` run inside `rust/`. 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.

data/lib/hyperuuid/runtime.rb

@@ -104,6 +104,16 @@ module HyperUuid
         rewrite(:v6_to_rfc_order, bytes)
       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. Backend selection (hyperuuid.rb)
+      # asks this before falling back to the WebAssembly backend, which needs neither.
+      def fiddle_library_available?
+        rid, lib_name = NativePlatform.rid_and_library_name
+        File.exist?(File.join(NATIVE_DIR, rid, lib_name))
+      rescue NativePlatform::UnsupportedPlatformError
+        false
+      end
+
       private
 
       # One 16-byte scratch allocation per thread, reused by every single-item call —

data/lib/hyperuuid/wasm_runtime.rb

@@ -0,0 +1,241 @@
+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, batch slicing) stays shared byte-for-byte across all three backends, and the
+  # same `Runtime::RandomSourceError` / `Runtime::TimestampOutOfRangeError` classes carry the
+  # same messages.
+  #
+  # 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")
+
+    # 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
+      ].freeze
+
+      def initialize(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 { |name| [name, instance.export(name.to_s).to_func] }
+        @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 RandomSourceError, "uuid_new_v4 failed with code #{rc}" 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 RandomSourceError, "uuid_new_v5 failed with code #{rc}" 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, "unix_millis does not fit the 60-bit v6 timestamp field"
+          else raise RandomSourceError, "uuid_new_v6 failed with code #{rc}"
+          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, "unix_millis does not fit the 60-bit v6 timestamp field"
+            else raise RandomSourceError, "uuid_new_v6_batch failed with code #{rc}"
+            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, "unix_millis must fit within the RFC 9562 48-bit field"
+          else raise RandomSourceError, "uuid_new_v7 failed with code #{rc}"
+          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, "unix_millis must fit within the RFC 9562 48-bit field"
+            else raise RandomSourceError, "uuid_new_v7_batch failed with code #{rc}"
+            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
+
+      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.
+      def i64(value)
+        value >= 2**63 ? value - 2**64 : value
+      end
+
+      def u64(value)
+        value.negative? ? value + 2**64 : value
+      end
+    end
+  end
+end

data/lib/hyperuuid.rb

@@ -13,7 +13,7 @@ require_relative "hyperuuid/runtime"
 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.3.0"
 
   # Creates a random UUID version 4 (RFC 9562 §5.4).
   def self.new_v4
@@ -115,8 +115,24 @@ 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.
 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
@@ -136,7 +152,21 @@ 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 "not found" LoadError rather than a vaguer one
+          # from here.
+          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.3.0
 platform: aarch64-linux
 authors:
 - Brian Buvinghausen
@@ -84,11 +84,13 @@ files:
 - 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