hyperuuid-wasm 0.6.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 891b6e2ed78c68a12067a1dd6e8f4ba3a7328f6ba3f5ec3853e56d7c37275baa
+  data.tar.gz: 4252c3cee5c2654d852c3b3818b7de53cb9908ede2f30e6a530ebdaebf40cdd0
+SHA512:
+  metadata.gz: 6fda24dba0eefff039f615a7b80ba66f1948cfc4579bc96be3d81d33f015a30ea821b18ce29cf5f6c9f76f5b72b3f4e7ffa01f3f111ea9b4bd5c7f148d805055
+  data.tar.gz: 011a274e14ea76f4ca6701ca0341c81dd2873b5b658929be8f2834832486dbf7e44312cb2f2ec6ae46da7b952d9e96e50e5c4d2785ef90c1dd32ba38e8bb9127

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Skunk Werkx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,431 @@
+# hyperuuid
+
+[![CI](https://github.com/SkunkWerkx/HyperUuid/actions/workflows/ci.yml/badge.svg)](https://github.com/SkunkWerkx/HyperUuid/actions/workflows/ci.yml)
+[![RubyGems](https://img.shields.io/gem/v/hyperuuid.svg)](https://rubygems.org/gems/hyperuuid)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/SkunkWerkx/HyperUuid/blob/master/LICENSE)
+
+**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. Ruby 3.3 is the floor. 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 and
+their argument checks, batch slicing) is shared byte-for-byte between backends. The
+last-resort fallback, in the universal gem only, calls the native `libhyperuuid` shared
+library via [`Fiddle`](https://docs.ruby-lang.org/en/master/Fiddle.html) — dlopen/dlsym plus
+a raw C-ABI call, no runtime bridge. `HyperUuid::BACKEND` reports which one is live;
+`HYPERUUID_PURE=1` forces Fiddle for testing — see [Backends](#backends).
+
+```ruby
+require "hyperuuid"
+
+id = HyperUuid.new_v4
+id2 = HyperUuid.new_v5(HyperUuid::Namespaces::DNS, "example.com")
+id3 = HyperUuid.new_v6
+id4 = HyperUuid.new_v7
+
+id4.timestamp # recover the embedded UTC Time
+id4.timestamp(raise_on_mismatch: false) # nil instead of raising if id4 isn't v6/v7
+id4.to_sql_order # byte order SQL Server's uniqueidentifier needs to sort by creation order
+
+# One native call, one random-bytes fetch, one counter reservation for the whole batch:
+batch = HyperUuid.new_v7_batch(1000)
+```
+
+## The doors
+
+| Door | Returns | Takes |
+|---|---|---|
+| `new_v4` | `Uuid` | — |
+| `new_v5(namespace, name)` | `Uuid`, the same one for the same pair | a `Uuid` namespace (`Namespaces::DNS`/`URL`/`OID`/`X500`, or your own) and a `String` name — text is hashed as UTF-8, a binary String as its bytes, and it may be empty |
+| `new_v6(time = nil)` `new_v7(time = nil)` | `Uuid` | nothing (now), a `Time`, or an Integer of Unix-epoch milliseconds |
+| `new_v6_batch(count, time = nil)` `new_v7_batch(count, time = nil)` | `Array` of `Uuid` | a count, and the same time forms |
+| `new_v6_batch_bytes(count, time = nil)` `new_v7_batch_bytes(count, time = nil)` | one binary `String`, 16 bytes per UUID | as the batch doors — see [Bulk generation into bytes](#bulk-generation-into-bytes) |
+| `native_version` | the loaded core's `"major.minor.patch"` | — |
+| `available?` | `true`/`false`, never raising | — |
+
+Every generating door returns `HyperUuid::Uuid`, a minimal value object — this gem has no
+runtime dependency on the `uuid` gem:
+
+| On `Uuid` | |
+|---|---|
+| `Uuid.parse(text)` | the 8-4-4-4-12 hyphenated form `#to_s` produces, either case, and nothing else — an `ArgumentError` otherwise |
+| `Uuid.new(bytes)` | wraps 16 raw RFC 9562-ordered bytes |
+| `Uuid::NIL` `Uuid::MAX` | the RFC 9562 §5.9/§5.10 special values |
+| `#bytes` `#to_s` `#version` `#variant` | the frozen binary String, the hyphenated text, the version nibble, the variant bits |
+| `#timestamp(raise_on_mismatch: true)` | the UTC `Time` embedded in a version 6 or 7 UUID; `nil` instead of an `ArgumentError` for any other version when passed `false` |
+| `#to_sql_order` `#from_sql_order` | to and from the byte order SQL Server's `uniqueidentifier` sorts by |
+| `==` `eql?` `hash` `<=>` | value equality and byte-order comparison (`Comparable`) |
+
+`#to_sql_order`/`#from_sql_order` convert a version 6 or 7 UUID to and from the byte order SQL
+Server's `uniqueidentifier` needs on the wire to sort by creation order (`#to_sql_order`
+dispatches on the UUID's own version, matching `#timestamp`'s convention) — computed once in
+the native Rust core rather than reimplemented in Ruby, and verified there (and independently
+against the real `System.Data.SqlTypes.SqlGuid` comparator in the C# binding's test suite).
+Same-millisecond v6 UUIDs aren't guaranteed to sort correctly afterward — v6 has no counter,
+so `clock_seq`/`node` (not the timestamp) decide ties, the same pre-existing RFC 9562 v6
+limitation plain order already has. `#from_sql_order` figures out which version to invert by
+checking a byte position that's provably collision-free between the two (see the method's own
+doc comment).
+
+### Errors
+
+Two exceptions are this gem's own, and both carry the same message on every backend:
+
+- `HyperUuid::TimestampOutOfRangeError` — the time cannot be embedded: past version 7's
+  48-bit millisecond field, past version 6's 60-bit one, or negative (a `Time` before the Unix
+  epoch included).
+- `HyperUuid::RandomSourceError` — the operating system's random source failed.
+
+Through 0.3.0 these were reachable only as `HyperUuid::Runtime::TimestampOutOfRangeError` and
+`HyperUuid::Runtime::RandomSourceError`; those names remain, as aliases of the same classes.
+
+Everything else is a caller bug and raises Ruby's own error for it, checked once in the shared
+doors rather than left to whichever backend is live: a `TypeError` for a time that is not a
+`Time`, an Integer or `nil`, for a count that is not an Integer, for a namespace that is not a
+`Uuid` or a name that is not a `String`; an `ArgumentError` for a count outside
+0..2³² − 1.
+
+### Is the native core there?
+
+`HyperUuid.available?` answers whether a backend actually loaded — probed once, cached, never
+raising — for a consumer with a fallback of its own:
+
+```ruby
+id = HyperUuid.available? ? HyperUuid.new_v7.to_s : SecureRandom.uuid
+```
+
+`HyperUuid.native_version` reads the version out of the loaded core itself (its
+`hyperuuid_version` export), so a mismatch against `HyperUuid::VERSION` can be named before
+the first UUID is minted. `HyperUuid::BACKEND` says which backend was *selected*, which is not
+the same question: it reads `:fiddle` on a platform with no library at all, because that is
+the backend whose first call explains what is missing — a `LoadError` naming the path it
+looked for, or `HyperUuid::NativePlatform::UnsupportedPlatformError` naming the platform.
+
+## Why not `SecureRandom.uuid`?
+
+`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 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.
+
+The honest trade-off: this gem is native code, not pure Ruby — a precompiled extension in each platform gem, and on the universal gem a platform-specific `libhyperuuid.so`/`.dylib`/`.dll` loaded through Fiddle — so it runs only where one of those was built. If plain v4 randomness is all you need, `SecureRandom.uuid` is simpler and already in stdlib — that's a completely reasonable choice.
+
+## Bulk generation into bytes
+
+`new_v6_batch_bytes` and `new_v7_batch_bytes` return the batch as one binary `String` of raw RFC 9562-ordered bytes — 16 per UUID — instead of an Array of `Uuid` objects:
+
+```ruby
+bytes = HyperUuid.new_v7_batch_bytes(1000)
+first = bytes[0, 16]        # ready for a BINARY(16) bind parameter
+```
+
+**About 20x faster than `new_v7_batch`** for a 1000-UUID batch (10.4 µs versus 210 µs). The native call is identical — the difference is that `new_v7_batch` then allocates a `Uuid` object and its byte Strings for every item on top of it. This hands back the bytes the native core already produced, untouched.
+
+The catch, and it inverts the advice: **if you need `Uuid` objects, keep using `new_v7_batch`.** Slicing these bytes into objects yourself just relocates the identical allocations into your own code, and measures no better — sometimes worse. Reach for the byte form only when bytes are the destination: a bind parameter, a wire format, a bulk load.
+
+Slice it with `bytes[i * 16, 16]` — which is exactly what `new_v7_batch` does internally.
+
+## Benchmarks
+
+`ruby benchmark/uuid_benchmark.rb` reproduces every table here and the bytes-versus-objects
+comparison above. Its first line names the backend, core version and Ruby it measured, so
+run it again under `HYPERUUID_PURE=1` for the other backend.
+
+Real numbers, `benchmark-ips` on Ruby 4.0.7, linux-x64 on an Intel Core i9-11900H (`ruby benchmark/uuid_benchmark.rb`) — not claimed, measured. With the Magnus backend (the default wherever the extension loads):
+
+| Call | i/s | vs `SecureRandom.uuid` |
+|---|---:|---:|
+| `SecureRandom.uuid` | 872,365 | baseline |
+| `HyperUuid.new_v4` | 4,278,000 | **4.9x faster** |
+| `HyperUuid.new_v7` (explicit ms) | 3,517,000 | **4.0x faster** |
+| `HyperUuid.new_v6` (explicit ms) | 3,487,000 | **4.0x faster** |
+| `HyperUuid.new_v6` (current time) | 3,324,000 | **3.8x faster** |
+| `HyperUuid.new_v7` (current time) | 3,320,000 | **3.8x faster** |
+| `HyperUuid.new_v5` | 1,838,000 | 2.1x faster |
+
+A `HyperUuid.new_v4` — real entropy, correct version/variant bits, minted by the shared Rust core — costs a fifth of what `SecureRandom.uuid` does, because the Magnus extension is an ordinary native method call with nothing marshalled around it.
+
+The "current time" rows deserve a footnote, because they will not look like this everywhere. Here they land beside the explicit-ms rows: the only difference between the two is one `Process.clock_gettime(CLOCK_REALTIME)` wall-clock read, and on this machine that read is too cheap to see. On a machine with a slow clock it is the whole story — where a virtualized clock defeats the vDSO fast path the same read costs ~1µs, which puts both current-time rows at parity with `SecureRandom.uuid` while the explicit-ms rows stay well ahead of it. `SecureRandom.uuid` never reads a clock — random v4 is the only thing it does. If your clock is slow and you are minting many, read it once and pass the timestamp, or use the batch doors.
+
+The Fiddle fallback (`HYPERUUID_PURE=1`, and any platform without a prebuilt extension) keeps its own diet — a reused thread-local scratch buffer instead of two GC-finalizer-registering mallocs per call, zero-copy `String` passes for read-only inputs, an unsynchronized fast path past the load mutex — landing at 1.25x slower than `SecureRandom.uuid` for v4 (1.26 µs against 1.01 µs in its own run) and 1.45x slower for v6/v7, with the same structural story as before: `Fiddle`'s interpreted marshalling is the floor, and the batch doors are how you amortize it.
+
+Batch generation still amortizes per-call cost on both backends — one native call for the whole batch:
+
+| Call | i/s (Magnus backend) |
+|---|---:|
+| `new_v6` × 1000 (individual) | 3,498 |
+| `new_v6_batch(1000)` | 4,633 (**1.3x**) |
+| `new_v7` × 1000 (individual) | 3,539 |
+| `new_v7_batch(1000)` | 4,677 (**1.3x**) |
+
+The multiplier is small on this backend for the best reason available: the individual calls are cheap, so there is little waste left to amortize, and what `new_v7_batch` spends its 214 µs on is building a thousand `Uuid` objects — the byte form above does the same native work in 10 µs. On the Fiddle backend, where each call costs 1.4 µs, the same batch is 6.7x the loop. 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.
+
+## Backends
+
+| `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) — 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.
+
+`HYPERUUID_PURE` forces `:fiddle`, even where an extension would load. It is a testing and
+diagnostic switch — CI runs the whole suite through it, and it is how to rule an extension
+problem in or out — not a setting a deployment needs. It is read for presence, not value: set
+to anything at all, `0` and the empty string included, it forces Fiddle. A forced backend that
+turns out to have nothing to load does not fall through to another one: the first call raises,
+and `HyperUuid.available?` answers `false`. That is what happens inside a platform gem, which
+carries no Fiddle library: the `LoadError` names the universal gem
+(`gem install hyperuuid --platform ruby`, or Bundler's `force_ruby_platform`), where the
+Fiddle backend lives.
+
+**Threads.** Every backend is safe to call from any number of threads. The extension runs
+under the GVL. Fiddle releases the GVL for the duration of each call, so that is the one
+backend where Ruby threads run the core truly in parallel — each through its own scratch
+buffer, with the core's v7 counter shared and atomic. `spec/hyperuuid_spec.rb`'s "concurrent
+callers" examples run under both.
+
+**Ractors.** Main Ractor only, on every backend: called from another Ractor the doors raise
+`Ractor::UnsafeError`.
+
+## Verifying provenance
+
+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:
+
+```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 every native binary it packs — the Fiddle libraries, the Magnus
+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.
+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
+gem install hyperuuid
+```
+
+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
+Magnus extensions and nothing else native: no Fiddle library at all. The universal gem is
+the last resort, Fiddle with every platform's native library bundled, and it is what
+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. 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
+way [the Python binding's](../python/) wheels do — so each platform gem is a "fat" gem
+carrying one compiled extension per supported Ruby, under `lib/hyperuuid/<minor>/`, and picks
+one at `require` time:
+
+| Ruby | Linux (glibc and musl), Apple silicon macOS, Windows — x64 and arm64 | Gem installed |
+| --- | --- | --- |
+| a newer Ruby than the release covers (4.1+) | Fiddle | universal |
+| 4.0 (primary) | Magnus, `BACKEND == :native` | platform |
+| 3.4 (until its EOL 2028-03-31) | Magnus, `BACKEND == :native` | platform |
+| 3.3 (the floor, until its EOL 2027-03-31) | Fiddle | universal |
+
+What stands behind each cell: CI runs the whole suite through each Magnus extension on every
+push — Ruby 3.4 and 4.0 on all seven platform-gem platforms, the two musl ones inside each
+Ruby's own Alpine image — and the Fiddle suite on Ruby 4.0 on every one of them, plus on Ruby
+3.3 inside Alpine. Intel macOS has no CI leg: its library is cross-built and tested at the
+core, and Ruby there runs the universal gem's Fiddle backend over it. Anywhere else — a platform with no native build at
+all — the universal gem installs but `HyperUuid.available?` answers `false`, and the first
+call raises `HyperUuid::NativePlatform::UnsupportedPlatformError`.
+
+The platform gems declare `required_ruby_version >= 3.4, < 4.1` precisely so RubyGems
+*declines* them outside that range and resolves the universal gem instead — a wrong-ABI
+extension must never be installed in the first place. On Windows it would at least fail to
+load cleanly (the extension imports `<arch>-ucrt-ruby<minor>.dll` by name —
+`x64-ucrt-ruby400.dll` on x64, `aarch64-ucrt-ruby400.dll` on ARM), but Linux extensions
+don't link libruby at all, so one can load successfully against the wrong ABI and misbehave
+later. When 3.4 goes EOL it simply leaves the matrix and its users fall back to Fiddle, which
+is exactly what the fallback is for.
+
+**musl.** Alpine has platform gems of its own, `x86_64-linux-musl` and
+`aarch64-linux-musl`, whose extensions are built inside each Ruby's official `ruby:*-alpine`
+image and need nothing beyond musl's libc. The glibc gems name their libc too
+(`x86_64-linux-gnu`, `aarch64-linux-gnu`), which is what makes both `gem install` and
+Bundler pick the right one on every supported Ruby: next to a plain `x86_64-linux` gem,
+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.** 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
+`data/toolchains.json`); the one it has no support for is MSVC. Windows is also where the
+Fiddle fallback costs the most: measured on win-x64, Ruby 3.4, the Magnus backend does
+`new_v4` in 406ns against Fiddle's 2407ns (**5.9x**) and `new_v7` in 595ns against 2759ns
+(**4.6x**) — a far wider gap than any Linux or macOS leg shows — and on real Windows-on-ARM
+hardware, Ruby 4.0.6, `new_v4` in 416ns against Fiddle's 2299ns (**5.5x**) and `new_v7` in
+621ns against 2474ns (**4.0x**), the same shape. Both extensions are built for the `gnullvm`
+Rust targets rather than `gnu` — the same mingw-w64/UCRT ABI RubyInstaller's Ruby uses,
+linked with LLVM and compiler-rt instead of GCC and a statically-linked libgcc, which is what
+keeps the shipped extension small. The build script, and the two flags that are load-bearing
+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
+use the gem. The Fiddle backend finds the in-repo build on its own when nothing
+is staged under `lib/hyperuuid/native/`. The Magnus backend does not — an extension has to be
+built for the Ruby you are running and put where `require` looks — and that is what
+`rake native:dev` is for.
+
+```sh
+cd rust
+cargo cdylib                           # libhyperuuid, what the Fiddle backend loads
+
+cd ../ruby
+bundle install
+bundle exec rake native:dev          # build the Magnus extension for this Ruby and stage it
+bundle exec rspec                    # BACKEND == :native
+HYPERUUID_PURE=1 bundle exec rspec   # BACKEND == :fiddle
+bundle exec rake docs:check          # every public object carries a doc comment
+ruby benchmark/uuid_benchmark.rb     # prints the backend it measured
+```
+
+`rake native:dev` runs `cargo ruby-ext` (an alias in `rust/.cargo/config.toml` that builds the
+`ruby` feature into `rust/target/ruby/`, never over the plain library in
+`rust/target/release/`) and copies the result to
+`lib/hyperuuid/<minor>/hyperuuid_native.<so|bundle>` — the path `lib/hyperuuid.rb` tries
+first. The copy is also a rename, and it is the step `cargo ruby-ext` alone does not do: cargo
+names its output `libhyperuuid.so`, and Ruby derives the `Init_` function it calls from the
+file name it was asked to `require`. Three things worth knowing:
+
+- **Run it again after changing `rust/`.** The staged file is a copy; nothing rebuilds it.
+- **One staging per Ruby.** An extension is bound to one Ruby minor, so under a second Ruby
+  (`RBENV_VERSION=3.4.11 bundle exec rake native:dev`, say) the task rebuilds for that ABI
+  and stages beside the first, each Ruby loading its own.
+- **Without it, `bundle exec rspec` still passes — on Fiddle.** The examples under "native
+  backend" report themselves pending with `BACKEND=fiddle`; that line, or
+  `ruby -Ilib -rhyperuuid -e 'p HyperUuid::BACKEND'`, is how to tell which backend a run
+  exercised. Deleting `lib/hyperuuid/<minor>/` goes back to Fiddle.
+
+The task covers Linux and macOS. The Windows extensions need the `gnullvm` targets and linker
+flags in the forge's `build-magnus.sh`, which is also what CI uses on every platform.
+
+The musl build has no host to run on outside a container. With the core built for musl at
+`rust/target/musl/linux-musl-x64/libhyperuuid.so`, this runs the Fiddle suite against it on
+Alpine, with the checkout mounted read-only:
+
+```sh
+docker run --rm -v "$PWD/..":/src:ro ruby:4.0-alpine sh -euc '
+  mkdir /work && cp -r /src/ruby /work/ruby
+  mkdir -p /work/ruby/lib/hyperuuid/native/linux-musl-x64
+  cp /src/rust/target/musl/linux-musl-x64/libhyperuuid.so /work/ruby/lib/hyperuuid/native/linux-musl-x64/
+  cd /work/ruby && rm -f Gemfile.lock
+  bundle install --quiet --prefer-local
+  HYPERUUID_PURE=1 bundle exec rspec'
+```
+
+The floor's test is the same container on `ruby:3.3-alpine`. Bundler would compile a newer
+Fiddle there (see [Install](#install)), so this one goes around Bundler and runs against the
+Fiddle that Ruby 3.3 ships:
+
+```sh
+docker run --rm -v "$PWD/..":/src:ro ruby:3.3-alpine sh -euc '
+  mkdir /work && cp -r /src/ruby /work/ruby
+  mkdir -p /work/ruby/lib/hyperuuid/native/linux-musl-x64
+  cp /src/rust/target/musl/linux-musl-x64/libhyperuuid.so /work/ruby/lib/hyperuuid/native/linux-musl-x64/
+  cd /work/ruby && rm -f Gemfile Gemfile.lock
+  gem install rspec -v "~> 3.13" --no-document --silent
+  HYPERUUID_PURE=1 rspec'
+```
+
+The musl Magnus extension is built the way CI builds it by the forge's
+`ruby-magnus-musl/build-magnus-musl.sh`, which runs on any machine with Docker: from the repo
+root, `build-magnus-musl.sh hyperuuid linux-musl-x64 4.0 . <dir with the musl libhyperuuid.so> <out-dir>`
+compiles it in `ruby:4.0-alpine`, then runs this suite through it on a bare copy of that image.
+
+See [the repo root README](../README.md) for the full RFC 9562 coverage table and the state of every other language binding.
+
+## License
+
+[MIT](https://github.com/SkunkWerkx/HyperUuid/blob/master/LICENSE)

data/ext/hyperuuid_native/extconf.rb

@@ -0,0 +1,107 @@
+# The hyperuuid-wasm gem's extension: the Magnus extension, linked statically into a ruby.wasm
+# interpreter by `rbwasm build`. ruby.wasm cannot load an extension at runtime, so a consumer
+# puts this gem in the Gemfile they hand to rbwasm and gets one interpreter with HyperUuid
+# compiled in. Only this companion gem ships this file; the hyperuuid gems do not, because an
+# `extensions` entry there would run extconf on every host `gem install`.
+#
+# Bundler installs the gem on the host first, where there is nothing to build. Then rbwasm runs
+# this again with the cross-compiled Ruby's RbConfig, `make clean`, `make static`, and links
+# every *.a left in the build directory. Both paths below end in the same place: the archive
+# saved as hyperuuid_native.prebuilt (not *.a, which `make clean` removes), copied into place
+# by `make static`.
+#
+#  * Prebuilt, what a consumer gets: the gem carries one gzipped archive per Ruby minor (Rakefile,
+#    wasm:gem), built and attested in CI. No Rust toolchain on the consumer's machine.
+#  * From source, how CI makes those archives: HYPERUUID_RUST_DIR names the crate, and
+#    HYPERUUID_WASM_OUT, if set, receives a copy of the finished archive.
+require "mkmf"
+require "rbconfig"
+require "zlib"
+require "fileutils"
+
+unless RbConfig::CONFIG["host_os"].include?("wasi")
+  File.write("Makefile", dummy_makefile($srcdir).join)
+  exit
+end
+
+# rbwasm reads $target back out to name the extension's Init function in its extinit table.
+$target = "hyperuuid_native"
+minor = "#{RbConfig::CONFIG["MAJOR"]}.#{RbConfig::CONFIG["MINOR"]}"
+prebuilt = "hyperuuid_native.prebuilt"
+
+if (rust_dir = ENV["HYPERUUID_RUST_DIR"])
+  # rb-sys binds against the target Ruby through RBCONFIG_* variables. Ruby is not installed
+  # yet when rbwasm builds extensions, so the two header directories point at the source and
+  # build trees instead (rbwasm sets top_srcdir and extout for exactly this).
+  RbConfig::CONFIG.merge(
+    "rubyhdrdir" => File.join(ENV.fetch("top_srcdir"), "include"),
+    "rubyarchhdrdir" => File.join(ENV.fetch("extout"), "include", RbConfig::CONFIG["arch"])
+  ).each { |key, value| ENV["RBCONFIG_#{key}"] = value.to_s }
+  wasi_sdk = File.dirname(File.dirname(RbConfig::CONFIG["CC"].split.first))
+  ENV["BINDGEN_EXTRA_CLANG_ARGS"] = "--sysroot=#{wasi_sdk}/share/wasi-sysroot " \
+                                    "-D_WASI_EMULATED_SIGNAL -D_WASI_EMULATED_PROCESS_CLOCKS -D_WASI_EMULATED_MMAN"
+  ENV["CC_wasm32_wasip1"] = "#{wasi_sdk}/bin/clang"
+  target_dir = File.expand_path("target")
+  system("cargo", "rustc", "--manifest-path", File.join(rust_dir, "Cargo.toml"), "--release",
+         "--target", "wasm32-wasip1", "--crate-type", "staticlib", "--features", "ruby",
+         "--target-dir", target_dir, exception: true)
+  archive = File.binread(File.join(target_dir, "wasm32-wasip1/release/libhyperuuid.a"))
+  # The crate links into one object (release LTO), and besides Init_hyperuuid_native and the
+  # C ABI it exports three symbols that every Rust extension carrying std defines too:
+  # rust_eh_personality, which wasi-vfs (linked into every ruby.wasm) also defines;
+  # ruby_abi_version, rb-sys's ABI stamp for a dynamically loaded extension, which a static
+  # one never needs; and std's EMPTY_PANIC. Two definitions of any of them stop the link, so
+  # each is renamed to one this crate owns, and the HyperCast extension, renamed the same way,
+  # can share the interpreter. wasm llvm-objcopy can neither localize nor rename a symbol, so
+  # the names are rewritten in place at the same length, which leaves every offset in the
+  # archive and its objects valid (and keeps EMPTY_PANIC's v0 mangling well-formed). Nothing
+  # calls the first two: a static extension's ABI stamp is never looked up, and wasm32-wasip1
+  # builds with panic=abort.
+  {
+    "rust_eh_personality" => "hyperuuid_eh_person",
+    "ruby_abi_version" => "hyperuuid_abiver",
+    "9panicking11EMPTY_PANIC" => "9panicking11HUUID_PANIC"
+  }.each { |from, to| archive.gsub!(from, to) }
+  File.binwrite(prebuilt, archive)
+  system("#{wasi_sdk}/bin/llvm-ranlib", prebuilt, exception: true)
+  # And a newer Rust that exports another of std's symbols fails here, by name, rather than in
+  # the link of an interpreter that also carries the HyperCast extension.
+  member = nil
+  exported = IO.popen(["#{wasi_sdk}/bin/llvm-nm", "--defined-only", "--extern-only", prebuilt], err: File::NULL, &:read)
+               .each_line(chomp: true).filter_map do |line|
+    if line.end_with?(".o:")
+      member = line
+      next
+    end
+    line.split.last if member&.start_with?("hyperuuid-") && line.match?(/\A\h+ [A-Z] /)
+  end
+  shared = exported.grep(/\A(_R|_ZN|rust_|__rust|ruby_abi_version\z)/).grep_v(/HUUID_PANIC\z/)
+  shared.empty? or abort "hyperuuid-wasm: the extension exports #{shared.join(", ")}, which " \
+                         "another Rust extension in the same interpreter would define too"
+  if (out = ENV["HYPERUUID_WASM_OUT"])
+    FileUtils.mkdir_p(File.join(out, minor))
+    FileUtils.cp(prebuilt, File.join(out, minor, "hyperuuid_native.a"))
+  end
+else
+  gz = File.join(__dir__, minor, "hyperuuid_native.a.gz")
+  unless File.exist?(gz)
+    shipped = Dir[File.join(__dir__, "*", "hyperuuid_native.a.gz")].map { |f| File.basename(File.dirname(f)) }
+    abort "hyperuuid-wasm: no prebuilt extension for Ruby #{minor} (this gem carries #{shipped.sort.join(", ")})"
+  end
+  File.binwrite(prebuilt, Zlib::GzipReader.open(gz, &:read))
+end
+
+# install-so is rbwasm's dynamic-linking path (a pic target, for the component model), which
+# a static archive cannot serve.
+File.write("Makefile", <<~MAKE)
+  all: static
+  static:
+  \tcp #{prebuilt} hyperuuid_native.a
+  install-so:
+  \t@echo "hyperuuid-wasm links statically: build a wasm32-unknown-wasip1 interpreter" >&2; exit 1
+  install-rb:
+  \t@true
+  clean:
+  \trm -f hyperuuid_native.a
+  .PHONY: all static install-so install-rb clean
+MAKE

data/lib/hyperuuid/errors.rb

@@ -0,0 +1,12 @@
+module HyperUuid
+  # Raised when the operating system's random source fails while a UUID is being minted —
+  # the one way `new_v4`, `new_v6`, `new_v7` and their batch forms can fail once their
+  # arguments are valid. Carries the same message on every backend.
+  class RandomSourceError < StandardError; end
+
+  # Raised when a timestamp cannot be embedded in the UUID being minted: a version 7 value
+  # past RFC 9562's 48-bit millisecond field, a version 6 value past its 60-bit field, or
+  # any negative one (a `Time` before the Unix epoch included). Carries the same message on
+  # every backend.
+  class TimestampOutOfRangeError < StandardError; end
+end

data/lib/hyperuuid/namespaces.rb

@@ -0,0 +1,13 @@
+module HyperUuid
+  # Well-known namespace UUIDs defined in RFC 9562 Section 6.6.
+  module Namespaces
+    # The DNS namespace UUID.
+    DNS = Uuid.parse("6ba7b810-9dad-11d1-80b4-00c04fd430c8")
+    # The URL namespace UUID.
+    URL = Uuid.parse("6ba7b811-9dad-11d1-80b4-00c04fd430c8")
+    # The ISO OID namespace UUID.
+    OID = Uuid.parse("6ba7b812-9dad-11d1-80b4-00c04fd430c8")
+    # The X.500 DN namespace UUID.
+    X500 = Uuid.parse("6ba7b814-9dad-11d1-80b4-00c04fd430c8")
+  end
+end

data/lib/hyperuuid/native_platform.rb

@@ -0,0 +1,28 @@
+module HyperUuid
+  # Maps the running RUBY_PLATFORM to the RID-style directory (matching the other bindings'
+  # runtimes/{rid}/native/ / native/{rid}/ convention) and native library filename to load.
+  module NativePlatform
+    class UnsupportedPlatformError < StandardError; end
+
+    # +platform+ is a parameter only so the specs can walk the whole table from one host;
+    # every real caller takes the default.
+    def self.rid_and_library_name(platform = RUBY_PLATFORM)
+      arch = platform.match?(/arm64|aarch64/) ? "arm64" : "x64"
+
+      case platform
+      when /mingw|mswin|windows/
+        ["win-#{arch}", "hyperuuid.dll"]
+      when /darwin/
+        ["osx-#{arch}", "libhyperuuid.dylib"]
+      when /linux/
+        # Two C libraries, two builds: a glibc-linked library cannot be relied on to dlopen
+        # into a musl process (Alpine), so musl gets RIDs of its own. Ruby names the libc
+        # in its platform string there ("x86_64-linux-musl") and leaves it off on glibc.
+        os = platform.include?("musl") ? "linux-musl" : "linux"
+        ["#{os}-#{arch}", "libhyperuuid.so"]
+      else
+        raise UnsupportedPlatformError, "hyperuuid: unsupported platform RUBY_PLATFORM=#{platform}"
+      end
+    end
+  end
+end