hypercast 0.6.0 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f482418099cb3b96492d839da3f627716b4b4ba6a1b083d66f47f337edb197b3
-  data.tar.gz: 92e9560c193bd102dbbff75ace2b3aaa8dba75527a217c2b7f730f227af3e27b
+  metadata.gz: 53866363cee28bda9e47267c85d4c835708fb9aa20635c3968cb32985d12c264
+  data.tar.gz: 654ae196935c0fb5cb8b0393ad11c1a5c5f52845321d1ac6468dfc4dc3159663
 SHA512:
-  metadata.gz: 7f24fc4d78125c73b521c631318b778367321438c1791ee8e6055805d8bd2c274f2dd358d30af309350a201faba1aba0772815974a1c187d64896ad4f3f92af0
-  data.tar.gz: f349625cd4fd7b6dfa1311484186c924705a4c480213ace67aa1a6dea6b68e78d464f9187fbf0da88129c6995cc5f40e99fc01ae001088751ffe66b6e288af14
+  metadata.gz: 5fb20b6b023d88e80fc8ea334925310b5436c3aaca0ebcf86606f8794da375823019cc0efbf60445472bdcf6cee4cefd8f76eeb1475d87e3cbead7e26988d8e3
+  data.tar.gz: f51ff3c89feaaa99f38fec564f779364b358f1ba7f76c783e24202890e751183172df49352c7eeef6caf8bf54edf10b0493c8d453981e3136dd40791d969d31a

data/README.md

@@ -230,7 +230,7 @@ rather than through `Data.new`, whose keyword handling alone cost more than the
 
 | `HyperCast::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 `hypercast-wasm` gem is linked into a ruby.wasm interpreter; see [Ruby in the browser](#ruby-in-the-browser) |
 | `:fiddle` | `libhypercast` 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.
@@ -256,8 +256,8 @@ concurrent-callers example runs 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 `hypercast-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:
 
@@ -268,8 +268,9 @@ gh attestation verify hypercast-X.Y.Z-<platform>.gem --repo SkunkWerkx/HyperCast
 
 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
@@ -285,7 +286,7 @@ more on why `--signer-repo` is needed for some artifacts here and not others.
 gem install hypercast
 ```
 
-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
@@ -294,7 +295,7 @@ universal gem is the last resort, Fiddle with every platform's native library bu
 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.
+way. The ninth, `hypercast-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 is no `abi3` equivalent to collapse the version axis
@@ -358,6 +359,60 @@ the shipped extension small. The build script, and the two flags that are load-b
 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: `hypercast-wasm`, the same library and the same Magnus extension,
+prebuilt for `wasm32-wasip1`. List it **instead of** `hypercast` in the Gemfile you build the
+interpreter from (the two carry the same `lib/` files):
+
+```ruby
+source "https://rubygems.org"
+
+gem "hypercast-wasm"
+gem "js" # JavaScript interop, which a browser app almost always wants
+gem "bigdecimal" # only for Decimal#to_d; see below
+
+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 "hypercast"` as anywhere else. `HyperCast::BACKEND` is
+`:native`, and every door works as it does on a host Ruby.
+
+- **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.
+- **`Decimal#to_d` needs `gem "bigdecimal"` in that Gemfile.** bigdecimal is a bundled gem
+  with a C extension, and ruby.wasm builds a bundled gem's extension only when the Gemfile
+  names it; without it, `to_d` raises `LoadError`. `to_s` and `to_r` need nothing.
+- **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 HyperUuid.** `hyperuuid-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/` and `corpus/` beside `ruby/`; none of it

data/lib/hypercast.rb

@@ -29,7 +29,7 @@ require_relative "hypercast/runtime"
 module HyperCast
   # This gem's own version — kept in lockstep with hypercast.gemspec by the
   # prepare-release workflow, so the two can never drift apart again.
-  VERSION = "0.6.0"
+  VERSION = "0.6.1"
 
   # The success case of a verdict: a cast value.
   Success = Data.define(:value)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hypercast
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.6.1
 platform: ruby
 authors:
 - Brian Buvinghausen