hyperuuid 0.6.0-x86_64-linux-gnu → 0.6.1-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 16d05177a878c7c35fb8f44fc7f42691cbfdf30b152455d54dc7a1c041991e94
-  data.tar.gz: 12b9a5a8ea701149593f94a2370b42e4e5926f59a200f942bf9330555356b531
+  metadata.gz: d627ef885171a5aa3d5f12c8f53ac9cb6ba13da8d1c497e009dec0703d4f22dd
+  data.tar.gz: 34fca766efc82f71027cc2a5c4140b9858030bd7b67a1657fc604bd515eb3d03
 SHA512:
-  metadata.gz: 9155cd884ee4a26507529073cf7e1a98d0f24438a9dd09dc4508f7af32f577786a1a645b2a264e5b9849aae763258fc414fd564b8da987094f414db63503d4b7
-  data.tar.gz: 56fd684e1058f9c2da5741d5649be692bce1c146c42e005df1b281334b77374a4fb7bb9e78ac177d05a3cad54357a979296b716a5b35fdc71d77b21debf6cc53
+  metadata.gz: d3bc230eb26b9804d3294b75818b5519ac110c5f3dc7b4a9c6a071863e0ecb0c452ece80f151f9ad2758e8248d2bcc9343431d04141453dd2bba05123562abe7
+  data.tar.gz: dd4e4f93ce8d87b77ad4cab6b6958b569cc5aee052ff5e666b92e9c7bf3002dcfb84c03fde16e2d903935ed585bdb85da867c02360e3906d9ab80b8366b9b602

data/README.md

@@ -107,7 +107,7 @@ looked for, or `HyperUuid::NativePlatform::UnsupportedPlatformError` naming the
 
 `SecureRandom.uuid` only ever gives you a random v4 UUID — Ruby's stdlib has no built-in v5, v6, or v7 at all. If you need more than that, the choice is really "which gem":
 
-1. **Full RFC 9562 coverage, one gem, zero extra dependency.** v4/v5/v6/v7 plus batch generation plus `Nil`/`Max`, and the only thing this gem adds to your `Gemfile.lock` beyond `Fiddle` — which is Ruby's own bundled FFI layer, not a third-party C extension to compile.
+1. **Full RFC 9562 coverage, one gem, zero extra dependency.** v4/v5/v6/v7 plus batch generation plus `Nil`/`Max`, and nothing added to your `Gemfile.lock` beyond `Fiddle` — Ruby's own bundled FFI layer, not a third-party C extension to compile — and on the precompiled platform gems not even that.
 2. **No native-extension compile step.** Third-party UUID gems that go beyond v4 are typically pure Ruby or wrap a C extension compiled at install time; this gem ships its fast path as a prebuilt platform-gem extension and its fallback as a `dlopen`ed prebuilt library — either way, the gem itself compiles nothing at install time ([Install](#install) has the one caveat, which is Fiddle's own).
 3. **Batch generation.** `new_v7_batch(1000)` shares one timestamp capture, one random-bytes fetch, and one counter reservation across the whole batch instead of paying per-item overhead a thousand times over.
 4. **Cross-language consistency.** The same Rust core mints v5 namespace UUIDs for Python, Go, C#, and every other binding in this repo — verified in CI to match Python's own `uuid.uuid5` byte-for-byte. If your system isn't Ruby-only, no Ruby-only gem can offer that.
@@ -168,7 +168,7 @@ The multiplier is small on this backend for the best reason available: the indiv
 
 | `HyperUuid::BACKEND` | What runs | Chosen when |
 |---|---|---|
-| `:native` | the core linked into a Magnus extension | a precompiled platform gem is installed — every one carries an extension for each Ruby it installs on; see [Install](#install) |
+| `:native` | the core linked into a Magnus extension | a precompiled platform gem is installed — every one carries an extension for each Ruby it installs on; see [Install](#install) — or the `hyperuuid-wasm` gem is linked into a ruby.wasm interpreter; see [Ruby in the browser](#ruby-in-the-browser) |
 | `:fiddle` | `libhyperuuid` for this platform, `dlopen`ed through Fiddle | no extension loads: the universal gem, on a Ruby or platform no platform gem covers; also the answer when nothing loads at all |
 
 Selection happens once, at `require`, in that order.
@@ -194,8 +194,8 @@ callers" examples run under both.
 
 ## Verifying provenance
 
-Every gem RubyGems.org serves — the universal fallback and each of the seven precompiled
-platform gems — carries its own GitHub build-provenance attestation, signed directly by
+Every gem RubyGems.org serves — the universal fallback, each of the seven precompiled
+platform gems and `hyperuuid-wasm` — 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:
 
@@ -206,8 +206,9 @@ 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 every native binary it packs — the Fiddle libraries, the Magnus
-extensions (one per Ruby ABI per platform) — against *their own*
-attestations — those are signed from `SkunkWerkx/.github` by `hyper-build-native.yml`, so
+extensions (one per Ruby ABI per platform), the `wasm32-wasip1` archives — against *their own*
+attestations — those are signed from `SkunkWerkx/.github` by `hyper-build-native.yml` and
+`hyper-build-wasm.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.
@@ -223,7 +224,7 @@ more on why `--signer-repo` is needed for some artifacts here and not others.
 gem install hyperuuid
 ```
 
-Eight gems are published per release: seven precompiled Magnus platform gems that
+Nine gems are published per release. This section is about eight of them: seven precompiled Magnus platform gems that
 `gem install` and `bundle` auto-select when they match — `x86_64-linux-gnu`,
 `aarch64-linux-gnu`, `x86_64-linux-musl`, `aarch64-linux-musl`, `arm64-darwin`,
 `x64-mingw-ucrt` and `aarch64-mingw-ucrt` — and one universal `ruby`-platform gem. A platform gem carries its
@@ -232,7 +233,7 @@ the last resort, Fiddle with every platform's native library bundled, and it is
 RubyGems resolves for a Ruby the platform gems do not cover (3.3, or a Ruby newer than the
 release, such as 4.1 before a release ships for it) and on a platform no platform gem is
 built for — Intel macOS among them, which runs on Fiddle. No extra configuration needed either
-way.
+way. The ninth, `hyperuuid-wasm`, is only for ruby.wasm; see [Ruby in the browser](#ruby-in-the-browser).
 
 Selection has **two** axes here, unlike every other binding in this repo. A Magnus extension
 is bound to one Ruby minor ABI — there's no `abi3` equivalent to collapse the version axis the
@@ -272,13 +273,17 @@ Bundler pick the right one on every supported Ruby: next to a plain `x86_64-linu
 RubyGems before 4.0 resolves that one on Alpine instead, even under
 `--platform x86_64-linux-musl`.
 
-**Nothing in this gem is ever compiled, on any platform.** Its one dependency can be:
-`fiddle` is a bundled gem on Ruby 4.0 and a default gem on 3.3 and 3.4, and `gem install` is
-satisfied by the copy Ruby ships. Bundler resolves the newest `fiddle` on rubygems.org
-instead, and when that is newer than the one your Ruby ships — true today on 3.3 and 3.4, not
-on 4.0 — it builds Fiddle's own C extension, which takes a compiler and libffi's headers
-(`apk add build-base libffi-dev` on Alpine). Holding `fiddle` at your Ruby's version in the
-`Gemfile.lock` avoids that.
+**Nothing in this gem is ever compiled, on any platform.** The platform gems depend on nothing
+at all. The universal gem depends on `fiddle`, which can be: `fiddle` is a bundled gem on Ruby
+4.0 and a default gem on 3.3 and 3.4, and `gem install` is satisfied by the copy Ruby ships.
+Bundler resolves the newest `fiddle` on rubygems.org instead, and when that is newer than the
+one your Ruby ships — true today on 3.3 and 3.4, not on 4.0 — it builds Fiddle's own C
+extension, which takes a compiler and libffi's headers (`apk add build-base libffi-dev` on
+Alpine). That only reaches you where the universal gem installs: Ruby 3.3, Intel macOS, a
+Ruby newer than the release, or a platform with no platform gem. `bundle install
+--prefer-local` makes Bundler use the copy Ruby ships where it can (it did on Ruby 3.4's
+Bundler 2.6, not on 3.3's 2.5); otherwise install the compiler and headers. Pinning `fiddle`
+to your Ruby's version in the `Gemfile.lock` does not stop the build.
 
 Both Windows architectures get a Magnus gem. MinGW is the *only* Windows flavour `rb-sys`
 targets (`x64-mingw-ucrt` and `aarch64-mingw-ucrt`, both `supported: true` in its own
@@ -294,6 +299,57 @@ keeps the shipped extension small. The build script, and the two flags that are
 on the ARM leg (a static libunwind, and a clang-spelled `--target` for bindgen), live in the
 forge's `ruby-magnus` action (`build-magnus.sh`), shared with every other Hyper* repo.
 
+## Ruby in the browser
+
+ruby.wasm cannot load an extension at runtime. `rbwasm build` cross-compiles the extension of
+every gem in a Gemfile and links them all into the one interpreter it builds, so the browser
+gets a gem of its own: `hyperuuid-wasm`, the same library and the same Magnus extension,
+prebuilt for `wasm32-wasip1`. List it **instead of** `hyperuuid` in the Gemfile you build the
+interpreter from (the two carry the same `lib/` files):
+
+```ruby
+source "https://rubygems.org"
+
+gem "hyperuuid-wasm"
+gem "js" # JavaScript interop, which a browser app almost always wants
+
+group :development do
+  gem "ruby_wasm"
+end
+```
+
+```sh
+bundle install
+bundle exec rbwasm build --ruby-version 4.0 -o ruby.wasm
+```
+
+Load `ruby.wasm` with [`@ruby/wasm-wasi`](https://www.npmjs.com/package/@ruby/wasm-wasi)
+(`DefaultRubyVM` in a browser, `RubyVM.instantiateModule` under Node), then
+`require "/bundle/setup"` and `require "hyperuuid"` as anywhere else. `HyperUuid::BACKEND` is
+`:native`: every door, the batch and raw-bytes forms, and `new_v6`/`new_v7` with no argument,
+which read the clock through WASI.
+
+- **Ruby 3.4 and 4.0**, one archive each, the same minors the platform gems cover, picked by
+  `--ruby-version`. Any other minor stops the build with a message naming the ones the gem
+  carries. Built and tested against ruby_wasm 2.10.
+- **No Rust toolchain.** The gem's `extconf.rb` only hands rbwasm the prebuilt archive, and
+  rbwasm downloads its own wasi-sdk. The first `rbwasm build` compiles Ruby itself and takes
+  15–20 minutes; later builds reuse it.
+- **Static linking only,** into ruby.wasm's default `wasm32-unknown-wasip1` interpreter.
+  rbwasm's dynamic-linking build (a pic target, for the component model) is not supported.
+- **Size.** rbwasm packs every gem's files into the interpreter, the archives included, so the
+  gem adds about 2 MB to `ruby.wasm` (both archives are gzipped).
+- **With HyperCast.** `hypercast-wasm` links into the same interpreter. Every Rust extension
+  that carries std defines a few of the same symbols (`rust_eh_personality`, which ruby.wasm's
+  own wasi-vfs defines too, rb-sys's `ruby_abi_version`, and one of std's), and both gems
+  rename them to names of their own when CI builds the archive, which also fails if a newer
+  Rust starts exporting another.
+
+What stands behind it: CI builds each minor's archive from the commit, packs the gem the way
+it ships, links it into a fresh interpreter and runs [`wasm-smoke/test.rb`](wasm-smoke/test.rb)
+under Node and in headless Chrome (the forge's `hyper-build-wasm.yml`). The published gem is
+packed around those attested archives.
+
 ## Development
 
 Everything below runs from a checkout, with `rust/` beside `ruby/`; none of it is needed to

data/lib/hyperuuid/runtime.rb

@@ -1,10 +1,15 @@
-require "fiddle"
+# 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 Swift binding's
-  # dlopen approach). Fiddle ships with every Ruby install; it's a plain gem dependency here
-  # (see hyperuuid.gemspec) rather than a third-party one — mirroring Python's
+  # 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
@@ -63,7 +68,7 @@ module HyperUuid
 
       def new_v6_batch(count, unix_millis)
         return "" if count.zero?
-        out = Fiddle::Pointer.malloc(count * 16, Fiddle::RUBY_FREE)
+        out = buffer(count * 16)
         rc = functions[:new_v6_batch].call(unix_millis, count, out)
         case rc
         when 0 then out[0, count * 16]
@@ -88,7 +93,7 @@ module HyperUuid
 
       def new_v7_batch(count, unix_millis)
         return "" if count.zero?
-        out = Fiddle::Pointer.malloc(count * 16, Fiddle::RUBY_FREE)
+        out = buffer(count * 16)
         rc = functions[:new_v7_batch].call(unix_millis, count, out)
         case rc
         when 0 then out[0, count * 16]
@@ -175,7 +180,15 @@ module HyperUuid
       # (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] ||= Fiddle::Pointer.malloc(16, Fiddle::RUBY_FREE)
+        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

data/lib/hyperuuid.rb

@@ -18,7 +18,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.6.0"
+  VERSION = "0.6.1"
 
   # 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.)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hyperuuid
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: x86_64-linux-gnu
 authors:
 - Brian Buvinghausen
@@ -9,20 +9,6 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: fiddle
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement