dommy-rack 0.10.0 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cc970f04543db2ddf8d988cceaeacfc644fa3b04773655767e477512ba85deb
-  data.tar.gz: 5dd3d1215a44fd431b40fc62705c1ed8ef3d438b9321895c90980aa9cec574af
+  metadata.gz: 242882a8db41a841906a2292592dcf047941a3578e043cf9dc872d03b6649c77
+  data.tar.gz: 62adc178e7d8bffd1e4d923a13f75d130de05d12b953c43377c0d7dc48ee72c2
 SHA512:
-  metadata.gz: 7628031ea4b93483bfedb41fb5f716bf7ab80e2155d9505250b618fb20175952035d4c7570d1403895be39c69064213d27507f3d845cd0a2f18486b587b9726d
-  data.tar.gz: '0852d2605cb0919350c97a93e2d63992e856b3440831249632c66071787b9349def147cf08d3f862664f2fe8d1371807a14249a9637fc522f9ca5307a14e4e01'
+  metadata.gz: 41a58a2614a4608d75957cd777bf9e30d657cba682a90509c473627b50c5f88ad929c438afa10a5b54f641f26b7b4a8061280b567b84325ba23445543c895a32
+  data.tar.gz: 9e68474ae55c4051d0844da0ffea2c2df9e043a5e31cf86a6d52b805df78dd410110f3aab8bd006bc6690fc483474217154f1be3af037eab87c4e06c7e31dbf9

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.11.0 — 2026-09-11
+
+### Added
+- `Session#dialog_handler=` — answer the page's `alert` / `confirm` / `prompt`. The handler stays installed across navigations, so it also answers dialogs on pages loaded later.
+- Traced requests now carry spans from inside the app (controller, SQL, render, and the jobs and mails a request triggers), flushed with the request they belong to. See dommy-rails for the Rails-side instrumentation.
+
+### Fixed
+- A request whose app raises still closes its trace bracket, so the trace ends with the failure instead of an open request.
+- A subresource fetch made while a request is in flight keeps its own spans rather than attaching them to the outer request.
+- SQL bind values, when enabled, are masked through the trace's own sensitive-key filter — the same one that masks form params.
+- A snapshot's content is stored before its artifact event is written, so a trace read back straight away is complete.
+
 ## 0.10.0 — 2026-07-13
 
 ### Added

data/lib/dommy/rack/http_exchange.rb

@@ -17,6 +17,13 @@ module Dommy
     #   it as `last_request` and fires request listeners; an async path routes the
     #   same notification through the scheduler inbox).
     # * `on_response` — observe the Response (response listeners).
+    # * `on_abort`    — observe an env whose `@app.call` raised (no Response).
+    # * `on_app_start` / `on_app_finish` — bracket the app call ITSELF. Unlike
+    #   the observation hooks above (which an async path routes through the
+    #   scheduler inbox, i.e. LATER and on the page thread), these run inline,
+    #   on whatever thread calls the app, so per-request state a hook installs
+    #   for the app to find — the Trace's thread-local — is live exactly while
+    #   the app runs. Anything they need to hand back travels on the env.
     #
     # Reload bookkeeping (`last_request_args`) and history/document application are
     # NOT here: they belong to the page thread and stay in Session / Navigation.
@@ -24,13 +31,17 @@ module Dommy
       # @param headers [HeaderStore, Hash] anything responding to `merge(overrides)
       #   -> Hash`; the Session passes its live HeaderStore for the page path, a
       #   plain snapshot Hash for a worker path.
-      def initialize(app:, config:, cookie_jar:, headers:, on_request: nil, on_response: nil)
+      def initialize(app:, config:, cookie_jar:, headers:, on_request: nil, on_response: nil, on_abort: nil,
+        on_app_start: nil, on_app_finish: nil)
         @app = app
         @config = config
         @cookie_jar = cookie_jar
         @headers = headers
         @on_request = on_request
         @on_response = on_response
+        @on_abort = on_abort
+        @on_app_start = on_app_start
+        @on_app_finish = on_app_finish
       end
 
       # Perform one request and return its Response. `headers` are per-request
@@ -45,7 +56,20 @@ module Dommy
           cookie_string: @cookie_jar.cookies_for(absolute_url)
         )
         @on_request&.call(env)
-        status, response_headers, response_body = @app.call(env)
+        # on_app_start opened a request bracket (the Trace exposes itself
+        # thread-locally inside it); an app exception must still close it, or
+        # per-request state leaks past the failed request. Close it BEFORE
+        # on_abort, which reads what the bracket left on the env. The exception
+        # itself propagates unchanged.
+        @on_app_start&.call(env)
+        begin
+          status, response_headers, response_body = @app.call(env)
+        rescue ::Exception # rubocop:disable Lint/RescueException -- close the bracket for ANY abort
+          @on_app_finish&.call(env)
+          @on_abort&.call(env)
+          raise
+        end
+        @on_app_finish&.call(env)
         response = Response.new(status, response_headers, response_body, url: absolute_url)
         response.set_cookie_strings.each do |sc|
           @cookie_jar.store_from_header(sc, absolute_url)

data/lib/dommy/rack/session.rb

@@ -49,7 +49,7 @@ module Dommy
         keyword_init: true
       )
 
-      attr_reader :last_request, :last_response, :history, :trace
+      attr_reader :last_request, :last_response, :history, :trace, :dialog_handler
 
       # A factory `->(session) { js_runtime_host }` that binds a JS runtime to a
       # session for `javascript: true`. dommy-js-quickjs installs one when its
@@ -129,6 +129,9 @@ module Dommy
         @scope_stack = []
         @request_listeners = []
         @response_listeners = []
+        @abort_listeners = []
+        @app_start_listeners = []
+        @app_finish_listeners = []
         @document_loaded_listeners = []
         @subresource_allowlist = []        # hosts allowed for cross-origin <script>/fetch/XHR
         @blocked_subresource_hosts = []    # cross-origin hosts declined since the last reset (awaiting a decision)
@@ -145,6 +148,14 @@ module Dommy
       # verbs drive JS handlers.
       def javascript? = !@js_runtime.nil?
 
+      # Supply native dialog answers to the current page and to every page
+      # subsequently installed while the handler is active. The Capybara driver
+      # uses this around accept_confirm / dismiss_confirm (and alert/prompt).
+      def dialog_handler=(handler)
+        @dialog_handler = handler
+        @current_window.dialog_handler = handler if @current_window
+      end
+
       # The bound JS runtime (a SessionRuntime), or nil when JS is disabled.
       # Exposed for the Trace to subscribe to the runtime's console / js_error /
       # script seams; not part of the everyday browsing API.
@@ -511,6 +522,35 @@ module Dommy
         self
       end
 
+      # Register a callback invoked with the Rack env when a request ABORTS
+      # (the app raised, so no Response exists). Every on_request has a
+      # matching on_response OR on_abort — per-request state can bracket on
+      # the pair.
+      def on_abort(&block)
+        @abort_listeners << block
+        self
+      end
+
+      # Register callbacks that BRACKET the Rack app call itself, with the env.
+      # Unlike on_request / on_response (which the async-network path routes
+      # through the scheduler inbox, so they run after the fact on the page
+      # thread), these fire inline on whatever thread calls the app — which is
+      # the only place a hook can install per-request state the app itself will
+      # find, such as the Trace's thread-local. State they need to hand to the
+      # later on_response travels on the env, not on the listener's owner.
+      def on_app_start(&block)
+        @app_start_listeners << block
+        self
+      end
+
+      # The matching close. Runs for a successful AND a raising app call, and
+      # before on_abort so the aborted request's observer sees what the bracket
+      # left on the env.
+      def on_app_finish(&block)
+        @app_finish_listeners << block
+        self
+      end
+
       # Register a callback invoked with the new Window each time a navigation
       # installs an HTML document (visit, redirects, link clicks, form submits,
       # back/forward, reload, meta refresh). This is the page-load lifecycle
@@ -680,6 +720,15 @@ module Dommy
           },
           on_response: lambda { |response|
             @response_listeners.each { |cb| cb.call(response) }
+          },
+          on_abort: lambda { |env|
+            @abort_listeners.each { |cb| cb.call(env) }
+          },
+          on_app_start: lambda { |env|
+            @app_start_listeners.each { |cb| cb.call(env) }
+          },
+          on_app_finish: lambda { |env|
+            @app_finish_listeners.each { |cb| cb.call(env) }
           }
         )
       end
@@ -728,6 +777,7 @@ module Dommy
         @current_url = final_url
         if response.html?
           @current_window = response.window
+          @current_window.dialog_handler = @dialog_handler
           # Set the geometry mode before scripts boot so the very first
           # getBoundingClientRect a framework calls already sees it.
           @current_window.approximate_layout = @approximate_layout if @approximate_layout
@@ -848,6 +898,19 @@ module Dommy
           },
           on_response: sched && lambda { |response|
             sched.post_external { @response_listeners.each { |cb| cb.call(response) } }
+          },
+          on_abort: sched && lambda { |env|
+            sched.post_external { @abort_listeners.each { |cb| cb.call(env) } }
+          },
+          # The app-call bracket is NOT posted to the inbox: it has to be open
+          # while the worker thread is inside the app, which a page-thread
+          # callback scheduled for later can never be. Its listeners touch only
+          # thread-locals and the env, so running them off-thread is safe.
+          on_app_start: lambda { |env|
+            @app_start_listeners.each { |cb| cb.call(env) }
+          },
+          on_app_finish: lambda { |env|
+            @app_finish_listeners.each { |cb| cb.call(env) }
           }
         )
       end

data/lib/dommy/rack/trace/formatter.rb

@@ -35,6 +35,7 @@ module Dommy
             when :console then "CONSOLE [#{data[:level]}] #{data[:text]}"
             when :js_error then "JS_ERROR #{data[:message]}"
             when :dom then dom(data)
+            when :span then "SPAN [#{data[:kind]}] #{data[:label]} (#{data[:duration_ms]}ms)"
             else "#{event.type.to_s.upcase} #{compact(data)}"
             end
           end

data/lib/dommy/rack/trace.rb

@@ -36,6 +36,16 @@ module Dommy
       LEVELS = %i[off actions verbose].freeze
       REALM_TYPES = %i[script console js_error].freeze
 
+      # The app-call bracket's channels. The thread-locals are how in-app
+      # instrumentation (dommy-rails' TraceInstrumentation) finds the trace
+      # whose request is running on THIS thread; the env keys carry that
+      # request's spans — and the bracket's saved outer values — back to the
+      # response listener, which may run later and on another thread.
+      TRACE_THREAD_KEY = :__dommy_active_trace__
+      SPANS_THREAD_KEY = :__dommy_trace_spans__
+      SPANS_ENV_KEY = "dommy.trace.spans"
+      BRACKET_ENV_KEY = "dommy.trace.outer_bracket"
+
       # Build a Trace, wire it to the session's (and its runtime's) seams, and
       # return it. A `:off` trace wires nothing.
       def self.attach(session, level: :verbose, dom: false, filter: ParamFilter::DEFAULT, snapshots: false)
@@ -68,6 +78,11 @@ module Dommy
 
         @session.on_request { |env| __internal_on_request(env) }
         @session.on_response { |response| __internal_on_response(response) }
+        @session.on_abort { |env| __internal_on_abort(env) } if @session.respond_to?(:on_abort)
+        if @session.respond_to?(:on_app_start)
+          @session.on_app_start { |env| __internal_open_app_bracket(env) }
+          @session.on_app_finish { |env| __internal_close_app_bracket(env) }
+        end
 
         runtime = @session.respond_to?(:__internal_js_runtime) ? @session.__internal_js_runtime : nil
         if runtime
@@ -90,8 +105,9 @@ module Dommy
 
         @seq += 1
         @action_seq = @seq
-        @events << Event.new(seq: @seq, t: now_ms, wall_ms: monotonic_ms, type: :action, name: verb,
+        event = Event.new(seq: @seq, t: now_ms, wall_ms: monotonic_ms, type: :action, name: verb,
           action_seq: nil, data: {verb: verb, label: label, source: __internal_caller_source})
+        @events << event
         nil
       end
 
@@ -117,6 +133,10 @@ module Dommy
         nil
       end
 
+      # The configured sensitive-key filter — instrumentation layers mask
+      # values they record (SQL binds) with the SAME rules as form params.
+      def __internal_param_filter__ = @param_filter
+
       # --- Queries (read-only views over the event stream) ---
 
       def http = events_of(:http)
@@ -139,7 +159,7 @@ module Dommy
       def to_s = to_text
 
       def to_ndjson(status: "ok", wall_time: nil, metadata: nil)
-        inline = @artifacts.transform_values { |content| {content: content, encoding: "utf-8"} }
+        inline = InlineArtifacts.new(@artifacts)
         Ndjson.new(@events, level: @level, wall_time: wall_time, metadata: metadata,
           artifacts: inline, end_wall_ms: monotonic_ms).document(status: status)
       end
@@ -166,38 +186,109 @@ module Dommy
         dir
       end
 
+      # Lazily shapes an artifact's inline emission fields ({content:,
+      # encoding:}) by seq — the single owner of the inline wire shape that
+      # to_ndjson hands the serializer.
+      class InlineArtifacts
+        def initialize(artifacts)
+          @artifacts = artifacts
+        end
+
+        def [](seq)
+          content = @artifacts[seq]
+          content ? {content: content, encoding: "utf-8"} : nil
+        end
+      end
+
+      # Instrumentation entry point (reached via the thread-local): buffer an
+      # inside-the-request span (controller/db/render — anything an
+      # instrumentation layer measured). Emitted as completed span events,
+      # parented to the enclosing :http event, when the response arrives —
+      # spans finish before the response exists, so they can't reference it
+      # any earlier. Public; the surrounding request seams stay private.
+      #
+      # The buffer is the one the app-call bracket published thread-locally,
+      # not an ivar: a subresource fetch (JS `fetch`/XHR) runs the app on a
+      # network worker thread, so a per-Trace buffer would be a race AND would
+      # mis-attribute those spans to whatever the page thread was doing.
+      def __internal_record_span__(kind:, label:, duration_ms:, data: nil)
+        buffer = Thread.current[SPANS_THREAD_KEY]
+        return if @level == :off || buffer.nil?
+
+        buffer << {kind: kind.to_s, label: label.to_s,
+                   duration_ms: duration_ms.to_f.round(2), data: data}
+        nil
+      end
+
       private
 
       # Emit one event, gated by the recording level, and return it (or nil if
       # gated out). `seq` is the canonical order; `t` is the virtual clock if a
       # window exists.
-      def __internal_emit(type, data, name: nil, window: nil)
+      # `artifact:` carries the event's captured content (a DOM snapshot),
+      # stored under the event's seq alongside it.
+      def __internal_emit(type, data, name: nil, window: nil, artifact: nil)
         return if @level == :off
         return if REALM_TYPES.include?(type) && @level != :verbose
 
         @seq += 1
         event = Event.new(seq: @seq, t: window&.scheduler&.now_ms, wall_ms: monotonic_ms, type: type,
           name: name, action_seq: @action_seq, data: data)
+        @artifacts[event.seq] = artifact if artifact
         @events << event
         event
       end
 
-      # on_request fires before its on_response (single-threaded, per redirect
-      # hop), so stash the method/path here and emit the `:http` event when the
-      # response arrives with its status.
+      # on_request fires before its on_response (per redirect hop, in order),
+      # so stash the method/path here and emit the `:http` event when the
+      # response arrives with its status. The env is stashed too: the app-call
+      # bracket leaves this request's spans on it, and on the async-network
+      # path this listener runs after the app already finished.
       def __internal_on_request(env)
         @pending_request = {
           method: env["REQUEST_METHOD"],
           path: env["PATH_INFO"],
-          query: presence(env["QUERY_STRING"])
+          query: presence(env["QUERY_STRING"]),
+          env: env
         }
         nil
       end
 
+      # --- the app-call bracket (runs on the thread that calls the app) ---
+
+      # Expose this trace to in-app instrumentation (dommy-rails subscribes to
+      # ActiveSupport::Notifications and records spans through the thread-local)
+      # for exactly the duration of the app call, and give it a buffer to fill.
+      # The buffer rides on the env, so the response listener finds this
+      # request's spans even when the app ran on another thread.
+      #
+      # The previous values are saved rather than assumed nil: a nested request
+      # (an app that drives a Dommy session of its own) must restore its
+      # caller's bracket instead of tearing it down.
+      def __internal_open_app_bracket(env)
+        return if @level == :off
+
+        spans = []
+        env[SPANS_ENV_KEY] = spans
+        env[BRACKET_ENV_KEY] = [Thread.current[TRACE_THREAD_KEY], Thread.current[SPANS_THREAD_KEY]]
+        Thread.current[TRACE_THREAD_KEY] = self
+        Thread.current[SPANS_THREAD_KEY] = spans
+        nil
+      end
+
+      def __internal_close_app_bracket(env)
+        saved = env.delete(BRACKET_ENV_KEY)
+        return if saved.nil?
+
+        Thread.current[TRACE_THREAD_KEY] = saved[0]
+        Thread.current[SPANS_THREAD_KEY] = saved[1]
+        nil
+      end
+
       def __internal_on_response(response)
         request = @pending_request || {}
         @pending_request = nil
-        __internal_emit(:http, {
+        http = __internal_emit(:http, {
           method: request[:method],
           path: request[:path] || path_of(response.url),
           query: request[:query],
@@ -206,6 +297,36 @@ module Dommy
           location: response.location_header,
           set_cookie: response.set_cookie_strings.map { |raw| cookie_name(raw) }
         })
+        __internal_flush_spans(http, request[:env])
+      end
+
+      # The request never produced a Response (the app raised): record the
+      # aborted request itself, with the spans the closed bracket left on the
+      # env, so the trace shows what ran before the exception.
+      def __internal_on_abort(env)
+        request = @pending_request || {}
+        @pending_request = nil
+        http = __internal_emit(:http, {
+          method: request[:method] || env["REQUEST_METHOD"],
+          path: request[:path] || env["PATH_INFO"],
+          query: request[:query],
+          status: nil,
+          aborted: true
+        })
+        __internal_flush_spans(http, request[:env] || env)
+      end
+
+      def __internal_flush_spans(http_event, env)
+        spans = env && env.delete(SPANS_ENV_KEY)
+        return if spans.nil? || spans.empty? || http_event.nil?
+
+        spans.each do |span|
+          payload = {kind: span[:kind], label: span[:label],
+                     duration_ms: span[:duration_ms], parent: http_event.seq}
+          payload.merge!(span[:data]) if span[:data]
+          __internal_emit(:span, payload)
+        end
+        nil
       end
 
       def __internal_on_document(window)
@@ -219,10 +340,9 @@ module Dommy
         html = @session.document&.to_html
         return unless html
 
-        event = __internal_emit(:artifact,
+        __internal_emit(:artifact,
           {kind: "dom_snapshot", label: "DOM #{@session.current_url}", content_type: "text/html"},
-          window: window)
-        @artifacts[event.seq] = html if event
+          window: window, artifact: html)
       end
 
       # --- DOM observation ---

data/lib/dommy/rack/version.rb

@@ -2,6 +2,6 @@
 
 module Dommy
   module Rack
-    VERSION = "0.10.0"
+    VERSION = "0.11.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dommy-rack
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.11.0
 platform: ruby
 authors:
 - takahashim
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.11.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.11.0
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
@@ -101,7 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.10
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Rack-backed browser session layer for Dommy
 test_files: []