rusty_racer 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0b742605170382bce639eaa6c8acd1917f6ed4e6f8a5d4f83d40701ffb14b25
-  data.tar.gz: ce873858c2a28e9903ca9abec1cc72e061f3561f1cf2c8d5b0ff3694d613ec55
+  metadata.gz: 746bc2e7e881d601b38f6052fb45f4f87d72d4580a46ea738e2c716af6641f82
+  data.tar.gz: 4fcc456589eabd593e506d7c941b7fe95635400225aac9807908a008f63e73ad
 SHA512:
-  metadata.gz: 1e3960b00b14c62813d731ee85c8f41cca8f04a0ff7657446f205dda2f24c5e11fd07b00da000b1d7be503bb00f083cf389f3736fac8d6344343a6ec26a3a11e
-  data.tar.gz: 3ee0d6217b064b70362a7e2475e5db840a0b613922f91a418d3548464066ea1824d1c073870e5d9d6da4cdc351fa481e490d667520123675f2b7d730a926d23e
+  metadata.gz: 20aeb8c39cc3f321b5015b78ff2c4ae54553babd54735bbb256aeaea16c2428cccc03141a55c179ebad34822243d2d39508517df33f34d6236a7a368cbe274b5
+  data.tar.gz: 5ff495f94287dfd8464855d5e20c84c4743b91a3d320760decf17244dad5efa67c503b74dd2994792059e0f7236b10992157bfd5c4cb5681b02fe162b47a8a4d

data/README.md

@@ -21,6 +21,9 @@ Embed [V8](https://v8.dev/) in Ruby, built on [rusty_v8](https://crates.io/crate
 - **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.
 
@@ -33,9 +36,10 @@ 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. It is also younger and
-**experimental** — fewer miles, no Windows yet, no per-isolate memory cap. Parity
-with mini_racer is not a goal; the overlap is convergent evolution, not a port.
+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
 
@@ -83,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.

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.2"
+version = "0.1.3"
 edition = "2021"
 publish = false
 

data/ext/rusty_racer/src/lib.rs

@@ -186,7 +186,52 @@ enum VmError {
         message: String,
         backtrace: Vec<String>,
     },
-    Terminated, // watchdog/stop -> RustyRacer::ScriptTerminatedError
+    Terminated,  // watchdog/stop -> RustyRacer::ScriptTerminatedError
+    OutOfMemory, // memory_limit hit -> RustyRacer::V8OutOfMemoryError
+}
+
+// V8's near-heap-limit callback (registered per isolate when memory_limit > 0).
+// V8 calls this, synchronously on the owner thread, when a GC still leaves the
+// heap about to exceed the configured ceiling — i.e. the script is running away
+// on memory. `data` is the isolate ptr we registered (Core.iso_ptr). We flag the
+// isolate and terminate the running JS so it unwinds with a catchable error
+// rather than V8 aborting the process. The return value becomes V8's new ceiling:
+// hand it a DOUBLED limit so the unwind itself (and any pending finalizers) has
+// room to allocate without tripping a hard OOM abort mid-unwind. Core::run, once
+// the op has unwound, forces a GC to reclaim and resets the ceiling — see the OOM
+// recovery there. The bump is a no-op-after-the-fact: doubling here, GC + reset
+// after, so the limit keeps protecting later ops.
+unsafe extern "C" fn near_heap_limit_cb(data: *mut c_void, current_heap_limit: usize, _initial: usize) -> usize {
+    let isolate = unsafe { &mut *(data as *mut v8::Isolate) };
+    // get_slot_mut (not istate!): this runs as an extern "C" callback from V8's
+    // C++ allocator, where a panic would unwind across the FFI boundary. The slot
+    // is always present once an op can run (set in Isolate::new before any JS), but
+    // skip flagging rather than .expect()-panic in the impossible absent case.
+    // Setting the flag releases the &mut borrow before terminate_execution (&self).
+    if isolate.get_slot_mut::<IsolateState>().map(|s| s.oom_fired = true).is_some() {
+        isolate.terminate_execution();
+    }
+    current_heap_limit.saturating_mul(2)
+}
+
+// After an OOM the running op's outcome is a bare Terminated (the terminate the
+// callback fired). Swap it for OutOfMemory so it surfaces as V8OutOfMemoryError,
+// preserving the reply's variant (the caller dispatches on it). Only the error
+// arm changes; a Terminated from a real timeout/stop never reaches here because
+// this runs only when oom_fired was set.
+fn relabel_oom(reply: VmReply) -> VmReply {
+    fn fix<T>(r: Result<T, VmError>) -> Result<T, VmError> {
+        match r {
+            Err(VmError::Terminated) => Err(VmError::OutOfMemory),
+            other => other,
+        }
+    }
+    match reply {
+        VmReply::Done(r) => VmReply::Done(fix(r)),
+        VmReply::ModuleCompiled(r) => VmReply::ModuleCompiled(fix(r)),
+        VmReply::ScriptCompiled(r) => VmReply::ScriptCompiled(fix(r)),
+        VmReply::CodeCache(r) => VmReply::CodeCache(fix(r)),
+    }
 }
 
 // ---------------------------------------------------------------------------
@@ -522,6 +567,12 @@ struct IsolateState {
     instantiate_resolve: Option<RootedProc>,
     instantiate_resolve_err: Option<BoxValue<Exception>>,
     watchdog: Arc<WatchdogShared>,
+    // Set by near_heap_limit_cb when the configured memory_limit is hit: it
+    // terminates the running JS, and Core::run reads this after the op to relabel
+    // the terminate as OutOfMemory and recover the heap (GC + reset the ceiling).
+    // Plain bool (no atomic): the callback fires synchronously on the owner thread,
+    // never concurrently with the bracket that reads it.
+    oom_fired: bool,
 }
 
 impl IsolateState {
@@ -543,6 +594,7 @@ impl IsolateState {
             instantiate_resolve: None,
             instantiate_resolve_err: None,
             watchdog: WatchdogShared::new(),
+            oom_fired: false,
         }
     }
 }
@@ -1033,6 +1085,11 @@ struct Core {
     // Default per-eval/call timeout (ms); 0 = none. eval(timeout_ms:)'s explicit
     // value overrides it. Guards against an in-V8 infinite loop without a watchdog.
     default_timeout_ms: u64,
+    // Per-isolate heap ceiling (bytes); 0 = none. When set, the isolate is created
+    // with this as V8's max heap and near_heap_limit_cb is registered; Core::run's
+    // OOM recovery resets the ceiling back to this after each OOM. Space-axis twin
+    // of default_timeout_ms.
+    memory_limit: usize,
     // Set by Context#dynamic_import_resolver=; called for a JS import() to map
     // (specifier, referrer) to an already-loaded Module. GC-rooted like procs.
     dynamic_import_resolver: Mutex<Option<RootedProc>>,
@@ -1457,6 +1514,9 @@ fn build_snapshot(code: &str, base: Option<Vec<u8>>, warmup: bool) -> Result<Vec
                         VmError::Parse(m) | VmError::Runtime(m) => m,
                         VmError::JsError { message, .. } => message,
                         VmError::Terminated => "snapshot code was terminated".to_string(),
+                        // Unreachable: the snapshot-creator isolate carries no
+                        // memory_limit, so near_heap_limit_cb is never registered.
+                        VmError::OutOfMemory => "snapshot code ran out of memory".to_string(),
                     });
                 }
             }
@@ -1492,16 +1552,22 @@ impl Isolate {
         host_namespace: Option<String>,
         snapshot: Option<magnus::typed_data::Obj<Snapshot>>,
         timeout_ms: u64,
+        memory_limit: usize,
         explicit_microtasks: bool,
     ) -> Result<Self, Error> {
         init_v8();
         // A snapshot blob bakes globalThis state in: the first Context::new (in
         // new_realm below) deserializes that default context for free.
         let snapshot_bytes = snapshot.map(|s| s.blob.borrow().clone());
-        let create_params = match snapshot_bytes {
+        let mut create_params = match snapshot_bytes {
             Some(bytes) => v8::CreateParams::default().snapshot_blob(v8::StartupData::from(bytes)),
             None => Default::default(),
         };
+        // Cap V8's heap at the configured limit so its near-heap-limit callback
+        // fires as the script approaches it (initial 0 = V8's default initial heap).
+        if memory_limit > 0 {
+            create_params = create_params.heap_limits(0, memory_limit);
+        }
         let mut isolate = v8::Isolate::new(create_params);
         // Always Explicit at the V8 level; the binding performs the kAuto
         // end-of-script drain itself (auto_drain) so it stays inside the
@@ -1541,6 +1607,12 @@ impl Isolate {
         // registry moves only the 8-byte pointer; the boxed OwnedIsolate stays put.
         let mut boxed = Box::new(isolate);
         let iso_ptr = IsoPtr(&mut **boxed as *mut v8::Isolate);
+        // Arm the memory limit now that iso_ptr is stable: the callback's data IS
+        // this ptr (it reads the slot's oom_fired and terminates through it), and
+        // Core::run resets the ceiling through the same ptr on recovery.
+        if memory_limit > 0 {
+            boxed.add_near_heap_limit_callback(near_heap_limit_cb, iso_ptr.0 as *mut c_void);
+        }
         let iso_id = NEXT_ISOLATE_ID.fetch_add(1, Ordering::SeqCst);
         isolates().lock().unwrap().insert(iso_id, SendIso(boxed));
         // Root the owner Thread VALUE so its address can't be reused while this
@@ -1559,6 +1631,7 @@ impl Isolate {
             depth: std::sync::atomic::AtomicU32::new(0),
             procs: Mutex::new(ProcTable::default()),
             default_timeout_ms: timeout_ms,
+            memory_limit,
             dynamic_import_resolver: Mutex::new(None),
             watchdog,
             watchdog_join: Mutex::new(Some(watchdog_join)),
@@ -1654,11 +1727,37 @@ impl Core {
                     self.scan_start_field.load(Ordering::Relaxed),
                     stack_top,
                 );
-                let reply = std::panic::catch_unwind(AssertUnwindSafe(|| {
+                let mut reply = std::panic::catch_unwind(AssertUnwindSafe(|| {
                     v8::scope!(let scope, unsafe { &mut *iso });
                     service_request(scope, request, true)
                 }))
                 .ok();
+                // OOM recovery. The near-heap-limit callback bumped the ceiling and
+                // terminated the op so it could unwind; the scope is closed and JS has
+                // stopped now. Reclaim the runaway allocation (a forced GC) and reset
+                // the ceiling back to memory_limit so the limit keeps protecting later
+                // ops, then relabel the terminate as OutOfMemory. watchdog_fired stays
+                // false for an OOM, so the request's end-sweep left the terminate flag
+                // set — cancel it here.
+                if self.memory_limit > 0 && std::mem::take(&mut istate!(unsafe { &mut *iso }).oom_fired) {
+                    let iso_ref = unsafe { &mut *iso };
+                    // Reclaim the runaway allocation, then reset the ceiling from the
+                    // doubled bump back to memory_limit (V8 clamps it no lower than the
+                    // live heap — a genuinely-retained set above the limit necessarily
+                    // loosens it, inherent to recovering the isolate rather than
+                    // discarding it), and re-arm the callback for the next op.
+                    iso_ref.low_memory_notification();
+                    iso_ref.remove_near_heap_limit_callback(near_heap_limit_cb, self.memory_limit);
+                    iso_ref.add_near_heap_limit_callback(near_heap_limit_cb, iso as *mut c_void);
+                    // Clear the terminate the OOM set (the request end-sweep skips it —
+                    // that only sweeps watchdog_fired). Do this AFTER the GC: the forced
+                    // GC above runs with the callback still armed, so a still-huge live
+                    // set can re-fire it mid-GC, re-setting both terminate and oom_fired;
+                    // clearing both here keeps either from leaking into the next op.
+                    iso_ref.cancel_terminate_execution();
+                    istate!(iso_ref).oom_fired = false;
+                    reply = reply.map(relabel_oom);
+                }
                 unsafe { (*iso).exit() };
                 reply
             } else {
@@ -2070,6 +2169,13 @@ impl Core {
             st.scripts = ScriptReg::default();
             st.instantiate_resolve = None;
         }
+        // Unregister the near-heap-limit callback before disposal: dropping the box
+        // runs V8's teardown GC, which could otherwise re-invoke near_heap_limit_cb
+        // (touching the just-reset slot of an isolate being destroyed). The watchdog
+        // is already stopped above; this closes the matching space-axis hole.
+        if self.memory_limit > 0 {
+            unsafe { &mut *self.iso_ptr.0 }.remove_near_heap_limit_callback(near_heap_limit_cb, 0);
+        }
         // Remove (and drop) the OwnedIsolate — V8 disposal runs here — AFTER the
         // watchdog joined and the Globals were cleared, while the isolate is
         // entered (above). Drop outside the lock so V8 teardown can't deadlock on
@@ -2524,6 +2630,10 @@ fn vm_err(ruby: &Ruby, e: VmError) -> Error {
             err_class(ruby, "ScriptTerminatedError"),
             "JavaScript was terminated (timeout or stop)",
         ),
+        VmError::OutOfMemory => Error::new(
+            err_class(ruby, "V8OutOfMemoryError"),
+            "JavaScript exceeded the isolate memory_limit",
+        ),
     }
 }
 
@@ -2601,7 +2711,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     // The isolate (VM) + its isolate-level ops; hands out Contexts.
     let isolate = module.define_class("Isolate", ruby.class_object())?;
     // keyword-arg wrapper Isolate.new(snapshot:, ...) lives in lib/rusty_racer.rb
-    isolate.define_singleton_method("_new", function!(Isolate::new, 4))?;
+    isolate.define_singleton_method("_new", function!(Isolate::new, 5))?;
     isolate.define_method("context", method!(Isolate::context, 0))?;
     isolate.define_method("create_context", method!(Isolate::create_context, 0))?;
     isolate.define_method("terminate", method!(Isolate::terminate, 0))?;

data/ext/rusty_racer/src/watchdog.rs

@@ -185,6 +185,7 @@ pub(crate) fn run_js_bracketed(
         && ran_js
         && !fired
         && matches!(outcome, Err(VmError::Terminated))
+        && !istate!(scope).oom_fired
     {
         report_watchdog_anomaly(scope, label, watchdog, timeout_ms, started.elapsed());
     }
@@ -193,6 +194,15 @@ pub(crate) fn run_js_bracketed(
         if ran_js {
             outcome = Err(VmError::Terminated);
         }
+    } else if ran_js && istate!(scope).oom_fired {
+        // The memory_limit callback fired TerminateExecution during this op. body
+        // may not have noticed it — a microtask/TLA drain that was interrupted
+        // leaves a pending promise and returns Ok (auto_drain just stops at the
+        // terminate) — so force the terminated outcome rather than let an OOM
+        // surface as a bogus success. Core::run relabels it to OutOfMemory and
+        // recovers the heap. (No watchdog_fired here: the OOM terminate is swept by
+        // Core::run's recovery, not the request end-sweep.)
+        outcome = Err(VmError::Terminated);
     }
     outcome
 }

data/lib/rusty_racer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RustyRacer
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

data/lib/rusty_racer.rb

@@ -27,6 +27,10 @@ module RustyRacer
   class ParseError < EvalError; end
   class RuntimeError < EvalError; end
   class ScriptTerminatedError < EvalError; end
+  # Raised when JS allocation exceeds the isolate's memory_limit. Catchable like
+  # any eval error — a runaway script fails its own eval instead of aborting the
+  # process. The space-axis twin of ScriptTerminatedError (the time axis).
+  class V8OutOfMemoryError < EvalError; end
   class SnapshotError < Error; end
   class PlatformAlreadyInitialized < Error; end
 
@@ -41,16 +45,22 @@ module RustyRacer
     # Keyword-arg constructor over the positional Rust primitive. A snapshot
     # (RustyRacer::Snapshot) boots the isolate with its baked-in state;
     # timeout_ms caps each eval/call (0 = no limit) against in-V8 infinite
-    # loops. microtasks mirrors V8's kAuto/kExplicit: :auto (default) drains
+    # loops. memory_limit caps the V8 heap in bytes (0 = no limit): a script
+    # that exceeds it is terminated and raises V8OutOfMemoryError rather than
+    # aborting the process, and the isolate stays usable afterward. It is a soft
+    # limit — V8 enforces it at GC granularity, so usage may briefly overshoot,
+    # and it must comfortably exceed the isolate's baseline (and any snapshot's
+    # baked-in heap), since the limit is only armed once the isolate has booted.
+    # microtasks mirrors V8's kAuto/kExplicit: :auto (default) drains
     # the microtask queue when the outermost eval/call/run/evaluate completes
     # (the standard embedder contract); :explicit drains only on
     # #perform_microtask_checkpoint.
-    def self.new(host_namespace: nil, snapshot: nil, timeout_ms: 0, microtasks: :auto)
+    def self.new(host_namespace: nil, snapshot: nil, timeout_ms: 0, memory_limit: 0, microtasks: :auto)
       unless %i[auto explicit].include?(microtasks)
         raise ArgumentError, "microtasks must be :auto or :explicit, got #{microtasks.inspect}"
       end
 
-      _new(host_namespace, snapshot, timeout_ms, microtasks == :explicit)
+      _new(host_namespace, snapshot, timeout_ms, memory_limit, microtasks == :explicit)
     end
 
     # ->(specifier, referrer_url, context) { Module } for JS import(). |context|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rusty_racer
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Keita Urashima
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-13 00:00:00.000000000 Z
+date: 2026-06-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys