rusty_racer 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af5578c6ac8ba4eb6d367097be2faef786fdc0cb077ac5c76c14f1ec50106d41
-  data.tar.gz: 5cc05af64db35a3202c3fd72d2b0809e621ee7fa59c3db4e913ea537d835c438
+  metadata.gz: 7df2aeec586e04d155d2635f6df9b51e219b31108fad5829e7a5ed5eb8a784a3
+  data.tar.gz: '099e1e39f64e041d082fb86269ae4265406e4f05279e3d24909a9e6f4fa89de0'
 SHA512:
-  metadata.gz: ab88c79367db640e4144c0844a2ffcc0168f353de01ad7c225902c756d350f7a48188d9a3c0890ec6da2a61dc83e6a2484e519ccb082bb171d4fa795f89a4e7f
-  data.tar.gz: da6ca243ceb13b6d353ce15c6b59e725d617c0712e146a13017f2bbb2d7715dad0705849c4ce36b1b941b0dcb1a2a1750390d557b80c3e7a196809a66a5d4efa
+  metadata.gz: 5d8f2b15aca012b8c3933b960009e1d248cf2284774eff23c4740688796dfff97d4fe647fc0792f68e70fe4a66aa4fb4cdb7869451a82fac625178f57b8f56d2
+  data.tar.gz: c66d30a7c1bfd8d00f62c7ee99e6356f1f9f6c4a8aeebab9e05552a945c51d54f4dd31f3787fa95bd60e425e1dae3240fdb90186c9c2bb87a7b945a0b55b06cd

data/README.md

@@ -38,12 +38,12 @@ Embed [V8](https://v8.dev/) in Ruby, built on [rusty_v8](https://crates.io/crate
 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,
+marshalling** (`BigInt`/`Date`/`Map`/`Set` and shared/cyclic graphs cross as
+distinct Ruby types, where mini_racer does a narrower value conversion); 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
+at parity once the per-op JS work dominates. 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

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

data/ext/rusty_racer/src/lib.rs

@@ -54,7 +54,7 @@ use marshal::{js_to_jsval, jsval_to_js, jsval_to_ruby, ruby_to_jsval, JsVal};
 mod ops;
 use ops::{run_source, service_request, Compiled, Request, VmReply};
 mod stack;
-use stack::{discover_scan_start_field, set_v8_stack_limit, STACK_DEBUG};
+use stack::{current_real_isolate, discover_scan_start_field, set_v8_stack_limit, STACK_DEBUG};
 mod watchdog;
 use watchdog::{
     arm_watchdog, disarm_watchdog, run_js_bracketed, watchdog_loop, WatchdogShared, WATCHDOG_DEBUG,
@@ -242,6 +242,8 @@ fn relabel_oom(reply: VmReply) -> VmReply {
         VmReply::ModuleCompiled(r) => VmReply::ModuleCompiled(fix(r)),
         VmReply::ScriptCompiled(r) => VmReply::ScriptCompiled(fix(r)),
         VmReply::CodeCache(r) => VmReply::CodeCache(fix(r)),
+        // Carries no Result and can't OOM (no JS allocation) — pass through.
+        VmReply::Heap(s) => VmReply::Heap(s),
     }
 }
 
@@ -519,6 +521,48 @@ struct ScriptReg {
 struct V8State {
     main_context: Option<v8::Global<v8::Context>>,
     contexts: HashMap<i32, v8::Global<v8::Context>>,
+    // Each realm gets its OWN v8::MicrotaskQueue (created in new_realm, owned
+    // here, keyed like the contexts: main_queue for id 0, queues for the rest).
+    // Why per-realm rather than the isolate-wide default: reset/dispose can then
+    // DISCARD a torn-down realm's pending microtasks by simply dropping its queue
+    // — without that, a queued promise reaction (it captures its creation realm)
+    // sits in the shared queue forever and pins the old v8::Context, so a warm
+    // isolate that Context#resets per visit leaks one whole realm per reset (V8
+    // counts it as a live native context; even a full GC can't reclaim it). The
+    // queue must outlive its context: dropping the UniqueRef DESTRUCTs the queue,
+    // which removes it from V8's per-isolate ring (so V8 won't scan it) and frees
+    // its microtasks. reset/dispose don't drop it directly — they move the old
+    // (context, queue) into `retiring` so flush_retiring can repoint then free it
+    // safely (see those fields).
+    main_queue: Option<v8::UniqueRef<v8::MicrotaskQueue>>,
+    queues: HashMap<i32, v8::UniqueRef<v8::MicrotaskQueue>>,
+    // A long-lived, never-drained queue a retired realm's context is repointed to
+    // before its own queue is freed. V8 enqueues a promise reaction into the
+    // HANDLER's context's queue, and rusty's realms are mutually accessible (one
+    // shared security token + NS.contextGlobal), so a LIVE realm can still hold —
+    // and later resolve — a promise whose handler lives in a realm we tore down;
+    // if that realm's queue were already freed the enqueue would be a
+    // use-after-free. Repointing to the graveyard makes any such late enqueue land
+    // in valid memory (the microtask simply never runs). Created once per isolate,
+    // dropped only at isolate teardown.
+    //
+    // TRADEOFF: the graveyard is never drained, so a microtask landed there lives
+    // until isolate teardown — a small, bounded-per-occurrence leak on the narrow
+    // "resolve a promise into an already-disposed realm" path. Vastly smaller than
+    // the whole-realm-per-reset leak this design fixes, and empty in normal use
+    // (you don't resolve a disposed realm's promises), so it is an accepted cost of
+    // keeping that late enqueue memory-safe.
+    graveyard_queue: Option<v8::UniqueRef<v8::MicrotaskQueue>>,
+    // Realms retired by reset/dispose, awaiting teardown. We can't free a realm's
+    // queue at reset/dispose time: (1) Context::SetMicrotaskQueue (the graveyard
+    // repoint) requires NO context entered, which fails for a NESTED reset (an
+    // outer eval's context is on the stack); (2) freeing before repointing risks
+    // the cross-realm use-after-free above. So we stash (old context, old queue)
+    // here — both stay alive, so no dangling pointer and no unbounded leak — and
+    // flush_retiring drains this list at the end of the outermost request, when
+    // no context is entered: it repoints each context to the graveyard, then drops
+    // the queues (discarding their pending microtasks — the actual leak fix).
+    retiring: Vec<(v8::Global<v8::Context>, v8::UniqueRef<v8::MicrotaskQueue>)>,
     next_context_id: i32,
     host_namespace: Option<String>,
     // One security token shared by every realm of this isolate: the
@@ -585,6 +629,12 @@ struct IsolateState {
     // 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,
+    // The JS stack captured at a watchdog timeout: when a deadline fires, the
+    // watchdog requests an interrupt that runs on THIS thread with JS still live
+    // (see timeout_interrupt) and snapshots the stack here BEFORE terminating, so
+    // the ScriptTerminatedError can name what was running. Taken (cleared) when the
+    // terminated op's error is built; None for any non-timeout outcome.
+    timeout_backtrace: Option<Vec<String>>,
 }
 
 impl IsolateState {
@@ -608,6 +658,7 @@ impl IsolateState {
             watchdog: WatchdogShared::new(),
             oom_fired: false,
             oom_initial_limit: 0,
+            timeout_backtrace: None,
         }
     }
 }
@@ -695,12 +746,44 @@ fn transfer_registry() -> &'static Mutex<HashMap<u64, SendBackingStore>> {
 // transfers, which a process will never reach.
 static NEXT_TRANSFER_TOKEN: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(1);
 
+// Drain EVERY realm's microtask queue once. Each realm has its own queue (see
+// V8State::queues), so a single scope.perform_microtask_checkpoint() — which only
+// touches the isolate's default queue — would run NOTHING (every realm's promises
+// land in the realm's own queue). This restores the old isolate-wide "drain
+// everything" semantics: a microtask queued in ANY realm runs, regardless of
+// which realm the checkpoint was requested from. V8 drains each queue until empty
+// and enters each microtask's own realm, so same-realm cascades fully resolve in
+// one pass; a cross-realm cascade (a microtask in realm A enqueueing into realm B
+// that was already drained this pass) resolves on the next checkpoint — callers
+// that need full quiescence loop (csim does).
+fn drain_all_realms(scope: &mut v8::PinScope<'_, '_>) {
+    // Snapshot the queue pointers, then drain without holding the IsolateState
+    // borrow (a microtask re-enters host fns that borrow it). The queue OBJECTS
+    // are address-stable (owned via UniqueRef, heap-allocated by V8), so the
+    // snapshot survives a queues-HashMap realloc (e.g. a microtask creating a
+    // realm); and reset/dispose — the only things that free a queue — are refused
+    // while draining (checkpoint_draining set the flag), so no pointer dangles.
+    let queues: Vec<*const v8::MicrotaskQueue> = {
+        let st = istate!(scope);
+        st.realms
+            .main_queue
+            .iter()
+            .chain(st.realms.queues.values())
+            .map(|q| &**q as *const v8::MicrotaskQueue)
+            .collect()
+    };
+    for q in queues {
+        unsafe { (*q).perform_checkpoint(&mut ***scope) };
+    }
+}
+
 // Run a microtask checkpoint with DRAINING set (nesting-safe via save/restore),
-// so a nested Reset/DisposeContext issued by a drained microtask is refused.
+// so a nested Reset/DisposeContext issued by a drained microtask is refused —
+// which also keeps drain_all_realms's queue snapshot from dangling.
 fn checkpoint_draining(scope: &mut v8::PinScope<'_, '_>) {
     let prev = istate!(scope).draining;
     istate!(scope).draining = true;
-    scope.perform_microtask_checkpoint();
+    drain_all_realms(scope);
     istate!(scope).draining = prev;
 }
 
@@ -1297,7 +1380,9 @@ fn drain_microtasks(
     _args: v8::FunctionCallbackArguments<'_>,
     _rv: v8::ReturnValue<'_, v8::Value>,
 ) {
-    scope.perform_microtask_checkpoint();
+    // Drain every realm's queue (isolate-wide semantics), under the draining
+    // guard so a microtask can't reset/dispose a realm mid-drain.
+    checkpoint_draining(scope);
 }
 
 // NS.contextGlobal(id) -> the globalThis of context |id|. Cross-context
@@ -1572,10 +1657,20 @@ unsafe extern "C" fn promise_reject_cb(message: v8::PromiseRejectMessage) {
 
 // Build a fresh v8::Context and install the host namespace (from STATE) into
 // it — the single definition of "a realm of this isolate", shared by boot,
-// reset and create_context so realms can't drift apart.
-fn new_realm(scope: &mut v8::PinScope<'_, '_, ()>) -> v8::Global<v8::Context> {
+// reset and create_context so realms can't drift apart. Returns the context
+// Global AND its dedicated microtask queue; the caller owns the queue in
+// V8State alongside the context (see V8State::queues for why per-realm).
+fn new_realm(
+    scope: &mut v8::PinScope<'_, '_, ()>,
+) -> (v8::Global<v8::Context>, v8::UniqueRef<v8::MicrotaskQueue>) {
+    // Explicit policy like the isolate's: rusty drives every drain by hand
+    // (auto_drain / NS.drainMicrotasks), so V8 must never auto-run this queue.
+    let mut queue = v8::MicrotaskQueue::new(&mut **scope, v8::MicrotasksPolicy::Explicit);
     let fresh = {
-        let context = v8::Context::new(scope, Default::default());
+        let context = v8::Context::new(scope, v8::ContextOptions {
+            microtask_queue: Some(&mut *queue as *mut _),
+            ..Default::default()
+        });
         v8::Global::new(scope, context)
     };
     // DESIGN DECISION: every realm of an isolate shares ONE security token, so
@@ -1615,7 +1710,44 @@ fn new_realm(scope: &mut v8::PinScope<'_, '_, ()>) -> v8::Global<v8::Context> {
     if let Some(name) = host_namespace {
         install_host_namespace(scope, &fresh, &name);
     }
-    fresh
+    (fresh, queue)
+}
+
+// Tear down every realm parked in `retiring` (by reset/dispose): repoint each old
+// context at the graveyard queue, then free the old queues (discarding their
+// pending microtasks — the leak fix). MUST run with NO context entered, because
+// Context::SetMicrotaskQueue requires it — so the only caller is the OUTERMOST
+// service_request, after its op (and all nested ones) have unwound their
+// ContextScopes. A no-op when nothing is retired.
+fn flush_retiring(scope: &mut v8::PinScope<'_, '_, ()>) {
+    if istate!(scope).realms.retiring.is_empty() {
+        return;
+    }
+    let graveyard: *const v8::MicrotaskQueue = match istate!(scope).realms.graveyard_queue.as_ref() {
+        Some(q) => &**q as *const _,
+        // The graveyard is created at boot and never cleared, so with entries
+        // waiting this is unreachable; assert so a future refactor that defers its
+        // creation fails loudly instead of silently stranding `retiring` (which
+        // would quietly resurrect the whole-realm leak). Bail without taking the
+        // list, so nothing is lost if it somehow happens in release.
+        None => {
+            debug_assert!(false, "graveyard queue missing while realms are retiring");
+            return;
+        }
+    };
+    let retiring = std::mem::take(&mut istate!(scope).realms.retiring);
+    for (ctx, _queue) in &retiring {
+        let local = v8::Local::new(scope, ctx);
+        // SAFETY: the graveyard queue is owned by V8State for the isolate's whole
+        // life, so the pointer is valid for this set_microtask_queue call. Repoint
+        // BEFORE the queues drop below, so a cross-realm reference that keeps `ctx`
+        // alive can't be left holding a freed queue.
+        local.set_microtask_queue(unsafe { &*graveyard });
+    }
+    // Dropping `retiring` here frees each old queue (and its now-discarded pending
+    // microtasks) and each old context Global. Every context was just repointed to
+    // the graveyard, so no live context holds a freed queue pointer.
+    drop(retiring);
 }
 
 // Inject globalThis.<name> = { drainMicrotasks } into a context. Re-run on
@@ -1828,8 +1960,12 @@ impl Isolate {
         // namespace from the slot (seeded above).
         {
             v8::scope!(let scope, &mut isolate);
-            let main_context = new_realm(scope);
+            let (main_context, main_queue) = new_realm(scope);
             istate!(scope).realms.main_context = Some(main_context);
+            istate!(scope).realms.main_queue = Some(main_queue);
+            // The shared graveyard for retired realms' contexts (see V8State).
+            let graveyard = v8::MicrotaskQueue::new(&mut **scope, v8::MicrotasksPolicy::Explicit);
+            istate!(scope).realms.graveyard_queue = Some(graveyard);
         }
         // Box the OwnedIsolate so it has a STABLE address, then capture a raw ptr
         // INTO the box (a `&mut Isolate` is `&mut NonNull<RealIsolate>`, pointing
@@ -1843,6 +1979,10 @@ impl Isolate {
         // 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);
+        // Wire the watchdog's interrupt target now that iso_ptr is stable: on a
+        // timeout the loop requests an interrupt against this ptr to capture the JS
+        // stack on the isolate thread before terminating (see timeout_interrupt).
+        watchdog.set_iso_ptr(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
@@ -1920,6 +2060,16 @@ impl Core {
         self.ensure_owner_and_live(ruby)?;
         let iso = self.iso_ptr.0;
         let depth = self.depth.fetch_add(1, Ordering::SeqCst);
+        // Drop any prior timeout's captured stack at the START of an OUTERMOST op,
+        // so it can't leak onto this op's error. Cleared only at depth 0 (not for
+        // nested ops) on purpose: a nested timeout's terminate is isolate-global
+        // and tears down the whole op stack, so EVERY frame's error (nested and the
+        // escalated outer one) should surface the same culprit — reply_value peeks
+        // (clones) rather than takes, leaving it readable for the outer frame until
+        // the next outermost op clears it here.
+        if depth == 0 {
+            istate!(unsafe { &mut *iso }).timeout_backtrace = None;
+        }
         // EVERYTHING that touches V8 — enter, the scope, the JS run, the scope
         // drop, exit — happens inside ONE without_gvl, hence on ONE native thread
         // with no GVL boundary in between: M:N could otherwise migrate us to a
@@ -1998,22 +2148,57 @@ impl Core {
                 unsafe { (*iso).exit() };
                 reply
             } else {
-                // Re-entrant (a host callback, having reacquired the GVL to run a
-                // proc that issued this op, is on the V8 stack): the isolate is
-                // already entered by the depth-0 op on THIS native thread, so
-                // bootstrap onto the ambient HandleScope rather than re-enter.
+                // Re-entrant (a host callback or module resolver, having
+                // reacquired the GVL to run a proc that issued this op, is on the
+                // V8 stack). USUALLY the JS on the stack belongs to THIS isolate
+                // (same-isolate reentry) — which is therefore already entered on
+                // THIS native thread — so we bootstrap onto the ambient
+                // HandleScope without re-entering.
+                //
+                // But an embedder driving MANY isolates (e.g. capybara-simulated's
+                // windows) can interleave them: a host callback on isolate A runs
+                // Ruby that evals isolate B, whose own callback re-enters A. Now A
+                // is on the V8 stack (depth > 0) yet B — not A — is the isolate
+                // CURRENTLY entered on this thread, so bootstrapping a scope on A
+                // and opening a ContextScope would trip V8's "scope and Context do
+                // not belong to the same Isolate" panic (it checks the scope's
+                // isolate against Isolate::GetCurrent()). Detect that case and
+                // properly enter A on top of B, restoring B on exit. Entering an
+                // already-current isolate is also harmless (V8's entered-isolate
+                // stack nests), so this is correct for same-isolate reentry too —
+                // we only pay the enter/exit when a FOREIGN isolate is on top.
+                //
                 // The stack limit + scan-start set at depth 0 are NOT re-pointed
                 // here: reentry runs in DEEPER frames of the SAME stack, so the
-                // depth-0 values still bound it correctly. The one exception is a
+                // depth-0 values still bound it correctly (whichever isolate is
+                // current — each tracks its own limit). The one exception is a
                 // host callback that SWITCHES stacks — e.g. resumes a Ruby Fiber
                 // that itself evals — where the depth-0 (native) settings are
                 // stale for the fiber; that nested-fiber-under-callback case is an
                 // unsupported edge (the realistic fiber path is a depth-0 eval).
-                std::panic::catch_unwind(AssertUnwindSafe(|| {
-                    v8::callback_scope!(unsafe scope, unsafe { &mut *iso });
-                    service_request(scope, request, false)
+                let foreign = unsafe { *(iso as *const *mut c_void) } != current_real_isolate();
+                if foreign {
+                    unsafe { (*iso).enter() };
+                }
+                let reply = std::panic::catch_unwind(AssertUnwindSafe(|| {
+                    if foreign {
+                        // A had no ambient scope under B's entry — open a fresh
+                        // HandleScope on A, exactly as the depth-0 path does.
+                        v8::scope!(let scope, unsafe { &mut *iso });
+                        service_request(scope, request, false)
+                    } else {
+                        v8::callback_scope!(unsafe scope, unsafe { &mut *iso });
+                        service_request(scope, request, false)
+                    }
                 }))
-                .ok()
+                .ok();
+                // Pop A back off (restoring B as current). Safe even after a
+                // panic unwind: the scope's Drop ran but left A entered, and
+                // exit() asserts A == GetCurrent(), which holds here.
+                if foreign {
+                    unsafe { (*iso).exit() };
+                }
+                reply
             }
         });
         self.depth.fetch_sub(1, Ordering::SeqCst);
@@ -2032,9 +2217,18 @@ impl Core {
     }
 
     // Map a terminal reply to a Ruby value (the common eval/call/run shape).
-    fn reply_value(ruby: &Ruby, reply: VmReply) -> Result<Value, Error> {
+    // &self so a Terminated outcome can pick up the JS stack the watchdog snapshot
+    // captured (see timeout_interrupt / take_timeout_backtrace).
+    fn reply_value(&self, ruby: &Ruby, reply: VmReply) -> Result<Value, Error> {
         match reply {
             VmReply::Done(Ok(val)) => jsval_to_ruby(ruby, &val),
+            // Clone (don't take): a nested timeout's terminate unwinds the whole op
+            // stack, so the escalated outer frame's error should name the same
+            // culprit too. The capture is dropped at the next outermost op's start
+            // (run), which keeps it from leaking onto an unrelated later op.
+            VmReply::Done(Err(VmError::Terminated)) => {
+                Err(terminated_error(ruby, self.peek_timeout_backtrace()))
+            }
             VmReply::Done(Err(e)) => Err(vm_err(ruby, e)),
             _ => Err(Error::new(
                 ruby.exception_runtime_error(),
@@ -2043,6 +2237,14 @@ impl Core {
         }
     }
 
+    // Clone the JS stack the watchdog's interrupt captured at the last timeout.
+    // Owner thread, isolate live — called right after run() returns, the same
+    // access pattern as swap_instantiate. Does NOT clear it (run() clears at the
+    // next outermost op) so a nested timeout's outer frame can read it too.
+    fn peek_timeout_backtrace(&self) -> Option<Vec<String>> {
+        istate!(unsafe { &mut *self.iso_ptr.0 }).timeout_backtrace.clone()
+    }
+
     fn call_proc(
         &self,
         ruby: &Ruby,
@@ -2104,14 +2306,43 @@ impl Core {
             void,
             timeout_ms: self.default_timeout_ms,
         })?;
-        Self::reply_value(ruby, reply)
+        self.reply_value(ruby, reply)
     }
 
     fn drain_microtasks(&self, ruby: &Ruby) -> Result<Value, Error> {
         let reply = self.run(ruby, Request::DrainMicrotasks {
             timeout_ms: self.default_timeout_ms,
         })?;
-        Self::reply_value(ruby, reply)
+        self.reply_value(ruby, reply)
+    }
+
+    // Isolate#heap_statistics -> a Symbol-keyed Hash of v8::HeapStatistics
+    // (bytes; the two *_contexts entries are counts). See Request::HeapStatistics.
+    fn heap_statistics(&self, ruby: &Ruby) -> Result<Value, Error> {
+        let reply = self.run(ruby, Request::HeapStatistics)?;
+        let VmReply::Heap(s) = reply else {
+            return Err(Error::new(
+                ruby.exception_runtime_error(),
+                "internal: unexpected heap reply",
+            ));
+        };
+        let h = ruby.hash_new();
+        h.aset(ruby.to_symbol("used_heap_size"), s.used_heap_size)?;
+        h.aset(ruby.to_symbol("total_heap_size"), s.total_heap_size)?;
+        h.aset(ruby.to_symbol("heap_size_limit"), s.heap_size_limit)?;
+        h.aset(ruby.to_symbol("malloced_memory"), s.malloced_memory)?;
+        h.aset(ruby.to_symbol("peak_malloced_memory"), s.peak_malloced_memory)?;
+        h.aset(ruby.to_symbol("external_memory"), s.external_memory)?;
+        h.aset(ruby.to_symbol("number_of_native_contexts"), s.number_of_native_contexts)?;
+        h.aset(ruby.to_symbol("number_of_detached_contexts"), s.number_of_detached_contexts)?;
+        Ok(h.as_value())
+    }
+
+    // Isolate#low_memory_notification: ask V8 to run a full GC now.
+    fn low_memory_notification(&self, ruby: &Ruby) -> Result<(), Error> {
+        let reply = self.run(ruby, Request::LowMemoryNotification)?;
+        self.reply_value(ruby, reply)?;
+        Ok(())
     }
 
     fn eval_t(
@@ -2128,7 +2359,7 @@ impl Core {
             filename,
             timeout_ms,
         })?;
-        Self::reply_value(ruby, reply)
+        self.reply_value(ruby, reply)
     }
 
     fn attach(&self, ruby: &Ruby, context_id: i32, name: String, proc: Proc) -> Result<Value, Error> {
@@ -2142,7 +2373,7 @@ impl Core {
             host_fn_id,
             timeout_ms: self.default_timeout_ms,
         })?;
-        Self::reply_value(ruby, reply)
+        self.reply_value(ruby, reply)
     }
 
     // attach_many: install several host fns in ONE round-trip to the V8 thread
@@ -2174,7 +2405,7 @@ impl Core {
             entries: named_ids,
             timeout_ms: self.default_timeout_ms,
         })?;
-        Self::reply_value(ruby, reply)
+        self.reply_value(ruby, reply)
     }
 
     // Release the GC roots of the procs attached into |context_id| — its
@@ -2188,7 +2419,7 @@ impl Core {
 
     fn reset(&self, ruby: &Ruby, context_id: i32) -> Result<Value, Error> {
         let reply = self.run(ruby, Request::Reset { context_id })?;
-        let out = Self::reply_value(ruby, reply)?;
+        let out = self.reply_value(ruby, reply)?;
         // Only on success — a refused reset (unknown/suspended realm) keeps
         // its attached fns callable.
         self.release_context_procs(context_id);
@@ -2198,13 +2429,13 @@ impl Core {
     // Build a new context; returns its id (replied as an Int).
     fn create_context(&self, ruby: &Ruby) -> Result<i32, Error> {
         let reply = self.run(ruby, Request::CreateContext)?;
-        let id = Self::reply_value(ruby, reply)?;
+        let id = self.reply_value(ruby, reply)?;
         i32::try_convert(id)
     }
 
     fn dispose_context(&self, ruby: &Ruby, context_id: i32) -> Result<(), Error> {
         let reply = self.run(ruby, Request::DisposeContext { context_id })?;
-        Self::reply_value(ruby, reply)?;
+        self.reply_value(ruby, reply)?;
         self.release_context_procs(context_id);
         Ok(())
     }
@@ -2277,7 +2508,7 @@ impl Core {
         if let Some(exc) = resolver_err {
             return Err(Error::from(*exc));
         }
-        Self::reply_value(ruby, reply?)
+        self.reply_value(ruby, reply?)
     }
 
     fn evaluate_module(&self, ruby: &Ruby, module_id: i32) -> Result<Value, Error> {
@@ -2285,22 +2516,22 @@ impl Core {
             module_id,
             timeout_ms: self.default_timeout_ms,
         })?;
-        Self::reply_value(ruby, reply)
+        self.reply_value(ruby, reply)
     }
 
     fn module_namespace(&self, ruby: &Ruby, module_id: i32) -> Result<Value, Error> {
         let reply = self.run(ruby, Request::ModuleNamespace { module_id })?;
-        Self::reply_value(ruby, reply)
+        self.reply_value(ruby, reply)
     }
 
     fn module_status(&self, ruby: &Ruby, module_id: i32) -> Result<Value, Error> {
         let reply = self.run(ruby, Request::ModuleStatus { module_id })?;
-        Self::reply_value(ruby, reply)
+        self.reply_value(ruby, reply)
     }
 
     fn dispose_module(&self, ruby: &Ruby, module_id: i32) -> Result<(), Error> {
         let reply = self.run(ruby, Request::DisposeModule { module_id })?;
-        Self::reply_value(ruby, reply).map(|_| ())
+        self.reply_value(ruby, reply).map(|_| ())
     }
 
     // Classic script: compile, run, dispose.
@@ -2338,12 +2569,12 @@ impl Core {
             script_id,
             timeout_ms: self.default_timeout_ms,
         })?;
-        Self::reply_value(ruby, reply)
+        self.reply_value(ruby, reply)
     }
 
     fn dispose_script(&self, ruby: &Ruby, script_id: i32) -> Result<(), Error> {
         let reply = self.run(ruby, Request::DisposeScript { script_id })?;
-        Self::reply_value(ruby, reply).map(|_| ())
+        self.reply_value(ruby, reply).map(|_| ())
     }
 
     // Serialize a fresh bytecode cache from a compiled handle's current state
@@ -2524,6 +2755,17 @@ impl Isolate {
     fn perform_microtask_checkpoint(ruby: &Ruby, rb_self: &Self) -> Result<Value, Error> {
         rb_self.core.drain_microtasks(ruby)
     }
+    // Isolate#heap_statistics -> Hash. A diagnostic window into the V8 heap;
+    // watch number_of_native_contexts / number_of_detached_contexts to spot a
+    // realm leak across Context#reset.
+    fn heap_statistics(ruby: &Ruby, rb_self: &Self) -> Result<Value, Error> {
+        rb_self.core.heap_statistics(ruby)
+    }
+    // Isolate#low_memory_notification: full GC now. Reclaims dead realms between
+    // visits, and distinguishes reclaimable garbage from a genuine leak.
+    fn low_memory_notification(ruby: &Ruby, rb_self: &Self) -> Result<(), Error> {
+        rb_self.core.low_memory_notification(ruby)
+    }
     // dynamic_import_resolver = ->(specifier, referrer_url) { module } for import().
     fn set_dynamic_import_resolver(rb_self: &Self, proc: Proc) {
         rb_self.core.set_dynamic_import_resolver(proc);
@@ -2884,6 +3126,36 @@ fn vm_err(ruby: &Ruby, e: VmError) -> Error {
     }
 }
 
+// Build a RustyRacer::ScriptTerminatedError, attaching the JS stack the watchdog
+// snapshotted at the timeout (top frame first) as both #js_backtrace and — when
+// non-empty — the exception's Ruby backtrace, plus the top frame in the message
+// so even plain logging names what was running. js_backtrace is None for a stop
+// that isn't a watchdog timeout (e.g. Isolate#terminate), where no stack was
+// captured; then #js_backtrace is [] and the Ruby backtrace is left intact.
+fn terminated_error(ruby: &Ruby, js_backtrace: Option<Vec<String>>) -> Error {
+    let class = err_class(ruby, "ScriptTerminatedError");
+    let frames = js_backtrace.unwrap_or_default();
+    let message = match frames.first() {
+        Some(top) => format!("JavaScript was terminated (timeout or stop); running: {top}"),
+        None => "JavaScript was terminated (timeout or stop)".to_string(),
+    };
+    let exc: Value = match class.funcall("new", (message.as_str(),)) {
+        Ok(v) => v,
+        Err(e) => return e,
+    };
+    // Always expose #js_backtrace (even []) so the accessor is never nil.
+    let _ = exc.funcall::<_, _, Value>("instance_variable_set", ("@js_backtrace", frames.clone()));
+    // Only override the Ruby backtrace when we actually have JS frames — for a
+    // bare stop, keep Ruby's own backtrace (the eval call site) instead of [].
+    if !frames.is_empty() {
+        let _ = exc.funcall::<_, _, Value>("set_backtrace", (frames,));
+    }
+    match magnus::Exception::from_value(exc) {
+        Some(e) => Error::from(e),
+        None => Error::new(class, message),
+    }
+}
+
 // Build a RustyRacer::RuntimeError carrying the JS stack as its Ruby backtrace.
 // Constructs the exception instance so we can set_backtrace before raising;
 // falls back to a plain Error if any of that fails.
@@ -2971,6 +3243,11 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
         "_set_dynamic_import_resolver",
         method!(Isolate::set_dynamic_import_resolver, 1),
     )?;
+    isolate.define_method("heap_statistics", method!(Isolate::heap_statistics, 0))?;
+    isolate.define_method(
+        "low_memory_notification",
+        method!(Isolate::low_memory_notification, 0),
+    )?;
     isolate.define_method("dispose", method!(Isolate::dispose, 0))?;
     isolate.define_method("disposed?", method!(Isolate::disposed, 0))?;
 

data/ext/rusty_racer/src/ops.rs

@@ -137,6 +137,18 @@ pub(crate) enum Request {
     ModuleCodeCache {
         module_id: i32,
     },
+    // Isolate-level memory introspection / hint (realm-independent). Read
+    // v8::HeapStatistics — used/total/limit, malloced + external bytes, and the
+    // live (number_of_native_contexts) and detached (number_of_detached_contexts)
+    // native-context counts. The two context counts are the lever for diagnosing
+    // a realm leak across Context#reset: a healthy warm isolate's live+detached
+    // count plateaus, a leak makes it climb.
+    HeapStatistics,
+    // Ask V8 to run a full GC now (Isolate::LowMemoryNotification) — lets the
+    // embedder reclaim dead realms between visits without waiting for the
+    // near-heap-limit callback, and tells reclaimable garbage apart from a real
+    // leak (memory that survives this is genuinely retained).
+    LowMemoryNotification,
 }
 
 // compile_module result: the module's id plus any produced bytecode cache and
@@ -147,6 +159,20 @@ pub(crate) struct Compiled {
     pub(crate) cache_rejected: bool,
 }
 
+// A snapshot of v8::HeapStatistics, in bytes (counts for the context fields).
+// Plain copyable numbers so it crosses out of the V8 op into a Ruby Hash without
+// any handle. See Request::HeapStatistics for what the context counts tell you.
+pub(crate) struct HeapStats {
+    pub(crate) used_heap_size: u64,
+    pub(crate) total_heap_size: u64,
+    pub(crate) heap_size_limit: u64,
+    pub(crate) malloced_memory: u64,
+    pub(crate) peak_malloced_memory: u64,
+    pub(crate) external_memory: u64,
+    pub(crate) number_of_native_contexts: u64,
+    pub(crate) number_of_detached_contexts: u64,
+}
+
 // The terminal reply of an op: service_request returns it straight up to
 // Core::run (no channel). Host callbacks and module resolvers don't round-trip
 // through here — they run inline (with_gvl).
@@ -158,6 +184,8 @@ pub(crate) enum VmReply {
     // Script#/Module#create_code_cache: the serialized bytes, or None when V8
     // can't produce a cache (or the handle's realm is gone).
     CodeCache(Result<Option<Vec<u8>>, VmError>),
+    // Isolate#heap_statistics: a snapshot of v8::HeapStatistics.
+    Heap(HeapStats),
 }
 
 pub(crate) fn run_source(scope: &mut v8::PinScope<'_, '_>, source: &str, filename: &str) -> Result<JsVal, VmError> {
@@ -315,6 +343,12 @@ pub(crate) fn service_request(scope: &mut v8::PinScope<'_, '_, ()>, request: Req
         istate!(scope).watchdog_fired = false;
         scope.cancel_terminate_execution();
     }
+    // Free realms retired by this request (or a nested reset/dispose) now that the
+    // stack has fully unwound and NO context is entered — Context::SetMicrotaskQueue
+    // (the graveyard repoint inside) requires that.
+    if outermost {
+        flush_retiring(scope);
+    }
     reply
 }
 
@@ -342,7 +376,9 @@ fn request_realm(state: &IsolateState, request: &Request) -> Option<i32> {
         | Request::DisposeModule { .. }
         | Request::DisposeScript { .. }
         | Request::ScriptCodeCache { .. }
-        | Request::ModuleCodeCache { .. } => None,
+        | Request::ModuleCodeCache { .. }
+        | Request::HeapStatistics
+        | Request::LowMemoryNotification => None,
     }
 }
 
@@ -417,9 +453,35 @@ fn dispatch_one(scope: &mut v8::PinScope<'_, '_, ()>, request: Request, outermos
         // It needs the module's context entered (unlike UnboundScript), so
         // a gone realm yields nil.
         Request::ModuleCodeCache { module_id } => op_module_code_cache(scope, module_id),
+        Request::HeapStatistics => op_heap_statistics(scope),
+        Request::LowMemoryNotification => op_low_memory_notification(scope),
     }
 }
 
+// Snapshot v8::HeapStatistics. No handles, no JS — a PinScope<()> derefs to the
+// Isolate, so the stats read straight off it.
+fn op_heap_statistics(scope: &mut v8::PinScope<'_, '_, ()>) -> VmReply {
+    let s = scope.get_heap_statistics();
+    VmReply::Heap(HeapStats {
+        used_heap_size: s.used_heap_size() as u64,
+        total_heap_size: s.total_heap_size() as u64,
+        heap_size_limit: s.heap_size_limit() as u64,
+        malloced_memory: s.malloced_memory() as u64,
+        peak_malloced_memory: s.peak_malloced_memory() as u64,
+        external_memory: s.external_memory() as u64,
+        number_of_native_contexts: s.number_of_native_contexts() as u64,
+        number_of_detached_contexts: s.number_of_detached_contexts() as u64,
+    })
+}
+
+// Hint V8 to free as much as it can right now (a full GC). Runs entered, under
+// the GVL-released op, on the owner thread — the same place the OOM recovery
+// already calls it.
+fn op_low_memory_notification(scope: &mut v8::PinScope<'_, '_, ()>) -> VmReply {
+    scope.low_memory_notification();
+    VmReply::Done(Ok(JsVal::Undefined))
+}
+
 fn op_eval(scope: &mut v8::PinScope<'_, '_, ()>, context_id: i32, source: String, filename: String, timeout_ms: u64, outermost: bool) -> VmReply {
     let outcome = run_js_bracketed(scope, outermost, timeout_ms, "eval", |scope, outermost| {
         let realm = context_for(istate!(scope), context_id);
@@ -574,13 +636,22 @@ fn op_reset(scope: &mut v8::PinScope<'_, '_, ()>, context_id: i32) -> VmReply {
                 .into(),
         )))
     } else {
-        let fresh = new_realm(scope);
+        let (fresh, fresh_queue) = new_realm(scope);
         {
             let realms = &mut istate!(scope).realms;
-            if context_id == 0 {
-                realms.main_context = Some(fresh);
+            // Swap in the fresh realm and PARK the old context + queue in
+            // `retiring` (don't drop the queue here): freeing it now could strand a
+            // freed pointer in the old context if a cross-realm reference outlives
+            // this reset, and the graveyard repoint can't run while a context is
+            // entered (nested reset). flush_retiring frees them safely at the next
+            // outermost request boundary.
+            let (old_ctx, old_queue) = if context_id == 0 {
+                (realms.main_context.replace(fresh), realms.main_queue.replace(fresh_queue))
             } else {
-                realms.contexts.insert(context_id, fresh);
+                (realms.contexts.insert(context_id, fresh), realms.queues.insert(context_id, fresh_queue))
+            };
+            if let (Some(c), Some(q)) = (old_ctx, old_queue) {
+                realms.retiring.push((c, q));
             }
         }
         // Drop modules bound to this context — their realm just changed.
@@ -596,8 +667,9 @@ fn op_create_context(scope: &mut v8::PinScope<'_, '_, ()>) -> VmReply {
         realms.next_context_id += 1;
         id
     };
-    let fresh = new_realm(scope);
+    let (fresh, fresh_queue) = new_realm(scope);
     istate!(scope).realms.contexts.insert(id, fresh);
+    istate!(scope).realms.queues.insert(id, fresh_queue);
     VmReply::Done(Ok(JsVal::Int(id as i64)))
 }
 
@@ -614,9 +686,17 @@ fn op_dispose_context(scope: &mut v8::PinScope<'_, '_, ()>, context_id: i32) ->
                 .into(),
         )))
     } else {
-        // Dropping the Global lets V8 collect the context. id 0 is the
-        // default context and never disposed independently.
-        istate!(scope).realms.contexts.remove(&context_id);
+        // Park the context + queue in `retiring` rather than dropping them here:
+        // freeing the queue could strand a freed pointer in a cross-realm-reachable
+        // context, and the graveyard repoint needs no context entered.
+        // flush_retiring frees them at the next outermost request boundary, which
+        // is what finally lets V8 collect the context. id 0 is the default context
+        // and never disposed independently.
+        let old_ctx = istate!(scope).realms.contexts.remove(&context_id);
+        let old_queue = istate!(scope).realms.queues.remove(&context_id);
+        if let (Some(c), Some(q)) = (old_ctx, old_queue) {
+            istate!(scope).realms.retiring.push((c, q));
+        }
         // Reclaim the modules compiled in it (else they leak until
         // isolate teardown).
         drop_context_artifacts(istate!(scope), context_id);

data/ext/rusty_racer/src/stack.rs

@@ -1,9 +1,13 @@
 // V8 stack limit + conservative-GC-scan retargeting (in-thread: V8 runs on the
 // calling Ruby thread's stack — a native pthread stack, or a Ruby Fiber's
-// separate mmap'd stack). Self-contained: only raw pointers, std, libc, and the
-// exported V8 symbols below — no IsolateState/JsVal/marshalling. The crate uses
-// discover_scan_start_field (once per isolate), set_v8_stack_limit (per op), and
-// STACK_DEBUG (set at init); everything else is private to this module.
+// separate mmap'd stack), plus the current-isolate query the reentry path needs.
+// Self-contained: only raw pointers, std, libc, and the exported V8 symbols below
+// — no IsolateState/JsVal/marshalling. It also hosts current_real_isolate() (the
+// entered-isolate query) since that too is just one of the exported V8 symbols
+// below, kept here so the FFI block stays in one place. The crate uses
+// discover_scan_start_field (once per isolate), set_v8_stack_limit (per op),
+// current_real_isolate (per reentrant op), and STACK_DEBUG (set at init);
+// everything else is private to this module.
 
 use std::ffi::c_void;
 // Only native_stack_bounds (linux) needs it; gated so non-linux builds (macOS)
@@ -32,6 +36,19 @@ unsafe extern "C" {
     fn v8__internal__Heap__SetStackStart(heap: *mut c_void);
     #[link_name = "_ZN2v84base5Stack13GetStackStartEv"]
     fn v8__base__Stack__GetStackStart() -> usize;
+    // rusty_v8's C binding for v8::Isolate::GetCurrent() — the thread-local
+    // "currently entered" isolate. No #[link_name]: the exported symbol is
+    // literally this name (rusty_v8's binding glue), same as the crate's own
+    // private declaration. Lets a re-entrant op tell whether ITS isolate is the
+    // one currently entered, or a foreign isolate was entered on top of it (the
+    // cross-isolate reentry case — see Core::run).
+    fn v8__Isolate__GetCurrent() -> *mut c_void;
+}
+
+// The raw v8::Isolate* currently entered on this native thread (null if none).
+// Compared by identity against an isolate's own raw pointer.
+pub(crate) fn current_real_isolate() -> *mut c_void {
+    unsafe { v8__Isolate__GetCurrent() }
 }
 
 // Locate V8's conservative-GC-scan stack_start field

data/ext/rusty_racer/src/watchdog.rs

@@ -12,13 +12,22 @@
 // op handlers and isolate setup (still in lib.rs) call them;
 // report_watchdog_anomaly is private to this module.
 
-use std::sync::atomic::{AtomicBool, Ordering};
+use std::ffi::c_void;
+use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
 use std::sync::{Arc, Condvar, Mutex};
 use std::time::{Duration, Instant};
 
 use crate::istate;
 use crate::{IsolateState, JsVal, VmError};
 
+// Top N JS frames captured at a timeout — enough to name the culprit without
+// walking a pathological deep stack.
+const MAX_TIMEOUT_FRAMES: usize = 32;
+// Per-frame string cap. Function names and (especially) script URLs are
+// attacker-controlled JS and can be arbitrarily long (a multi-KB data: URL);
+// cap each so a runaway can't bloat the error message / backtrace.
+const MAX_FRAME_NAME: usize = 256;
+
 // The watchdog runs on ONE persistent thread per isolate rather than a fresh
 // std::thread per request: spawning + joining a thread on every op cost ~16µs
 // (5.5x) when a timeout was set, dwarfing the actual work. The thread sleeps on
@@ -27,6 +36,11 @@ use crate::{IsolateState, JsVal, VmError};
 pub(crate) struct WatchdogShared {
     inner: Mutex<WatchdogInner>,
     cv: Condvar,
+    // The owning isolate's raw `*mut v8::Isolate` as a usize (0 until wired up by
+    // set_iso_ptr, right after the isolate is boxed). The loop needs it to address
+    // the RequestInterrupt callback's `data` at fire time; kept as an atomic
+    // (outside the Mutex) so the loop reads it without serialising on arm/disarm.
+    iso_ptr: AtomicUsize,
 }
 
 impl WatchdogShared {
@@ -40,9 +54,17 @@ impl WatchdogShared {
                 shutdown: false,
             }),
             cv: Condvar::new(),
+            iso_ptr: AtomicUsize::new(0),
         })
     }
 
+    // Wire up the isolate pointer once it is stable (after the OwnedIsolate is
+    // boxed). Called before any op can arm a deadline, so the loop always sees it
+    // set by the time it could fire.
+    pub(crate) fn set_iso_ptr(&self, iso_ptr: *mut std::ffi::c_void) {
+        self.iso_ptr.store(iso_ptr as usize, Ordering::Relaxed);
+    }
+
     // Signal the loop to stop and wake it. Called once at isolate teardown,
     // before the isolate is touched, so the loop can't fire a terminate into an
     // isolate we're mid-disposing.
@@ -94,8 +116,21 @@ pub(crate) fn watchdog_loop(shared: Arc<WatchdogShared>, handle: v8::IsolateHand
             Some(frame) => {
                 let now = Instant::now();
                 if now >= frame.deadline {
-                    handle.terminate_execution();
                     inner.fired_generation = Some(frame.generation);
+                    // Don't terminate directly: request an interrupt so the stack
+                    // is captured on the isolate thread (with JS live) before the
+                    // terminate — see timeout_interrupt. fired_generation is set
+                    // FIRST and we still hold `inner`, so the callback (which locks
+                    // `inner` to read it) can't run until we release, and will see
+                    // it set. Fall back to a direct terminate if the isolate ptr
+                    // isn't wired yet (can't happen once an op has armed) — never
+                    // leave a runaway un-terminated.
+                    let iso = shared.iso_ptr.load(Ordering::Relaxed);
+                    if iso != 0 {
+                        handle.request_interrupt(timeout_interrupt, iso as *mut c_void);
+                    } else {
+                        handle.terminate_execution();
+                    }
                     // Drop the fired frame so the loop moves on to the next
                     // deadline instead of re-firing this one every wakeup.
                     inner.frames.retain(|f| f.generation != frame.generation);
@@ -110,6 +145,92 @@ pub(crate) fn watchdog_loop(shared: Arc<WatchdogShared>, handle: v8::IsolateHand
 
 // (The watchdog Arc now lives in IsolateState; arm/disarm reach it via istate!.)
 
+// The RequestInterrupt callback the watchdog fires when a deadline passes. It
+// runs on the ISOLATE thread with the runaway JS still on the stack, so it can
+// snapshot the stack BEFORE TerminateExecution unwinds it. `data` is the
+// `*mut v8::Isolate` (the same pointer near_heap_limit_cb uses); the
+// UnsafeRawIsolatePtr arg is ignored.
+//
+// GUARDED by fired_generation: a RequestInterrupt callback can't be cancelled, so
+// one still pending after its op already disarmed must NOT capture+terminate the
+// NEXT op. It acts only while some fired deadline is still awaiting its terminate
+// (fired_generation set) — which is exactly when a terminate is warranted, for
+// whatever op is currently on the stack.
+unsafe extern "C" fn timeout_interrupt(_isolate: v8::UnsafeRawIsolatePtr, data: *mut c_void) {
+    let isolate = unsafe { &mut *(data as *mut v8::Isolate) };
+    let pending = isolate
+        .get_slot::<IsolateState>()
+        .map(|s| s.watchdog.inner.lock().unwrap().fired_generation.is_some())
+        .unwrap_or(false);
+    if !pending {
+        return;
+    }
+    // Enter SOME realm (the main one — always present) just to get a
+    // context-typed scope, which StackTrace::current_stack_trace requires.
+    // CurrentStackTrace reads the ISOLATE's running stack regardless of which
+    // realm is entered, so this captures the real runaway frames even if they're
+    // in another realm. Capture, stash for the unwinding op's error, THEN
+    // terminate (so the stack is still live when we snapshot it).
+    v8::scope!(let scope, isolate);
+    let Some(main) = istate!(scope).realms.main_context.clone() else {
+        scope.terminate_execution();
+        return;
+    };
+    let context = v8::Local::new(scope, &main);
+    let scope = &mut v8::ContextScope::new(scope, context);
+    let frames = capture_js_backtrace(scope, MAX_TIMEOUT_FRAMES);
+    istate!(scope).timeout_backtrace = Some(frames);
+    scope.terminate_execution();
+}
+
+// Snapshot up to |max_frames| of the current JS stack as "func (script:line:col)"
+// strings, top frame first. Empty when there's no JS stack (e.g. already
+// terminating) — best-effort, never fatal.
+fn capture_js_backtrace(scope: &mut v8::PinScope<'_, '_>, max_frames: usize) -> Vec<String> {
+    let Some(trace) = v8::StackTrace::current_stack_trace(scope, max_frames) else {
+        return Vec::new();
+    };
+    let count = trace.get_frame_count();
+    let mut out = Vec::with_capacity(count);
+    for i in 0..count {
+        let Some(frame) = trace.get_frame(scope, i) else {
+            continue;
+        };
+        let func = clamp_name(
+            frame
+                .get_function_name(scope)
+                .map(|s| s.to_rust_string_lossy(scope))
+                .filter(|s| !s.is_empty())
+                .unwrap_or_else(|| "<anonymous>".to_string()),
+        );
+        let script = clamp_name(
+            frame
+                .get_script_name_or_source_url(scope)
+                .map(|s| s.to_rust_string_lossy(scope))
+                .filter(|s| !s.is_empty())
+                .unwrap_or_else(|| "<unknown>".to_string()),
+        );
+        out.push(format!(
+            "{func} ({script}:{}:{})",
+            frame.get_line_number(),
+            frame.get_column()
+        ));
+    }
+    out
+}
+
+// Cap a frame name/script string at MAX_FRAME_NAME chars (on a char boundary),
+// appending an ellipsis when truncated, so an attacker-controlled long name can't
+// bloat the error.
+fn clamp_name(mut s: String) -> String {
+    if s.len() > MAX_FRAME_NAME {
+        let end = (0..=MAX_FRAME_NAME).rev().find(|&i| s.is_char_boundary(i)).unwrap_or(0);
+        s.truncate(end);
+        s.push('…');
+    }
+    s
+}
+
 // Arm the watchdog for this request: push a frame with its own deadline and
 // wake the loop. Returns the generation token to hand to `disarm_watchdog`
 // (None when timeout_ms is 0 — no watchdog for this request).

data/lib/rusty_racer/version.rb

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

data/lib/rusty_racer.rb

@@ -26,7 +26,14 @@ module RustyRacer
   class EvalError < Error; end
   class ParseError < EvalError; end
   class RuntimeError < EvalError; end
-  class ScriptTerminatedError < EvalError; end
+  class ScriptTerminatedError < EvalError
+    # The JS stack at the moment the call timed out (watchdog), as
+    # ["func (script:line:col)", ...], top frame first — captured on the isolate
+    # thread just before TerminateExecution. [] when no stack was captured (e.g. a
+    # bare Isolate#terminate rather than a timeout). The same frames are also set
+    # as the exception's #backtrace when present.
+    def js_backtrace = @js_backtrace || []
+  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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rusty_racer
 version: !ruby/object:Gem::Version
-  version: 0.1.8
+  version: 0.1.10
 platform: ruby
 authors:
 - Keita Urashima
-autorequire:
+autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-06-15 00:00:00.000000000 Z
+date: 2026-06-19 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: []