rusty_racer 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea693d067ec0ea289296493726bbecd72444e811218ca35a1beb44bbaf863e7d
-  data.tar.gz: f1de072c0f64819c07708e47d385c345b7300e54a41c5186b79858ba73e3f7b7
+  metadata.gz: 746bc2e7e881d601b38f6052fb45f4f87d72d4580a46ea738e2c716af6641f82
+  data.tar.gz: 4fcc456589eabd593e506d7c941b7fe95635400225aac9807908a008f63e73ad
 SHA512:
-  metadata.gz: bb7f4c71efcb143172a42c80898a9e10eeadc4c519e4f98e317907483ffd4565e751f7d0946b377964cb4b83b4e026cbe555449fac425b284572f088cb6d012e
-  data.tar.gz: a859077b54ca976af9466271ada3cd094695b1f896ce09f3bc35d753912dc4e19743f589e322c0f438ca08cc4383bafa5faca16852831dbfd59e80dd74e61614
+  metadata.gz: 20aeb8c39cc3f321b5015b78ff2c4ae54553babd54735bbb256aeaea16c2428cccc03141a55c179ebad34822243d2d39508517df33f34d6236a7a368cbe274b5
+  data.tar.gz: 5ff495f94287dfd8464855d5e20c84c4743b91a3d320760decf17244dad5efa67c503b74dd2994792059e0f7236b10992157bfd5c4cb5681b02fe162b47a8a4d

data/README.md

@@ -9,6 +9,38 @@ Embed [V8](https://v8.dev/) in Ruby, built on [rusty_v8](https://crates.io/crate
 > is **thread-confined**: every operation must happen on that owner thread, or it
 > raises. `Isolate#terminate` is the exception — it is safe from any thread.
 
+## Highlights
+
+- **ES modules**, including dynamic `import()` with an embedder-owned resolver —
+  not just classic scripts.
+- **Faithful value marshalling**: `BigInt`, `Date`, `Map`, `Set`, typed binary
+  (`Uint8Array`/`ArrayBuffer` ↔ binary `String`), and shared/cyclic object
+  graphs all round-trip — no lossy JSON hop.
+- **In-thread execution** — V8 runs on the calling Ruby thread, with no dedicated
+  V8 thread and no per-op thread hop; fast when you run many small ops.
+- **Drop-in [ExecJS](#execjs) runtime** — any ExecJS consumer switches with no
+  code change.
+- **Snapshots, realms (`Context`s), host callbacks, and a bytecode cache.**
+- **Resource limits on both axes** — a `timeout_ms` (time) and a `memory_limit`
+  (space), each catchable: a runaway script fails just its own `eval`, leaving
+  the isolate usable, instead of aborting the process.
+- **Precompiled gems** bundle V8 for Linux/macOS × Ruby 3.3–4.0 — no V8 build,
+  no Rust toolchain.
+
+### Compared to mini_racer
+
+[mini_racer](https://github.com/rubyjs/mini_racer) is the mature, widely-deployed
+incumbent — if you want a battle-tested binding or **Windows** support, reach for
+it. rusty_racer differs where it counts for some workloads: native **ES modules +
+dynamic import** (mini_racer is eval/classic-script oriented); **richer
+marshalling** (the types above round-trip natively instead of through a
+JSON-shaped projection); and **in-thread execution** with no per-op thread hop,
+which is faster for overhead-dominated workloads (lots of tiny `eval`/`call`) and
+at parity once the per-op JS work dominates. Both axes of resource limiting are
+covered — a `timeout_ms` (time) and a `memory_limit` (space), each catchable. It
+is also younger and **experimental** — fewer miles, no Windows yet. Parity with
+mini_racer is not a goal; the overlap is convergent evolution, not a port.
+
 ## What it can do
 
 Names follow V8's: an `Isolate` is the VM; it hands out `Context`s (v8::Context,
@@ -55,6 +87,25 @@ app.namespace["r"]                       # => 42
 
 Classic `<script>`s work the same way: `ctx.compile("1 + 1").run` # => 2.
 
+### Resource limits
+
+An isolate can cap untrusted code on both axes. Each limit terminates the
+offending op and raises a catchable error — the isolate stays usable afterward,
+so one runaway script fails just its own `eval`, not the whole process.
+
+```ruby
+# Time: timeout_ms caps each eval/call (per-call override on Context#eval).
+iso = RustyRacer::Isolate.new(timeout_ms: 1000)
+iso.context.eval("for (;;) {}")          # raises RustyRacer::ScriptTerminatedError
+
+# Space: memory_limit caps the V8 heap in bytes (a soft limit, enforced at GC
+# granularity). The isolate forces a GC and resets the ceiling on recovery.
+iso = RustyRacer::Isolate.new(memory_limit: 64 * 1024 * 1024)
+iso.context.eval("a = []; for (;;) a.push(new Array(1e6))")
+                                         # raises RustyRacer::V8OutOfMemoryError
+iso.context.eval("1 + 1")                # => 2 (still usable)
+```
+
 ### Bytecode caching
 
 V8 compiles lazily: the top level up front, each function body on first call.
@@ -122,6 +173,28 @@ warm isolate — a per-visit reset that avoids rebuilding the VM. Its contract:
   suspended on the V8 stack (e.g. resetting a realm from inside one of its own
   host fns).
 
+## ExecJS
+
+rusty_racer ships an optional [ExecJS](https://github.com/rails/execjs) runtime,
+so any ExecJS consumer (asset pipelines, CoffeeScript/Babel/Uglify wrappers, …)
+can run on V8-in-Ruby with no code change:
+
+```ruby
+require "rusty_racer/execjs"
+ExecJS.runtime = RustyRacer::ExecJSRuntime.new
+
+ExecJS.eval("'foo bar'.toUpperCase()")   # => "FOO BAR"
+ctx = ExecJS.compile("function add(a, b) { return a + b }")
+ctx.call("add", 1, 2)                     # => 3
+```
+
+The adapter is **opt-in** — `rusty_racer` never requires `execjs` itself, so it
+stays a non-dependency; `require "rusty_racer/execjs"` pulls it in only when you
+ask. Values cross with ExecJS's JSON semantics (functions and `undefined` drop
+out, Dates become ISO strings), matching what ExecJS's external runtimes give, so
+results are identical whatever runtime a library picked. The integration is
+verified against ExecJS's own runtime contract suite (`test/execjs_test.rb`).
+
 ## Threading
 
 An `Isolate` runs V8 **in-thread** on the Ruby thread that created it, and is

data/ext/rusty_racer/Cargo.toml

@@ -4,7 +4,7 @@
 # libv8-rusty needed under the cibuildgem native-per-platform model).
 [package]
 name = "rusty_racer"
-version = "0.1.1"
+version = "0.1.3"
 edition = "2021"
 publish = false