dommy-rack 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c964baa96ffd06e89b381a195f92728d59425d855c9eed0f2f60a901b405b82
-  data.tar.gz: 3883f5b58d4bc7817443486a46f597f4aa8204b4159f46e632fc998f084585d6
+  metadata.gz: 3cc970f04543db2ddf8d988cceaeacfc644fa3b04773655767e477512ba85deb
+  data.tar.gz: 5dd3d1215a44fd431b40fc62705c1ed8ef3d438b9321895c90980aa9cec574af
 SHA512:
-  metadata.gz: 6a342735719087256ae5ce571ec435b69b0a4e6ce264f400db0a6bc40baaa84cf36889769701ad32619d4694e0075e64e3dfe2bd3eaecffb84045bb66d85fd99
-  data.tar.gz: 7ed6fa76e4123a4bb13bdce963b2d657e58f6639c19c980952d42081d191e19356c7cdb9e9ae9781443afc83a3545c13798db339ffe247624f2970692269e40e
+  metadata.gz: 7628031ea4b93483bfedb41fb5f716bf7ab80e2155d9505250b618fb20175952035d4c7570d1403895be39c69064213d27507f3d845cd0a2f18486b587b9726d
+  data.tar.gz: '0852d2605cb0919350c97a93e2d63992e856b3440831249632c66071787b9349def147cf08d3f862664f2fe8d1371807a14249a9637fc522f9ca5307a14e4e01'

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.10.0 — 2026-07-13
+
+### Added
+- **In-process WebSockets:** a same-origin `new WebSocket(url)` on a page connects to the Rack app itself over a real RFC 6455 handshake, so ActionCable's full stack (cookie auth, origin check, cable event loop) runs unmodified and Turbo Streams broadcasts work in tests. Cross-origin URLs keep the in-memory stub.
+- **Joint session/window history:** same-document (`pushState`) navigations appear in the session history and `current_url`, and `Session#back` / `#forward` traverse them on the live page (Turbo Drive's restoration path) while document boundaries still re-request — matching a browser tab's single history list. JS-initiated traversal (`history.back()`) stays in sync.
+- `Session#dispose` — full teardown (JS runtimes plus live WebSocket transports); `#dispose_js` remains JS-only.
+
+### Fixed
+- Only `BUTTON` / `INPUT` elements are treated as submit buttons.
+
 ## 0.9.0 — 2026-06-22
 
 Versioned in lockstep with [`dommy`](https://github.com/takahashim/dommy) 0.9.0.

data/lib/dommy/rack/history.rb

@@ -2,43 +2,80 @@
 
 module Dommy
   module Rack
-    # Browser-tab-style navigation history: an ordered stack of visited URLs
-    # with a cursor. Visiting a new URL truncates any forward entries.
+    # Browser-tab-style navigation history: ONE ordered stack covering both
+    # full-document navigations and same-document (pushState) entries, like a
+    # real tab's joint history. Each entry remembers which window it belongs
+    # to and that window's own history index, so Session#back / #forward can
+    # decide between a popstate traversal (same live document — Turbo Drive's
+    # restoration path) and a full re-request (document boundary).
     class History
+      # `window` / `windex` tie the entry to a page and its window.history
+      # cursor position; Session#back / #forward traverse in-page (popstate)
+      # exactly when the target entry's window IS the live current window.
+      Entry = Struct.new(:url, :window, :windex)
+
       def initialize
         @stack = []
         @index = -1
       end
 
-      def push(url)
+      def push(url, window: nil, windex: nil)
         kept = @index >= 0 ? @stack[0..@index] : []
-        @stack = kept + [url]
+        @stack = kept + [Entry.new(url, window, windex)]
         @index = @stack.size - 1
         url
       end
 
-      # Move the cursor back one entry and return that URL, or nil at the start.
+      # Move the cursor back/forward one entry and return that Entry, or nil
+      # at the edge (Session picks the traversal mechanism from it).
       def back
         return nil if @index <= 0
 
         @index -= 1
-        current
+        current_entry
       end
 
-      # Move the cursor forward one entry and return that URL, or nil at the end.
       def forward
         return nil if @index >= @stack.size - 1
 
         @index += 1
-        current
+        current_entry
+      end
+
+      # replaceState: the current entry's URL changes in place.
+      def replace_current_url(url)
+        current_entry&.url = url
+        url
+      end
+
+      # Re-bind the current entry to a fresh window (a revisit re-loaded the
+      # URL into a new document), so later same-document sync matches it.
+      def rebind_current(window:, windex:)
+        entry = current_entry
+        return unless entry
+
+        entry.window = window
+        entry.windex = windex
       end
 
-      def current
+      # Mirror a traversal the page itself performed (JS history.back()):
+      # move the cursor to the entry recorded for (window, windex). No-op
+      # when unknown (e.g. an entry created before sync was installed).
+      def sync_to(window, windex)
+        i = @stack.index { |e| e.window.equal?(window) && e.windex == windex }
+        @index = i if i
+        current_entry
+      end
+
+      def current_entry
         @stack[@index] if @index >= 0
       end
 
+      # URL-shaped views, kept for compatibility with existing callers.
+      def current = current_entry&.url
+
       def entries
-        @stack.dup
+        @stack.map(&:url)
       end
     end
   end

data/lib/dommy/rack/navigation.rb

@@ -50,7 +50,7 @@ module Dommy
 
       # Perform a navigation, following redirects per session policy, then
       # apply the final response to the session (updating document + history).
-      def navigate(method:, url:, params: nil, body: nil, headers: {})
+      def navigate(method:, url:, params: nil, body: nil, headers: {}, replace: false)
         return navigate_about(url.to_s) if url.to_s.start_with?("about:")
 
         verb = method.to_s.upcase
@@ -67,7 +67,9 @@ module Dommy
         check_same_origin!(target)
 
         response, final_url = run(method: verb, url: target, params: params, body: body, headers: headers)
-        @session.apply_navigation_response(response, final_url)
+        # replace: a location.replace() / reload() / redirect updates the current
+        # history entry in place rather than pushing a new one.
+        @session.apply_navigation_response(response, final_url, replace: replace)
         maybe_follow_meta_refresh(response) || response
       end
 

data/lib/dommy/rack/session.rb

@@ -6,6 +6,29 @@ require "tmpdir"
 
 module Dommy
   module Rack
+    # The NavigationDelegate (Dommy::Navigation port) attached to each page's
+    # window: it forwards a page-initiated navigation/traversal intent to the
+    # owning Session (which defers and performs it at the next drain). Bound to
+    # the specific window so a stale, navigated-away page cannot steer the
+    # session — the Session checks window identity before recording.
+    class PageNavigationDelegate
+      def initialize(session, window)
+        @session = session
+        @window = window
+      end
+
+      def navigate(url:, source:, method: "GET", body: nil, params: nil, enctype: nil, headers: {}, replace: false)
+        @session.__enqueue_page_navigation__(@window, {
+          url: url, method: method, body: body, params: params, enctype: enctype,
+          headers: headers, replace: replace, source: source
+        })
+      end
+
+      def traverse(delta)
+        @session.__enqueue_page_traverse__(@window, delta)
+      end
+    end
+
     # A single browser-like session over a Rack application. Owns the current
     # URL, document, cookie jar, persistent header store, and history; delegates
     # URL/redirect logic to Navigation and form data collection to FormSubmission.
@@ -141,6 +164,7 @@ module Dommy
       # #advance_time.
       def settle
         require_js!.settle
+        __flush_page_navigation__
         self
       end
 
@@ -156,12 +180,41 @@ module Dommy
       def js_errors = @js_runtime ? @js_runtime.js_errors : []
       def console = @js_runtime ? @js_runtime.console : []
 
-      # Dispose the JS runtime(s). Safe to call when JS is disabled.
+      # Full session teardown: the JS runtime(s) plus any live WebSocket
+      # transports. Safe to call when JS is disabled, and repeatedly.
+      def dispose
+        Array(@live_websocket_transports).each(&:dispose)
+        @live_websocket_transports = nil
+        dispose_js
+      end
+
+      # Dispose the JS runtime(s) only. Safe to call when JS is disabled.
       def dispose_js
         @js_runtime&.dispose
         @js_runtime = nil
       end
 
+      # Factory for the window's websocket_connector seam (installed per
+      # realm by SessionRuntime): a same-origin `new WebSocket(url)` connects
+      # to the Rack app itself over rack.hijack (see WebSocketTransport), so
+      # ActionCable-backed features (Turbo Streams broadcasts, …) work
+      # in-process. A cross-origin URL returns nil, leaving the WebSocket on
+      # its in-memory stub.
+      def __internal_websocket_connector(window)
+        lambda do |ws, url, _protocols|
+          base = @current_url || default_host
+          target = WebSocketTransport.rack_target(url, base: base)
+          next nil unless target
+
+          transport = WebSocketTransport.new(
+            app: @app, ws: ws, scheduler: window.scheduler, url: target,
+            origin: Url.origin(target), cookie_string: @cookie_jar.cookies_for(target.to_s)
+          )
+          (@live_websocket_transports ||= []) << transport
+          transport
+        end
+      end
+
       # --- Config readers used by collaborators ---
 
       def default_host = @config.default_host
@@ -261,8 +314,8 @@ module Dommy
         result
       end
 
-      def navigate(method: "GET", url:, params: nil, body: nil, headers: {})
-        @navigation.navigate(method: method, url: url, params: params, body: body, headers: headers)
+      def navigate(method: "GET", url:, params: nil, body: nil, headers: {}, replace: false)
+        @navigation.navigate(method: method, url: url, params: params, body: body, headers: headers, replace: replace)
       end
 
       def reload
@@ -273,14 +326,63 @@ module Dommy
         response
       end
 
+      # Traverse the joint history like a browser's back button: a
+      # same-document target within the LIVE page (a Turbo Drive pushState
+      # entry) moves window.history and fires popstate — Turbo's restoration
+      # visit runs, no full request; a target across a document boundary
+      # re-requests the URL. Returns the destination URL, or nil at the edge.
+      # A JS session may need `settle` afterwards for the restoration fetch.
       def back
-        url = @history.back
-        @navigation.revisit(url) if url
+        traverse_history(:back)
       end
 
       def forward
-        url = @history.forward
-        @navigation.revisit(url) if url
+        traverse_history(:forward)
+      end
+
+      # --- NavigationDelegate port (see Dommy::Navigation) ---
+
+      # The delegate attached to each page's window (in SessionRuntime). A
+      # page-initiated navigation — a JS `location.href=` / `form.submit()`, a
+      # submitted form, an activated `<a>` — routes here. Navigation is a task:
+      # performing it synchronously could dispose the JS realm still on the
+      # stack, so it is recorded and performed at the next drain (#after_interaction
+      # / #settle), exactly like the standalone Browser.
+      def __navigation_delegate_for__(window)
+        PageNavigationDelegate.new(self, window)
+      end
+
+      def __enqueue_page_navigation__(window, nav)
+        # A retained handle to a navigated-away page must not steer the session.
+        return unless window.equal?(@current_window)
+
+        @pending_navigation = nav
+      end
+
+      def __enqueue_page_traverse__(window, delta)
+        return unless window.equal?(@current_window)
+
+        @pending_navigation = {traverse: delta}
+      end
+
+      # Perform a recorded page navigation, if any. Called after the JS runtime
+      # drains so the document/realm swap never runs with the outgoing realm's
+      # JS on the stack.
+      def __flush_page_navigation__
+        nav = @pending_navigation
+        return unless nav
+
+        @pending_navigation = nil
+        if nav.key?(:traverse)
+          traverse_history(nav[:traverse].negative? ? :back : :forward)
+        else
+          perform_page_navigation(nav)
+        end
+      rescue CrossOriginError, UnsupportedURLError, InvalidFormError, TooManyRedirectsError
+        # A page-initiated navigation that is blocked, unsupported, or loops on
+        # redirects is dropped (a browser blocks/abandons it); it must not crash
+        # the drain the way a Ruby-driven `visit` (which re-raises) does.
+        nil
       end
 
       # --- Basic request API (navigates, updating page state) ---
@@ -582,6 +684,27 @@ module Dommy
         )
       end
 
+      # One step of the joint back/forward traversal (see #back).
+      def traverse_history(direction)
+        target = direction == :back ? @history.back : @history.forward
+        return nil unless target
+
+        if target.window&.equal?(@current_window) && target.windex
+          begin
+            @history_traversing = true
+            @current_window.history.__internal_go_to__(target.windex)
+          ensure
+            @history_traversing = false
+          end
+          @current_url = target.url
+          @js_runtime&.drain
+        else
+          @navigation.revisit(target.url)
+        end
+        target.url
+      end
+      private :traverse_history
+
       # Build a worker-safe thunk that fetches `target` (already absolute) and
       # returns the Response, for the async-network path. Called on the page
       # thread: it enforces same-origin and captures a header snapshot here, then
@@ -600,7 +723,7 @@ module Dommy
 
       # Apply a final navigation response: update last_response, current_url,
       # the document (HTML only), and the history stack.
-      def apply_navigation_response(response, final_url, push_history: true)
+      def apply_navigation_response(response, final_url, push_history: true, replace: false)
         @last_response = response
         @current_url = final_url
         if response.html?
@@ -612,9 +735,53 @@ module Dommy
           # DOMContentLoaded) run, so CSS-driven computed styles and :visible
           # are correct from the first observation.
           install_stylesheet_loading(@current_window) if load_stylesheets?
+          # The history entry exists and the window-history sync is live
+          # BEFORE scripts boot: Turbo's replaceState-on-start then lands on
+          # THIS entry, and its pushState navigations append after it.
+          windex = @current_window.history.__internal_index__
+          if replace
+            # location.replace() / reload() / a redirect: overwrite the current
+            # entry's URL and rebind it to the new document (no new entry).
+            @history.replace_current_url(final_url)
+            @history.rebind_current(window: @current_window, windex: windex)
+          elsif push_history
+            @history.push(final_url, window: @current_window, windex: windex)
+          else
+            # A revisit re-loaded this URL into a fresh document: re-bind the
+            # existing entry so traversal sync matches the live window.
+            @history.rebind_current(window: @current_window, windex: windex)
+          end
+          install_history_sync(@current_window)
           @document_loaded_listeners.each { |cb| cb.call(@current_window) }
+        elsif replace
+          @history.replace_current_url(final_url)
+        elsif push_history
+          @history.push(final_url)
+        end
+      end
+
+      # Mirror the page's same-document history operations (Turbo Drive's
+      # pushState navigations, JS history.back()) into the session: the joint
+      # history gains/updates entries and current_url follows, so
+      # `browser.current_path` and `browser.back` see what a browser's URL
+      # bar and back button would. Guarded against echo while the session
+      # itself drives a traversal, and against a stale window — a retained
+      # handle to a navigated-away page must not touch the session's state.
+      def install_history_sync(window)
+        window.history.__internal_on_change__ = lambda do |kind, url|
+          next if @history_traversing
+          next unless window.equal?(@current_window)
+
+          @current_url = url
+          case kind
+          when :push
+            @history.push(url, window: window, windex: window.history.__internal_index__)
+          when :replace
+            @history.replace_current_url(url)
+          when :traverse
+            @history.sync_to(window, window.history.__internal_index__)
+          end
         end
-        @history.push(final_url) if push_history
       end
 
       # Wire same-origin CSS loading for a freshly installed document: fill
@@ -659,6 +826,7 @@ module Dommy
       # before the next line. A no-op when JS is disabled (the mixin default).
       def after_interaction
         @js_runtime&.drain
+        __flush_page_navigation__
       end
 
       private
@@ -721,6 +889,43 @@ module Dommy
         @current_url ? {"Referer" => @current_url} : {}
       end
 
+      # Carry out a page-initiated navigation recorded by the delegate: resolve
+      # the target, skip non-http(s) schemes (javascript:/mailto:/data:) and a
+      # bare same-page fragment link, then navigate — folding form params into
+      # the query (GET) or body (POST) as usual.
+      def perform_page_navigation(nav)
+        target = resolve_document_url(nav[:url])
+        return unless %w[http https].include?(uri_scheme(target))
+        return if nav[:params].nil? && same_page_fragment?(target)
+
+        method = (nav[:method] || "GET").to_s.upcase
+        params = nav[:params]
+        method, params = apply_delegate_method_override(method, params) if params
+        navigate(method: method, url: target, params: params, body: nav[:body],
+                 headers: referer_headers, replace: nav[:replace])
+      end
+
+      # The delegate path serializes forms through core FormSubmission, which
+      # doesn't know the session's method-override policy; apply it here so a
+      # Rails `_method` hidden field turns a POST into PATCH/PUT/DELETE even for
+      # an app without Rack::MethodOverride — matching the non-delegate submit.
+      def apply_delegate_method_override(method, params)
+        return [method, params] unless method == "POST" && @config.respect_method_override
+
+        pairs = params.dup
+        i = pairs.index { |name, _| name == @config.method_override_param }
+        return [method, params] unless i
+
+        override = pairs.delete_at(i)[1].to_s.upcase
+        %w[PATCH PUT DELETE].include?(override) ? [override, pairs] : [method, params]
+      end
+
+      def uri_scheme(url)
+        URI.parse(url).scheme.to_s.downcase
+      rescue URI::InvalidURIError
+        ""
+      end
+
       # A link to the current page that differs only by fragment does not
       # issue a request (browser behavior).
       def same_page_fragment?(target)
@@ -763,10 +968,10 @@ module Dommy
       # A <button> defaults to type=submit; an <input> submits only for
       # type=submit or type=image.
       def submit_button?(button)
-        if button.tag_name == "BUTTON"
-          button.type == "submit"
-        else
-          %w[submit image].include?(button.type)
+        case button.tag_name
+        when "BUTTON" then button.type == "submit"
+        when "INPUT" then %w[submit image].include?(button.type)
+        else false
         end
       end
 

data/lib/dommy/rack/session_runtime.rb

@@ -133,6 +133,10 @@ module Dommy
         if (window = doc&.default_view)
           rt.install_window(window)
           rt.install_browser_globals
+          # Page-initiated navigations (JS location.href=, form submit, activated
+          # <a>) route through the core NavigationDelegate port to the session,
+          # which defers and performs them at the next drain.
+          window.navigation_delegate = @session.__navigation_delegate_for__(window)
           resources = ::Dommy::Rack::Resources.new(@session)
           # Off-thread network is opt-in: with a session executor, fetch / XHR
           # resolve through a DeferredResponse on this window's scheduler;
@@ -140,6 +144,9 @@ module Dommy
           window.globals["__fetch_handler__"] = ::Dommy::Resources::FetchHandler.new(
             resources, executor: @session.network_executor, scheduler: window.scheduler
           )
+          # Same-origin WebSockets connect to the Rack app itself (ActionCable
+          # et al.); cross-origin ones keep the in-memory stub.
+          window.websocket_connector = @session.__internal_websocket_connector(window)
           # Dynamically-inserted `<script src>` (webpack/Vite on-demand chunks)
           # fetch + run through the same resources adapter, after boot.
           doc.external_script_runner = lambda do |element, src|

data/lib/dommy/rack/url.rb

@@ -43,6 +43,18 @@ module Dommy
       def escape_non_ascii(str)
         str.b.gsub(/[^\x00-\x7F]/n) { |byte| format("%%%02X", byte.unpack1("C")) }
       end
+
+      # `host` or `host:port`, omitting a default port (the `Host` header /
+      # tuple-origin serialization rule shared by HTTP and WebSocket).
+      def http_host(uri)
+        uri.port == uri.default_port ? uri.host : "#{uri.host}:#{uri.port}"
+      end
+
+      # `scheme://host[:port]`, the tuple origin for `uri` (used for the
+      # `Origin` header a same-origin WebSocket connection presents).
+      def origin(uri)
+        "#{uri.scheme}://#{http_host(uri)}"
+      end
     end
   end
 end

data/lib/dommy/rack/version.rb

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

data/lib/dommy/rack/web_socket_frame.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Dommy
+  module Rack
+    # RFC 6455 frame codec — the byte layout only, no I/O lifecycle. Encodes
+    # client frames (masked, per §5.3) and decodes server frames from a
+    # blocking IO. WebSocketTransport owns the socket, threads, and what each
+    # opcode means; this module owns how a frame is laid out on the wire.
+    module WebSocketFrame
+      module_function
+
+      TEXT = 0x1
+      BINARY = 0x2
+      CLOSE = 0x8
+      PING = 0x9
+      PONG = 0xA
+
+      # Read one frame from `io`. Returns [opcode, payload] with the payload
+      # unmasked. Raises EOFError when the stream ends mid-frame.
+      def read(io)
+        b1, b2 = read_exact(io, 2).unpack("C2")
+        opcode = b1 & 0x0f
+        length = b2 & 0x7f
+        length = read_exact(io, 2).unpack1("n") if length == 126
+        length = read_exact(io, 8).unpack1("Q>") if length == 127
+        mask = (b2 & 0x80).positive? ? read_exact(io, 4) : nil
+        payload = length.zero? ? +"" : read_exact(io, length)
+        payload = xor_mask(payload, mask) if mask
+        [opcode, payload]
+      end
+
+      # A single client frame: FIN + opcode, then the length with the mask
+      # bit set (clients MUST mask; RFC 6455 §5.3), the 4-byte key, and the
+      # masked payload.
+      def client_frame(opcode, payload)
+        header = [0x80 | opcode].pack("C")
+        length = payload.bytesize
+        header <<
+          if length < 126 then [0x80 | length].pack("C")
+          elsif length < 65_536 then [0x80 | 126, length].pack("Cn")
+          else [0x80 | 127, length].pack("CQ>")
+          end
+        key = SecureRandom.bytes(4)
+        header + key + xor_mask(payload, key)
+      end
+
+      # The body of a close frame: 2-byte status code + UTF-8 reason.
+      def close_payload(code, reason)
+        [code].pack("n") + reason.to_s.b
+      end
+
+      # [code, reason] from a close frame's payload; an empty payload means
+      # "no status received" (1005).
+      def parse_close(payload)
+        code = payload.bytesize >= 2 ? payload[0, 2].unpack1("n") : 1005
+        reason = payload.byteslice(2..).to_s.force_encoding(Encoding::UTF_8)
+        [code, reason]
+      end
+
+      def read_exact(io, n)
+        data = +""
+        while data.bytesize < n
+          chunk = io.read(n - data.bytesize)
+          raise EOFError, "connection closed" if chunk.nil?
+
+          data << chunk
+        end
+        data
+      end
+
+      # XOR (un)masking — its own inverse, so one helper serves both sides.
+      def xor_mask(payload, key)
+        bytes = payload.bytes
+        key_bytes = key.bytes
+        bytes.each_index { |i| bytes[i] ^= key_bytes[i % 4] }
+        bytes.pack("C*")
+      end
+    end
+  end
+end

data/lib/dommy/rack/web_socket_transport.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+require "socket"
+require "securerandom"
+require "stringio"
+require "uri"
+
+module Dommy
+  module Rack
+    # In-process WebSocket transport: connects a page's `new WebSocket(url)`
+    # to the Rack app ITSELF, the same way fetch/XHR resolve through the app.
+    # The server side receives a real RFC 6455 upgrade request and a real
+    # socket (one end of a socketpair, handed over via `rack.hijack`), so
+    # ActionCable's full stack runs unmodified — connection auth sees the
+    # session's cookies, the origin check sees the session's origin, and the
+    # cable event loop reads/writes actual WebSocket frames.
+    #
+    # The client side of the protocol lives here: frame semantics over the
+    # WebSocketFrame codec (text/close/ping handling; ActionCable messages are
+    # single-frame text) plus a reader thread that parses server frames and
+    # marshals them onto the page thread via `scheduler.post_external`, where
+    # they fire the WebSocket's open/message/close events. `settle` /
+    # `advance_time` deliver them, like any other external completion.
+    #
+    # Lifetime: a transport belongs to the page (realm) that opened it; the
+    # session closes all live transports on dispose. Note that ActionCable
+    # sends its JSON pings on REAL time (an every-3s event-loop timer), not
+    # the page's virtual clock — harmless for tests, which settle on the
+    # subscription/broadcast messages they wait for.
+    class WebSocketTransport
+      # Resolve `url` for the connector: an absolute ws(s) URL (http(s) is
+      # accepted and treated the same) that is same-origin with `base`.
+      # Returns the URI, or nil (the WebSocket then falls back to the
+      # in-memory stub).
+      def self.rack_target(url, base:)
+        target = URI.join(base.to_s, url.to_s)
+        scheme = {"ws" => "http", "wss" => "https"}[target.scheme] || target.scheme
+        return nil unless %w[http https].include?(scheme)
+
+        b = URI.parse(base.to_s)
+        return nil unless b.host == target.host && b.port == target.port
+
+        target.scheme = scheme
+        # Re-parse so the return value is a URI::HTTP(S), not a URI::WS whose
+        # scheme string was swapped (URI classes compare by class + value).
+        URI.parse(target.to_s)
+      rescue URI::Error
+        nil
+      end
+
+      def initialize(app:, ws:, scheduler:, url:, origin:, cookie_string: "")
+        @ws = ws
+        @scheduler = scheduler
+        @url = url
+        @write_mutex = Mutex.new
+        @sent_close = false
+        @closed = false
+
+        @client_io, server_io = ::Socket.pair(:UNIX, :STREAM)
+        env = handshake_env(url, origin, cookie_string, server_io)
+        status, _headers, _body = app.call(env)
+        if env["rack.hijack_io"].nil? && status != -1
+          # The app answered with a normal HTTP response (no cable mounted at
+          # this path, or the upgrade was rejected): fail like a browser —
+          # error then close, deferred so `onerror` handlers attach first.
+          fail_connection
+        else
+          @reader = Thread.new { run_reader }
+        end
+      end
+
+      # --- API the WebSocket delegates to (page thread) ---
+
+      def send_text(data)
+        write_frame(WebSocketFrame::TEXT, data.b)
+      end
+
+      def close(code = 1000, reason = "")
+        send_close_frame(code == 1005 ? 1000 : code, reason)
+      end
+
+      # Hard teardown (session dispose): drop the socket; the reader thread
+      # exits on EOF. Safe to call repeatedly.
+      def dispose
+        @closed = true
+        @client_io&.close unless @client_io&.closed?
+        @reader&.join(1)
+      rescue IOError
+        nil
+      end
+
+      private
+
+      def handshake_env(url, origin, cookie_string, server_io)
+        env = {
+          "REQUEST_METHOD" => "GET",
+          "SCRIPT_NAME" => "",
+          "PATH_INFO" => url.path.empty? ? "/" : url.path,
+          "QUERY_STRING" => url.query.to_s,
+          "SERVER_NAME" => url.host,
+          "SERVER_PORT" => url.port.to_s,
+          "HTTP_HOST" => Url.http_host(url),
+          "HTTP_UPGRADE" => "websocket",
+          "HTTP_CONNECTION" => "Upgrade",
+          "HTTP_SEC_WEBSOCKET_KEY" => SecureRandom.base64(16),
+          "HTTP_SEC_WEBSOCKET_VERSION" => "13",
+          "HTTP_ORIGIN" => origin,
+          "REMOTE_ADDR" => "127.0.0.1",
+          "rack.url_scheme" => url.scheme,
+          "rack.input" => StringIO.new(""),
+          "rack.errors" => $stderr,
+          "rack.multithread" => true,
+          "rack.multiprocess" => false,
+          "rack.run_once" => false,
+          "rack.hijack?" => true,
+        }
+        env["HTTP_COOKIE"] = cookie_string unless cookie_string.to_s.empty?
+        env["rack.hijack"] = proc { env["rack.hijack_io"] = server_io }
+        env
+      end
+
+      def fail_connection
+        @closed = true
+        @client_io.close
+        @scheduler.queue_microtask(proc do
+          @ws.__transport_error__
+          @ws.__transport_closed__(1006, "", was_clean: false)
+        end)
+      end
+
+      # --- Reader thread ---
+
+      def run_reader
+        protocol = read_handshake_response!
+        post { @ws.__transport_open__(protocol) }
+        read_frames
+      rescue HandshakeFailed
+        post { @ws.__transport_error__ }
+        post { @ws.__transport_closed__(1006, "", was_clean: false) }
+      rescue IOError, EOFError, Errno::ECONNRESET, Errno::EPIPE
+        post { @ws.__transport_closed__(1006, "", was_clean: false) } unless @closed
+      ensure
+        @client_io.close rescue nil
+      end
+
+      class HandshakeFailed < StandardError; end
+
+      # Read the server's HTTP response head; only `101 Switching Protocols`
+      # continues (the handshake accept hash is not re-verified — the server
+      # is the app under test, not an untrusted peer). Returns the selected
+      # subprotocol, if any.
+      def read_handshake_response!
+        head = +""
+        head << WebSocketFrame.read_exact(@client_io, 1) until head.end_with?("\r\n\r\n")
+        raise HandshakeFailed unless head.start_with?("HTTP/1.1 101")
+
+        head[/^sec-websocket-protocol:\s*(\S+)/i, 1]
+      end
+
+      def read_frames
+        loop do
+          opcode, payload = WebSocketFrame.read(@client_io)
+
+          case opcode
+          when WebSocketFrame::TEXT, WebSocketFrame::BINARY # continuation frames unsupported: cable messages are single-frame
+            data = opcode == WebSocketFrame::TEXT ? payload.force_encoding(Encoding::UTF_8) : payload
+            post { @ws.__transport_message__(data) }
+          when WebSocketFrame::CLOSE # complete the handshake, then report
+            code, reason = WebSocketFrame.parse_close(payload)
+            send_close_frame(code == 1005 ? 1000 : code, "")
+            @closed = true
+            post { @ws.__transport_closed__(code, reason, was_clean: true) }
+            break
+          when WebSocketFrame::PING
+            write_frame(WebSocketFrame::PONG, payload)
+          end
+        end
+      end
+
+      # --- Frame writing (page thread and reader thread; mutex-guarded) ---
+
+      def send_close_frame(code, reason)
+        return if @sent_close
+
+        @sent_close = true
+        write_frame(WebSocketFrame::CLOSE, WebSocketFrame.close_payload(code, reason))
+      end
+
+      def write_frame(opcode, payload)
+        frame = WebSocketFrame.client_frame(opcode, payload)
+        @write_mutex.synchronize do
+          return if @client_io.closed?
+
+          @client_io.write(frame)
+        end
+      rescue IOError, Errno::EPIPE
+        nil
+      end
+
+      def post(&block)
+        @scheduler.post_external(&block)
+      end
+    end
+  end
+end

data/lib/dommy/rack.rb

@@ -22,6 +22,8 @@ require_relative "rack/resources"
 require_relative "rack/network_bridge"
 require_relative "rack/session_runtime"
 require_relative "rack/trace"
+require_relative "rack/web_socket_frame"
+require_relative "rack/web_socket_transport"
 require_relative "rack/session"
 
 module Dommy

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dommy-rack
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - takahashim
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 0.10.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: 0.10.0
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
@@ -78,6 +78,8 @@ files:
 - lib/dommy/rack/url.rb
 - lib/dommy/rack/version.rb
 - lib/dommy/rack/visibility.rb
+- lib/dommy/rack/web_socket_frame.rb
+- lib/dommy/rack/web_socket_transport.rb
 - sig/dommy/rack.rbs
 homepage: https://github.com/takahashim/dommy
 licenses:
@@ -99,7 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.10
 specification_version: 4
 summary: Rack-backed browser session layer for Dommy
 test_files: []