rusty_racer 0.2.6 → 0.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebbfddd8204b62eed228d53d476247e3b76bf08a894b02fb3e8ffe78836b6b02
-  data.tar.gz: 77d0190f0387cbdf240d49ef4ac3b75c1550a18a74de8ceed78a8c97c1956d96
+  metadata.gz: 6eedc8d154897325a2990e5ed6999a368b7c81c64528d5d406ed469e5d808fc4
+  data.tar.gz: f0c356c5b22a4574323e7efe73c56bd07267d5428438d22dadf2c4a08953b468
 SHA512:
-  metadata.gz: e0a3df4af6404d9357a008e2adcb4d8303a39db35ad9d3d4ef0240217222bd0fd0be40c9b18b36b9778e30e9eac8a5ce9b20514ecc962975cc25b1466d504aac
-  data.tar.gz: 497c28687de4bc14c7b666e99a3205406e84384459b923dca24b8d2080db552d3266bbffbfbecfb0a4e61bde9c17aa4413f39e321d1c866339df6944782c3930
+  metadata.gz: 02acd6e295f14544a9f146f0b916ac1ac585b63634bb12c353d39059dc7ffef50337e76cd81c318463060c2e8f901a19667f384cbd1967ed776290dfd1d7c0cb
+  data.tar.gz: bc2513ed51e0a7ed2c45bc4c8cc85a051a7d83f9d1cdc56675cc2e1a3fcfd915c7b77bede14f91ac10e475d877e43563cea38c734d5cab36a2be6b806200312c

data/CHANGELOG.md

@@ -1,5 +1,53 @@
 # 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
+
+- An operation on a Ruby Fiber looks its stack's bounds up once per stack
+  rather than once per operation that a 16-entry cache had dropped. Capybara
+  filters each result set in an Enumerator left suspended until GC frees it, so
+  a page of finds runs on hundreds of distinct fiber stacks, and each lookup read
+  all of `/proc/self/maps` — a fifth of a find loop, and slower the larger
+  Ruby's fiber pool grew. Every stack an operation has run on is now kept (Ruby
+  hands its pooled stacks out again and never unmaps them), and on Linux 6.11+ a
+  lookup asks the kernel for the one mapping (`PROCMAP_QUERY`) instead of
+  reading the whole map. A call into V8 from a fresh fiber, steady state: 160 µs
+  → 1.0 µs beside a 2,200-line map, 521 µs → 1.0 µs beside 8,300 lines.
+
 ## 0.2.6
 
 ### Added

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.6"
+version = "0.2.8"
 edition = "2024"
 publish = false
 
@@ -29,8 +29,9 @@ rb-sys = "0.9"
 # (which is built with rusty_v8_enable_simdutf=true) on every platform.
 v8 = { version = "150.4.0", features = ["simdutf"] }
 # pthread stack-bounds query, to set V8's stack limit per op relative to the
-# current native thread (in-thread V8 runs on the Ruby thread's stack).
-libc = "0.2"
+# current native thread (in-thread V8 runs on the Ruby thread's stack). 0.2.172
+# for `_IOWR`, which builds the PROCMAP_QUERY ioctl number per architecture.
+libc = "0.2.172"
 
 # `cargo test` links libruby: the crate calls into it, though the marshalling tests
 # that run without a VM never do.

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/ext/rusty_racer/src/stack.rs

@@ -151,33 +151,24 @@ fn native_stack_bounds() -> (usize, usize) {
     (0, 0)
 }
 
-// Lower bound (and upper, for the cache test) of the memory region containing
-// `addr` — i.e. the BOTTOM of the stack `addr` is on. Used for a Ruby Fiber,
-// whose mmap'd stack pthread can't see: V8's limit must sit ABOVE this bottom or
-// a deep fiber recursion overflows the real stack and SEGVs the unmapped guard.
-// (0, 0) if unknown.
+// The BOTTOM of the stack `addr` is on, and the highest address an op has been
+// seen running at on it. Used for a Ruby Fiber, whose mmap'd stack pthread can't
+// see: V8's limit must sit ABOVE this bottom or a deep fiber recursion overflows
+// the real stack and SEGVs the unmapped guard. (0, 0) if unknown.
 //
-// Cached per native thread, several regions at a time, because a miss asks the
-// OS for the whole memory map and costs far more than the op it serves: with ONE
-// slot
-// a workload that alternates between fibers missed on every single op, and an
-// eval went from 1.2us to 31us as soon as two fibers took turns (measured on a
-// 212-line maps; a Rails process has many times that). Ruby pools fiber stacks,
-// so the live set is small and stable — one Enumerator per Capybara result, say
-// — and a handful of slots turns that back into hits.
+// Cached per native thread, for EVERY stack an op has run on, because a miss
+// asks the OS and a workload can run each op on a stack it has never used before:
+// Capybara filters each result set in an Enumerator, left suspended until GC
+// frees it, so a thousand finds run on a thousand distinct fiber stacks. A cache
+// of sixteen slots missed on nearly every one of them, and where a miss reads all
+// of /proc/self/maps — whose length grows with Ruby's fiber pool — those reads
+// were a fifth of the find loop (1003 per 1000 finds). Keeping every stack makes
+// the steady state free: the pool hands the same stacks out again (its free list
+// is LIFO, and it never unmaps them — below), so once each has had an op on it
+// nothing misses. The table is as large as the set of stacks ops have run on,
+// which that pool bounds.
 //
-// Eviction is RANDOM, not round-robin (or LRU, which behaves the same here):
-// ops cycling through more fibers than there are slots are exactly the pattern
-// those policies handle worst, since each eviction takes the entry needed next
-// and the hit rate collapses to zero — one fiber over the size measured as slow
-// as having no cache at all. Evicting at random keeps roughly
-// slots/live-fibers of the accesses, so going over the size degrades gradually
-// instead of falling off a cliff. Empty slots are filled before anything is
-// evicted. Entries are never invalidated: a dead fiber's keeps its slot until
-// some miss draws it, and with a live set that fits there are no misses at all
-// — which is why a hit has to be self-justifying rather than merely plausible.
-//
-// So the mapping's top is never used, or even kept, as an upper bound. A fiber
+// The mapping's top is never used, or even kept, as an upper bound. A fiber
 // stack's mapping can extend far above the stack itself, where the kernel merged
 // it with an adjacent anonymous mapping of the same protection that has nothing
 // to do with the fiber pool (measured: a 644KB stack inside an 8840KB mapping,
@@ -207,94 +198,160 @@ fn native_stack_bounds() -> (usize, usize) {
 // Within that window a cached bottom is the fiber's real bottom: Ruby brackets
 // every fiber stack with PROT_NONE guard pages, so the mapping cannot start
 // below the stack, and a pooled slot is handed to the next fiber with identical
-// bounds.
-const FIBER_REGION_SLOTS: usize = 16;
-
-#[derive(Clone, Copy)]
-struct FiberRegion {
-    // The mapping's bottom, and the key: 0 marks the slot unused.
+// bounds. Entries are never invalidated, and that rests on the pool too: Ruby
+// frees a pool allocation only when built with FIBER_POOL_ALLOCATION_FREE (cont.c
+// defines it for a limited address space, i.e. 32-bit, which V8 doesn't ship for,
+// and for RB_EXPERIMENTAL_FIBER_POOL), so the bounds an op saw on a stack stay
+// the bounds of every later fiber there. Under a build that does unmap, an entry
+// can outlive its memory; a hit is then still right when the memory is mapped
+// again as the same pool's stacks at the same address — the same stride, so the
+// same guards — and wrong, with a bottom below the new one, when a later mapping
+// puts a guard page inside the old window. The same goes for a stack that is not
+// Ruby's: a C extension's own coroutine stack, unmapped once it is done with and
+// its addresses reused, can leave an entry that answers for memory it no longer
+// describes. Ruby's M:N thread stacks are safe the way its fibers are: a freed
+// one is only madvised, never unmapped.
+#[derive(Clone, Copy, Debug, PartialEq)]
+struct FiberStack {
+    // The bottom of the stack's mapping.
     lo: usize,
     // Highest address a V8 op has run at on this stack.
     seen: usize,
 }
 
-#[derive(Clone, Copy)]
-struct FiberRegions {
-    slots: [FiberRegion; FIBER_REGION_SLOTS],
-    // xorshift64 state for picking a victim. Seeded to a fixed nonzero constant
-    // (the golden-ratio one): nothing here needs unpredictability, only that the
-    // eviction order doesn't line up with the caller's rotation through fibers.
-    rng: u64,
+// Sorted by `lo`, with disjoint [lo, seen] windows — so `seen` ascends too, and
+// both lookups below are binary searches.
+struct FiberStacks(Vec<FiberStack>);
+
+impl FiberStacks {
+    // The entry whose window holds `addr`.
+    fn find(&self, addr: usize) -> Option<FiberStack> {
+        let below = self.0.partition_point(|s| s.lo <= addr);
+        let stack = *self.0.get(below.checked_sub(1)?)?;
+        (addr <= stack.seen).then_some(stack)
+    }
+
+    // (bottom, highest-address-seen) of the stack `addr` is on: the entry's when
+    // one holds it, else `query`'s answer for `addr`, recorded — 0 there being
+    // "unknown", which is recorded nowhere.
+    fn bounds(&mut self, addr: usize, query: impl FnOnce(usize) -> usize) -> (usize, usize) {
+        if let Some(stack) = self.find(addr) {
+            return (stack.lo, stack.seen);
+        }
+        let lo = query(addr);
+        if lo == 0 {
+            return (0, 0);
+        }
+        self.record(lo, addr);
+        (lo, addr)
+    }
+
+    // Record an op at `addr` on the stack whose bottom was just looked up as
+    // `lo`. Being fresh, that replaces every entry overlapping [lo, addr]: the
+    // same stack's narrower window, or one describing memory since mapped afresh.
+    // Every query checks that its mapping holds `addr`, so `lo <= addr`.
+    fn record(&mut self, lo: usize, addr: usize) {
+        debug_assert!(lo <= addr);
+        let from = self.0.partition_point(|s| s.seen < lo);
+        let to = self.0.partition_point(|s| s.lo <= addr);
+        self.0.splice(from..to, [FiberStack { lo, seen: addr }]);
+    }
 }
 
 thread_local! {
-    static FIBER_REGIONS: std::cell::RefCell<FiberRegions> = const {
-        std::cell::RefCell::new(FiberRegions {
-            slots: [FiberRegion { lo: 0, seen: 0 }; FIBER_REGION_SLOTS],
-            rng: 0x9E37_79B9_7F4A_7C15,
-        })
-    };
+    static FIBER_STACKS: std::cell::RefCell<FiberStacks> =
+        const { std::cell::RefCell::new(FiberStacks(Vec::new())) };
 }
 
 // (bottom, highest-address-seen) of the stack `addr` is on. `addr` must be an
 // address the CALLER knows is on that stack and as high up it as it can offer —
 // it both answers the lookup and becomes the entry's `seen` on a miss, so a
-// caller that passes its topmost frame gets the widest sound window. A RefCell
-// rather than a Cell so a hit reads the slots in place instead of copying the
-// whole table out on every fiber op.
+// caller that passes its topmost frame gets the widest sound window. An op run
+// while the thread's locals are being torn down gets the fail-safe (0, 0).
 fn current_region_bounds_cached(addr: usize) -> (usize, usize) {
-    FIBER_REGIONS.with(|c| {
-        if let Some(r) = c
-            .borrow()
-            .slots
-            .iter()
-            .find(|r| r.lo != 0 && addr >= r.lo && addr <= r.seen)
-        {
-            return (r.lo, r.seen);
-        }
-        let (lo, _) = query_region_bounds(addr);
-        if lo == 0 {
-            return (0, 0);
-        }
-        let mut cache = c.borrow_mut();
-        // Prefer the entry for a stack we already know (a frame above anything
-        // seen on it so far, which just widens the window), then an empty slot,
-        // and only then evict.
-        let slot = cache
-            .slots
-            .iter()
-            .position(|r| r.lo == lo)
-            .or_else(|| cache.slots.iter().position(|r| r.lo == 0))
-            .unwrap_or_else(|| {
-                cache.rng ^= cache.rng << 13;
-                cache.rng ^= cache.rng >> 7;
-                cache.rng ^= cache.rng << 17;
-                (cache.rng % FIBER_REGION_SLOTS as u64) as usize
-            });
-        cache.slots[slot] = FiberRegion { lo, seen: addr };
-        (lo, addr)
-    })
+    FIBER_STACKS
+        .try_with(|stacks| stacks.borrow_mut().bounds(addr, query_region_bottom))
+        .unwrap_or((0, 0))
 }
 
-// The [start, end) of the mapping containing `addr`, or (0, 0) when it can't be
-// established. Only called on a cache miss (a new fiber), because it is slow.
+// The bottom of the mapping containing `addr`, or 0 when it can't be
+// established. Only called on a cache miss: a stack no op has run on yet, or a
+// frame above any seen on it.
 //
-// (0, 0) is the fail-safe answer, not an error: every caller falls back to a
-// fixed budget below the SP, which is what this gem did on every platform before
-// any of these lookups existed. So a platform without an implementation, or a
-// lookup that returns something we can't vouch for, degrades to a smaller JS
-// stack rather than to a wrong one.
+// 0 is the fail-safe answer, not an error: every caller falls back to a fixed
+// budget below the SP, which is what this gem did on every platform before any
+// of these lookups existed. So a platform without an implementation, or a lookup
+// that returns something we can't vouch for, degrades to a smaller JS stack
+// rather than to a wrong one.
 //
-// Linux reads /proc/self/maps fresh each time.
+// Linux asks the kernel for the one mapping (PROCMAP_QUERY, 6.11+: ~0.65us for
+// the open, the ioctl and the close, measured beside 3000 mappings) and reads
+// all of /proc/self/maps only where the ioctl isn't there — ~25-200us, growing
+// with the map. The file is opened per call rather than kept: an open file
+// would go on describing the PARENT's address space in a forked child.
+#[cfg(target_os = "linux")]
+fn query_region_bottom(addr: usize) -> usize {
+    let Ok(mut maps) = std::fs::File::open("/proc/self/maps") else {
+        return 0;
+    };
+    procmap_query_bottom(&maps, addr).unwrap_or_else(|| read_maps_bottom(&mut maps, addr))
+}
+
+// The bottom of the mapping containing `addr`, through the PROCMAP_QUERY ioctl
+// on an open /proc/self/maps; None when the ioctl fails, which on a live stack
+// address means a kernel without it (ENOTTY), or answers with a mapping that
+// does not hold `addr`, which the kernel's never does but an emulated /proc
+// might.
 #[cfg(target_os = "linux")]
-fn query_region_bounds(addr: usize) -> (usize, usize) {
+fn procmap_query_bottom(maps: &std::fs::File, addr: usize) -> Option<usize> {
+    use std::os::fd::AsRawFd;
+    // struct procmap_query, from linux/fs.h — not in libc. Only `vma_start` is
+    // read back, but the ioctl number encodes the whole struct's size.
+    #[repr(C)]
+    #[derive(Default)]
+    struct ProcmapQuery {
+        size: u64,
+        query_flags: u64,
+        query_addr: u64,
+        vma_start: u64,
+        vma_end: u64,
+        vma_flags: u64,
+        vma_page_size: u64,
+        vma_offset: u64,
+        inode: u64,
+        dev_major: u32,
+        dev_minor: u32,
+        vma_name_size: u32,
+        build_id_size: u32,
+        vma_name_addr: u64,
+        build_id_addr: u64,
+    }
+    // Flags 0 ask for the mapping COVERING query_addr, not the next one above it.
+    const PROCMAP_QUERY: libc::Ioctl = libc::_IOWR::<ProcmapQuery>(b'f' as u32, 17);
+    let mut query = ProcmapQuery {
+        size: std::mem::size_of::<ProcmapQuery>() as u64,
+        query_addr: addr as u64,
+        ..Default::default()
+    };
+    let rc = unsafe {
+        libc::ioctl(
+            maps.as_raw_fd(),
+            PROCMAP_QUERY,
+            &mut query as *mut ProcmapQuery,
+        )
+    };
+    let (lo, hi) = (query.vma_start as usize, query.vma_end as usize);
+    (rc == 0 && lo <= addr && addr < hi).then_some(lo)
+}
+
+// The bottom of the mapping containing `addr`, from the text of
+// /proc/self/maps, or 0 if no line covers it.
+#[cfg(target_os = "linux")]
+fn read_maps_bottom(maps: &mut std::fs::File, addr: usize) -> usize {
     use std::io::Read;
     let mut buf = String::new();
-    if std::fs::File::open("/proc/self/maps")
-        .and_then(|mut f| f.read_to_string(&mut buf))
-        .is_err()
-    {
-        return (0, 0);
+    if maps.read_to_string(&mut buf).is_err() {
+        return 0;
     }
     for line in buf.lines() {
         // e.g. "7f6a...000-7f6a...000 rw-p 00000000 00:00 0 ..."
@@ -309,10 +366,10 @@ fn query_region_bounds(addr: usize) -> (usize, usize) {
             continue;
         };
         if addr >= lo && addr < hi {
-            return (lo, hi);
+            return lo;
         }
     }
-    (0, 0)
+    0
 }
 
 // macOS has no /proc, so ask the Mach VM directly. mach_vm_region reports the
@@ -322,7 +379,7 @@ fn query_region_bounds(addr: usize) -> (usize, usize) {
 // that isn't tells us we either walked into something that is not a stack or
 // misread the reply, in which case the fixed-budget fallback is the safer answer.
 #[cfg(target_os = "macos")]
-fn query_region_bounds(addr: usize) -> (usize, usize) {
+fn query_region_bottom(addr: usize) -> usize {
     // Not in libc, which points at the `mach2` crate instead; these are the only
     // entry points we need, so declare them here rather than take the dependency.
     // (libc does carry mach_task_self_, but deprecated for the same reason.)
@@ -370,20 +427,20 @@ fn query_region_bounds(addr: usize) -> (usize, usize) {
             mach_port_deallocate(mach_task_self_, object_name);
         }
         if kr != KERN_SUCCESS || size == 0 || info[0] & VM_PROT_READ_WRITE != VM_PROT_READ_WRITE {
-            return (0, 0);
+            return 0;
         }
         let (lo, hi) = (start as usize, start.saturating_add(size) as usize);
         if addr >= lo && addr < hi {
-            (lo, hi)
+            lo
         } else {
-            (0, 0) // `addr` was in a hole; this is the region after it
+            0 // `addr` was in a hole; this is the region after it
         }
     }
 }
 
 #[cfg(not(any(target_os = "linux", target_os = "macos")))]
-fn query_region_bounds(_addr: usize) -> (usize, usize) {
-    (0, 0)
+fn query_region_bottom(_addr: usize) -> usize {
+    0
 }
 
 // Set from RUSTY_RACER_STACK_DEBUG at init; gates the per-op stack diagnostics.
@@ -517,7 +574,7 @@ impl<'a> StackScope<'a> {
             } else {
                 // Region unknown. Both shipped platforms implement the lookup,
                 // so reaching this on one of them means the lookup FAILED (see
-                // query_region_bounds for what it refuses to vouch for) — worth
+                // query_region_bottom for what it refuses to vouch for) — worth
                 // chasing rather than assuming, since the budget here is only a
                 // guess: a fixed reserve below the SP, hoping the fiber is that
                 // deep. It usually is for an OUTERMOST fiber op, whose SP sits
@@ -596,12 +653,15 @@ impl<'a> StackScope<'a> {
         //     stack (the cache's `seen`, NOT the mapping top, which can reach far
         //     into an unrelated neighbour — see current_region_bounds_cached);
         //     otherwise we cannot tell it is on our stack at all, and adopting it
-        //     would send the scan up through our guard page. Since that window
-        //     lives in a cache with random eviction, the test can also fail
-        //     because the entry was evicted between the two ops — the scan then
-        //     narrows to this op's own frame, i.e. the same residual documented
-        //     there for a real stack switch, now reachable at random once more
-        //     fiber stacks are live than the cache holds.
+        //     would send the scan up through our guard page. The enclosing op
+        //     ran on this stack at or below `seen` — it widened the entry to its
+        //     own `stack_top` if nothing had — and an entry is only ever replaced
+        //     by a fresh lookup overlapping it, which for a stack still mapped is
+        //     the same stack with a higher `seen`. So the test holds for every
+        //     enclosing op on our stack whose lookup went through this thread's
+        //     table; one that ran on another native thread (an M:N Ruby thread
+        //     that resumed elsewhere inside a host callback) is unknown here, and
+        //     the scan narrows to this op's own frame — the residual below.
         let new_scan_start = if on_native {
             unsafe { v8__base__Stack__GetStackStart() }
         } else if nested && region.0 != 0 && prev_scan_start > sp && prev_scan_start <= region.1 {
@@ -655,3 +715,219 @@ impl Drop for StackScope<'_> {
         }
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn stacks(entries: &[(usize, usize)]) -> FiberStacks {
+        FiberStacks(
+            entries
+                .iter()
+                .map(|&(lo, seen)| FiberStack { lo, seen })
+                .collect(),
+        )
+    }
+
+    #[test]
+    fn a_lookup_hits_only_inside_a_window() {
+        let table = stacks(&[(0x1000, 0x1800), (0x3000, 0x3400)]);
+        assert_eq!(table.find(0x0fff), None);
+        assert_eq!(
+            table.find(0x1000),
+            Some(FiberStack {
+                lo: 0x1000,
+                seen: 0x1800
+            })
+        );
+        assert_eq!(table.find(0x1800).map(|s| s.lo), Some(0x1000));
+        // Above `seen` is not known to be on that stack, though no other entry
+        // claims it.
+        assert_eq!(table.find(0x1801), None);
+        assert_eq!(table.find(0x3200).map(|s| s.lo), Some(0x3000));
+        assert_eq!(table.find(0x3401), None);
+    }
+
+    #[test]
+    fn a_stack_is_looked_up_once_and_again_only_above_its_window() {
+        let mut table = stacks(&[]);
+        let queries = std::cell::Cell::new(0);
+        let mut bounds = |addr| {
+            table.bounds(addr, |_| {
+                queries.set(queries.get() + 1);
+                0x1000
+            })
+        };
+        assert_eq!(bounds(0x1800), (0x1000, 0x1800));
+        assert_eq!(bounds(0x1400), (0x1000, 0x1800));
+        assert_eq!(bounds(0x1800), (0x1000, 0x1800));
+        assert_eq!(queries.get(), 1);
+        assert_eq!(bounds(0x1c00), (0x1000, 0x1c00));
+        assert_eq!(bounds(0x1900), (0x1000, 0x1c00));
+        assert_eq!(queries.get(), 2);
+    }
+
+    #[test]
+    fn an_unknown_bottom_is_not_recorded() {
+        let mut table = stacks(&[]);
+        assert_eq!(table.bounds(0x1800, |_| 0), (0, 0));
+        assert_eq!(table.0, Vec::new());
+    }
+
+    #[test]
+    fn a_frame_above_the_window_widens_the_same_entry() {
+        let mut table = stacks(&[(0x1000, 0x1800), (0x3000, 0x3400)]);
+        table.record(0x1000, 0x1c00);
+        assert_eq!(table.0, stacks(&[(0x1000, 0x1c00), (0x3000, 0x3400)]).0);
+    }
+
+    #[test]
+    fn a_new_stack_is_inserted_in_order() {
+        let mut table = stacks(&[(0x1000, 0x1800), (0x5000, 0x5400)]);
+        table.record(0x3000, 0x3100);
+        table.record(0x0100, 0x0200);
+        table.record(0x9000, 0x9100);
+        assert_eq!(
+            table.0,
+            stacks(&[
+                (0x0100, 0x0200),
+                (0x1000, 0x1800),
+                (0x3000, 0x3100),
+                (0x5000, 0x5400),
+                (0x9000, 0x9100)
+            ])
+            .0
+        );
+    }
+
+    #[test]
+    fn a_fresh_bottom_replaces_every_entry_it_overlaps() {
+        // Memory once holding two stacks, now one mapping from 0x1400: both old
+        // windows reach into [0x1400, 0x3200], so neither may answer again.
+        let mut table = stacks(&[
+            (0x0100, 0x0200),
+            (0x1000, 0x1800),
+            (0x3000, 0x3400),
+            (0x5000, 0x5400),
+        ]);
+        table.record(0x1400, 0x3200);
+        assert_eq!(
+            table.0,
+            stacks(&[(0x0100, 0x0200), (0x1400, 0x3200), (0x5000, 0x5400)]).0
+        );
+        assert_eq!(table.find(0x1200), None);
+    }
+
+    // A mapping laid out as Ruby's fiber pool lays a stack out: read-write
+    // pages with PROT_NONE guard pages among them. Unmapped on drop.
+    #[cfg(target_os = "linux")]
+    struct GuardedStack {
+        base: usize,
+        len: usize,
+    }
+
+    #[cfg(target_os = "linux")]
+    impl GuardedStack {
+        fn page() -> usize {
+            unsafe { libc::sysconf(libc::_SC_PAGESIZE) as usize }
+        }
+
+        // `pages` pages, of which those at the `guards` indexes are PROT_NONE.
+        fn map(pages: usize, guards: &[usize]) -> Self {
+            let len = pages * Self::page();
+            let stack = Self {
+                base: Self::mmap(0, len, 0),
+                len,
+            };
+            stack.protect(guards);
+            stack
+        }
+
+        // Map the same addresses afresh (MAP_FIXED replaces the old mapping in
+        // one step, so no other thread's mmap can land in between), with other
+        // guards.
+        fn remap(&self, guards: &[usize]) {
+            assert_eq!(Self::mmap(self.base, self.len, libc::MAP_FIXED), self.base);
+            self.protect(guards);
+        }
+
+        fn mmap(at: usize, len: usize, flags: libc::c_int) -> usize {
+            let base = unsafe {
+                libc::mmap(
+                    at as *mut c_void,
+                    len,
+                    libc::PROT_READ | libc::PROT_WRITE,
+                    libc::MAP_PRIVATE | libc::MAP_ANONYMOUS | flags,
+                    -1,
+                    0,
+                )
+            };
+            assert_ne!(base, libc::MAP_FAILED);
+            base as usize
+        }
+
+        fn protect(&self, guards: &[usize]) {
+            for &guard in guards {
+                let page = self.page_at(guard) as *mut c_void;
+                assert_eq!(
+                    unsafe { libc::mprotect(page, Self::page(), libc::PROT_NONE) },
+                    0
+                );
+            }
+        }
+
+        fn page_at(&self, index: usize) -> usize {
+            self.base + index * Self::page()
+        }
+    }
+
+    #[cfg(target_os = "linux")]
+    impl Drop for GuardedStack {
+        fn drop(&mut self) {
+            unsafe { libc::munmap(self.base as *mut c_void, self.len) };
+        }
+    }
+
+    // Both ways of asking agree with each other and with the layout.
+    #[cfg(target_os = "linux")]
+    fn assert_bottom(addr: usize, expected: usize) {
+        assert_eq!(query_region_bottom(addr), expected);
+        let mut maps = std::fs::File::open("/proc/self/maps").unwrap();
+        assert_eq!(read_maps_bottom(&mut maps, addr), expected);
+        // Older kernels have no PROCMAP_QUERY; where there is one it must agree.
+        if let Some(bottom) = procmap_query_bottom(&maps, addr) {
+            assert_eq!(bottom, expected);
+        }
+    }
+
+    #[cfg(target_os = "linux")]
+    #[test]
+    fn the_bottom_is_the_page_above_the_guard() {
+        let stack = GuardedStack::map(8, &[0]);
+        assert_bottom(stack.page_at(5) + 17, stack.page_at(1));
+        assert_bottom(stack.page_at(1), stack.page_at(1));
+    }
+
+    #[cfg(target_os = "linux")]
+    #[test]
+    fn a_stack_mapped_again_with_other_guards_has_its_new_bottom() {
+        // Unmap a fiber's stack and map the same addresses again with a guard
+        // inside the old one: a lookup is a fresh question, so it answers with
+        // the new bottom, never the one the old mapping had.
+        let stack = GuardedStack::map(8, &[0]);
+        assert_bottom(stack.page_at(6), stack.page_at(1));
+        stack.remap(&[0, 4]);
+        assert_bottom(stack.page_at(6), stack.page_at(5));
+    }
+
+    #[cfg(target_os = "linux")]
+    #[test]
+    fn a_live_stack_is_found_where_it_runs() {
+        // This thread's own stack: the frame is somewhere above its bottom.
+        let marker = 0u8;
+        let addr = &marker as *const u8 as usize;
+        let bottom = query_region_bottom(addr);
+        assert_ne!(bottom, 0);
+        assert!(bottom <= addr);
+    }
+}

data/lib/rusty_racer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RustyRacer
-  VERSION = "0.2.6"
+  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.6
+  version: 0.2.8
 platform: ruby
 authors:
 - Keita Urashima