mini_racer_rs 1.0.0

data/Cargo.toml

@@ -0,0 +1,62 @@
+[workspace]
+exclude = ["crates/mini_racer_wire/fuzz"]
+members = [
+  "crates/mini_racer_engine",
+  "crates/mini_racer_sync",
+  "crates/mini_racer_wire",
+  "ext/mini_racer_rs",
+]
+resolver = "3"
+
+[workspace.package]
+edition = "2024"
+license = "MIT"
+publish = false
+repository = "https://github.com/andymai/mini_racer_rs"
+rust-version = "1.91"
+version = "1.0.0"
+
+[workspace.dependencies]
+deno_core_icudata = "=0.78.0"
+libc = "0.2"
+loom = "0.7.2"
+magnus = {version = "=0.9.2", features = ["rb-sys"]}
+mini_racer_engine = {path = "crates/mini_racer_engine"}
+mini_racer_sync = {path = "crates/mini_racer_sync"}
+mini_racer_wire = {path = "crates/mini_racer_wire"}
+proptest = {version = "1", default-features = false, features = ["std"]}
+rb-sys = "=0.9.130"
+thiserror = "2"
+v8 = "=152.2.0"
+
+[workspace.lints.rust]
+unexpected_cfgs = {level = "warn", check-cfg = ["cfg(loom)"]}
+unsafe_code = "deny"
+unsafe_op_in_unsafe_fn = "deny"
+
+[workspace.lints.clippy]
+all = {level = "deny", priority = -1}
+allow_attributes_without_reason = "deny"
+dbg_macro = "deny"
+exit = "deny"
+expect_used = "deny"
+mem_forget = "deny"
+multiple_unsafe_ops_per_block = "deny"
+nursery = {level = "warn", priority = -1}
+panic = "deny"
+pedantic = {level = "warn", priority = -1}
+print_stderr = "deny"
+print_stdout = "deny"
+todo = "deny"
+undocumented_unsafe_blocks = "deny"
+unimplemented = "deny"
+unwrap_used = "deny"
+# Internal crates with no published API surface.
+missing_errors_doc = "allow"
+missing_panics_doc = "allow"
+module_name_repetitions = "allow"
+
+[profile.release]
+debug = "line-tables-only"
+# FFI guards (invariant I4) turn panics into errors, which needs unwinding.
+panic = "unwind"

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andy Aragon
+
+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,254 @@
+<div align="center">
+
+# mini_racer_rs
+
+A drop-in replacement for mini_racer, implemented in Rust on V8 15.2.
+
+[![CI](https://github.com/andymai/mini_racer_rs/actions/workflows/ci.yml/badge.svg)](https://github.com/andymai/mini_racer_rs/actions/workflows/ci.yml)
+[![Commit activity](https://img.shields.io/github/commit-activity/m/andymai/mini_racer_rs?label=commits%2Fmonth)](https://github.com/andymai/mini_racer_rs/commits/main)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Ruby 3.3 | 3.4 | 4.0](https://img.shields.io/badge/ruby-3.3%20%7C%203.4%20%7C%204.0-red.svg)](#scope)
+[![V8 15.2](https://img.shields.io/badge/V8-15.2-4285F4.svg)](#how-it-works)
+[![mini_racer 0.22.1 suite](https://img.shields.io/badge/mini__racer%200.22.1%20suite-passing-success.svg)](COMPATIBILITY.md)
+
+**[Install](#install)** · **[Quick start](#quick-start)** · **[API](#api-at-a-glance)** · **[Switching](#switching-from-mini_racer)** · **[Benchmarks](#benchmarks)** · **[How it works](#how-it-works)** · **[Compatibility](COMPATIBILITY.md)** · **[Architecture](ARCHITECTURE.md)**
+
+</div>
+
+mini_racer_rs implements the `MiniRacer` Ruby API from mini_racer 0.22.1, with faster Ruby and JavaScript round trips, V8 15.2, prebuilt native gems, fiber scheduler support, and safer handling of difficult values. It defines the `MiniRacer` namespace and ships `lib/mini_racer.rb`, so `require "mini_racer"` and ExecJS continue to work.
+
+> **Pre-release:** Nothing is published to RubyGems.org yet, and the release workflow is held. Install from the repository until the first release. mini_racer_rs is an independent project and is not affiliated with the Discourse staff who maintain mini_racer.
+
+## Highlights
+
+- **4 to 5 times faster Ruby round trips.** An eval, call, or callback round trip takes 1.3 to 1.6 µs, against 6.1 to 6.6 µs in mini_racer. A call on a context with `timeout:` takes 1.6 µs instead of 21.1 µs because one watchdog serves the process.
+- **1.9 times faster Babel transforms.** A transform through ExecJS takes 5.3 ms instead of 10.0 ms. Babel itself takes 5.3 ms inside V8 15.2, against 10.3 ms inside V8 13.6. Terser and React rendering take about the same time in both gems.
+- **4.6 times faster production bundle loads.** Scripts of 1 MB or more compile from a process-wide V8 code cache. A 44 MB production server rendering bundle loads into a new context in 215 ms against 983 ms. The 8.2 MB MUI bundle loads and renders once in 121 ms against 167 ms, and startup plus Babel takes 14.8 ms against 44.8 ms.
+- **Less memory for loaded and abandoned contexts.** A context holding the 44 MB bundle takes 136 MB against 301 MB, and one holding the MUI bundle takes 56 MB against 110 MB. When 20,000 contexts are left to Ruby's garbage collector, resident memory peaks at 102 MB against 2,916 MB.
+- **Forks pause worker work, and children use their own threads.** For forks made through Ruby's `fork`, `IO.popen("-")`, or `Process.daemon`, mini_racer_rs waits for context runners, pauses its worker pool, and waits for running tasks; an async `WebAssembly.compile` in a new default-mode child completes on the child's own pool. On Ubuntu 24.04 with glibc 2.39, 20 of 20 mini_racer children aborted with signal 6 after loading and rendering React, while 20 of 20 mini_racer_rs children exited cleanly. On Fedora, mini_racer children hung within the first 50 forks of `test/stress/fork_busy.rb`, while mini_racer_rs completed 300 forks per run on Fedora and Ubuntu.
+- **V8 15.2.124.1.** mini_racer 0.22.1 uses V8 13.6.233.17.
+- **No compiler at release install.** Native gems cover glibc Linux on x86_64 and aarch64, plus macOS on arm64 and x86_64. Each carries extensions for Ruby 3.3, 3.4, and 4.0. mini_racer 0.22.1 ships as source and compiles C++ against libv8-node.
+- **Fiber scheduler support.** A fiber waiting on JavaScript lets other fibers on its thread run. Three 100 ms busy loops in separate contexts and fibers finish in 100 ms, against 300 ms when mini_racer blocks the thread.
+- **171 of 174 upstream tests pass.** The mini_racer suite runs unmodified, with its other 3 tests skipped by mini_racer itself. ExecJS passes 197 of 198 tests on its MiniRacer runtime, with 1 skipped.
+- **Difficult values return safely.** A `Map` with a function key returns an error Hash instead of aborting the process with SIGABRT. `Object(1n)` returns `1`, and an offset typed array returns its buffer as a binary String.
+- **Four checked layers.** A script enforces crate boundaries, `unsafe` is confined to four fenced modules, loom model-checks the thread handoff, fuzzing covers the wire codec, sanitizers run nightly, and results are differentially tested against mini_racer. The release pipeline runs the full suites for every released extension.
+
+All performance numbers compare mini_racer_rs with mini_racer 0.22.1 on Ruby 3.4.2 and Linux on an AMD Ryzen 9 7950X3D, with both gems pinned to the same eight cores and the `performance` governor.
+
+## Install
+
+The package switch is one Gemfile line:
+
+```diff
+- gem "mini_racer"
++ gem "mini_racer_rs"
+```
+
+Run `bundle install`. Bundler is required because RubyGems may otherwise activate the original `mini_racer` first. Loading both gems raises a `LoadError` that names the conflict. Reverse the Gemfile change to switch back.
+
+Until the first release publishes native gems, build from a checkout as described in [CONTRIBUTING.md](CONTRIBUTING.md). Run `bin/setup`. Source builds require Rust 1.91 or newer and libclang. Once published, installing a native gem will compile nothing.
+
+## Quick start
+
+This example was run against both gems and produced exactly the outputs shown:
+
+```ruby check
+require "mini_racer"
+
+context = MiniRacer::Context.new(timeout: 500, max_memory: 50_000_000)
+
+context.eval("function add(a, b) { return a + b }")
+context.call("add", 2, 3)                      # => 5
+
+context.attach("ruby.upcase", ->(text) { text.upcase })
+context.eval("ruby.upcase('hello')")           # => "HELLO"
+
+context.eval_await("Promise.resolve(42)")      # => 42
+
+begin
+  context.eval("while (true) {}")
+rescue MiniRacer::ScriptTerminatedError => e
+  e.message                                    # => "terminated"
+end
+context.eval("add(1, 1)")                      # => 2
+
+snapshot = MiniRacer::Snapshot.new("var greeting = 'hello from a snapshot'")
+MiniRacer::Context.new(snapshot: snapshot).eval("greeting") # => "hello from a snapshot"
+```
+
+ExecJS 2.10.2 uses it as its MiniRacer runtime:
+
+```ruby check
+require "execjs"
+
+ExecJS.runtime.name                            # => "mini_racer (V8)"
+ExecJS.eval("[1, 2].map(x => x * 2)")         # => [2, 4]
+```
+
+## API at a glance
+
+| API | What it does |
+|---|---|
+| `Context.new(**options)` | Creates a context with its own V8 isolate and runner thread. |
+| `Context#eval(source, filename: nil)` | Runs JavaScript and returns the result as Ruby values. |
+| `Context#call(name, *args)` | Calls a global JavaScript function by dotted name with Ruby arguments. |
+| `Context#eval_await`, `#call_await` | Like `eval` and `call`, but wait for a returned Promise to settle and return its value. A rejection raises `MiniRacer::RuntimeError`. |
+| `Context#attach(name, callable)` | Exposes a Ruby proc or method under a dotted JavaScript name. |
+| `Context#load(path)` | Evaluates a JavaScript file. |
+| `Context#stop` | Terminates a running script from another thread. |
+| `Context#dispose` | Frees the isolate. |
+| `Context#heap_stats`, `#heap_snapshot`, `#write_heap_snapshot(path)`, `#low_memory_notification` | Inspects the heap, writes snapshots, or asks V8 to free memory. |
+| `Context#pump_message_loop`, `#perform_microtask_checkpoint` | Runs pending V8 tasks and microtasks. |
+| `Snapshot.new`, `#warmup!`, `#dump`, `Snapshot.load` | Creates, warms, serializes, and loads startup snapshots. |
+| `Platform.set_flags!(*flags)` | Sets V8 flags before the first context. |
+
+`Context.new` accepts these options:
+
+| Option | Effect |
+|---|---|
+| `timeout:` | Maximum milliseconds for each eval or call before `MiniRacer::ScriptTerminatedError`. |
+| `max_memory:` | V8 heap limit in bytes, checked after each garbage collection. An overage raises `MiniRacer::V8OutOfMemoryError`, and the context remains usable. |
+| `ensure_gc_after_idle:` | Idle milliseconds before one full garbage collection. `0` disables it. |
+| `snapshot:` | A `MiniRacer::Snapshot` used to initialize the context. |
+
+Errors are `MiniRacer::ParseError`, `MiniRacer::RuntimeError` with JavaScript frames in its backtrace, `MiniRacer::ScriptTerminatedError`, `MiniRacer::V8OutOfMemoryError`, `MiniRacer::ContextDisposedError`, `MiniRacer::SnapshotError`, and `MiniRacer::PlatformAlreadyInitialized`. All descend from `MiniRacer::Error`.
+
+## Switching from mini_racer
+
+### What changes
+
+The public API and require path stay the same. The main changes are native installation, faster small calls and Babel transforms, fiber-aware waiting, newer V8 behavior, and safer conversion of difficult values. Applications that make many small calls gain the most. See [Highlights](#highlights) for measurements.
+
+### Check before you ship
+
+- You're affected if your tests or code compare exact JavaScript error messages or locale-formatted text. V8 15.2 can word them differently from V8 13.6.
+
+- You're affected if an attached Ruby callback calls back into its own context from another fiber, such as inside `Enumerator#next`. mini_racer_rs raises `ThreadError`; mini_racer allows it.
+
+- You're affected if a callback exits by `throw`, returns out of a proc, or is stopped by `Thread#kill`. The script ends with `Error: terminated`, then the jump continues after `eval` returns. mini_racer hangs.
+
+- You're affected if JavaScript reads a non-ASCII message from a callback exception. mini_racer_rs passes UTF-8, such as `"café"`, while mini_racer passes `"café"`.
+
+- You're affected if `fork`, `IO.popen("-")`, or `Process.daemon` runs after V8 starts. Both modes wait up to 500 ms for runners, interrupting JavaScript after 50 ms; both then pause the worker pool and wait up to 100 ms for running tasks. Uninterruptible operations and workers can outlast these best-effort waits, and the fork proceeds. Default children reject inherited contexts; new contexts run worker work on the child's own threads, but are best effort after either wait expires. `:single_threaded` children take over idle inherited contexts, reject busy ones (all after runner timeout), and accept new contexts.
+
+- You're affected if, with `:single_threaded`, you fork in a way that bypasses Ruby's `fork`, such as a C-level `fork()`. Inherited contexts are unusable in the child.
+
+- You're affected if another thread calls `dispose` while a call is running. It returns after the call finishes and the isolate is gone. mini_racer returns immediately and frees the isolate later.
+
+- You're affected if your code references `MiniRacer::Loader`. It does not exist in mini_racer_rs.
+
+See [COMPATIBILITY.md](COMPATIBILITY.md) for every difference.
+
+### Stay on mini_racer if
+
+- You deploy on musl-based Linux such as Alpine. mini_racer supports it through libv8-node's musl gems, while mini_racer_rs does not install there. Neither gem supports Windows.
+
+- You need a gem from RubyGems.org today. mini_racer_rs is pre-release, while mini_racer is the established gem maintained by Discourse staff.
+
+- Download size matters more than compile time. The largest mini_racer_rs native gem is 65.6 MB because it includes extensions for three Ruby versions. The mini_racer download on x86_64 Linux is 47.1 MB, followed by compilation.
+
+### Gems that depend on mini_racer
+
+If another gem brings in `mini_racer`, point Bundler at the repository's shim. It is an empty gem named `mini_racer`, version 0.22.1, that depends on the `mini_racer_rs` version from the same checkout.
+
+```ruby
+gem "mini_racer_rs"
+gem "mini_racer", github: "andymai/mini_racer_rs", tag: "vX.Y.Z", glob: "shim/*.gemspec"
+```
+
+The repository tests shim resolution with `path:` sources and rtlcss in `test/consumers/transitive/`. The `github:` form has not been run end to end. A dependency whose `mini_racer` requirement excludes version 0.22.1 cannot use the shim.
+
+## Benchmarks
+
+| Workload | mini_racer 0.22.1 | mini_racer_rs | Ratio |
+|---|---:|---:|---:|
+| Babel transform of a 3 KB JSX component, through ExecJS | 10.0 ms | 5.3 ms | 1.9x |
+| Terser minify of a 78 KB library, through ExecJS | 51.6 ms | 51.2 ms | 1.0x |
+| React server render of 1,000 items (17 KB of HTML), through ExecJS | 192 µs | 174 µs | 1.1x |
+| React in a new context: load the bundle and render 1,000 items, through ExecJS | 12.0 ms | 12.1 ms | 1.0x |
+| Handlebars render of 50 rows, through `Context#call` | 47.9 µs | 40.1 µs | 1.2x |
+| Autoprefixer on Bootstrap's 280 KB stylesheet, through ExecJS | 27.2 ms | 23.7 ms | 1.1x |
+| MUI dashboard server render of 200 rows and 299 icons (469 KB of HTML), through ExecJS | 32.2 ms | 30.5 ms | 1.1x |
+| MUI in a new context: load the 8.2 MB bundle and render once, through ExecJS | 167 ms | 121 ms | 1.4x |
+| Load a 44 MB production server rendering bundle into a new context, through ExecJS | 983 ms | 215 ms | 4.6x |
+
+The table reports the eight library workloads plus the 44 MB production server rendering bundle load. Results are medians of 5 runs from the release build of commit `2513a48`, with every workload producing identical output in both gems. They were measured on Ruby 3.4.2 and Linux on an AMD Ryzen 9 7950X3D, with the CPU governor set to `performance` and both gems pinned to CPUs 0 through 7.
+
+```sh
+bundle exec ruby bench/run.rb --cpus 0-7
+```
+
+[BENCHMARKS.md](BENCHMARKS.md) describes the method, per-call costs, memory results, and mini_racer's own `benchmark/serde` suite.
+
+<!-- compat-table:start -->
+## Compatibility
+
+| Engine | Done | Planned | Deviation |
+|---|---|---|---|
+| CRuby | 54 | 0 | 25 |
+| TruffleRuby | 58 | 0 | 0 |
+
+See [COMPATIBILITY.md](COMPATIBILITY.md).
+<!-- compat-table:end -->
+
+## How it works
+
+mini_racer_rs uses the `v8` crate, rusty_v8 152.2.0, with Ruby bindings through magnus and rb-sys. Each context owns a V8 isolate and a native runner thread with a stack of at least 2 MiB, so V8 frames never use a Ruby thread's stack. A per-context lock permits one dispatch at a time.
+
+```text
+ Ruby thread                          runner thread (one per context)
+ ───────────                          ───────────────────────────────
+ MiniRacer::Context#eval
+   │ encode request (V8 wire format)
+   ├──────────── channel ───────────▶ receive request
+   │ spin, then park (GVL released)    run JavaScript in the V8 isolate
+   │                                   serialize the result
+   ◀──────────── channel ─────────────┤
+   │ decode straight into Ruby objects
+   ▼
+ result
+```
+
+A waiting Ruby thread first spins briefly with the GVL held, then spins without it, then parks with the GVL released. Under a fiber scheduler, only the waiting fiber parks. Values use V8's serialization format and decode directly into Ruby objects without an intermediate tree. Repeated objects retain their identity.
+
+One watchdog thread per process enforces every context's `timeout:`. In `:single_threaded` mode, a fork quiesces the runners, the child takes over contexts that were idle, and contexts in use raise there. In every process, mini_racer_rs points V8's platform at a copied vtable whose worker-thread slots post to a pool it owns. V8's platform has one worker thread, which never receives a task. A fork pauses the pool, and the parent resumes it when the fork returns; inherited contexts raise in the child in the default multi-threaded mode.
+
+The implementation is split into four crates:
+
+- `mini_racer_wire`: the wire codec, with no unsafe code.
+- `mini_racer_sync`: the thread protocol, with no unsafe code and loom checking.
+- `mini_racer_engine`: V8 process state and runners, and the only crate that names `v8`.
+- `mini_racer_rs`: the Ruby extension, and the only crate that names magnus or rb-sys.
+
+[ARCHITECTURE.md](ARCHITECTURE.md) follows a call end to end and covers the design in depth.
+
+## Scope
+
+mini_racer_rs deliberately does not:
+
+- Run on Windows or musl-based Linux such as Alpine. Supported platforms are glibc Linux on x86_64 and aarch64, plus macOS on arm64 and x86_64.
+
+- Provide Node.js APIs. JavaScript runs in plain V8 without file system, network, or process access. JavaScript can reach only the Ruby callables you `attach`.
+
+- Work reliably without Bundler. RubyGems may activate the original mini_racer first.
+
+- Satisfy a dependency that pins a `mini_racer` version other than 0.22.1. This includes minibars with its `~> 0.6.4` requirement.
+
+- Extend the `MiniRacer` API beyond mini_racer 0.22.1. Deliberate differences are recorded in [COMPATIBILITY.md](COMPATIBILITY.md).
+
+Supported Ruby implementations are CRuby 3.3, 3.4, and 4.0, plus TruffleRuby through mini_racer's unchanged TruffleRuby backend.
+
+## Documentation
+
+| Document | Covers |
+|---|---|
+| [ARCHITECTURE.md](ARCHITECTURE.md) | Crates, a call end to end, values, termination, callbacks, promises, snapshots, forks, fiber schedulers, safety rules, and verification. |
+| [COMPATIBILITY.md](COMPATIBILITY.md) | Every public API item and deliberate difference from mini_racer 0.22.1, with its reason. |
+| [BENCHMARKS.md](BENCHMARKS.md) | Benchmark method and full results. |
+| [STABILITY.md](STABILITY.md) | Versioning, the public API, unstable interfaces, and support policy. |
+| [SECURITY.md](SECURITY.md) | Vulnerability reporting, untrusted JavaScript, and supply-chain controls. |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Setup, checks, tests, and conventions. |
+
+## License
+
+mini_racer_rs is available under the [MIT License](LICENSE). [AI-DISCLOSURE.md](AI-DISCLOSURE.md) describes how AI tooling was used to build the project.