rusty_racer 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc72e8a18f16fc78197991e4e29ff01ba94afb83ae26d3ea162903654f485dae
-  data.tar.gz: 06a00da38cb052af3a29fa772f93fa14f3e8f267f8a7c88723aad827f908a3d7
+  metadata.gz: ebbfddd8204b62eed228d53d476247e3b76bf08a894b02fb3e8ffe78836b6b02
+  data.tar.gz: 77d0190f0387cbdf240d49ef4ac3b75c1550a18a74de8ceed78a8c97c1956d96
 SHA512:
-  metadata.gz: 3e86f16c51dbe2b1096a7710ea105da2f95f68b640f9a3265f63b85ffcd6f630fb9642305a3afd88da1a559ce50f1238b4b1ff8c8e573d1c8ab20bfd684e03f0
-  data.tar.gz: aa1020630d83aa95c83837c8d1aa14bd3e56a207d955de314892f1c8e247a3519ad7101f9b6d6f1a9dab8f3f535c92bb59ab11cd342245be8f777bbdb21a60d3
+  metadata.gz: e0a3df4af6404d9357a008e2adcb4d8303a39db35ad9d3d4ef0240217222bd0fd0be40c9b18b36b9778e30e9eac8a5ce9b20514ecc962975cc25b1466d504aac
+  data.tar.gz: 497c28687de4bc14c7b666e99a3205406e84384459b923dca24b8d2080db552d3266bbffbfbecfb0a4e61bde9c17aa4413f39e321d1c866339df6944782c3930

data/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+## 0.2.6
+
+### Added
+
+- `Context#function(path)` returns a `RustyRacer::Function`: the function a
+  dotted path names, resolved once, with the object it was read off kept as its
+  `this`. `#call` / `#call_void` invoke it as `Context#call` / `#call_void`
+  would — same marshalling, timeout, errors and re-entrancy — without walking
+  the path or making a property name per call. It raises `DisposedError` once
+  its realm is reset or disposed and never keeps that realm alive; `#dispose`
+  releases it early, and garbage collection releases it too.
+
+### Changed
+
+- Ruby → JS marshalling no longer runs the page's JavaScript. Arrays and
+  objects built for JS have their elements and entries defined
+  (`CreateDataProperty`) rather than assigned, so an accessor on
+  `Array.prototype` or `Object.prototype` can no longer intercept or swallow
+  call arguments, host function results or the host namespace's members. A
+  `"__proto__"` key in a Hash now becomes an own property of the object, as
+  `JSON.parse` makes it, instead of setting its prototype.
+- Ruby → JS marshalling dispatches on the value's built-in type first: a String,
+  Symbol, Array or Hash argument no longer pays for a raised-and-rescued
+  conversion probe or a constant lookup (a String argument cost ~1.2 µs more
+  than none; now ~0.07 µs). Subclasses, `to_f` (an `ActiveSupport::Duration`),
+  `to_str`, `to_ary` and `to_hash` conversions marshal as before — except that
+  an Array or Hash subclass is now always an array or an object, where one that
+  also defined `to_str` (or a Hash subclass `to_ary`) used to cross as that.
+- A getter or `Proxy` trap that throws while `Context#call` resolves its path
+  now raises a `RuntimeError` carrying the JS stack, and the thrown value
+  propagates through a host function like any other JS throw.
+- A `Module` or `Script` whose wrapper is garbage-collected without `#dispose`
+  is released too (at the end of the isolate's next operation), where 0.2.5 kept
+  it until its realm was reset or disposed. `#dispose` itself now only queues
+  the release, as `Function#dispose` does, so it works from any thread — in
+  0.2.5 a dispose from another thread marked the wrapper disposed but silently
+  kept the module or script for good.
+- A module's url (its `import.meta.url`, its url as a referrer) is kept for as
+  long as V8 keeps the module, not as long as its wrapper or its realm: a
+  dependency the resolver compiled and Ruby dropped or disposed, or a function
+  of a disposed realm's module that another realm still holds, still reads it.
+  In 0.2.5 either read `undefined`.
+
+### Documented
+
+- What reading a JS value into Ruby runs (getters, `Proxy` traps, holes read
+  through the prototype chain, `toString`) and the binary-String ↔ `Uint8Array`
+  rule — README, "Marshalling and the page's JavaScript".
+
+### Deliberately unchanged
+
+- JS → Ruby still renders a value with no structural form — a function, a
+  RegExp, a depth-truncated object — through its ToString, which a page can
+  override (`Function.prototype.toString`) to run code or throw during the read.
+  V8's side-effect-free renderer (`Value::ToDetailString`, already used for
+  Symbols) would run nothing, but it truncates a function's source past 128
+  characters and renders objects as `#<Object>`, so switching is a behaviour
+  change left for a release that decides it on purpose.

data/README.md

@@ -67,6 +67,11 @@ ctx.call("add", 20, 22)                  # => 42
 ctx.call_void("doSideEffect")            # runs it; never marshals the return
 ctx.eval_void("globalThis.app = boot()") # ditto for the completion value
 
+# Resolve a function once and keep it: no path walk or name per call, and its
+# holder stays its `this` (see "Function handles" below).
+add = ctx.function("add")
+add.call(20, 22)                         # => 42
+
 # Ruby callbacks into JS; a raised Ruby exception becomes a JS exception.
 ctx.attach("rubyUpcase", ->(s) { s.upcase })
 ctx.eval("rubyUpcase('hi')")             # => "HI"
@@ -93,6 +98,65 @@ ran to completion. When the value is incidental, say so: `#eval_void`,
 result. A statement list has a completion value whether you want one or not, so
 plumbing an object into a global (`globalThis.win = someProxy`) is enough to
 make a plain `#eval` fail after every one of its writes has landed.
+`#eval_primitive` sits between the two: it returns the completion value only
+where it is a primitive, and nil for an object or a symbol, which it never reads.
+
+### Function handles
+
+`Context#function(path)` resolves a dotted path (`"app.router.go"`) the way
+`#call` does — each segment an ordinary property read off the context's
+`globalThis` — once, and returns a `RustyRacer::Function` bound to what it found:
+the function, and the object it was read off as its `this`. `#call(*args)` and
+`#call_void(*args)` then invoke it exactly as `Context#call` / `#call_void` would
+— same argument and result marshalling, same timeout, same errors, and they work
+from inside a host function like any other op — without walking the path or
+making a property name per call. Reassigning or deleting the path afterwards
+does not change what the handle calls.
+
+A handle lives as long as its realm does. Once its context is `reset` or
+`dispose`d (or the isolate is), `#call` raises `RustyRacer::DisposedError`, and
+the handle no longer keeps that realm alive. (`#disposed?` answers for the handle
+and its isolate only: a realm's reset is found by the next call.) `#dispose` lets
+go of one early, and a handle that is simply garbage-collected is released too,
+at the end of the isolate's next operation. A path that leads into *another*
+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.
+
+### Releasing handles
+
+A `Function`, `Script` or `Module` handle is released when it is `#dispose`d —
+from any thread — or garbage-collected, at the end of the isolate's next
+operation, and with its realm's `reset` or `dispose` at the latest. Releasing a
+handle only drops the isolate's hold on what it names: functions a script
+defined keep working, and a module V8 still keeps — linked into a live graph, or
+reached from another realm — keeps its `import.meta.url` and its url as a
+referrer, wrapper or realm or not.
+
+### Marshalling and the page's JavaScript
+
+Values cross by copy, not by reference.
+
+- **Ruby → JS builds new values without running any JavaScript.** An array's
+  elements and an object's entries are *defined* on the new container
+  (`CreateDataProperty`), never assigned, so an accessor a script has put on
+  `Array.prototype[0]` or `Object.prototype.x` neither sees nor swallows them,
+  and a `"__proto__"` key is an own property, as `JSON.parse` makes it. Maps and
+  Sets are filled by V8's original builtins, whatever `Map.prototype.set` is now.
+- **JS → Ruby reads values the way a script would.** An object's own enumerable
+  string keys are listed and each is read with an ordinary `[[Get]]`, so a getter
+  runs; a `Proxy` is read through its `ownKeys`, `getOwnPropertyDescriptor` and
+  `get` traps; an array's holes read through its prototype chain, as `arr[i]`
+  does; a function, a RegExp or any other value with no structural form becomes
+  its `toString()`, which may be the page's. A throw anywhere in that fails the op
+  (see above), and `#call_void` / `#eval_void` skip the read entirely. Map and Set
+  contents, typed arrays and buffers are read without running JavaScript.
+- **A String's encoding tag is its type.** A binary (`ASCII-8BIT`) String crosses
+  as a `Uint8Array`, and a `Uint8Array`, `ArrayBuffer` or `SharedArrayBuffer`
+  comes back as a binary String. Any text encoding crosses as a JS string, and
+  must hold valid characters — invalid UTF-8 raises `EncodingError` rather than
+  turn into U+FFFD — so text read with `File.binread` or off a socket needs its
+  real encoding (`force_encoding`) before it crosses as text.
 
 ES modules (the embedder owns the URL→module registry):
 
@@ -114,6 +178,12 @@ loop here (see below), a `true` graph whose `await` never settles returns from
 `evaluate` with the module body still suspended, and `status` reports
 `:evaluated` either way — so `graph_async?` is what distinguishes the two.
 
+A rejected evaluation — a top-level throw, or a top-level `await` that rejects —
+raises from `evaluate`. Pass `report:` the name of a function on the context's
+global to have it called with the reason instead (HTML's "report the
+exception"), at once for a throw and as it settles for an `await`:
+`app.evaluate(report: "reportError")`.
+
 Classic `<script>`s work the same way: `ctx.compile("1 + 1").run` # => 2.
 
 ### Resource limits
@@ -203,6 +273,12 @@ Also available:
   `microtasks: :auto` also drains at the end of each outermost eval/call/evaluate;
   `microtasks: :explicit` leaves it fully manual. There is no event loop or timers
   either way.
+- **`Isolate#pump_message_loop`** — runs the tasks V8 posts instead of running
+  inline, most visibly `FinalizationRegistry` cleanup callbacks: a microtask
+  checkpoint never runs them, so without a pump a collected target's callback
+  never fires. It drains every pending task without blocking, then a microtask
+  checkpoint; with nothing pending it is a no-op. The callbacks are ordinary JS,
+  so the pump is capped by `timeout_ms` like an `eval`.
 - **`Isolate#terminate`**, **`Isolate#dynamic_import_resolver=`**,
   **`Context#reset`** (below), and **`Platform.set_flags!`**.
 
@@ -218,7 +294,9 @@ warm isolate — a per-visit reset that avoids rebuilding the VM. Its contract:
 - **Runtime mutations are dropped.** Anything set on the realm at runtime is gone.
 - **Host fns are dropped.** Functions `attach`/`attach_many`'d into the realm are
   released — the isolate stops holding them, so whatever they captured becomes
-  collectable; re-attach them after a reset.
+  collectable; re-attach them after a reset. One the embedder kept hold of (through
+  another realm, say) throws `unknown host function` when called; it never runs
+  what was attached after it.
 - **Modules and classic scripts are dropped.** Handles compiled in the realm die
   with the old context.
 - **The realm id and the shared same-origin token are preserved** — the id keeps

data/ext/rusty_racer/Cargo.toml

@@ -5,7 +5,7 @@
 # links and loads with no custom archive.
 [package]
 name = "rusty_racer"
-version = "0.2.4"
+version = "0.2.6"
 edition = "2024"
 publish = false
 
@@ -31,3 +31,8 @@ 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"
+
+# `cargo test` links libruby: the crate calls into it, though the marshalling tests
+# that run without a VM never do.
+[dev-dependencies]
+rb-sys = { version = "0.9", features = ["link-ruby"] }