rusty_racer 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0b742605170382bce639eaa6c8acd1917f6ed4e6f8a5d4f83d40701ffb14b25
-  data.tar.gz: ce873858c2a28e9903ca9abec1cc72e061f3561f1cf2c8d5b0ff3694d613ec55
+  metadata.gz: 329c875cb612dccca54a8c70302d26ad0a38b8a1821733aa6eac9c4795e77d8b
+  data.tar.gz: 4d2665db69e108f6ef37fa9d4f0ae4bc3224ab1756e911abec76cfad558f8bd4
 SHA512:
-  metadata.gz: 1e3960b00b14c62813d731ee85c8f41cca8f04a0ff7657446f205dda2f24c5e11fd07b00da000b1d7be503bb00f083cf389f3736fac8d6344343a6ec26a3a11e
-  data.tar.gz: 3ee0d6217b064b70362a7e2475e5db840a0b613922f91a418d3548464066ea1824d1c073870e5d9d6da4cdc351fa481e490d667520123675f2b7d730a926d23e
+  metadata.gz: f95ae2f448af2ade88af369bea7c0b41c500e4028aeed04e34574e148c7d5f460ac068804bc49b409ab55ad352d063fcb0269064b27b1cf3a2a0453a8e245e2f
+  data.tar.gz: 4b853defb2dbde4c0455b9eefb5b6ba9d40002e94953f5d1540c4035087e8128c6b6df843463429b0e5cbcb404a0d1a1c625d13a24fee301a300eaf50dc9ad84

data/README.md

@@ -21,6 +21,11 @@ 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. A heap runaway is caught
+  even with no explicit `memory_limit` — V8's default ceiling raises instead of
+  aborting.
 - **Precompiled gems** bundle V8 for Linux/macOS × Ruby 3.3–4.0 — no V8 build,
   no Rust toolchain.
 
@@ -33,9 +38,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 +89,32 @@ 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)
+```
+
+Even without an explicit `memory_limit`, a heap runaway raises
+`V8OutOfMemoryError` against V8's own default ceiling (~2 GB on 64-bit) rather
+than aborting the process — pass `memory_limit:` for a tighter bound. (One
+caveat: if the process's available memory — e.g. a container cgroup limit — sits
+below the active ceiling, the OS may kill the process before V8's callback
+fires; set an explicit `memory_limit` under that bound to keep it catchable.)
+
 ### 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.4"
 edition = "2021"
 publish = false
 

data/ext/rusty_racer/src/lib.rs

@@ -186,7 +186,63 @@ 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 on EVERY isolate). V8 calls this,
+// synchronously on the owner thread, when a GC still leaves the heap about to
+// exceed the current ceiling — i.e. the script is running away on memory. That
+// ceiling is the configured memory_limit when one was set, otherwise V8's own
+// platform-derived default (the default-protection path), so a runaway raises a
+// catchable error either way instead of aborting the process. `data` is the
+// isolate ptr we registered (Core.iso_ptr). We flag the isolate and terminate the
+// running JS so it unwinds with that catchable error. 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.
+    // The closure releases the &mut borrow before terminate_execution (&self).
+    // Also record V8's `initial` ceiling so recovery can restore it when no
+    // explicit memory_limit was set (see oom_initial_limit).
+    let flagged = isolate
+        .get_slot_mut::<IsolateState>()
+        .map(|s| {
+            s.oom_fired = true;
+            s.oom_initial_limit = initial;
+        })
+        .is_some();
+    if flagged {
+        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 +578,18 @@ struct IsolateState {
     instantiate_resolve: Option<RootedProc>,
     instantiate_resolve_err: Option<BoxValue<Exception>>,
     watchdog: Arc<WatchdogShared>,
+    // Set by near_heap_limit_cb when the heap ceiling 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,
+    // V8's original heap ceiling, captured from the callback's `initial` argument
+    // when it fires. Recovery resets the ceiling to memory_limit when one was set,
+    // but with no explicit limit (the default-protection path) the ceiling IS V8's
+    // platform-derived default, whose value we don't otherwise know — so we restore
+    // to this captured initial instead. 0 until the callback has fired at least once.
+    oom_initial_limit: usize,
 }
 
 impl IsolateState {
@@ -543,6 +611,8 @@ impl IsolateState {
             instantiate_resolve: None,
             instantiate_resolve_err: None,
             watchdog: WatchdogShared::new(),
+            oom_fired: false,
+            oom_initial_limit: 0,
         }
     }
 }
@@ -1033,6 +1103,13 @@ 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 = V8's default ceiling. When set, the
+    // isolate is created with this as V8's max heap; near_heap_limit_cb is registered
+    // either way (against this ceiling when set, V8's default otherwise), so a runaway
+    // is always catchable rather than a process abort. Core::run's OOM recovery resets
+    // the ceiling after each OOM (to this when set, else V8's captured default — see
+    // oom_initial_limit). 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 +1534,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 is a separate isolate
+                        // that never registers near_heap_limit_cb.
+                        VmError::OutOfMemory => "snapshot code ran out of memory".to_string(),
                     });
                 }
             }
@@ -1492,16 +1572,24 @@ 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).
+        // With no explicit limit the callback is still registered below, against
+        // V8's own default ceiling, so a runaway raises instead of aborting.
+        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 +1629,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 heap-limit callback 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.
+        // Registered unconditionally — with memory_limit it guards that ceiling,
+        // without one it guards V8's default ceiling (catchable, not a process abort).
+        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 +1653,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 +1749,44 @@ 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 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 std::mem::take(&mut istate!(unsafe { &mut *iso }).oom_fired) {
+                    let iso_ref = unsafe { &mut *iso };
+                    // The ceiling to restore: the configured memory_limit when one was
+                    // set, otherwise V8's default ceiling, which the callback captured
+                    // in oom_initial_limit (we don't otherwise know its value).
+                    let restore_to = if self.memory_limit > 0 {
+                        self.memory_limit
+                    } else {
+                        istate!(iso_ref).oom_initial_limit
+                    };
+                    // Reclaim the runaway allocation, then reset the ceiling from the
+                    // doubled bump back to restore_to (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, restore_to);
+                    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 +2198,12 @@ 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.
+        // Registered unconditionally (default protection), so always remove it.
+        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 +2658,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 +2739,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.4"
 end

data/lib/rusty_racer.rb

@@ -27,6 +27,11 @@ module RustyRacer
   class ParseError < EvalError; end
   class RuntimeError < EvalError; end
   class ScriptTerminatedError < EvalError; end
+  # Raised when JS allocation exceeds the isolate's heap ceiling (the configured
+  # memory_limit, or V8's default ceiling when none was set). 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 +46,29 @@ 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: a script that exceeds the
+    # ceiling is terminated and raises V8OutOfMemoryError rather than aborting
+    # the process, and the isolate stays usable afterward. 0 (the default) does
+    # NOT disable this — it leaves V8's own platform-derived default ceiling
+    # (typically ~2 GB on 64-bit) in place, so a runaway is still catchable
+    # instead of a fatal abort; pass a smaller value for a tighter bound. It is
+    # a soft limit — V8 enforces it at GC granularity, so usage may briefly
+    # overshoot, and an explicit limit must comfortably exceed the isolate's
+    # baseline (and any snapshot's baked-in heap), since it is only armed once
+    # the isolate has booted. Caveat: if the process's available memory (e.g. a
+    # container cgroup limit) is below the active ceiling, the OS may kill the
+    # process before V8's callback fires — set an explicit memory_limit under
+    # that bound to keep the error catchable.
+    # 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.4
 platform: ruby
 authors:
 - Keita Urashima
-autorequire: 
+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
@@ -54,7 +54,7 @@ metadata:
   source_code_uri: https://github.com/ursm/rusty_racer
   bug_tracker_uri: https://github.com/ursm/rusty_racer/issues
   rubygems_mfa_required: 'true'
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -70,7 +70,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubygems_version: 3.5.22
-signing_key: 
+signing_key:
 specification_version: 4
 summary: Embed V8 in Ruby via rusty_v8 + Magnus (rb-sys)
 test_files: []