rusty_racer 0.1.16 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 65667fe42e623b8ca26d70810029cc49de133a7c127e2a829c897359c510ef79
-  data.tar.gz: 4b82947a2404a0cea7ee14dc9a80f88a3abbd28c79c788d24b6f8b5f7524af65
+  metadata.gz: 074b269481c924fc8e99f129e361d29fb4847c9c91ac4afee96378721fe9eebd
+  data.tar.gz: 68b312cba649752c393c0736e10efd8280f87ae0406ef7826b8d9fe3ec5505ce
 SHA512:
-  metadata.gz: '084d1145e469c8d3422ec2402293e15d1e0fde2dd9d7436f16d5ec9655709207c809ca3e4d89f310ab5c91ae8b1449a5f4d80d2168d33f9c63217d2f14f09571'
-  data.tar.gz: ccfa7cd5c2d2e4cb847e15079a44bac3b1757410e2bf3f450ecf44524b8c0445b14c94d45f32d74688b4daec1cebe4decc74fb8c39455fc04bf02f4791a22c60
+  metadata.gz: c3ff8f690a9ad98912f2328d7be4bc10c3d1f38499365f628fbe4dac5e782832323bfc86976ac05fbe9406f288b75191fac11f1eb4f920d1caae056561d0eceb
+  data.tar.gz: a13dad93b256b9f15eef3baa27e79a97e2d7da61ec20c29aefc66907cd1cef4916fb0c84d65742233d182d48fed1fa369b48e86105bba7fede8a6afdaa008133

data/README.md

@@ -65,6 +65,7 @@ ctx.eval("({a: 1, b: [true, 'x']})")     # => {"a"=>1, "b"=>[true, "x"]}
 ctx.eval("function add(a, b) { return a + b }")
 ctx.call("add", 20, 22)                  # => 42
 ctx.call_void("doSideEffect")            # runs it; never marshals the return
+ctx.eval_void("globalThis.app = boot()") # ditto for the completion value
 
 # Ruby callbacks into JS; a raised Ruby exception becomes a JS exception.
 ctx.attach("rubyUpcase", ->(s) { s.upcase })
@@ -79,6 +80,20 @@ rescue RustyRacer::RuntimeError => e
 end
 ```
 
+Everything the binding raises descends from `RustyRacer::Error`, so one rescue
+covers the library. Under it: `ParseError`, `RuntimeError`,
+`ScriptTerminatedError` and `V8OutOfMemoryError` for what the JS did;
+`DisposedError` for using an isolate (or anything it handed out) after
+disposing it; `WrongThreadError` for reaching an isolate from the wrong thread.
+
+Reading a result is not passive — marshalling runs JS (getters, `Proxy` traps,
+`toString`), and a throw there fails the operation even though the code itself
+ran to completion. When the value is incidental, say so: `#eval_void`,
+`Script#run_void` and `#call_void` run for the effect and never touch the
+result. A statement list has a completion value whether you want one or not, so
+plumbing an object into a global (`globalThis.win = someProxy`) is enough to
+make a plain `#eval` fail after every one of its writes has landed.
+
 ES modules (the embedder owns the URL→module registry):
 
 ```ruby
@@ -86,10 +101,19 @@ dep = ctx.compile_module("export const x = 21;", filename: "/dep.js")
 app = ctx.compile_module('import {x} from "./dep.js"; export const r = x * 2;',
                          filename: "/app.js")
 app.instantiate { |specifier, referrer| dep if specifier == "./dep.js" }
+app.graph_async?                         # => false
 app.evaluate
 app.namespace["r"]                       # => 42
 ```
 
+`graph_async?` asks whether top-level `await` appears anywhere in the *linked*
+graph, so an `await` in a dependency counts — which is why it needs an
+instantiated module and raises before then. `false` is the answer that carries a
+guarantee: `evaluate` ran the whole graph to completion. Since there is no event
+loop here (see below), a `true` graph whose `await` never settles returns from
+`evaluate` with the module body still suspended, and `status` reports
+`:evaluated` either way — so `graph_async?` is what distinguishes the two.
+
 Classic `<script>`s work the same way: `ctx.compile("1 + 1").run` # => 2.
 
 ### Resource limits

data/ext/rusty_racer/Cargo.toml

@@ -5,7 +5,7 @@
 # links and loads with no custom archive.
 [package]
 name = "rusty_racer"
-version = "0.1.16"
+version = "0.2.1"
 edition = "2024"
 publish = false
 

data/ext/rusty_racer/src/lib.rs

@@ -326,13 +326,21 @@ fn current_ruby_thread() -> usize {
 // that class carrying the message. Must be called with the GVL held.
 fn error_to_exception(e: &Error) -> Option<Exception> {
     let v = e.value()?;
-    if let Ok(exc) = Exception::try_convert(v) {
-        return Some(exc);
-    }
+    // ExceptionClass FIRST. Error::new(class, msg) stores the CLASS, and
+    // Exception::try_convert would happily accept it — it falls back to calling
+    // #exception on the value, which hands back a fresh instance carrying only
+    // the class name, silently dropping our message.
     if let Ok(class) = ExceptionClass::try_convert(v) {
-        return class.new_instance((e.to_string(),)).ok();
+        // magnus renders such an Error as "Class: message"; the instance carries
+        // the class already, so strip it rather than say it twice.
+        let text = e.to_string();
+        let message = text
+            .strip_prefix(&format!("{class}: "))
+            .unwrap_or(&text)
+            .to_owned();
+        return class.new_instance((message,)).ok();
     }
-    None
+    Exception::try_convert(v).ok()
 }
 
 // JS called a host function. We are on the owner thread with the GVL RELEASED
@@ -351,8 +359,20 @@ fn host_fn_callback(
         Err(_) => return,
     };
     let mut js_args = Vec::with_capacity(args.length() as usize);
-    for i in 0..args.length() {
-        js_args.push(js_to_jsval(scope, args.get(i)));
+    {
+        // Marshalling an argument RUNS JS — accessors, Proxy traps — and a throw
+        // there has to fail the host call, not hand the Ruby proc a value that
+        // was never read. Without a TryCatch of our own the exception simply
+        // rides along until something happens to clear it, so whether the caller
+        // ever saw it came down to whether the proc re-entered V8.
+        v8::tc_scope!(let tc, scope);
+        for i in 0..args.length() {
+            js_args.push(js_to_jsval(tc, args.get(i)));
+        }
+        if tc.has_caught() {
+            tc.rethrow();
+            return;
+        }
     }
     // Reach the owning Core through the slot back-pointer (the callback holds
     // only a scope). Null only before wiring, which is before any JS can run.
@@ -924,19 +944,22 @@ fn resolve_imported<'s>(
     // import's auto-link (None -> dynamic_import_resolver, with the initiating
     // realm so it can resolve per-realm).
     let instantiate = istate!(scope).instantiate_resolve.as_ref().map(|r| r.get());
+    let mut dynamic_err = None;
     let dep_id = match instantiate {
         Some(resolve) => {
+            // The error conversion happens INSIDE with_gvl: error_to_exception
+            // calls into Ruby (so it can allocate, so it can GC) and BoxValue::new
+            // registers a GC root — neither is safe with the GVL released.
             match with_gvl(|| {
                 resolve_module_via_ruby(unsafe { &*core_ptr }, resolve, &spec, &ref_url, None)
+                    .map_err(|e| error_to_exception(&e).map(BoxValue::new))
             }) {
                 Ok(id) => id,
                 // Stash the resolver's own raised exception (GC-rooted) so the
                 // InstantiateModule op can re-raise it with its original class
                 // instead of a generic "failed to link".
-                Err(e) => {
-                    if let Some(exc) = error_to_exception(&e) {
-                        istate!(scope).instantiate_resolve_err = Some(BoxValue::new(exc));
-                    }
+                Err(exc) => {
+                    istate!(scope).instantiate_resolve_err = exc;
                     None
                 }
             }
@@ -949,7 +972,7 @@ fn resolve_imported<'s>(
                 .as_ref()
                 .map(|r| r.get());
             match resolver {
-                Some(p) => with_gvl(|| {
+                Some(p) => match with_gvl(|| {
                     resolve_module_via_ruby(
                         unsafe { &*core_ptr },
                         p,
@@ -957,23 +980,81 @@ fn resolve_imported<'s>(
                         &ref_url,
                         Some(here.unwrap_or(0)),
                     )
-                })
-                .unwrap_or(None),
+                    // Rendering the message reads the Ruby exception, so it too
+                    // stays inside with_gvl.
+                    .map_err(|e| e.to_string())
+                }) {
+                    Ok(id) => id,
+                    // Unlike the static branch there is no Ruby frame waiting to
+                    // re-raise into — this failure becomes the import()'s promise
+                    // rejection — so the resolver's own message has to travel out
+                    // as the JS error or it is lost.
+                    Err(why) => {
+                        dynamic_err = Some(why);
+                        None
+                    }
+                },
                 None => None,
             }
         }
     };
-    let dep_id = dep_id?;
+    // From here on, every exit that isn't a module throws first. V8 has no
+    // channel for "why" — it just sees an empty return, installs no error of its
+    // own and resets the graph — so without a thrown exception the failure
+    // reaches Ruby as a bare "unexpected failure" naming neither the import nor
+    // where it came from, which is the single most common module wiring mistake.
+    // (The two bails above stay silent: both are broken internal state, not
+    // anything the caller did.) The one path that must also stay silent is a
+    // STATIC resolver that raised — its own Ruby exception is already stashed
+    // for instantiate_module to re-raise, and ours would mask it. The dynamic
+    // branch has no such frame, so it carries its message in dynamic_err.
+    let raised = istate!(scope).instantiate_resolve_err.is_some();
+    let fail = |scope: &mut v8::PinScope<'_, '_>, message: String| {
+        if !raised {
+            throw_js_error(scope, &message);
+        }
+        None
+    };
+    let import = format!("{spec:?} imported from {ref_url}");
+    let Some(dep_id) = dep_id else {
+        return match dynamic_err {
+            Some(why) => fail(scope, format!("{why} (resolving {import})")),
+            None => fail(
+                scope,
+                format!("failed to resolve module specifier {import}"),
+            ),
+        };
+    };
     // The dep must live in the context actually being linked — the auto-link of
     // a dynamic import runs in whatever realm import() fired in, which kAuto can
     // detach from the request that started it. A foreign-context module would
     // V8-CHECK-abort.
-    let g = {
-        let (g, _, cid) = istate!(scope).modules.by_id.get(&dep_id)?;
-        if Some(*cid) != here {
-            return None;
+    let found = istate!(scope)
+        .modules
+        .by_id
+        .get(&dep_id)
+        .map(|(g, _, cid)| (g.clone(), *cid));
+    let g = match (here, found) {
+        (Some(here), Some((g, cid))) if cid == here => g,
+        (Some(_), Some(_)) => {
+            return fail(
+                scope,
+                format!("resolver returned a module from another realm for {import}"),
+            );
+        }
+        // The realm being linked is gone. Not reachable while a module is
+        // linking (see |here| above), but reporting it as a realm mismatch
+        // would name the wrong cause.
+        (None, _) => return fail(scope, format!("the realm being linked is gone ({import})")),
+        // Only reachable if the module went away between the resolver handing it
+        // over and this lookup; to the caller that reads the same as never
+        // having resolved it.
+        (_, None) => {
+            return fail(
+                scope,
+                format!("failed to resolve module specifier {import}"),
+            );
         }
-        g.clone()
     };
     Some(v8::Local::new(scope, &g))
 }
@@ -1916,8 +1997,16 @@ fn build_snapshot(code: &str, base: Option<Vec<u8>>, warmup: bool) -> Result<Vec
         {
             let cscope = &mut v8::ContextScope::new(scope, context);
             if !code.is_empty()
-                && let Err(e) =
-                    run_source(cscope, code, if warmup { "<warmup>" } else { "<snapshot>" })
+                && let Err(e) = run_source(
+                    cscope,
+                    code,
+                    if warmup { "<warmup>" } else { "<snapshot>" },
+                    // Snapshot/warmup code runs for its EFFECT (the heap it
+                    // leaves behind); nothing reads its completion value, so
+                    // don't marshal it — a bundle ending in an expression must
+                    // not fail the snapshot over a value no one wants.
+                    true,
+                )
             {
                 err = Some(match e {
                     VmError::Parse(m) | VmError::Runtime(m) => m,
@@ -2104,7 +2193,7 @@ impl Core {
         }
         if self.shared.lock().unwrap().disposed {
             return Err(Error::new(
-                ruby.exception_runtime_error(),
+                err_class(ruby, "DisposedError"),
                 "disposed context",
             ));
         }
@@ -2280,7 +2369,7 @@ impl Core {
                 // isolate (every later op refuses) rather than risk using it.
                 self.shared.lock().unwrap().disposed = true;
                 Err(Error::new(
-                    ruby.exception_runtime_error(),
+                    err_class(ruby, "InternalError"),
                     "internal error: operation panicked; the isolate has been disposed",
                 ))
             }
@@ -2302,7 +2391,7 @@ impl Core {
             }
             VmReply::Done(Err(e)) => Err(vm_err(ruby, e)),
             _ => Err(Error::new(
-                ruby.exception_runtime_error(),
+                err_class(ruby, "InternalError"),
                 "internal: unexpected reply kind",
             )),
         }
@@ -2402,7 +2491,7 @@ impl Core {
         let reply = self.run(ruby, Request::HeapStatistics)?;
         let VmReply::Heap(s) = reply else {
             return Err(Error::new(
-                ruby.exception_runtime_error(),
+                err_class(ruby, "InternalError"),
                 "internal: unexpected heap reply",
             ));
         };
@@ -2441,6 +2530,7 @@ impl Core {
         source: String,
         filename: String,
         timeout_ms: u64,
+        void: bool,
     ) -> Result<Value, Error> {
         let reply = self.run(
             ruby,
@@ -2449,6 +2539,7 @@ impl Core {
                 source,
                 filename,
                 timeout_ms,
+                void,
             },
         )?;
         self.reply_value(ruby, reply)
@@ -2576,7 +2667,7 @@ impl Core {
             VmReply::ModuleCompiled(Ok(cm)) => Ok(cm),
             VmReply::ModuleCompiled(Err(e)) => Err(vm_err(ruby, e)),
             _ => Err(Error::new(
-                ruby.exception_runtime_error(),
+                err_class(ruby, "InternalError"),
                 "internal: unexpected compile reply",
             )),
         }
@@ -2649,6 +2740,11 @@ impl Core {
         self.reply_value(ruby, reply)
     }
 
+    fn module_graph_async(&self, ruby: &Ruby, module_id: i32) -> Result<Value, Error> {
+        let reply = self.run(ruby, Request::ModuleGraphAsync { module_id })?;
+        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(|_| ())
@@ -2681,18 +2777,19 @@ impl Core {
             VmReply::ScriptCompiled(Ok(cs)) => Ok(cs),
             VmReply::ScriptCompiled(Err(e)) => Err(vm_err(ruby, e)),
             _ => Err(Error::new(
-                ruby.exception_runtime_error(),
+                err_class(ruby, "InternalError"),
                 "internal: unexpected compile reply",
             )),
         }
     }
 
-    fn run_script(&self, ruby: &Ruby, script_id: i32) -> Result<Value, Error> {
+    fn run_script(&self, ruby: &Ruby, script_id: i32, void: bool) -> Result<Value, Error> {
         let reply = self.run(
             ruby,
             Request::RunScript {
                 script_id,
                 timeout_ms: self.default_timeout_ms,
+                void,
             },
         )?;
         self.reply_value(ruby, reply)
@@ -2794,7 +2891,7 @@ impl Core {
             // and SEGV — refuse it, leaving the isolate usable.
             if self.depth.load(Ordering::SeqCst) != 0 {
                 return Err(Error::new(
-                    ruby.exception_runtime_error(),
+                    err_class(ruby, "Error"),
                     "RustyRacer: cannot dispose an isolate from within a running op or host callback",
                 ));
             }
@@ -2915,19 +3012,21 @@ impl Context {
         // id 0's lifetime is the isolate's; extras also track their own dispose.
         if self.disposed.load(Ordering::SeqCst) || self.core.is_disposed() {
             return Err(Error::new(
-                ruby.exception_runtime_error(),
+                err_class(ruby, "DisposedError"),
                 "disposed context",
             ));
         }
         Ok(())
     }
     // timeout_ms 0 = use the isolate's default; an explicit value overrides it.
+    // |void| discards the completion value instead of marshalling it.
     fn eval(
         ruby: &Ruby,
         rb_self: &Self,
         source: String,
         timeout_ms: u64,
         filename: String,
+        void: bool,
     ) -> Result<Value, Error> {
         rb_self.check_live(ruby)?;
         let timeout = if timeout_ms == 0 {
@@ -2937,7 +3036,7 @@ impl Context {
         };
         rb_self
             .core
-            .eval_t(ruby, rb_self.id, source, filename, timeout)
+            .eval_t(ruby, rb_self.id, source, filename, timeout, void)
     }
     fn call(ruby: &Ruby, rb_self: &Self, args: &[Value]) -> Result<Value, Error> {
         rb_self.check_live(ruby)?;
@@ -3112,7 +3211,7 @@ impl JsModule {
         // iso.dispose is a use-after-free.
         if self.disposed.load(Ordering::SeqCst) || self.core.is_disposed() {
             return Err(Error::new(
-                ruby.exception_runtime_error(),
+                err_class(ruby, "DisposedError"),
                 "disposed module",
             ));
         }
@@ -3140,6 +3239,19 @@ impl JsModule {
         rb_self.check_live(ruby)?;
         rb_self.core.module_status(ruby, rb_self.module_id)
     }
+    // True when top-level await appears anywhere in the module's LINKED import
+    // graph (v8::Module::IsGraphAsync) — a dependency's await counts, which is
+    // why no check on the source text alone can stand in for this. FALSE is the
+    // load-bearing answer: V8 guarantees the evaluation promise is settled, so
+    // #evaluate returning means the whole graph ran. True and it may have
+    // returned with the body still suspended, while #status reads :evaluated
+    // regardless (V8 folds its internal kEvaluatingAsync into kEvaluated).
+    // Raises RustyRacer::RuntimeError unless the module is instantiated: before
+    // linking there is no graph to walk.
+    fn graph_async(ruby: &Ruby, rb_self: &Self) -> Result<Value, Error> {
+        rb_self.check_live(ruby)?;
+        rb_self.core.module_graph_async(ruby, rb_self.module_id)
+    }
     // The bytecode cache produced at compile (produce_cache: true), as a binary
     // String, or nil. Persist it cross-process and pass back via cached_data:.
     fn cached_data(ruby: &Ruby, rb_self: &Self) -> Value {
@@ -3176,7 +3288,7 @@ impl Script {
         // Also refuse once the isolate is disposed (see JsModule::check_live).
         if self.disposed.load(Ordering::SeqCst) || self.core.is_disposed() {
             return Err(Error::new(
-                ruby.exception_runtime_error(),
+                err_class(ruby, "DisposedError"),
                 "disposed script",
             ));
         }
@@ -3186,7 +3298,13 @@ impl Script {
     // thrown exception is a RuntimeError; a timeout/stop a ScriptTerminatedError.
     fn run(ruby: &Ruby, rb_self: &Self) -> Result<Value, Error> {
         rb_self.check_live(ruby)?;
-        rb_self.core.run_script(ruby, rb_self.script_id)
+        rb_self.core.run_script(ruby, rb_self.script_id, false)
+    }
+    // Run it for its effect only, discarding the completion value (see
+    // Context#eval_void) — what a <script> tag does.
+    fn run_void(ruby: &Ruby, rb_self: &Self) -> Result<Value, Error> {
+        rb_self.check_live(ruby)?;
+        rb_self.core.run_script(ruby, rb_self.script_id, true)
     }
     fn cached_data(ruby: &Ruby, rb_self: &Self) -> Value {
         code_cache_value(ruby, rb_self.cached_data.as_ref())
@@ -3231,7 +3349,7 @@ fn code_cache_from_reply(ruby: &Ruby, reply: VmReply) -> Result<Option<Vec<u8>>,
         VmReply::CodeCache(Ok(bytes)) => Ok(bytes),
         VmReply::CodeCache(Err(e)) => Err(vm_err(ruby, e)),
         _ => Err(Error::new(
-            ruby.exception_runtime_error(),
+            err_class(ruby, "InternalError"),
             "internal: unexpected code-cache reply",
         )),
     }
@@ -3367,7 +3485,7 @@ fn resolve_module_via_ruby(
     })?;
     if !std::ptr::eq(Arc::as_ptr(&obj.core), core as *const Core) {
         return Err(Error::new(
-            ruby.exception_runtime_error(),
+            err_class(&ruby, "Error"),
             "module resolver returned a Module from a different Context",
         ));
     }
@@ -3407,8 +3525,9 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
 
     // A v8::Context (realm): eval/call/attach/compile_module.
     let context = module.define_class("Context", ruby.class_object())?;
-    // keyword-arg wrapper Context#eval(source, timeout_ms:, filename:) in lib.
-    context.define_method("_eval", method!(Context::eval, 3))?;
+    // Backs both keyword-arg wrappers in lib: Context#eval(source, timeout_ms:,
+    // filename:) and #eval_void, which differ only in the 4th arg (the void flag).
+    context.define_method("_eval", method!(Context::eval, 4))?;
     context.define_method("call", method!(Context::call, -1))?;
     context.define_method("call_void", method!(Context::call_void, -1))?;
     context.define_method("attach", method!(Context::attach, 2))?;
@@ -3424,6 +3543,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     // Classic compiled script: Context#compile -> #run / #cached_data.
     let script = module.define_class("Script", ruby.class_object())?;
     script.define_method("run", method!(Script::run, 0))?;
+    script.define_method("run_void", method!(Script::run_void, 0))?;
     script.define_method("cached_data", method!(Script::cached_data, 0))?;
     script.define_method("cache_rejected?", method!(Script::cache_rejected, 0))?;
     script.define_method("create_code_cache", method!(Script::create_code_cache, 0))?;
@@ -3444,6 +3564,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
     jsmodule.define_method("evaluate", method!(JsModule::evaluate, 0))?;
     jsmodule.define_method("namespace", method!(JsModule::namespace, 0))?;
     jsmodule.define_method("_status", method!(JsModule::status, 0))?;
+    jsmodule.define_method("graph_async?", method!(JsModule::graph_async, 0))?;
     jsmodule.define_method("cached_data", method!(JsModule::cached_data, 0))?;
     jsmodule.define_method("cache_rejected?", method!(JsModule::cache_rejected, 0))?;
     jsmodule.define_method("create_code_cache", method!(JsModule::create_code_cache, 0))?;

data/ext/rusty_racer/src/marshal.rs

@@ -149,7 +149,7 @@ fn js_container_id(
     // First sighting but too deep: truncate WITHOUT registering, so no later
     // Ref can target a container that was never emitted.
     if depth >= MAX_MARSHAL_DEPTH {
-        return Err(JsVal::Str(value.to_rust_string_lossy(scope)));
+        return Err(JsVal::Str(stringify(scope, value)));
     }
     let id = seen.next_id;
     seen.next_id += 1;
@@ -342,7 +342,7 @@ fn js_to_jsval_d(
                 let Some(key) = names.get_index(scope, i) else {
                     continue;
                 };
-                let key_str = key.to_rust_string_lossy(scope);
+                let key_str = stringify(scope, key);
                 let val = obj
                     .get(scope, key)
                     .unwrap_or_else(|| v8::undefined(scope).into());
@@ -350,8 +350,43 @@ fn js_to_jsval_d(
             }
             return JsVal::Obj { id, entries };
         }
+        // Enumeration THREW — a module namespace whose bindings aren't
+        // initialized yet, a Proxy with a hostile ownKeys trap. Falling through
+        // to the stringify below would hand the caller a plausible-looking
+        // "[object Object]" for an object we never actually read. Leave the
+        // pending exception alone instead and let the op's TryCatch report it —
+        // and give back the id, or a sibling Ref to this same object would point
+        // at a container that is never emitted.
+        unregister_container(seen, obj, id);
+        return JsVal::Undefined;
+    }
+    JsVal::Str(stringify(scope, value))
+}
+
+// The escape hatch for values with no structural representation — Function,
+// Date, RegExp, Symbol. to_rust_string_lossy is Value::ToString, which THROWS on
+// a Symbol, and a Symbol sitting anywhere in a graph (every React element has
+// one) would then leave a pending exception behind and fail the whole op over a
+// value that marshalled fine. to_detail_string is V8's no-side-effects renderer
+// and cannot throw, so Symbols go through it.
+fn stringify(scope: &mut v8::PinScope<'_, '_>, value: v8::Local<v8::Value>) -> String {
+    if value.is_symbol() {
+        return value
+            .to_detail_string(scope)
+            .map(|s| s.to_rust_string_lossy(scope))
+            .unwrap_or_default();
+    }
+    value.to_rust_string_lossy(scope)
+}
+
+// Undo js_container_id's registration for a container we end up NOT emitting.
+// The id is always the last one pushed to its bucket, since nothing else can
+// register while we are inside this object.
+fn unregister_container(seen: &mut JsSeen, obj: v8::Local<v8::Object>, id: u32) {
+    let hash = obj.get_identity_hash().get();
+    if let Some(bucket) = seen.map.get_mut(&hash) {
+        bucket.retain(|(_, existing)| *existing != id);
     }
-    JsVal::Str(value.to_rust_string_lossy(scope))
 }
 
 // Owned-by-value (not &JsVal): a JsVal::Bytes hands its Vec straight to V8's

data/ext/rusty_racer/src/ops.rs

@@ -18,6 +18,29 @@ use crate::istate;
 use crate::marshal::{JsVal, js_to_jsval, jsval_to_js};
 use crate::*;
 
+// Marshal an op's result, treating a throw on the way out as the op's outcome.
+// Marshalling RUNS JS — accessors, Proxy traps, toString — and an exception
+// raised there is as real as one from the script itself, but it lands after the
+// call has already succeeded, so nothing else looks at it: the TryCatch drops it
+// on unwind and the caller keeps a value that no longer means anything (an
+// object whose enumeration threw marshals to undefined). A macro rather than a
+// fn because the tc_scope! binding has no nameable type here.
+macro_rules! marshalled {
+    ($tc:expr, $value:expr) => {{
+        let tc = $tc;
+        let out = js_to_jsval(tc, $value);
+        let exc = tc.exception();
+        if exc.is_none() {
+            Ok(out)
+        } else if tc.has_terminated() {
+            Err(VmError::Terminated)
+        } else {
+            let stack = tc.stack_trace();
+            Err(capture_js_error(tc, exc, stack))
+        }
+    }};
+}
+
 // One VM operation, built by a magnus method and run inline by Core::run ->
 // service_request -> dispatch_one. |context_id| selects which realm the op runs
 // in: 0 = the main realm (Context's own globalThis, swappable by reset_realm),
@@ -28,6 +51,11 @@ pub(crate) enum Request {
         source: String,
         filename: String,
         timeout_ms: u64,
+        // void = don't marshal the completion value (see Call's |void|). A
+        // statement-list eval run for its EFFECT still has one — the last
+        // statement's value — and marshalling it can throw (an accessor, a
+        // Proxy trap) or walk a huge graph, for a value the caller discards.
+        void: bool,
     },
     // Resolve a dotted function path on globalThis and invoke it with marshalled
     // args (v8::Function::call), preserving the holder as `this`. Distinct from
@@ -104,6 +132,11 @@ pub(crate) enum Request {
     ModuleStatus {
         module_id: i32,
     },
+    // Whether top-level await appears anywhere in the module's linked import
+    // graph (v8::Module::IsGraphAsync), as a bool.
+    ModuleGraphAsync {
+        module_id: i32,
+    },
     DisposeModule {
         module_id: i32,
     },
@@ -118,10 +151,12 @@ pub(crate) enum Request {
         produce_cache: bool,
         eager: bool,
     },
-    // Bind the script to its context and run it; returns the completion value.
+    // Bind the script to its context and run it; returns the completion value
+    // (unless |void| — see Eval).
     RunScript {
         script_id: i32,
         timeout_ms: u64,
+        void: bool,
     },
     DisposeScript {
         script_id: i32,
@@ -192,6 +227,7 @@ pub(crate) fn run_source(
     scope: &mut v8::PinScope<'_, '_>,
     source: &str,
     filename: &str,
+    void: bool,
 ) -> Result<JsVal, VmError> {
     v8::tc_scope!(let tc, scope);
     // Compile and run as distinct phases so a compile failure maps to
@@ -224,7 +260,8 @@ pub(crate) fn run_source(
         }
     };
     match script.run(tc) {
-        Some(value) => Ok(js_to_jsval(tc, value)),
+        Some(_) if void => Ok(JsVal::Undefined),
+        Some(value) => marshalled!(tc, value),
         None if tc.has_terminated() => Err(VmError::Terminated),
         None => {
             let exc = tc.exception();
@@ -279,7 +316,7 @@ fn call_function(
     match func.call(tc, recv, &argv) {
         // void: skip marshalling the return so a huge/cyclic result is never walked.
         Some(_) if void => Ok(JsVal::Undefined),
-        Some(value) => Ok(js_to_jsval(tc, value)),
+        Some(value) => marshalled!(tc, value),
         None if tc.has_terminated() => Err(VmError::Terminated),
         None => {
             let exc = tc.exception();
@@ -396,6 +433,7 @@ fn request_realm(state: &IsolateState, request: &Request) -> Option<i32> {
         | Request::CreateContext
         | Request::DisposeContext { .. }
         | Request::ModuleStatus { .. }
+        | Request::ModuleGraphAsync { .. }
         | Request::DisposeModule { .. }
         | Request::DisposeScript { .. }
         | Request::ScriptCodeCache { .. }
@@ -419,7 +457,10 @@ fn dispatch_one(
             source,
             filename,
             timeout_ms,
-        } => op_eval(scope, context_id, source, filename, timeout_ms, outermost),
+            void,
+        } => op_eval(
+            scope, context_id, source, filename, timeout_ms, void, outermost,
+        ),
         Request::Call {
             context_id,
             name,
@@ -465,6 +506,7 @@ fn dispatch_one(
         } => op_evaluate_module(scope, module_id, timeout_ms, outermost),
         Request::ModuleNamespace { module_id } => op_module_namespace(scope, module_id),
         Request::ModuleStatus { module_id } => op_module_status(scope, module_id),
+        Request::ModuleGraphAsync { module_id } => op_module_graph_async(scope, module_id),
         Request::DisposeModule { module_id } => op_dispose_module(scope, module_id),
         Request::CompileScript {
             context_id,
@@ -485,7 +527,8 @@ fn dispatch_one(
         Request::RunScript {
             script_id,
             timeout_ms,
-        } => op_run_script(scope, script_id, timeout_ms, outermost),
+            void,
+        } => op_run_script(scope, script_id, timeout_ms, void, outermost),
         Request::DisposeScript { script_id } => op_dispose_script(scope, script_id),
         // Serialize the script's CURRENT compile state. The stored handle is
         // the UnboundScript, which V8 fills in with inner-function bytecode as
@@ -528,12 +571,14 @@ fn op_low_memory_notification(scope: &mut v8::PinScope<'_, '_, ()>) -> VmReply {
     VmReply::Done(Ok(JsVal::Undefined))
 }
 
+#[allow(clippy::too_many_arguments)]
 fn op_eval(
     scope: &mut v8::PinScope<'_, '_, ()>,
     context_id: i32,
     source: String,
     filename: String,
     timeout_ms: u64,
+    void: bool,
     outermost: bool,
 ) -> VmReply {
     let outcome = run_js_bracketed(scope, outermost, timeout_ms, "eval", |scope, outermost| {
@@ -542,7 +587,7 @@ fn op_eval(
             Some(ctx) => {
                 let context = v8::Local::new(scope, &ctx);
                 let scope = &mut v8::ContextScope::new(scope, context);
-                let out = run_source(scope, &source, &filename);
+                let out = run_source(scope, &source, &filename, void);
                 auto_drain(scope, outermost);
                 (true, out)
             }
@@ -1065,6 +1110,20 @@ fn op_evaluate_module(
     VmReply::Done(outcome)
 }
 
+// get_module_namespace and is_graph_async both CHECK-abort (a release check, so
+// it kills the process) below Instantiated, so both ask this first. Everything
+// from Instantiated up is admissible, Errored included: a module that fails to
+// LINK is reset to Uninstantiated by V8's ResetGraph, so Errored can only mean
+// "linked, then evaluation failed" — the graph is still there to read.
+fn require_instantiated(module: v8::Local<v8::Module>, what: &str) -> Result<(), VmError> {
+    match module.get_status() {
+        v8::ModuleStatus::Uninstantiated | v8::ModuleStatus::Instantiating => Err(
+            VmError::Runtime(format!("module must be instantiated before {what}")),
+        ),
+        _ => Ok(()),
+    }
+}
+
 fn op_module_namespace(scope: &mut v8::PinScope<'_, '_, ()>, module_id: i32) -> VmReply {
     let handle = module_handle(istate!(scope), module_id);
     let outcome = match handle {
@@ -1075,15 +1134,27 @@ fn op_module_namespace(scope: &mut v8::PinScope<'_, '_, ()>, module_id: i32) ->
                 let context = v8::Local::new(scope, &cx);
                 let scope = &mut v8::ContextScope::new(scope, context);
                 let module = v8::Local::new(scope, &g);
-                // get_module_namespace CHECK-aborts unless the module
-                // is at least Instantiated.
-                match module.get_status() {
-                    v8::ModuleStatus::Uninstantiated | v8::ModuleStatus::Instantiating => Err(
-                        VmError::Runtime("module must be instantiated before namespace".into()),
-                    ),
-                    _ => {
-                        let ns = module.get_module_namespace();
-                        Ok(js_to_jsval(scope, ns))
+                // An errored module's namespace is unreadable — its bindings
+                // never initialized — and the useful answer is WHY it errored,
+                // the same one instantiate and evaluate give.
+                if module.get_status() == v8::ModuleStatus::Errored {
+                    Err(VmError::JsError {
+                        message: module.get_exception().to_rust_string_lossy(scope),
+                        backtrace: vec![],
+                    })
+                } else {
+                    match require_instantiated(module, "namespace") {
+                        Err(e) => Err(e),
+                        Ok(()) => {
+                            let ns = module.get_module_namespace();
+                            // Reading the namespace RUNS JS: every export is an
+                            // accessor, and one whose binding is still
+                            // uninitialized throws. Unwatched, that throw made
+                            // enumeration fail and the caller silently got the
+                            // stringified object in place of their exports.
+                            v8::tc_scope!(let tc, scope);
+                            marshalled!(tc, ns)
+                        }
                     }
                 }
             }
@@ -1112,6 +1183,26 @@ fn op_module_status(scope: &mut v8::PinScope<'_, '_, ()>, module_id: i32) -> VmR
     VmReply::Done(outcome)
 }
 
+// Does top-level await appear anywhere in this module's import graph? V8 walks
+// the linked graph from here, so an `await` in a dependency counts too — which
+// is why no amount of looking at one source text can answer it, and why it needs
+// an instantiated module: before linking there is no graph to walk. What V8
+// guarantees is the false case — "if IsGraphAsync() is false, the returned
+// Promise is settled" — i.e. false means #evaluate ran the whole graph to
+// completion. No context is entered: the walk reads module slots, runs no JS.
+fn op_module_graph_async(scope: &mut v8::PinScope<'_, '_, ()>, module_id: i32) -> VmReply {
+    let handle = module_handle(istate!(scope), module_id);
+    let outcome = match handle {
+        None => Err(VmError::Runtime("unknown module".into())),
+        Some((g, _cid)) => {
+            let module = v8::Local::new(scope, &g);
+            require_instantiated(module, "graph_async?")
+                .map(|()| JsVal::Bool(module.is_graph_async()))
+        }
+    };
+    VmReply::Done(outcome)
+}
+
 fn op_dispose_module(scope: &mut v8::PinScope<'_, '_, ()>, module_id: i32) -> VmReply {
     let m = &mut istate!(scope).modules;
     m.by_id.remove(&module_id);
@@ -1202,6 +1293,7 @@ fn op_run_script(
     scope: &mut v8::PinScope<'_, '_, ()>,
     script_id: i32,
     timeout_ms: u64,
+    void: bool,
     outermost: bool,
 ) -> VmReply {
     let outcome = run_js_bracketed(
@@ -1226,7 +1318,8 @@ fn op_run_script(
                         let out = {
                             v8::tc_scope!(let tc, scope);
                             match script.run(tc) {
-                                Some(value) => Ok(js_to_jsval(tc, value)),
+                                Some(_) if void => Ok(JsVal::Undefined),
+                                Some(value) => marshalled!(tc, value),
                                 None if tc.has_terminated() => Err(VmError::Terminated),
                                 None => {
                                     let exc = tc.exception();

data/lib/rusty_racer/execjs.rb

@@ -35,9 +35,15 @@ module RustyRacer
         # ExecJS guarantees a bare global (no browser/Node ambient): V8 installs a
         # default `console`, so drop it to match the contract (consumers attach
         # their own if needed), exactly as the mini_racer runtime does.
-        @context.eval('delete globalThis.console')
+        @context.eval_void('delete globalThis.console')
         source = encode(source)
-        translate { @context.eval(source, filename: LOCATION) } if /\S/.match?(source)
+        # eval_void: a bundle is run to POPULATE the context, and its completion
+        # value — the last thing a UMD wrapper happened to evaluate — is nobody's
+        # answer. Marshalling it would walk the whole exports graph on every
+        # context creation, and a lazy/hostile property there would fail the
+        # constructor over a value ExecJS discards. #exec/#eval below must NOT
+        # use it: they read the JSON their wrapper returns.
+        translate { @context.eval_void(source, filename: LOCATION) } if /\S/.match?(source)
       end
 
       # Run statements in a function body and return what they `return` (nil when

data/lib/rusty_racer/version.rb

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

data/lib/rusty_racer.rb

@@ -42,6 +42,19 @@ module RustyRacer
   class SnapshotError < Error; end
   class PlatformAlreadyInitialized < Error; end
 
+  # Raised when a disposed Isolate, Context, Module or Script is used — or one
+  # whose Isolate has been disposed, which takes everything it handed out with
+  # it. Disposal is deliberate, so this says "you used it after you released
+  # it", not "something went wrong".
+  class DisposedError < Error; end
+
+  # A broken invariant inside the binding rather than anything the caller did:
+  # an unexpected reply kind, or an operation that panicked. Reaching one is a
+  # bug in rusty_racer and worth reporting. It exists so that EVERY error the
+  # extension raises is a RustyRacer::Error, and one rescue can cover the
+  # library.
+  class InternalError < Error; end
+
   # Raised when an Isolate (or a Context/Module/Script it handed out) is used
   # from a thread other than the one that created it. An isolate is
   # thread-confined: every operation must run on its owner thread. The lone
@@ -99,7 +112,18 @@ module RustyRacer
     # `timeout_ms` (0 = the isolate default) caps this eval; `filename` names the
     # script in stack traces and parse-error locations.
     def eval(source, timeout_ms: 0, filename: '<eval>')
-      _eval(source, timeout_ms, filename)
+      _eval(source, timeout_ms, filename, false)
+    end
+
+    # Run `source` for its EFFECT and return nil, without marshalling its
+    # completion value — the counterpart of #call_void, and what a <script> tag
+    # does. Worth reaching for whenever the value is incidental: a statement
+    # list still has one (its last statement's), and marshalling reads the
+    # value, which runs JS — a getter or a Proxy trap can throw, failing an eval
+    # whose writes all landed. `globalThis.win = someProxy` is the shape that
+    # bites.
+    def eval_void(source, timeout_ms: 0, filename: '<eval>')
+      _eval(source, timeout_ms, filename, true)
     end
 
     # Compile a classic <script>; returns a RustyRacer::Script to #run.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rusty_racer
 version: !ruby/object:Gem::Version
-  version: 0.1.16
+  version: 0.2.1
 platform: ruby
 authors:
 - Keita Urashima
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-07-28 00:00:00.000000000 Z
+date: 2026-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rb_sys