mini_racer_rs 1.0.6 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
data/README.md CHANGED
@@ -15,42 +15,42 @@ A drop-in replacement for mini_racer, implemented in Rust on V8 15.2.
15
15
 
16
16
  </div>
17
17
 
18
- 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.
18
+ mini_racer_rs implements the `MiniRacer` API from mini_racer 0.22.1. It defines `MiniRacer` and ships `lib/mini_racer.rb`, so `require "mini_racer"` and ExecJS keep working.
19
19
 
20
20
  > mini_racer_rs is an independent project and is not affiliated with the Discourse staff who maintain mini_racer.
21
21
 
22
22
  ## Highlights
23
23
 
24
- - **JavaScript round trips are 5 to 9 times faster.** An eval takes 1.09 µs against 6.91 µs, a call takes 0.72 µs against 6.51 µs, and a callback takes 1.12 µs against 6.12 µs. A call on a context with `timeout:` takes 0.76 µs instead of 20.48 µs because one watchdog serves the process.
25
- - **A Babel transform through ExecJS is 1.95x faster.** It takes 5.15 ms instead of 10.05 ms. Babel itself takes 5.3 ms inside V8 15.2, against 10.3 ms inside V8 13.6, while Terser and React rendering take about the same time in both gems.
26
- - **A 44 MB production server rendering bundle loads 4.6x faster.** It loads into a new context in 215 ms against 983 ms, measured at commit `2513a48`, and scripts of 1 MB or more compile from a process-wide V8 code cache. At commit `220bfe7`, the 8.2 MB MUI bundle loads and renders once in 105 ms against 167 ms, while startup plus Babel takes 13.3 ms against 44.4 ms.
27
- - **A context holding the MUI bundle uses 44 MB instead of 110 MB.** At commit `220bfe7`, a context holding Babel uses 15.2 MB against 28.5 MB, and contexts loading the same large script read one shared copy of its source. A context holding the 44 MB production bundle used 136 MB against 301 MB at commit `2513a48`, before sources were shared. When 20,000 contexts are left to Ruby's garbage collector, resident memory peaks at 102 MB against 2,920 MB.
28
- - **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.
29
- - **V8 15.2.124.1.** mini_racer 0.22.1 uses V8 13.6.233.17.
30
- - **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.
31
- - **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.
32
- - **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.
33
- - **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.
34
- - **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.
24
+ - **Round trips:** 5 to 9 times faster (0.72 µs vs 6.51 µs per call).
25
+ - **Babel through ExecJS:** 1.95x faster (5.15 ms vs 10.05 ms).
26
+ - **Bundle load:** 4.6x faster for a 44 MB production server rendering bundle (215 ms vs 983 ms).
27
+ - **Memory:** A context holding the MUI bundle uses 44 MB vs 110 MB.
28
+ - **Forks:** After loading and rendering React: 20 of 20 clean mini_racer_rs exits vs 20 of 20 mini_racer aborts.
29
+ - **V8:** V8 15.2.124.1 vs V8 13.6.233.17 in mini_racer 0.22.1.
30
+ - **No compiler:** Native gems cover glibc Linux and macOS, both architectures, with Ruby 3.3, 3.4 and 4.0 extensions.
31
+ - **Fiber scheduler:** Three 100 ms loops in separate contexts and fibers finish in 100 ms vs 300 ms.
32
+ - **Upstream suites:** mini_racer passes 171 of 174 with 3 skipped by itself; ExecJS passes 197 of 198 with 1 skipped.
33
+ - **Difficult values:** A `Map` with a function key returns an error Hash instead of aborting with SIGABRT.
34
+ - **Checks:** Script-enforced crate boundaries, four fenced `unsafe` modules, loom, wire-codec fuzzing, nightly sanitizers and mini_racer differential tests.
35
35
 
36
- 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.
36
+ These numbers compare with mini_racer 0.22.1. See [Benchmarks](#benchmarks) for the method.
37
37
 
38
38
  ## Install
39
39
 
40
- The package switch is one Gemfile line:
40
+ Switch packages with one Gemfile line:
41
41
 
42
42
  ```diff
43
43
  - gem "mini_racer"
44
44
  + gem "mini_racer_rs"
45
45
  ```
46
46
 
47
- 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.
47
+ Run `bundle install`. Bundler is required because RubyGems may activate the original `mini_racer` first. Loading both gems raises a `LoadError` naming the conflict. Reverse the Gemfile change to switch back.
48
48
 
49
- On x86_64-linux-gnu, aarch64-linux-gnu, arm64-darwin, and x86_64-darwin, `bundle install` installs a native gem and compiles nothing. Elsewhere, the source gem builds the extension and requires Rust 1.91 or newer and libclang. To build from a checkout, follow [CONTRIBUTING.md](CONTRIBUTING.md) and run `bin/setup`.
49
+ On x86_64-linux-gnu, aarch64-linux-gnu, arm64-darwin, and x86_64-darwin, `bundle install` installs a native gem without compiling. Elsewhere, the source gem requires Rust 1.91 or newer and libclang to build the extension. For a checkout, follow [CONTRIBUTING.md](CONTRIBUTING.md) and run `bin/setup`.
50
50
 
51
51
  ## Quick start
52
52
 
53
- This example was run against both gems and produced exactly the outputs shown:
53
+ Both gems produced exactly these outputs:
54
54
 
55
55
  ```ruby check
56
56
  require "mini_racer"
@@ -101,6 +101,7 @@ ExecJS.eval("[1, 2].map(x => x * 2)") # => [2, 4]
101
101
  | `Context#pump_message_loop`, `#perform_microtask_checkpoint` | Runs pending V8 tasks and microtasks. |
102
102
  | `Snapshot.new`, `#warmup!`, `#dump`, `Snapshot.load` | Creates, warms, serializes, and loads startup snapshots. |
103
103
  | `Platform.set_flags!(*flags)` | Sets V8 flags before the first context. |
104
+ | `MiniRacerRs.register_source_map(bundle, map)` | Registers a source map for a bundle, so `MiniRacer::RuntimeError` backtraces show its original files and positions. |
104
105
 
105
106
  `Context.new` accepts these options:
106
107
 
@@ -111,29 +112,35 @@ ExecJS.eval("[1, 2].map(x => x * 2)") # => [2, 4]
111
112
  | `ensure_gc_after_idle:` | Idle milliseconds before one full garbage collection. `0` disables it. |
112
113
  | `snapshot:` | A `MiniRacer::Snapshot` used to initialize the context. |
113
114
 
114
- 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`.
115
+ Errors are `MiniRacer::ParseError`, `MiniRacer::RuntimeError`, `MiniRacer::ScriptTerminatedError`, `MiniRacer::V8OutOfMemoryError`, `MiniRacer::ContextDisposedError`, `MiniRacer::SnapshotError`, and `MiniRacer::PlatformAlreadyInitialized`. `MiniRacer::RuntimeError` includes JavaScript frames in its backtrace. All descend from `MiniRacer::Error`.
116
+
117
+ **Source maps.** Bundles must be UTF-8 Strings of at least 1,024 bytes. Maps must be JSON Strings in source map v3 format. When a context evaluates UTF-8 source containing a registered bundle, mini_racer_rs rewrites `MiniRacer::RuntimeError` backtraces. V8 positions inside the bundle become mapped original file, line, and column positions. V8 function names remain.
118
+
119
+ V8 positions remain for async frames and frames after the tenth. They also remain for `eval`, `new Function`, uncovered positions, and frames outside the bundle. JavaScript-reformatted stacks also keep V8 positions.
120
+
121
+ Detailed stack capture makes creating and throwing errors more expensive in affected contexts. Measured React and MUI server renders were unchanged. Registration is process wide and holds at most eight bundles. Maps cannot be removed. Registering a bundle again replaces its map. Trust bundles and maps like application code because source names appear in Ruby backtraces.
115
122
 
116
123
  ## Switching from mini_racer
117
124
 
118
125
  ### What changes
119
126
 
120
- 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.
127
+ The public API and require path stay the same. Changes include native installation, faster calls and Babel transforms, fiber-aware waiting, newer V8 behavior, and safer value conversion. `Object(1n)` returns `1`, and an offset typed array returns its buffer as a binary String. Applications making many small calls gain the most. See [Highlights](#highlights) for measurements.
121
128
 
122
129
  ### Check before you ship
123
130
 
124
- - 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.
131
+ - You're affected if tests or code compare exact JavaScript errors or locale-formatted text. V8 15.2 may differ from V8 13.6.
125
132
 
126
- - 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.
133
+ - You're affected if an attached callback reenters its context from another fiber, including inside `Enumerator#next`. mini_racer_rs raises `ThreadError`; mini_racer allows it.
127
134
 
128
- - 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.
135
+ - You're affected if a callback exits by `throw`, returns from a proc, or receives `Thread#kill`. The script ends with `Error: terminated`. The jump continues after `eval` returns. mini_racer hangs.
129
136
 
130
- - 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é"`.
137
+ - You're affected if JavaScript reads a callback exception's non-ASCII message. mini_racer_rs passes UTF-8, such as `"café"`; mini_racer passes `"café"`.
131
138
 
132
- - 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.
139
+ - You're affected if `fork`, `IO.popen("-")`, or `Process.daemon` runs after V8 starts. Both modes wait up to 500 ms for runners and interrupt JavaScript after 50 ms. They pause the worker pool and wait up to 100 ms for running tasks. Uninterruptible work may outlast these best-effort waits, and the fork proceeds. Default children reject inherited contexts. New contexts use the child's threads, but are best effort after either timeout. `:single_threaded` children take over idle inherited contexts and reject busy ones. After a runner timeout, they reject all inherited contexts. They accept new contexts.
133
140
 
134
- - 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.
141
+ - You're affected if `:single_threaded` forks bypass Ruby's `fork`, such as a C-level `fork()`. Inherited contexts are unusable in the child.
135
142
 
136
- - 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.
143
+ - You're affected if another thread calls `dispose` during a call. It returns after the call finishes and the isolate is gone. mini_racer returns immediately and frees the isolate later.
137
144
 
138
145
  - You're affected if your code references `MiniRacer::Loader`. It does not exist in mini_racer_rs.
139
146
 
@@ -141,26 +148,28 @@ See [COMPATIBILITY.md](COMPATIBILITY.md) for every difference.
141
148
 
142
149
  ### Stay on mini_racer if
143
150
 
144
- - 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.
151
+ - You deploy on musl-based Linux such as Alpine. mini_racer supports it through libv8-node's musl gems; mini_racer_rs does not. Neither supports Windows.
145
152
 
146
- - 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.
153
+ - Download size matters more than compile time. The largest native gem is 65.6 MB because it contains three Ruby extensions. mini_racer downloads 47.1 MB on x86_64 Linux, then compiles.
147
154
 
148
155
  ### Gems that depend on mini_racer
149
156
 
150
- 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.
157
+ If another gem adds `mini_racer`, point Bundler to the repository's shim. This empty `mini_racer` gem is version 0.22.1. It depends on the `mini_racer_rs` version from the same checkout.
151
158
 
152
159
  ```ruby
153
160
  gem "mini_racer_rs"
154
161
  gem "mini_racer", github: "andymai/mini_racer_rs", tag: "vX.Y.Z", glob: "shim/*.gemspec"
155
162
  ```
156
163
 
157
- 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.
164
+ The repository tests `path:` shim resolution with rtlcss in `test/consumers/transitive/`. The `github:` form has not run end to end. A dependency excluding `mini_racer` 0.22.1 cannot use the shim.
158
165
 
159
166
  ### Forking servers such as Puma
160
167
 
161
- Prime the process-wide V8 code cache before forking by evaluating each bundle of 1 MB or more twice in the master, using exactly the source text and file name the renderer uses, then dispose those contexts. The second evaluation builds the cache, later matching evaluations compile from it, and forked children inherit it. For Babel's 2.3 MB bundle at commit `5e13c1c`, a forked child's first load took, as medians across 5 trials, 60.8 ms when the parent had not loaded it, 65.5 ms after one load, and 25.0 ms after two loads. You can prime a `react-rails` app by building its server renderer twice. Parent contexts are not used in children. Only the cache carries over.
168
+ Before forking, evaluate each bundle of 1 MB or more twice in the master, then dispose those contexts. Use the renderer's exact source text and file name. The second evaluation builds the process-wide V8 code cache. Matching evaluations compile from it, and forked children inherit it. For Babel's 2.3 MB bundle at commit `5e13c1c`, a forked child's first load took 60.8 ms without a parent load. It took 65.5 ms after one load and 25.0 ms after two. These are medians across 5 trials. Prime a `react-rails` app by building its server renderer twice. Children do not use parent contexts. Only the cache carries over.
169
+
170
+ For 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 React rendering; all mini_racer_rs children exited cleanly. On Fedora, mini_racer hung within 50 `test/stress/fork_busy.rb` forks; mini_racer_rs completed 300 per run on Fedora and Ubuntu.
162
171
 
163
- With `mini_racer` 0.22.1, each worker compiles the bundle from source on its first load because there is no code cache.
172
+ With `mini_racer` 0.22.1, each worker compiles the bundle from source on its first load because it has no code cache.
164
173
 
165
174
  ## Benchmarks
166
175
 
@@ -176,20 +185,35 @@ With `mini_racer` 0.22.1, each worker compiles the bundle from source on its fir
176
185
  | MUI in a new context: load the 8.2 MB bundle and render once, through ExecJS | 167 ms | 105 ms | 1.6x |
177
186
  | Load a 44 MB production server rendering bundle into a new context, through ExecJS | 983 ms | 215 ms | 4.6x |
178
187
 
179
- Results are medians of 5 runs, with every workload producing identical output in both gems. The eight library workloads use the release build of commit `220bfe7`, and the 44 MB production server rendering bundle load uses commit `2513a48`. Measurements ran 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.
188
+ Results are medians of 5 runs. Every workload produced identical output in both gems. The eight library workloads use the release build of commit `220bfe7`. The 44 MB production bundle load uses commit `2513a48`. Benchmarks ran on Ruby 3.4.2 and Linux with an AMD Ryzen 9 7950X3D. The governor was `performance`. Both gems were pinned to CPUs 0 through 7.
189
+
190
+ The per-call and memory figures below were measured on the same machine. Startup plus Babel, Babel context and MUI context figures come from commit `220bfe7`. One watchdog thread serves the whole process, making a call with `timeout:` fast. Scripts of 1 MB or more use a process-wide V8 code cache. Contexts loading the same large script share one source copy.
191
+
192
+ | Measure | mini_racer 0.22.1 | mini_racer_rs |
193
+ |---|---:|---:|
194
+ | eval round trip | 6.91 µs | 1.09 µs |
195
+ | call round trip | 6.51 µs | 0.72 µs |
196
+ | callback round trip | 6.12 µs | 1.12 µs |
197
+ | call on a context with `timeout:` | 20.48 µs | 0.76 µs |
198
+ | Babel inside V8 | 10.3 ms | 5.3 ms |
199
+ | startup plus Babel | 44.4 ms | 13.3 ms |
200
+ | context holding Babel | 28.5 MB | 15.2 MB |
201
+ | context holding the 8.2 MB MUI bundle | 110 MB | 44 MB |
202
+ | context holding the 44 MB production bundle, at commit `2513a48` before sources were shared | 301 MB | 136 MB |
203
+ | peak resident memory with 20,000 contexts left to Ruby's garbage collector | 2,920 MB | 102 MB |
180
204
 
181
205
  ```sh
182
206
  bundle exec ruby bench/run.rb --cpus 0-7
183
207
  ```
184
208
 
185
- [BENCHMARKS.md](BENCHMARKS.md) describes the method, per-call costs, memory results, and mini_racer's own `benchmark/serde` suite.
209
+ [BENCHMARKS.md](BENCHMARKS.md) covers the method, per-call costs, memory results, and mini_racer's `benchmark/serde` suite.
186
210
 
187
211
  <!-- compat-table:start -->
188
212
  ## Compatibility
189
213
 
190
214
  | Engine | Done | Planned | Deviation |
191
215
  |---|---|---|---|
192
- | CRuby | 54 | 0 | 27 |
216
+ | CRuby | 54 | 0 | 28 |
193
217
  | TruffleRuby | 58 | 0 | 0 |
194
218
 
195
219
  See [COMPATIBILITY.md](COMPATIBILITY.md).
@@ -197,7 +221,7 @@ See [COMPATIBILITY.md](COMPATIBILITY.md).
197
221
 
198
222
  ## How it works
199
223
 
200
- 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.
224
+ mini_racer_rs uses the `v8` crate, rusty_v8 152.2.0, with magnus and rb-sys Ruby bindings. Each context owns a V8 isolate and native runner thread. Its stack is at least 2 MiB, keeping V8 frames off Ruby thread stacks. A per-context lock allows one dispatch at a time.
201
225
 
202
226
  ```text
203
227
  Ruby thread runner thread (one per context)
@@ -213,34 +237,36 @@ mini_racer_rs uses the `v8` crate, rusty_v8 152.2.0, with Ruby bindings through
213
237
  result
214
238
  ```
215
239
 
216
- 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.
240
+ A waiting Ruby thread spins with the GVL held, then without it. It then parks with the GVL released. After enough consecutive answers arrive beyond the spin budget, that context skips spinning and parks at once until an answer arrives within the budget. Under a fiber scheduler, only the waiting fiber parks. Values use V8's serialization format and decode directly into Ruby objects. There is no intermediate tree. Repeated objects keep their identity.
217
241
 
218
- 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.
242
+ One watchdog thread per process enforces every context's `timeout:`. In `:single_threaded` mode, forks quiesce runners. Children take over idle contexts; contexts in use raise there. mini_racer_rs gives V8 a copied platform vtable in each process. Worker-thread slots post to its own pool. V8's platform has one worker thread, which receives no tasks. Forking pauses the pool. The parent resumes it afterward. Default multi-threaded children reject inherited contexts.
219
243
 
220
- The implementation is split into four crates:
244
+ The implementation has four crates:
221
245
 
222
246
  - `mini_racer_wire`: the wire codec, with no unsafe code.
223
247
  - `mini_racer_sync`: the thread protocol, with no unsafe code and loom checking.
224
- - `mini_racer_engine`: V8 process state and runners, and the only crate that names `v8`.
225
- - `mini_racer_rs`: the Ruby extension, and the only crate that names magnus or rb-sys.
248
+ - `mini_racer_engine`: V8 process state and runners, and the only crate naming `v8`.
249
+ - `mini_racer_rs`: the Ruby extension, and the only crate naming magnus or rb-sys.
250
+
251
+ The release pipeline runs the full suites for every released extension.
226
252
 
227
- [ARCHITECTURE.md](ARCHITECTURE.md) follows a call end to end and covers the design in depth.
253
+ [ARCHITECTURE.md](ARCHITECTURE.md) follows a call end to end and explains the design.
228
254
 
229
255
  ## Scope
230
256
 
231
- mini_racer_rs deliberately does not:
257
+ mini_racer_rs does not:
232
258
 
233
- - 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.
259
+ - Run on Windows or musl-based Linux such as Alpine. It supports glibc Linux on x86_64 and aarch64, and macOS on arm64 and x86_64.
234
260
 
235
- - 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`.
261
+ - Provide Node.js APIs. JavaScript runs in plain V8 without file system, network, or process access. It can reach only Ruby callables you `attach`.
236
262
 
237
263
  - Work reliably without Bundler. RubyGems may activate the original mini_racer first.
238
264
 
239
- - Satisfy a dependency that pins a `mini_racer` version other than 0.22.1. This includes minibars with its `~> 0.6.4` requirement.
265
+ - Satisfy dependencies pinning `mini_racer` versions other than 0.22.1. This includes minibars and its `~> 0.6.4` requirement.
240
266
 
241
- - Extend the `MiniRacer` API beyond mini_racer 0.22.1. Deliberate differences are recorded in [COMPATIBILITY.md](COMPATIBILITY.md).
267
+ - Extend the `MiniRacer` API beyond mini_racer 0.22.1. [COMPATIBILITY.md](COMPATIBILITY.md) records deliberate differences.
242
268
 
243
- Supported Ruby implementations are CRuby 3.3, 3.4, and 4.0, plus TruffleRuby through mini_racer's unchanged TruffleRuby backend.
269
+ Supported implementations are CRuby 3.3, 3.4, and 4.0, plus TruffleRuby through mini_racer's unchanged TruffleRuby backend.
244
270
 
245
271
  ## Documentation
246
272
 
@@ -1040,6 +1040,7 @@ limitations under the License.
1040
1040
 
1041
1041
  ### Apache License 2.0
1042
1042
 
1043
+ - `itoa`: David Tolnay <dtolnay@gmail.com>
1043
1044
  - `libc`
1044
1045
  - `paste`: David Tolnay <dtolnay@gmail.com>
1045
1046
  - `proc-macro2`: David Tolnay <dtolnay@gmail.com>, Alex Crichton <alex@alexcrichton.com>
@@ -1048,6 +1049,7 @@ limitations under the License.
1048
1049
  - `serde`: Erick Tryzelaar <erick.tryzelaar@gmail.com>, David Tolnay <dtolnay@gmail.com>
1049
1050
  - `serde_core`: Erick Tryzelaar <erick.tryzelaar@gmail.com>, David Tolnay <dtolnay@gmail.com>
1050
1051
  - `serde_derive`: Erick Tryzelaar <erick.tryzelaar@gmail.com>, David Tolnay <dtolnay@gmail.com>
1052
+ - `serde_json`
1051
1053
  - `syn`: David Tolnay <dtolnay@gmail.com>
1052
1054
  - `syn`: David Tolnay <dtolnay@gmail.com>
1053
1055
  - `thiserror-impl`: David Tolnay <dtolnay@gmail.com>
@@ -1270,6 +1272,64 @@ USE OR OTHER DEALINGS IN THE SOFTWARE.
1270
1272
 
1271
1273
  ### MIT License
1272
1274
 
1275
+ - `zmij`: David Tolnay <dtolnay@gmail.com>
1276
+ ```text
1277
+ Permission is hereby granted, free of charge, to any
1278
+ person obtaining a copy of this software and associated
1279
+ documentation files (the "Software"), to deal in the
1280
+ Software without restriction, including without
1281
+ limitation the rights to use, copy, modify, merge,
1282
+ publish, distribute, sublicense, and/or sell copies of
1283
+ the Software, and to permit persons to whom the Software
1284
+ is furnished to do so, subject to the following
1285
+ conditions:
1286
+
1287
+ The above copyright notice and this permission notice
1288
+ shall be included in all copies or substantial portions
1289
+ of the Software.
1290
+
1291
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
1292
+ ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED
1293
+ TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
1294
+ PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
1295
+ SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
1296
+ CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
1297
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
1298
+ IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
1299
+ DEALINGS IN THE SOFTWARE.
1300
+
1301
+ ```
1302
+
1303
+ ### MIT License
1304
+
1305
+ - `memchr`: Andrew Gallant <jamslam@gmail.com>, bluss
1306
+ ```text
1307
+ The MIT License (MIT)
1308
+
1309
+ Copyright (c) 2015 Andrew Gallant
1310
+
1311
+ Permission is hereby granted, free of charge, to any person obtaining a copy
1312
+ of this software and associated documentation files (the "Software"), to deal
1313
+ in the Software without restriction, including without limitation the rights
1314
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
1315
+ copies of the Software, and to permit persons to whom the Software is
1316
+ furnished to do so, subject to the following conditions:
1317
+
1318
+ The above copyright notice and this permission notice shall be included in
1319
+ all copies or substantial portions of the Software.
1320
+
1321
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
1322
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
1323
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
1324
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
1325
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
1326
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
1327
+ THE SOFTWARE.
1328
+
1329
+ ```
1330
+
1331
+ ### MIT License
1332
+
1273
1333
  - `libm`: Alex Crichton <alex@alexcrichton.com>, Amanieu d'Antras <amanieu@gmail.com>, Jorge Aparicio <japaricious@gmail.com>, Trevor Gross <tg@trevorgross.com>
1274
1334
  ```text
1275
1335
  rust-lang/libm as a whole is available for use under the MIT license:
@@ -16,6 +16,7 @@ no-madvise-wrap = []
16
16
  [dependencies]
17
17
  deno_core_icudata.workspace = true
18
18
  libc.workspace = true
19
+ mini_racer_sourcemap.workspace = true
19
20
  mini_racer_sync.workspace = true
20
21
  mini_racer_wire.workspace = true
21
22
  thiserror.workspace = true
@@ -24,6 +24,17 @@ pub enum InvalidSnapshot {
24
24
  Empty,
25
25
  }
26
26
 
27
+ /// Why `SourceMaps::register` refused a map.
28
+ #[derive(Debug, thiserror::Error)]
29
+ pub enum SourceMapError {
30
+ #[error(transparent)]
31
+ Map(#[from] mini_racer_sourcemap::MapError),
32
+ #[error("at most {0} bundles can have a source map")]
33
+ Full(usize),
34
+ #[error("the bundle is shorter than {0} bytes")]
35
+ Short(usize),
36
+ }
37
+
27
38
  #[derive(Debug, Clone, Copy, PartialEq, Eq)]
28
39
  pub enum JsErrorKind {
29
40
  Parse,
@@ -18,6 +18,8 @@ mod text;
18
18
 
19
19
  pub use context::{ContextHandle, Host, Unparker, WaitHandle, WaitOutcome};
20
20
  pub use control::{CallRequest, CallbackReply, ContextConfig, JsText};
21
- pub use error::{EngineError, FlagError, InvalidSnapshot, JsError, JsErrorKind, TerminationCause};
21
+ pub use error::{
22
+ EngineError, FlagError, InvalidSnapshot, JsError, JsErrorKind, SourceMapError, TerminationCause,
23
+ };
22
24
  pub use snapshot::{SnapshotBlob, WeakSnapshotBlob};
23
25
  pub use text::{Decoded, Transcoder};
@@ -7,6 +7,7 @@ use mini_racer_sync::{ForkGate, Phase, lock};
7
7
 
8
8
  use crate::control::ControlBlock;
9
9
  use crate::process::code_cache::CodeCache;
10
+ use crate::process::source_maps::SourceMaps;
10
11
  use crate::process::sources::Sources;
11
12
  use crate::process::tasks::TaskRegistry;
12
13
  use crate::process::watchdog::Watchdog;
@@ -53,13 +54,18 @@ pub struct Generation {
53
54
  workers: Workers,
54
55
  code_cache: CodeCache,
55
56
  sources: Sources,
57
+ source_maps: SourceMaps,
56
58
  next: OnceLock<Box<Self>>,
57
59
  }
58
60
 
59
61
  static ROOT: OnceLock<Generation> = OnceLock::new();
60
62
 
61
63
  impl Generation {
62
- fn new(epoch: u64, quiesced: bool, code_cache: CodeCache, sources: Sources) -> Self {
64
+ fn new(
65
+ epoch: u64,
66
+ quiesced: bool,
67
+ (code_cache, sources, source_maps): (CodeCache, Sources, SourceMaps),
68
+ ) -> Self {
63
69
  Self {
64
70
  epoch,
65
71
  quiesced,
@@ -72,6 +78,7 @@ impl Generation {
72
78
  workers: Workers::default(),
73
79
  code_cache,
74
80
  sources,
81
+ source_maps,
75
82
  next: OnceLock::new(),
76
83
  }
77
84
  }
@@ -102,6 +109,11 @@ impl Generation {
102
109
  &self.sources
103
110
  }
104
111
 
112
+ #[must_use]
113
+ pub const fn source_maps(&self) -> &SourceMaps {
114
+ &self.source_maps
115
+ }
116
+
105
117
  pub fn register(&self, block: &Arc<ControlBlock>) {
106
118
  let mut blocks = lock(&self.blocks);
107
119
  blocks.retain(|block| block.strong_count() > 0);
@@ -123,8 +135,7 @@ impl Generation {
123
135
 
124
136
  pub fn current() -> &'static Generation {
125
137
  let epoch = epoch();
126
- let mut generation =
127
- ROOT.get_or_init(|| Generation::new(epoch, true, CodeCache::default(), Sources::default()));
138
+ let mut generation = ROOT.get_or_init(|| Generation::new(epoch, true, Default::default()));
128
139
  while generation.epoch != epoch {
129
140
  let quiesced = generation.quiesced && generation.prepared.load(Ordering::SeqCst);
130
141
  let next = generation.epoch.saturating_add(1);
@@ -133,8 +144,11 @@ pub fn current() -> &'static Generation {
133
144
  Box::new(Generation::new(
134
145
  next,
135
146
  quiesced,
136
- parent.code_cache.inherited(),
137
- parent.sources.inherited(),
147
+ (
148
+ parent.code_cache.inherited(),
149
+ parent.sources.inherited(),
150
+ parent.source_maps.inherited(),
151
+ ),
138
152
  ))
139
153
  });
140
154
  }
@@ -0,0 +1,104 @@
1
+ use std::sync::atomic::{AtomicUsize, Ordering};
2
+ use std::sync::{Arc, Mutex};
3
+
4
+ use mini_racer_sourcemap::{Placement, SourceMap};
5
+ use mini_racer_sync::lock;
6
+
7
+ use crate::error::SourceMapError;
8
+
9
+ /// Bundles with a source map, each parsed once.
10
+ pub const MAX_MAPS: usize = 8;
11
+ /// A bundle's fewest bytes. Shorter text could turn up inside unrelated
12
+ /// code, whose frames its map would then relocate; any real bundle is many
13
+ /// times longer, the smallest of the consumer bundles 90 KB.
14
+ pub const MIN_BUNDLE: usize = 1024;
15
+
16
+ /// Refuses a map too long to parse by its length alone, so a caller need not
17
+ /// copy it first.
18
+ pub fn check_length(length: usize) -> Result<(), SourceMapError> {
19
+ Ok(mini_racer_sourcemap::check_length(length)?)
20
+ }
21
+
22
+ /// The source maps one process has registered, found by their bundle's
23
+ /// content: each kept once, parsed, and read by every context whose eval
24
+ /// holds its bundle.
25
+ #[derive(Default)]
26
+ pub struct SourceMaps {
27
+ maps: Mutex<Vec<Arc<SourceMap>>>,
28
+ // The shortest bundle's length, or 0 with none, so a source too short to
29
+ // hold any is passed over without the lock.
30
+ shortest: AtomicUsize,
31
+ }
32
+
33
+ impl SourceMaps {
34
+ /// Parses `map` for `bundle` and keeps it, in place of the map an earlier
35
+ /// call gave the same bundle; past `MAX_MAPS` bundles, a new one is
36
+ /// refused.
37
+ #[expect(
38
+ clippy::significant_drop_tightening,
39
+ reason = "the shortest length is stored under the lock, so it never trails the list"
40
+ )]
41
+ pub fn register(&self, bundle: &str, map: &[u8]) -> Result<(), SourceMapError> {
42
+ if bundle.len() < MIN_BUNDLE {
43
+ return Err(SourceMapError::Short(MIN_BUNDLE));
44
+ }
45
+ let parsed = Arc::new(SourceMap::new(bundle, map)?);
46
+ // A child forked while this holds the lock starts with no maps, so it
47
+ // is held only to swap, and a map replaced is freed after.
48
+ let replaced = {
49
+ let mut maps = lock(&self.maps);
50
+ let replaced = if let Some(kept) = maps
51
+ .iter_mut()
52
+ .find(|kept| kept.bundle() == bundle.as_bytes())
53
+ {
54
+ Some(std::mem::replace(kept, parsed))
55
+ } else if maps.len() < MAX_MAPS {
56
+ maps.push(parsed);
57
+ None
58
+ } else {
59
+ return Err(SourceMapError::Full(MAX_MAPS));
60
+ };
61
+ let shortest = maps
62
+ .iter()
63
+ .map(|kept| kept.bundle().len())
64
+ .min()
65
+ .unwrap_or(0);
66
+ self.shortest.store(shortest, Ordering::Release);
67
+ replaced
68
+ };
69
+ drop(replaced);
70
+ Ok(())
71
+ }
72
+
73
+ /// The registered map whose bundle `source` holds, the longest when it
74
+ /// holds several, as one bundle may hold another, and where it starts.
75
+ pub(crate) fn find(&self, source: &[u8]) -> Option<(Arc<SourceMap>, Placement)> {
76
+ let shortest = self.shortest.load(Ordering::Acquire);
77
+ if shortest == 0 || source.len() < shortest {
78
+ return None;
79
+ }
80
+ let mut maps = lock(&self.maps).clone();
81
+ maps.sort_by_key(|map| std::cmp::Reverse(map.bundle().len()));
82
+ maps.into_iter()
83
+ .find_map(|map| map.find(source).map(|placement| (map, placement)))
84
+ }
85
+
86
+ // A forked child's own list, from its parent's: try-locked, as a thread
87
+ // gone with the fork may have held it.
88
+ pub(crate) fn inherited(&self) -> Self {
89
+ let maps = self
90
+ .maps
91
+ .try_lock()
92
+ .map(|maps| maps.clone())
93
+ .unwrap_or_default();
94
+ let shortest = maps
95
+ .iter()
96
+ .map(|kept| kept.bundle().len())
97
+ .min()
98
+ .unwrap_or(0);
99
+ Self {
100
+ maps: Mutex::new(maps),
101
+ shortest: AtomicUsize::new(shortest),
102
+ }
103
+ }
104
+ }
@@ -1,6 +1,7 @@
1
1
  pub mod code_cache;
2
2
  pub mod fork;
3
3
  pub mod platform;
4
+ pub mod source_maps;
4
5
  pub mod sources;
5
6
  pub(crate) mod tasks;
6
7
  pub(crate) mod watchdog;