rusty_racer 0.2.7 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 214a3eb41745b4ed7c93662fa1cc1e1ecd11bc4678d5633eeab9a2075f5b4965
-  data.tar.gz: 87d473be7421ac6ff8d2c5ef7d2e5039ab75987660c313a37916d3f81def2477
+  metadata.gz: 6eedc8d154897325a2990e5ed6999a368b7c81c64528d5d406ed469e5d808fc4
+  data.tar.gz: f0c356c5b22a4574323e7efe73c56bd07267d5428438d22dadf2c4a08953b468
 SHA512:
-  metadata.gz: 8bd2a0dbfd742b01ceb21447a7028401362d3f9cf55ed449e1eae66aae88fa020c9a80edcdd49e606395880d9c54e4a3d3e8af4b20449387ab6246a234fcd6f6
-  data.tar.gz: 0147def7b482ce78b420bfff341f5575a045ba806c1ea853ad3d24bbe2557735a2e672ed9a1510da8727ce9ae0f01ce7409460d8362b6819f3cc2cc30bffbbd8
+  metadata.gz: 02acd6e295f14544a9f146f0b916ac1ac585b63634bb12c353d39059dc7ffef50337e76cd81c318463060c2e8f901a19667f384cbd1967ed776290dfd1d7c0cb
+  data.tar.gz: bc2513ed51e0a7ed2c45bc4c8cc85a051a7d83f9d1cdc56675cc2e1a3fcfd915c7b77bede14f91ac10e475d877e43563cea38c734d5cab36a2be6b806200312c

data/CHANGELOG.md

@@ -1,5 +1,38 @@
 # Changelog
 
+## 0.2.8
+
+### Added
+
+- A **host object** per realm: an object with no prototype that no global
+  holds (its global keeps it under a V8 private key), for the host and the
+  realm's own bindings to share where a page's script can neither read, call nor
+  replace what they put there. Every path the host names starts there when it
+  begins with `@`: `Context#attach('@fetch', proc)` / `#attach_many` put a host
+  function there (intermediates with no prototype, every property defined, not
+  assigned), `#function('@steps.query')` / `#call` / `#call_void` find one
+  there, `Module#evaluate(report: '@reportError')` reports to one there, and
+  `Isolate.new(host_namespace: '@RustyRacer')` installs rusty_racer's own
+  functions (`contextGlobal`, `contextOf`, `drainMicrotasks`, …) there instead
+  of on the global. `RustyRacer::HOST_OBJECT`, as an argument (or a host
+  function's result) crossing into JS, is the realm's host object — how the
+  bindings are handed it, and the realm's host object crosses back into Ruby as
+  `HOST_OBJECT`; an embedder linking rusty_racer as a library reaches it
+  natively with `rusty_racer::host_object(scope)`, from its realm init hook.
+  An `@` path is walked through own properties alone, so nothing a page put on
+  a prototype sees or answers the walk. A namespace on the host object has
+  `hostObjectOf(id)` besides: another realm's host object, for one realm's
+  bindings to reach another's. Made as a realm first uses it, made anew with the
+  realm by `reset`.
+
+### Changed
+
+- A path beginning with `@` no longer names a property of the global whose name
+  begins with `@` (`globalThis["@x"]`): it names the host object's.
+- `Module#evaluate(report:)` looks the reporter up as before — one property,
+  dots and all — on the global, or, for an `@` path, as `Context#function` finds
+  it on the host object.
+
 ## 0.2.7
 
 ### Changed

data/README.md

@@ -123,6 +123,62 @@ realm (`frames[0].fn` in an embedder whose realms see each other) holds that
 realm's function for as long as the handle's own realm lives, as any reference
 kept there would.
 
+### The host object
+
+An embedder that runs a page's script beside its own bindings wants the host's
+functions where the bindings can call them and the page can't. Every realm has a
+**host object** for that: an object of the realm with no prototype, which no
+global holds — the global keeps it under a V8 private key, which no script can
+name. A path the host names that begins with `@` starts there instead of at
+`globalThis`:
+
+```ruby
+# rusty_racer's own functions (contextGlobal, contextOf, drainMicrotasks, …)
+# there too, rather than on a global
+iso = RustyRacer::Isolate.new(host_namespace: "@RustyRacer")
+ctx = iso.context
+
+# Host functions the page never sees: no global, nothing to read, call or replace.
+ctx.attach("@fetch", ->(url) { fetch(url) })
+ctx.attach_many("@net.open" => open_proc, "@net.close" => close_proc)
+
+# The bindings are handed the object as an argument — HOST_OBJECT crosses into
+# JS as the realm's host object — and keep it in a closure or a module binding.
+ctx.call("installBindings", RustyRacer::HOST_OBJECT)
+
+# What they put there, the host calls by its path, with no global name.
+query = ctx.function("@steps.query")  # host.steps.query, `this` = host.steps
+query.call("#main")
+ctx.call("@steps.flush")
+mod.evaluate(report: "@reportError")  # Module#evaluate's reporter, too
+```
+
+An `@` path is walked through **own** properties alone: the intermediates an
+`@` attach makes (`@net` above) have no prototype either, every property it
+makes is *defined*, and a segment an object lacks reads as missing rather than
+off its prototype — so no accessor a page put on `Object.prototype` or
+`Function.prototype` sees the walk, takes the host's function, or hands the host
+one of its own. A `Module#evaluate(report:)` `@` path is walked the same way.
+
+Which realm's: each realm has its own, made as it is first used, and made anew
+with the realm by `reset` (what was attached there goes as a global's does).
+`HOST_OBJECT` is the host object of the realm the operation runs in — a
+Context's, a `Function` handle's (whatever realm the function it calls is of),
+or, as a host function's result, the realm that host function was attached to —
+and that realm's host object crosses back into Ruby as `HOST_OBJECT`; another
+realm's reads as a plain object. With `host_namespace: "@…"` the namespace has
+one member more, `hostObjectOf(id)`: realm `id`'s host object, for one realm's
+bindings to reach another's (a namespace on the global never has it).
+
+Hand it over before any script of the page's runs: `call` reaches the bindings
+by a global name, which a page could otherwise have replaced — and have the
+bindings delete that name as they take it. An embedder linking rusty_racer as a
+library reaches it natively with `rusty_racer::host_object(scope)` instead —
+from its realm init hook, say, to hand it to bindings baked into a snapshot
+before any script runs. The object has no prototype, so V8 keeps it as a
+dictionary: bindings that call through it in a hot loop do better to keep the
+functions they read off it.
+
 ### Releasing handles
 
 A `Function`, `Script` or `Module` handle is released when it is `#dispose`d —

data/ext/rusty_racer/Cargo.toml

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

data/ext/rusty_racer/src/lib.rs

@@ -1027,6 +1027,9 @@ struct V8State {
     retiring: Vec<(v8::Global<v8::Context>, v8::UniqueRef<v8::MicrotaskQueue>)>,
     next_context_id: i32,
     host_namespace: Option<String>,
+    // The private key every realm's global holds its host object under
+    // (host_object_key), once something has asked for one.
+    host_key: Option<v8::Global<v8::Private>>,
     // One security token shared by every realm of this isolate: the
     // embedder's frames are same-origin, so cross-context access (e.g.
     // NS.contextGlobal) must pass V8's access checks, which compare the
@@ -1998,6 +2001,30 @@ fn context_global(
     }
 }
 
+// NS.hostObjectOf(id) -> the host object of context |id| (host_object), made
+// there if it has none yet — for one realm's bindings to reach another's, as
+// contextGlobal reaches its global. Only on a namespace that is itself on the
+// host object (`host_namespace: '@…'`): a namespace on the global would hand
+// every realm's host object to any script. Throws on an unknown/disposed id.
+fn host_object_of(
+    scope: &mut v8::PinScope<'_, '_>,
+    args: v8::FunctionCallbackArguments<'_>,
+    mut rv: v8::ReturnValue<'_, v8::Value>,
+) {
+    let Some(id) = args.get(0).int32_value(scope) else {
+        throw_js_error(scope, "hostObjectOf expects a context id");
+        return;
+    };
+    match context_for(istate!(scope), id) {
+        Some(g) => {
+            let context = v8::Local::new(scope, &g);
+            let scope = &mut v8::ContextScope::new(scope, context);
+            rv.set(host_object(scope).into());
+        }
+        None => throw_js_error(scope, &format!("unknown context {id}")),
+    }
+}
+
 // NS.contextOf(value) -> the id of the context |value| was created in, or
 // undefined for primitives and for objects whose context is no longer a live
 // realm (e.g. it was reset away). Lets the embedder attribute a function or
@@ -2269,6 +2296,97 @@ pub fn set_realm_init_hook(hook: RealmInitHook) {
     let _ = REALM_INIT_HOOK.set(hook);
 }
 
+// The HOST OBJECT of the realm |scope| has entered: an object of the realm's,
+// with no prototype, that no property of any global holds — the realm's global
+// keeps it under a private key, which no script can name — so the host and the
+// realm's own bindings share it and a page's script neither reads, calls nor
+// replaces what it holds. A path that begins `@` starts from it rather than from
+// the global: `attach('@x.y', proc)` puts a host function there,
+// `Context#function('@x.y')` / `#call('@x.y')` find one there, `host_namespace:
+// '@NS'` installs the namespace there, `evaluate(report: '@r')` reports to one
+// there; and `RustyRacer::HOST_OBJECT`, as an argument crossing into JS, is this
+// object — how the bindings are handed it, where an embedder's realm init hook
+// (which calls this) does not hand it over itself. Made as it is first asked
+// for, so a realm that never uses it carries none.
+//
+// The private key lives with the global, so the object goes with its realm: a
+// reset or a disposal needs nothing of it, and no context slot is used (see
+// id_of_context for why realms keep none).
+pub fn host_object<'s>(scope: &mut v8::PinScope<'s, '_>) -> v8::Local<'s, v8::Object> {
+    if let Some(object) = existing_host_object(scope) {
+        return object;
+    }
+    let object = null_prototype_object(scope);
+    let global = scope.get_current_context().global(scope);
+    let key = host_object_key(scope);
+    global.set_private(scope, key, object.into());
+    object
+}
+
+// The current realm's host object if it has made one yet, without making it.
+pub(crate) fn existing_host_object<'s>(
+    scope: &mut v8::PinScope<'s, '_>,
+) -> Option<v8::Local<'s, v8::Object>> {
+    let global = scope.get_current_context().global(scope);
+    let key = host_object_key(scope);
+    v8::Local::<v8::Object>::try_from(global.get_private(scope, key)?).ok()
+}
+
+// The private key a global holds its host object under: an API private, so it
+// is one key per isolate whoever asks — the binding's own isolates keep it
+// (V8State::host_key) rather than looking it up by name at every use.
+fn host_object_key<'s>(scope: &mut v8::PinScope<'s, '_>) -> v8::Local<'s, v8::Private> {
+    let kept = scope
+        .get_slot::<IsolateState>()
+        .and_then(|state| state.realms.host_key.clone());
+    if let Some(key) = kept {
+        return v8::Local::new(scope, &key);
+    }
+    let name = v8::String::new(scope, "rusty_racer:host_object").expect("a short string");
+    let key = v8::Private::for_api(scope, Some(name));
+    let kept = v8::Global::new(scope, key);
+    if let Some(state) = scope.get_slot_mut::<IsolateState>() {
+        state.realms.host_key = Some(kept);
+    }
+    key
+}
+
+// An object of the current realm with no prototype: a read of a name it lacks
+// ends there, never in an Object.prototype a page may have put a getter on.
+fn null_prototype_object<'s>(scope: &mut v8::PinScope<'s, '_>) -> v8::Local<'s, v8::Object> {
+    let null = v8::null(scope).into();
+    v8::Object::with_prototype_and_properties(scope, null, &[], &[])
+}
+
+// Where a path starts, and the rest of it: `@a.b` is the host object's `a.b`, any
+// other path the global's.
+pub(crate) fn path_root<'s, 'p>(
+    scope: &mut v8::PinScope<'s, '_>,
+    path: &'p str,
+) -> (v8::Local<'s, v8::Object>, &'p str, bool) {
+    match path.strip_prefix('@') {
+        Some(rest) => (host_object(scope), rest, true),
+        None => (scope.get_current_context().global(scope), path, false),
+    }
+}
+
+// One segment of a path read off |holder|: an ordinary [[Get]] on the global's
+// side; on the host object's (|hidden|), its OWN property alone — undefined
+// where it has none, so no prototype of an object along the way (Object's, a
+// function's) is ever consulted, and a getter a page put there neither sees
+// the walk nor hands it an object of the page's. None when the read threw.
+pub(crate) fn path_segment<'s>(
+    scope: &mut v8::PinScope<'s, '_>,
+    holder: v8::Local<v8::Object>,
+    key: v8::Local<v8::String>,
+    hidden: bool,
+) -> Option<v8::Local<'s, v8::Value>> {
+    if hidden && !holder.has_own_property(scope, key.into())? {
+        return Some(v8::undefined(scope).into());
+    }
+    holder.get(scope, key.into())
+}
+
 fn new_realm(
     scope: &mut v8::PinScope<'_, '_, ()>,
     context_id: i32,
@@ -2373,9 +2491,12 @@ fn flush_retiring(scope: &mut v8::PinScope<'_, '_, ()>) {
     drop(retiring);
 }
 
-// Inject globalThis.<name> = { drainMicrotasks } into a context. Re-run on
-// reset_realm so the fresh realm keeps the namespace. Takes a scope (not the
-// isolate) so service_request can call it from nested servicing too.
+// Inject globalThis.<name> = { drainMicrotasks, ... } into a context — or, for
+// an `@name`, put it on the realm's host object instead, with no prototype, where
+// only the host and the realm's bindings reach it, and with one member more
+// there: hostObjectOf(id), another realm's host object. Re-run on reset_realm so the
+// fresh realm keeps the namespace. Takes a scope (not the isolate) so
+// service_request can call it from nested servicing too.
 fn install_host_namespace(
     scope: &mut v8::PinScope<'_, '_, ()>,
     ctx: &v8::Global<v8::Context>,
@@ -2384,7 +2505,12 @@ fn install_host_namespace(
     v8::scope!(let scope, &mut *scope);
     let context = v8::Local::new(scope, ctx);
     let scope = &mut v8::ContextScope::new(scope, context);
-    let ns = v8::Object::new(scope);
+    let (holder, name, hidden) = path_root(scope, name);
+    let ns = if hidden {
+        null_prototype_object(scope)
+    } else {
+        v8::Object::new(scope)
+    };
     let members: [(&str, Option<v8::Local<v8::Function>>); 9] = [
         (
             "drainMicrotasks",
@@ -2402,40 +2528,58 @@ fn install_host_namespace(
         ("shareIn", v8::Function::new(scope, share_in)),
         ("transferDrop", v8::Function::new(scope, transfer_drop)),
     ];
-    for (member, function) in members {
+    let hidden_members: &[(&str, Option<v8::Local<v8::Function>>)] = if hidden {
+        &[("hostObjectOf", v8::Function::new(scope, host_object_of))]
+    } else {
+        &[]
+    };
+    for (member, function) in members.into_iter().chain(hidden_members.iter().copied()) {
         if let (Some(f), Some(k)) = (function, v8::String::new(scope, member)) {
             ns.create_data_property(scope, k.into(), f.into());
         }
     }
     if let Some(key) = v8::String::new(scope, name) {
-        let global = context.global(scope);
-        global.create_data_property(scope, key.into(), ns.into());
+        holder.create_data_property(scope, key.into(), ns.into());
     }
 }
 
 // Set |function| at the dotted property path |name| on the global, creating
 // intermediate plain objects as needed — so attach("MiniRacer.foo", ...) lands
 // under the namespace whether or not globalThis.MiniRacer already exists, while
-// a bare "foo" still attaches on the global.
+// a bare "foo" still attaches on the global. An `@` path lands on the realm's
+// host object instead: walked through own properties alone (path_segment), its
+// missing intermediates made with no prototype, and every property DEFINED
+// there — nothing a page's script left on a prototype runs or is written to.
 fn attach_at_path(
     scope: &mut v8::PinScope<'_, '_>,
-    context: v8::Local<v8::Context>,
     name: &str,
     function: v8::Local<v8::Function>,
 ) -> Result<JsVal, VmError> {
-    let mut parts: Vec<&str> = name.split('.').collect();
+    let (mut holder, path, hidden) = path_root(scope, name);
+    let mut parts: Vec<&str> = path.split('.').collect();
     let leaf = parts
         .pop()
         .filter(|s| !s.is_empty())
         .ok_or_else(|| VmError::Runtime(format!("invalid attach name `{name}`")))?;
-    let mut holder = context.global(scope);
+    // Make a property of |holder|: defined on the host object's side, assigned on
+    // the global's (as attach always has, so an accessor there still sees it).
+    let put = |scope: &mut v8::PinScope<'_, '_>,
+               holder: v8::Local<v8::Object>,
+               key: v8::Local<v8::String>,
+               value: v8::Local<v8::Value>| {
+        if hidden {
+            holder.create_data_property(scope, key.into(), value)
+        } else {
+            holder.set(scope, key.into(), value)
+        }
+    };
     for part in parts {
         if part.is_empty() {
             return Err(VmError::Runtime(format!("invalid attach name `{name}`")));
         }
         let key = v8::String::new(scope, part)
             .ok_or_else(|| VmError::Runtime("name too large".into()))?;
-        holder = match holder.get(scope, key.into()) {
+        holder = match path_segment(scope, holder, key, hidden) {
             Some(v) if v.is_object() => v8::Local::<v8::Object>::try_from(v).unwrap(),
             // Don't clobber an existing non-object (e.g. a primitive global that
             // collides with the namespace name) — fail loudly instead.
@@ -2445,8 +2589,12 @@ fn attach_at_path(
                 )));
             }
             _ => {
-                let obj = v8::Object::new(scope);
-                if holder.set(scope, key.into(), obj.into()) != Some(true) {
+                let obj = if hidden {
+                    null_prototype_object(scope)
+                } else {
+                    v8::Object::new(scope)
+                };
+                if put(scope, holder, key, obj.into()) != Some(true) {
                     return Err(VmError::Runtime(format!(
                         "`{name}`: cannot create `{part}`"
                     )));
@@ -2457,7 +2605,7 @@ fn attach_at_path(
     }
     let key =
         v8::String::new(scope, leaf).ok_or_else(|| VmError::Runtime("name too large".into()))?;
-    if holder.set(scope, key.into(), function.into()) != Some(true) {
+    if put(scope, holder, key, function.into()) != Some(true) {
         return Err(VmError::Runtime(format!(
             "`{name}`: target is not writable/extensible"
         )));
@@ -4346,6 +4494,8 @@ fn init(ruby: &Ruby) -> Result<(), Error> {
 // same surface.
 pub fn install_classes(ruby: &Ruby) -> Result<(), Error> {
     let module = ruby.define_module("RustyRacer")?;
+    // The argument that crosses into JS as the realm's host object (host_object).
+    module.const_set("HOST_OBJECT", ruby.get_inner(&marshal::HOST_OBJECT))?;
 
     // The isolate (VM) + its isolate-level ops; hands out Contexts.
     let isolate = module.define_class("Isolate", ruby.class_object())?;

data/ext/rusty_racer/src/marshal.rs

@@ -9,7 +9,7 @@ use std::collections::HashMap;
 use std::ffi::c_void;
 
 use magnus::rb_sys::{AsRawValue, FromRawValue};
-use magnus::value::ReprValue;
+use magnus::value::{Lazy, ReprValue};
 use magnus::{
     Error, ExceptionClass, IntoValue, RArray, RHash, RString, Ruby, TryConvert, Value, prelude::*,
 };
@@ -78,6 +78,10 @@ pub(crate) enum JsVal {
     // Back-reference to an already-emitted container (preserves identity; makes
     // cycles representable instead of truncating at a depth cap).
     Ref(u32),
+    // Ruby RustyRacer::HOST_OBJECT <-> a realm's host object (`crate::host_object`):
+    // that of the realm an op runs in — a Context's, a Function handle's, a host
+    // function's own — both ways. Another realm's host object reads as an object.
+    HostObject,
 }
 
 // Cycles and sharing are handled by the Ref table (see JsVal::Ref), so this is
@@ -340,6 +344,14 @@ fn js_to_jsval_d(
     // their toString (the spike's primitive escape hatch).
     if value.is_object() && !value.is_function() {
         let obj = v8::Local::<v8::Object>::try_from(value).unwrap();
+        // The realm's own host object crosses back as RustyRacer::HOST_OBJECT,
+        // not as a Hash of what the bindings keep there. Only an object with no
+        // prototype can be it, which keeps the private read off the common path.
+        if obj.get_prototype(scope).is_some_and(|p| p.is_null())
+            && crate::existing_host_object(scope).is_some_and(|host| host == obj)
+        {
+            return JsVal::HostObject;
+        }
         let id = match js_container_id(scope, seen, value, obj, depth) {
             Ok(id) => id,
             Err(jsval) => return jsval,
@@ -539,6 +551,7 @@ fn jsval_to_js_d<'s>(
         JsVal::Ref(id) => built
             .get(scope, id)
             .unwrap_or_else(|| v8::undefined(scope).into()),
+        JsVal::HostObject => crate::host_object(scope).into(),
     }
 }
 
@@ -669,9 +682,32 @@ fn jsval_to_ruby_d(
             .get(id)
             .copied()
             .unwrap_or_else(|| ruby.qnil().as_value()),
+        JsVal::HostObject => ruby.get_inner(&HOST_OBJECT),
     })
 }
 
+// RustyRacer::HOST_OBJECT: the Ruby value that stands for a realm's host object
+// as it crosses into JS (JsVal::HostObject). The one instance of
+// RustyRacer::HostObject, whose allocator is undefined once it is made, so no
+// other can be; marked for good (Lazy), so it never moves either.
+fn host_object_inspect(_host: Value) -> &'static str {
+    "RustyRacer::HOST_OBJECT"
+}
+
+pub(crate) static HOST_OBJECT: Lazy<Value> = Lazy::new(|ruby| {
+    let class = ruby
+        .define_module("RustyRacer")
+        .and_then(|module| module.define_class("HostObject", ruby.class_object()))
+        .expect("RustyRacer::HostObject is definable");
+    class
+        .define_method("inspect", magnus::method!(host_object_inspect, 0))
+        .expect("HostObject#inspect is definable");
+    let host: Value = class.new_instance(()).expect("a HostObject is allocatable");
+    host.freeze();
+    class.undef_default_alloc_func();
+    host
+});
+
 // A Ruby String marshalled by its encoding TAG (the tag is the type):
 //   - ASCII-8BIT (binary) -> JsVal::Bytes (a JS Uint8Array);
 //   - any text encoding   -> JsVal::Str (UTF-8). Already-UTF-8 text is taken
@@ -842,6 +878,11 @@ fn ruby_to_jsval_d(val: Value, seen: &mut RbSeen, depth: u32) -> Result<JsVal, E
     }
     // What only a class, or a conversion method, can say.
     //
+    // RustyRacer::HOST_OBJECT -> the realm's host object, by identity.
+    if val.as_raw() == ruby.get_inner(&HOST_OBJECT).as_raw() {
+        return Ok(JsVal::HostObject);
+    }
+    //
     // Ruby Time -> JS Date. Before the Numeric fallback: magnus's f64 TryConvert
     // coerces a Time via to_f, so it would otherwise marshal as a bare epoch
     // number. Time#to_f is epoch seconds; Date wants ms.
@@ -1148,4 +1189,38 @@ mod tests {
             },
         );
     }
+
+    #[test]
+    fn the_host_object_is_one_per_realm_and_no_property_of_its_global() {
+        in_context(
+            "globalThis.keys = Reflect.ownKeys(globalThis).length",
+            |scope| {
+                let value = jsval_to_js(
+                    scope,
+                    JsVal::Array {
+                        id: 0,
+                        items: vec![JsVal::HostObject, JsVal::HostObject],
+                    },
+                );
+                let held = crate::host_object(scope);
+                let key = v8::String::new(scope, "held").unwrap();
+                held.create_data_property(scope, key.into(), v8::Integer::new(scope, 7).into());
+                global_set(scope, "v", value);
+                // (…the global's keys grown by `keys` and `v` alone)
+                assert_eq!(
+                    as_string(
+                        scope,
+                        "[v[0] === v[1], v[0].held, Object.getPrototypeOf(v[0]), Reflect.ownKeys(globalThis).length - keys].join()"
+                    ),
+                    "true,7,,2"
+                );
+                // (…another realm's is its own)
+                let other = v8::Context::new(scope, Default::default());
+                let scope = &mut v8::ContextScope::new(scope, other);
+                let fresh = crate::host_object(scope);
+                assert!(fresh != held);
+                assert!(crate::host_object(scope) == fresh);
+            },
+        );
+    }
 }

data/ext/rusty_racer/src/ops.rs

@@ -157,9 +157,9 @@ pub(crate) enum Request {
     EvaluateModule {
         module_id: i32,
         timeout_ms: u64,
-        // The name of a function on the module's context's global that reports its evaluation's rejection — HTML "run
-        // a module script": upon rejection, report the exception — now or as a top-level-await module settles; none:
-        // the rejection is the op's error, as far as the drain gets.
+        // The name of a function on the module's context's global (an `@` path: on its host object) that reports its
+        // evaluation's rejection — HTML "run a module script": upon rejection, report the exception — now or as a
+        // top-level-await module settles; none: the rejection is the op's error, as far as the drain gets.
         report: Option<String>,
     },
     ModuleNamespace {
@@ -294,19 +294,20 @@ pub(crate) fn run_source(
     }
 }
 
-// Resolve a dotted property path on the current realm's globalThis to a
-// function and the holder it was read off — its `this`, so `a.b.f` gets the right
-// receiver. Each segment is an ordinary [[Get]], so a getter or Proxy trap on the
-// path runs; when one throws, the error is Err(None): the caller's TryCatch holds
-// it (`caught!`).
+// Resolve a dotted property path on the current realm's globalThis — or, for an
+// `@` path, on its host object (`host_object`) — to a function and the holder it
+// was read off — its `this`, so `a.b.f` gets the right receiver. Each segment is
+// an ordinary [[Get]] (an `@` path's of an own property alone: path_segment), so
+// a getter or Proxy trap on the path runs; when one throws, the error is
+// Err(None): the caller's TryCatch holds it (`caught!`).
 fn resolve_function<'s>(
     scope: &mut v8::PinScope<'s, '_>,
     path: &str,
 ) -> Result<(v8::Local<'s, v8::Function>, v8::Local<'s, v8::Value>), Option<VmError>> {
-    let global = scope.get_current_context().global(scope);
-    let mut holder: v8::Local<v8::Value> = global.into();
-    let mut target: v8::Local<v8::Value> = global.into();
-    for part in path.split('.') {
+    let (root, rest, hidden) = path_root(scope, path);
+    let mut holder: v8::Local<v8::Value> = root.into();
+    let mut target: v8::Local<v8::Value> = root.into();
+    for part in rest.split('.') {
         let Some(obj) = target.to_object(scope) else {
             // The holder of `part` (a preceding segment) was null/undefined, so
             // there's nothing to read `part` from — name the holder, not `part`.
@@ -317,7 +318,7 @@ fn resolve_function<'s>(
         let Some(key) = v8::String::new(scope, part) else {
             return Err(Some(VmError::Runtime("property name too large".into())));
         };
-        let Some(next) = obj.get(scope, key.into()) else {
+        let Some(next) = path_segment(scope, obj, key, hidden) else {
             return Err(None);
         };
         holder = target;
@@ -883,8 +884,8 @@ fn op_attach(
     timeout_ms: u64,
     outermost: bool,
 ) -> VmReply {
-    // attach_at_path writes onto globalThis (and walks a dotted
-    // path), which can fire a user-defined accessor or Proxy trap —
+    // attach_at_path writes onto globalThis or the host object (and walks
+    // a dotted path), which can fire a user-defined accessor or Proxy trap —
     // arbitrary JS. So it goes through the same bracket as Eval: a
     // host fn the trap calls routes back, and a looping trap is
     // time-capped.
@@ -908,7 +909,7 @@ fn op_attach(
                         // under a namespace object, creating missing
                         // intermediates, so host fns needn't pollute the
                         // bare global.
-                        Some(function) => attach_at_path(scope, context, &name, function),
+                        Some(function) => attach_at_path(scope, &name, function),
                         None => Err(VmError::Runtime("failed to build function".into())),
                     };
                     auto_drain(scope, outermost);
@@ -955,7 +956,7 @@ fn op_attach_many(
                             .data(external.into())
                             .build(scope)
                         {
-                            Some(function) => attach_at_path(scope, context, name, function),
+                            Some(function) => attach_at_path(scope, name, function),
                             None => Err(VmError::Runtime(format!(
                                 "failed to build function for `{name}`"
                             ))),
@@ -1272,7 +1273,7 @@ fn op_evaluate_module(
                                 did_eval = true;
                                 v8::tc_scope!(let tc, scope);
                                 let reporter =
-                                    report.as_deref().and_then(|name| global_function(tc, name));
+                                    report.as_deref().and_then(|name| named_function(tc, name));
                                 match module.evaluate(tc) {
                                     // A synchronous top-level throw yields a
                                     // *rejected* promise (not None); a pending
@@ -1339,11 +1340,18 @@ fn op_evaluate_module(
     VmReply::Done(outcome)
 }
 
-// The function the current context's global has under `name`, or None.
-fn global_function<'s>(
+// The function the current context's global has under `name` (one property,
+// dots and all, as it always was) — or, for an `@` path, the one the path names
+// on its host object, as `Context#function` finds it — or None.
+fn named_function<'s>(
     scope: &mut v8::PinScope<'s, '_>,
     name: &str,
 ) -> Option<v8::Local<'s, v8::Function>> {
+    if name.starts_with('@') {
+        return resolve_function(scope, name)
+            .ok()
+            .map(|(function, _)| function);
+    }
     let key = v8::String::new(scope, name)?;
     let global = scope.get_current_context().global(scope);
     v8::Local::<v8::Function>::try_from(global.get(scope, key.into())?).ok()

data/lib/rusty_racer/version.rb

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

data/lib/rusty_racer.rb

@@ -91,10 +91,15 @@ module RustyRacer
     # the microtask queue when the outermost eval/call/run/evaluate completes
     # (the standard embedder contract); :explicit drains only on
     # #perform_microtask_checkpoint.
+    # host_namespace names the object every realm gets rusty_racer's own
+    # functions in (drainMicrotasks, contextGlobal, contextOf, ...): a property
+    # of the global (`'MiniRacer'`), or, as `'@MiniRacer'`, of the realm's host
+    # object, which no script of a page's can reach (see HOST_OBJECT).
     def self.new(host_namespace: nil, snapshot: nil, timeout_ms: 0, memory_limit: 0, microtasks: :auto)
       unless %i[auto explicit].include?(microtasks)
         raise ArgumentError, "microtasks must be :auto or :explicit, got #{microtasks.inspect}"
       end
+      raise ArgumentError, 'host_namespace: "@" names no property of the host object' if host_namespace == '@'
 
       _new(host_namespace, snapshot, timeout_ms, memory_limit, microtasks == :explicit)
     end
@@ -116,6 +121,24 @@ module RustyRacer
     end
   end
 
+  # HOST_OBJECT (defined natively): an argument that crosses into JS as the
+  # realm's HOST OBJECT — an object with no prototype that no global holds, which
+  # the host and the realm's own bindings share and no other script can reach.
+  # Every path the host names (Context#attach / #attach_many / #call /
+  # #call_void / #function, Module#evaluate's report:, Isolate.new's
+  # host_namespace:) starts from it when it begins with `@`:
+  #
+  #   ctx.attach('@fetch', ->(url) { ... })          # host.fetch, no global
+  #   ctx.call('installBindings', RustyRacer::HOST_OBJECT)
+  #   step = ctx.function('@steps.query')             # host.steps.query
+  #
+  # An `@` path walks own properties alone. HOST_OBJECT is the host object of
+  # the realm the operation runs in (a Context's, a Function handle's, a host
+  # function's own, for its result), and that object crosses back as
+  # HOST_OBJECT. Each realm has its own, made as it is first used; a reset makes
+  # the realm, and so its host object, anew. Hand it to the bindings before any
+  # script of a page's runs, by a name they delete as they take it.
+
   # A v8::Context (realm) handed out by an Isolate: where JS actually runs.
   class Context
     # `timeout_ms` (0 = the isolate default) caps this eval; `filename` names the
@@ -180,9 +203,9 @@ module RustyRacer
 
     # Evaluate the instantiated module. Its evaluation's rejection — a top-level throw, a top-level await's — raises
     # (RustyRacer::RuntimeError, as far as the drain after it settles), or, `report:` naming a function of its context's
-    # global, is that function's to report: called with the rejection's reason — a top-level throw's before this
-    # returns, a top-level await's as it settles — and nothing raised (HTML "run a module script": upon rejection,
-    # report the exception).
+    # global (an `@` path: on its host object, HOST_OBJECT), is that function's to report: called with the rejection's
+    # reason — a top-level throw's before this returns, a top-level await's as it settles — and nothing raised (HTML
+    # "run a module script": upon rejection, report the exception).
     def evaluate(report: nil)
       _evaluate(report&.to_s)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rusty_racer
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 0.2.8
 platform: ruby
 authors:
 - Keita Urashima