capybara-simulated 0.3.0 → 0.5.0

data/lib/capybara/simulated/v8_runtime.rb

@@ -106,8 +106,18 @@ module Capybara
           @ctx        = @iso.context
           @attached   = []
           @generation = 0
+          # rusty's heap-accounting API (heap_statistics / low_memory_notification)
+          # landed in 0.1.9. Probe the real Isolate once here — the Ctx wrapper
+          # delegates these unconditionally, so a `respond_to?` on the wrapper
+          # would always be true and never gate the version. Cached so the
+          # per-visit pressure check (rule 3) is an ivar read, not a dispatch.
+          @heap_accounting = @iso.respond_to?(:heap_statistics)
         end
 
+        # True iff the underlying rusty Isolate exposes the 0.1.9 heap-accounting
+        # API. Drives `relieve_heap_pressure`'s version gate.
+        def heap_accounting? = @heap_accounting
+
         # ── Context surface ─────────────────────────────────────────
         # rusty drains microtasks at call-depth zero (V8's default kAuto
         # policy), so a returned eval/call has already run its end-of-script
@@ -152,6 +162,10 @@ module Capybara
         def terminate                        = @iso.terminate
         def dispose                          = @iso.dispose
         def perform_microtask_checkpoint     = @iso.perform_microtask_checkpoint
+        # rusty >= 0.1.9: V8 heap accounting + a forced full GC. Used by the
+        # per-visit heap-pressure relief in `rebuild_ctx` (see there).
+        def heap_statistics                  = @iso.heap_statistics
+        def low_memory_notification          = @iso.low_memory_notification
 
         def dynamic_import_resolver=(prc)
           @iso.dynamic_import_resolver = prc
@@ -398,6 +412,7 @@ module Capybara
 
       def dispose_frame_realms
         @realm_module_handles&.clear
+        @frame_realm_depths&.clear
         return if @frame_realms.nil?
         @frame_realms.each_value {|fr| fr.dispose rescue nil }
         @frame_realms.clear
@@ -411,13 +426,24 @@ module Capybara
       # keeps the new realm's `parent`/`top` wired to the owning realm. The
       # Browser then re-points the iframe element at the new id (`__csimRebindFrameRealm`).
       def reload_frame_realm(old_id, parent_id, url, body, content_type)
-        if (fr = frame_realms.delete(old_id))
-          @realm_module_handles&.delete(old_id)
-          fr.dispose rescue nil
-        end
+        dispose_frame_realm(old_id)
         create_frame_realm(ctx, url, body, content_type, parent_id)
       end
 
+      # Tear down a single frame realm (e.g. a descendant frame destroyed when an
+      # ancestor frame re-navigates). No-op for nil/0/unknown ids.
+      def dispose_frame_realm(id)
+        return if id.nil? || id.zero?
+        # The frame's browsing context is going away — revoke the blob URLs it
+        # created (url-lifetime "Removing an iframe").
+        @browser.revoke_realm_blobs(id) rescue nil
+        @realm_module_handles&.delete(id)
+        @frame_realm_depths&.delete(id)
+        fr = frame_realms.delete(id)
+        fr.dispose rescue nil if fr
+        nil
+      end
+
       # One native microtask checkpoint — a checkpoint runs the queue until
       # empty, and rusty already performs one at the end of every top-level
       # eval/call (V8's default kAuto policy), so a single explicit checkpoint
@@ -492,6 +518,16 @@ module Capybara
         if @ctx
           begin
             @ctx.reset
+            # `@ctx.reset` swaps in a snapshot-fresh realm and `dispose_frame_realms`
+            # above tore down the visit's iframe realms — but V8 keeps those dead
+            # contexts as RECLAIMABLE GARBAGE: a per-frame realm (within_frame /
+            # `Isolate#create_context`) is a large GC root that V8's incremental
+            # GC won't collect between visits. Over a long run (esp. iframe-heavy
+            # pages) they pile toward the old-space cap, where the near-heap-limit
+            # GC thrashes instead of reclaiming. A full GC under pressure drops the
+            # used heap back to baseline (measured: ~450 MB -> ~150 MB, native
+            # contexts N -> 1). See `relieve_heap_pressure`.
+            relieve_heap_pressure
             attach_host_fns(@ctx)
             @ctx.eval('__csim_installWorker();')
             return @ctx
@@ -513,14 +549,7 @@ module Capybara
         # `ctx`), which rusty_racer's thread-confined isolates require. This
         # cold path is only the rare reset-failure fallback, so the inline
         # teardown isn't on the steady-state path.
-        if old
-          @@live_lock.synchronize { @@live.delete(old) }
-          begin
-            old.terminate rescue nil
-            old.dispose
-          rescue StandardError
-          end
-        end
+        dispose_ctx(old) if old
         @ctx = build_and_track_ctx
       end
 
@@ -529,6 +558,48 @@ module Capybara
       # path is the same operation.
       def reset_page = rebuild_ctx
 
+      # Memory-pressure threshold (MB) above which `rebuild_ctx` forces a full
+      # GC to reclaim dead per-frame realms (see the call site). Measured
+      # against used heap **+ external** (ArrayBuffer backing stores, image
+      # pixel buffers) — `used_heap_size` alone misses the external component,
+      # which on image-heavy specs is the bulk of the footprint. Default 1 GB:
+      # far above a normal single visit (~200-500 MB) so ordinary specs never
+      # trigger it, far below the 4 GB old-space cap so a multi-visit spec
+      # reclaims long before the near-heap-limit GC would thrash. `0` disables.
+      GC_PRESSURE_MB = (ENV['CSIM_V8_GC_PRESSURE_MB'] || '1024').to_i
+
+      # Opt-in heap accounting on every rebuild (CSIM_HEAP_DIAG). Resolved once
+      # at load (rule 3: don't re-read env per call); zero cost when off.
+      HEAP_DIAG = !ENV['CSIM_HEAP_DIAG'].nil?
+
+      # Forced full GC when V8-managed memory (used heap + external) crosses
+      # GC_PRESSURE_MB. The stat read is cheap (a counter snapshot every visit);
+      # the GC itself only fires once a multi-visit spec has actually piled up
+      # dead realms — measured at ~once per 25-50 iframe-heavy visits, reclaiming
+      # native contexts back to 1 and the heap to baseline — so the amortized
+      # cost is negligible while memory stays bounded. No-op on rusty < 0.1.9
+      # (no heap_statistics) or when disabled.
+      def relieve_heap_pressure
+        return unless GC_PRESSURE_MB.positive? && @ctx.heap_accounting?
+        s    = @ctx.heap_statistics
+        over = (s[:used_heap_size].to_i + s[:external_memory].to_i) > GC_PRESSURE_MB * 1_048_576
+        if HEAP_DIAG
+          warn(format('[csim heap] used=%dMB ext=%dMB native_ctx=%d over=%s',
+                      s[:used_heap_size].to_i >> 20, s[:external_memory].to_i >> 20,
+                      s[:number_of_native_contexts].to_i, over))
+        end
+        return unless over
+        @ctx.low_memory_notification
+        if HEAP_DIAG
+          a = @ctx.heap_statistics
+          warn(format('[csim heap]   -> after GC used=%dMB native_ctx=%d',
+                      a[:used_heap_size].to_i >> 20, a[:number_of_native_contexts].to_i))
+        end
+      rescue StandardError
+        # Older rusty without the diagnostics API, or a transient read failure —
+        # heap relief is best-effort, never fail a visit over it.
+      end
+
       # Built lazily on first use, on the calling (main) thread. There is no
       # pool / background pre-warm: under warm-compile the steady-state visit
       # reuses this one isolate via `Context#reset` (rebuild_ctx) and never
@@ -538,6 +609,7 @@ module Capybara
       # every isolate confined to one thread for its whole life. The one-time
       # synchronous build is ~3 ms.
       def ctx
+        return @ctx if @disposed   # don't resurrect a disposed runtime (closed window)
         @ctx ||= build_and_track_ctx
       end
 
@@ -548,11 +620,46 @@ module Capybara
         c
       end
 
+      # Terminate + dispose a tracked isolate and drop it from the at-exit
+      # `@@live` registry. Dispose FIRST and de-register only on success: if
+      # `dispose` raises (rescued), the isolate stays in `@@live` so the at_exit
+      # sweep retries it instead of leaking it un-disposed. Shared by the
+      # cold-rebuild fallback (`rebuild_ctx`) and `#dispose`.
+      def dispose_ctx(c)
+        return unless c
+        c.terminate rescue nil
+        c.dispose
+        @@live_lock.synchronize { @@live.delete(c) }
+      rescue StandardError
+      end
+
+      # Tear this runtime's isolate down for good. Each auxiliary window
+      # (`window.open` / a switched-into `target=_blank`) is its own Browser +
+      # V8Runtime + isolate; without this, closing the window reaped its
+      # background threads (Browser#dispose) but left the isolate ALIVE — the
+      # `@@live` at-exit registry holds a strong reference, so a bare GC never
+      # reclaimed it. Over a long suite those isolates (and their RSS)
+      # accumulated (measured: V8 isolate count 2 → 10, RSS ~2.7 → 6.6 GB across
+      # the Discourse suite). Idempotent; only ever called on teardown
+      # (Browser#dispose) — never on the per-test `reset_page` path, which
+      # reuses the isolate via `Context#reset`. The `ctx` getter stops rebuilding
+      # once `@disposed`, so a stray post-close call can't resurrect the isolate.
+      def dispose
+        return if @disposed
+        @disposed = true
+        dispose_frame_realms rescue nil
+        c, @ctx = @ctx, nil
+        dispose_ctx(c)
+      end
+
       # Per-call wall-clock cap (ms). Off by default. Opt in via
       # `CSIM_V8_CALL_TIMEOUT_MS=30000` for long-running suites where an
       # occasional JS-side infinite loop would otherwise stall the whole
       # run; the timeout converts the hang into a
-      # `RustyRacer::ScriptTerminatedError` on that one example. The
+      # `RustyRacer::ScriptTerminatedError` on that one example — whose
+      # `#message` / `#js_backtrace` (rusty >= 0.1.10) name the looping JS
+      # frame (function + source position), so an in-V8 hang is diagnosable
+      # from the failure alone, no live debugger attach needed. The
       # terminate escalates through any nested frames (it is
       # isolate-global by design), and the isolate itself stays healthy
       # for subsequent calls — csim treats a terminated call as fatal to
@@ -592,17 +699,15 @@ module Capybara
       # id (or nil on failure — then the bridge keeps its same-realm fallback).
       # The bridge maps `iframe.contentWindow` to `RustyRacer.contextGlobal(id)`.
       def attach_frame_realm_loader(c)
-        c.attach('__csim_createFrameRealm', ->(url, body, content_type, parent_id = 0) {
-          RuntimeShared.safe_call { create_frame_realm(c, url, body, content_type, parent_id) }
+        c.attach('__csim_createFrameRealm', ->(url, body, content_type, parent_id = 0, frame_name = nil, frame_doc_origin = nil, frame_location_origin = nil, js_url_source = nil) {
+          RuntimeShared.safe_call { create_frame_realm(c, url, body, content_type, parent_id, frame_name, frame_doc_origin, frame_location_origin, js_url_source) }
         })
         # Re-navigating an iframe (src/srcdoc reassigned) builds a fresh realm;
         # the bridge calls this to tear down the superseded one so it doesn't
         # linger in @frame_realms and get re-drained on every poll tick.
         # Disposing a non-executing child realm mid-callback is safe.
         c.attach('__csim_disposeFrameRealm', ->(id) {
-          @realm_module_handles&.delete(id)
-          fr = frame_realms.delete(id)
-          fr.dispose rescue nil if fr
+          dispose_frame_realm(id)   # also revokes the realm's blob URLs
           nil
         })
       end
@@ -613,8 +718,27 @@ module Capybara
       # state, point it at its own URL with the top frame as parent/top, then
       # load its document (running its scripts in the realm). Tracked for
       # event-loop draining + teardown.
-      def create_frame_realm(parent_ctx, url, body, content_type, parent_id = 0)
+      # Browsers cap nested browsing-context depth; with eager frame building a
+      # self-referential or pathologically nested iframe (`<iframe src=self>`)
+      # would otherwise build realms without bound and stall the settle loop.
+      # Depth is one more than the parent realm's (the main frame is depth 0).
+      MAX_FRAME_DEPTH = 16
+
+      def frame_realm_depths = (@frame_realm_depths ||= {})
+
+      def create_frame_realm(parent_ctx, url, body, content_type, parent_id = 0, frame_name = nil, frame_doc_origin = nil, frame_location_origin = nil, js_url_source = nil)
+        depth = (frame_realm_depths[parent_id] || 0) + 1
+        if depth > MAX_FRAME_DEPTH
+          @browser.log_console('warn', "iframe nesting depth #{depth} exceeds #{MAX_FRAME_DEPTH}; not building #{url}")
+          return nil
+        end
         realm = parent_ctx.create_context
+        # Record depth BEFORE loading the document: the frame's own scripts run
+        # during __csimLoadDocument below and may synchronously build NESTED frames
+        # (their create_frame_realm looks up this realm's depth as their parent's),
+        # so it must already be set or the nested depth undercounts and the cap
+        # never trips.
+        frame_realm_depths[realm.id] = depth
         # Re-evaling the snapshot source would redefine snapshot globals (e.g.
         # the `scrollX` accessor) and throw — re-entrantly. Only eval the
         # source on a bare no-snapshot dev ctx, where the realm boots empty.
@@ -638,8 +762,22 @@ module Capybara
           if (globalThis.#{HOST_NAMESPACE_NAME} && typeof globalThis.#{HOST_NAMESPACE_NAME}.contextGlobal === 'function') {
             var __parentWin = globalThis.#{HOST_NAMESPACE_NAME}.contextGlobal(#{parent_id.to_i});
             if (__parentWin) {
-              globalThis.parent = __parentWin;
-              globalThis.top    = __parentWin.top || __parentWin;
+              // Expose `parent`/`top` as THIS realm's WindowProxy for them (not the
+              // raw parent global) so `e.source === parent` holds and a frame's
+              // `parent.postMessage(...)` attributes the sender. `top` resolves
+              // through the parent's own top (already a proxy if the parent is a
+              // frame), unwrapped to its raw global then re-proxied for this realm.
+              var __NS = globalThis.#{HOST_NAMESPACE_NAME};
+              var __pf = globalThis.__csimFrameWindowProxyFor;
+              if (__pf && __NS && typeof __NS.contextOf === 'function') {
+                var __topRaw = __parentWin.top || __parentWin;
+                if (__topRaw && __topRaw.__csimRawWindow) __topRaw = __topRaw.__csimRawWindow;
+                globalThis.parent = __pf(__NS.contextOf(__parentWin)) || __parentWin;
+                globalThis.top    = __pf(__NS.contextOf(__topRaw)) || __topRaw;
+              } else {
+                globalThis.parent = __parentWin;
+                globalThis.top    = __parentWin.top || __parentWin;
+              }
             }
           }
         JS
@@ -648,8 +786,42 @@ module Capybara
         # HTML / control bytes survive (Ruby's String#inspect is NOT a faithful
         # JS string escaper — it mangles \a, \e, and binary bytes).
         realm.call('__csimUpdateLocation', url.to_s) unless url.to_s.empty?
+        # Set window.name from the container's `name` attribute BEFORE the document
+        # loads, so a frame whose load handler reads window.name to identify itself
+        # (declarative-shadow declarative-child-frame) sees it.
+        realm.call('__csimSetWindowName', frame_name.to_s) unless frame_name.nil?
+        # Seed the frame's document origin (opaque/inherited) BEFORE the document
+        # loads, so its load-time scripts read the right self.origin. nil → a
+        # real-URL frame whose origin is its own location origin.
+        realm.call('__csimSetDocumentOrigin', frame_doc_origin.to_s) unless frame_doc_origin.nil?
+        # The frame's location.origin (opaque "null" for about:blank / srcdoc /
+        # javascript:); decoupled from the location string so navigation is intact.
+        realm.call('__csimSetLocationOrigin', frame_location_origin.to_s) unless frame_location_origin.nil?
         realm.call('__csimLoadDocument', body.to_s, content_type.to_s)
+        # A `javascript:` URL frame: the initial empty document is now loaded and
+        # parent/top are wired, so evaluate the URL's script in the realm (global
+        # scope). Per HTML, only a STRING result navigates the frame to a new
+        # document built from it; any other result (incl. the common undefined)
+        # leaves the about:blank document, so only its side effects (e.g.
+        # `parent.foo()`) take effect. A throwing script is reported and left as a
+        # no-op rather than aborting the frame build.
+        unless js_url_source.nil?
+          begin
+            result = realm.eval(js_url_source.to_s)
+            realm.call('__csimLoadDocument', result, 'text/html') if result.is_a?(String)
+          rescue StandardError => e
+            @browser.log_console('warn', "javascript: URL frame threw: #{e.message}")
+          end
+        end
         frame_realms[realm.id] = realm
+        # Fire the nested document's window `load`. The frame's inline scripts ran
+        # during __csimLoadDocument and registered their `window.onload` (the usual
+        # `window.onload = () => parent.postMessage(...)` a frame reports back
+        # through); without firing it, an eagerly-built frame that the parent never
+        # touches would never run its load handler. Safe if no handler is set
+        # (dispatches to an empty listener list). Guarded so a frame whose load
+        # handler throws doesn't abort the build.
+        realm.call('__csimFireWindowLoad') rescue nil
         realm.id
       rescue StandardError => e
         @browser.log_console('warn', "frame realm load failed: #{e.message}")

data/lib/capybara/simulated/version.rb

@@ -2,6 +2,6 @@
 
 module Capybara
   module Simulated
-    VERSION = '0.3.0'
+    VERSION = '0.5.0'
   end
 end