rusty_racer 0.2.5 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 488967c6324cc118d0cf37974c23566725c7c6ce14ba48572330075d1b2dff66
-  data.tar.gz: 48f562d20d1217e91a9727d1fa348312c51c49b9f82607f3bd2803247e76976c
+  metadata.gz: ebbfddd8204b62eed228d53d476247e3b76bf08a894b02fb3e8ffe78836b6b02
+  data.tar.gz: 77d0190f0387cbdf240d49ef4ac3b75c1550a18a74de8ceed78a8c97c1956d96
 SHA512:
-  metadata.gz: faad4323b59c0eca2d69f66bb9698a41ab5837c0f417710b0f125ca39c0fad22e3d399f8fe730bd2c526a1e9cfe34ad9b8c8be5fdbc47b5c8a6e860eb23308f7
-  data.tar.gz: 304a7388700465fcfc86a8e7ffeba87c9bd95455075bce889277abe44193f8f407326a136cfe0be39738d53061603d249f153f031866c9570bddec424ac5b807
+  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"
@@ -96,6 +101,63 @@ 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):
 
 ```ruby

data/ext/rusty_racer/Cargo.toml

@@ -5,7 +5,7 @@
 # links and loads with no custom archive.
 [package]
 name = "rusty_racer"
-version = "0.2.5"
+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"] }