capybara-lightpanda 0.1.0

data/lib/capybara/lightpanda/client/subscriber.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Capybara
+  module Lightpanda
+    class Client
+      class Subscriber
+        def initialize
+          @subscriptions = Hash.new { |h, k| h[k] = [] }
+          @mutex = Mutex.new
+        end
+
+        def subscribe(event, &block)
+          @mutex.synchronize do
+            @subscriptions[event] << block
+          end
+        end
+
+        def unsubscribe(event, block = nil)
+          @mutex.synchronize do
+            if block
+              @subscriptions[event].delete(block)
+            else
+              @subscriptions.delete(event)
+            end
+          end
+        end
+
+        def dispatch(event, params)
+          callbacks = @mutex.synchronize { @subscriptions[event].dup }
+
+          callbacks.each { |callback| callback.call(params) }
+        end
+
+        def subscribed?(event)
+          @mutex.synchronize { @subscriptions.key?(event) && @subscriptions[event].any? }
+        end
+
+        def clear
+          @mutex.synchronize { @subscriptions.clear }
+        end
+      end
+    end
+  end
+end

data/lib/capybara/lightpanda/client/web_socket.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+require "websocket/driver"
+
+module Capybara
+  module Lightpanda
+    class Client
+      class WebSocket
+        attr_reader :url, :messages
+
+        def initialize(url, options)
+          @url = url
+          @options = options
+          @logger = options.logger
+          @socket = nil
+          @driver = nil
+          @thread = nil
+          @status = :closed
+          @messages = Queue.new
+          @driver_mutex = Mutex.new
+
+          connect
+        end
+
+        def send_message(message)
+          raise DeadBrowserError, "WebSocket is not open" unless @status == :open
+
+          @logger&.puts("\n\n▶ #{@logger.elapsed_time} #{message}")
+          @driver_mutex.synchronize { @driver.text(message) }
+        end
+
+        def close
+          return if @status == :closed
+
+          @status = :closing
+          @messages.close
+          @driver&.close
+          @thread&.join(1) || @thread&.kill
+          @socket&.close
+          @status = :closed
+        end
+
+        def closed?
+          @status == :closed
+        end
+
+        def open?
+          @status == :open
+        end
+
+        def write(data)
+          @socket.write(data)
+        rescue Errno::EPIPE, Errno::ECONNRESET, IOError
+          @status = :closed
+          @messages.close
+        end
+
+        private
+
+        def connect
+          uri = URI.parse(@url)
+
+          @socket = connect_with_retry(uri.host, uri.port)
+          @driver = ::WebSocket::Driver.client(self)
+
+          setup_callbacks
+
+          @driver.start
+
+          read_handshake_response
+          start_reader_thread
+        end
+
+        def connect_with_retry(host, port, retries: 10, delay: 0.1)
+          retries.times do |i|
+            return TCPSocket.new(host, port)
+          rescue Errno::ECONNREFUSED
+            raise if i == retries - 1
+
+            sleep delay
+          end
+        end
+
+        def setup_callbacks
+          @driver.on(:open) do
+            @status = :open
+          end
+
+          @driver.on(:message) do |event|
+            @logger&.puts("    ◀ #{@logger.elapsed_time} #{event.data}\n")
+            message = parse_message(event.data)
+            @messages << message if message
+          rescue ClosedQueueError
+            # Queue was closed during shutdown
+          end
+
+          @driver.on(:close) do
+            @status = :closed
+            @messages.close
+          end
+
+          @driver.on(:error) do |event|
+            @status = :error
+            @messages.close
+
+            raise DeadBrowserError, "WebSocket error: #{event.message}"
+          end
+        end
+
+        def start_reader_thread
+          @thread = Thread.new do
+            Thread.current.abort_on_exception = true
+
+            loop do
+              break if @status == :closed || @status == :closing
+
+              begin
+                next unless @socket.wait_readable(0.1)
+
+                data = @socket.readpartial(4096)
+                @driver_mutex.synchronize { @driver.parse(data) }
+              rescue Errno::ECONNRESET, Errno::EPIPE, IOError
+                @status = :closed
+                @messages.close
+                break
+              end
+            end
+          end
+        end
+
+        def read_handshake_response
+          started_at = Time.now
+
+          while @status != :open && Time.now - started_at < @options.timeout
+            next unless @socket.wait_readable(0.1)
+
+            begin
+              data = @socket.readpartial(4096)
+              @driver.parse(data)
+            rescue EOFError
+              raise DeadBrowserError, "Connection closed during handshake"
+            end
+          end
+
+          raise TimeoutError, "WebSocket connection timeout" unless @status == :open
+        end
+
+        def parse_message(data)
+          JSON.parse(data, max_nesting: false)
+        rescue JSON::ParserError => e
+          warn "Failed to parse WebSocket message: #{e.message}"
+
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/capybara/lightpanda/client.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+require "json"
+require "concurrent-ruby"
+
+require_relative "client/web_socket"
+require_relative "client/subscriber"
+
+module Capybara
+  module Lightpanda
+    class Client
+      attr_reader :ws_url, :options
+
+      def initialize(ws_url, options)
+        @ws_url = ws_url
+        @options = options
+        @ws = WebSocket.new(ws_url, options)
+        @command_id = 0
+        @pendings = Concurrent::Hash.new
+        @subscriber = Subscriber.new
+        @mutex = Mutex.new
+
+        start_message_thread
+      end
+
+      def command(method, params = {}, async: false, session_id: nil, timeout: nil)
+        message = build_message(method, params, session_id: session_id)
+
+        if async
+          @ws.send_message(JSON.generate(message))
+          return true
+        end
+
+        pending = Concurrent::IVar.new
+        @pendings[message[:id]] = pending
+
+        @ws.send_message(JSON.generate(message))
+
+        effective_timeout = timeout || @options.timeout
+        response = pending.value!(effective_timeout)
+
+        if response.nil?
+          raise DeadBrowserError, "Browser closed during #{method}" if @ws.closed?
+
+          raise TimeoutError, "Command #{method} timed out after #{effective_timeout}s"
+        end
+
+        handle_error(response) if response["error"]
+
+        response["result"]
+      ensure
+        @pendings.delete(message[:id]) if message
+      end
+
+      def on(event, &)
+        @subscriber.subscribe(event, &)
+      end
+
+      def off(event, block = nil)
+        @subscriber.unsubscribe(event, block)
+      end
+
+      def close
+        @ws&.close
+        @message_thread&.join(1) || @message_thread&.kill
+        @subscriber.clear
+        @pendings.clear
+      end
+
+      def closed?
+        @ws.closed?
+      end
+
+      private
+
+      def build_message(method, params, session_id: nil)
+        id = next_command_id
+        message = { id: id, method: method, params: params }
+        message[:sessionId] = session_id if session_id
+
+        message
+      end
+
+      def next_command_id
+        @mutex.synchronize { @command_id += 1 }
+      end
+
+      def start_message_thread
+        @message_thread = Thread.new do
+          Thread.current.abort_on_exception = true
+
+          while (message = @ws.messages.pop)
+            handle_message(message)
+          end
+        end
+      end
+
+      def handle_message(message)
+        if message["id"]
+          pending = @pendings[message["id"]]
+          pending&.set(message)
+        elsif message["method"]
+          @subscriber.dispatch(message["method"], message["params"])
+        end
+      end
+
+      def handle_error(response)
+        error = response["error"]
+        message = error["message"]
+
+        case message
+        when /No node with given id found/i
+          raise NodeNotFoundError, message
+        when /Cannot find context with specified id/i,
+             /Execution context was destroyed/i,
+             /Cannot find default execution context/i
+          raise NoExecutionContextError, message
+        else
+          raise BrowserError, error
+        end
+      end
+    end
+  end
+end

data/lib/capybara/lightpanda/cookies.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Capybara
+  module Lightpanda
+    class Cookies
+      # Typed wrapper around a CDP cookie hash so callers don't have to remember
+      # the camelCase keys (`httpOnly`, `sameSite`, …) the CDP returns. Mirrors
+      # ferrum's Cookies::Cookie. `attributes` exposes the raw hash for callers
+      # that still need it (e.g. YAML serialization in store/load).
+      class Cookie
+        attr_reader :attributes
+
+        def initialize(attributes)
+          @attributes = attributes
+        end
+
+        def name      = attributes["name"]
+        def value     = attributes["value"]
+        def domain    = attributes["domain"]
+        def path      = attributes["path"]
+        def samesite  = attributes["sameSite"]
+        def size      = attributes["size"]
+        def secure?   = attributes["secure"]
+        def httponly? = attributes["httpOnly"]
+        def session?  = attributes["session"]
+
+        alias same_site samesite
+        alias http_only? httponly?
+
+        # Time when the cookie expires, or nil for session cookies (CDP reports
+        # session cookies with `expires: -1`).
+        def expires
+          exp = attributes["expires"]
+          Time.at(exp) if exp.is_a?(Numeric) && exp.positive?
+        end
+
+        def ==(other)
+          other.is_a?(self.class) && other.attributes == attributes
+        end
+
+        alias eql? ==
+
+        def hash
+          attributes.hash
+        end
+
+        def to_h
+          attributes
+        end
+      end
+
+      attr_reader :browser
+
+      def initialize(browser)
+        @browser = browser
+      end
+
+      def all
+        result = browser.command("Network.getCookies")
+        (result["cookies"] || []).map { |c| Cookie.new(c) }
+      end
+
+      def get(name)
+        all.find { |cookie| cookie.name == name }
+      end
+
+      def set(name:, value:, domain: nil, path: "/", secure: false, http_only: false, expires: nil)
+        params = {
+          name: name,
+          value: value,
+          path: path,
+          secure: secure,
+          httpOnly: http_only,
+        }
+
+        params[:domain] = domain if domain
+        params[:expires] = expires.to_i if expires
+
+        browser.command("Network.setCookie", **params)
+      end
+
+      def remove(name:, domain: nil, path: "/")
+        params = { name: name, path: path }
+        params[:domain] = domain if domain
+
+        browser.command("Network.deleteCookies", **params)
+      end
+
+      # Lightpanda gotchas observed on current nightly:
+      #   * `Network.clearBrowserCookies` raises `InvalidParams` (so it does NOT
+      #     clear anything despite the upstream PR #1821 / >= v0.2.6 note).
+      #   * `Network.getCookies` (no `urls` param) is scoped to the CURRENT
+      #     page's origin — cookies set on previously-visited domains are
+      #     invisible from a different page.
+      #   * `Network.getCookies` on `about:blank` raises `InvalidDomain`.
+      #
+      # To honor Capybara's `reset_session! removes ALL cookies` contract
+      # across multiple test domains (e.g. `localhost` AND `127.0.0.1`), we
+      # iterate every origin Browser has navigated to and per-origin call
+      # `Network.getCookies(urls: [origin])` then `Network.deleteCookies(url:)`.
+      # The bulk-clear call is still attempted first as a fast path / future-
+      # proofing for when upstream fixes it.
+      def clear
+        begin
+          browser.command("Network.clearBrowserCookies")
+        rescue BrowserError, TimeoutError, StandardError
+          # InvalidParams on current nightly; pre-v0.2.6 used to crash the
+          # WebSocket. Either way, fall through to per-origin sweep.
+        end
+
+        sweep_visited_origins
+      end
+
+      # Persist all current cookies to a YAML file (ferrum parity).
+      # Returns the number of bytes written.
+      def store(path = "cookies.yml")
+        File.write(path, all.map(&:to_h).to_yaml)
+      end
+
+      # Load cookies from a YAML file produced by `store` and re-set them.
+      # CDP requires either domain or url for each cookie; entries from `store`
+      # already include domain, so they round-trip cleanly. Returns true on
+      # success (intentionally not a predicate — mirrors ferrum's API).
+      def load(path = "cookies.yml") # rubocop:disable Naming/PredicateMethod
+        cookies = YAML.load_file(path)
+        cookies.each { |c| restore_cookie(c) }
+        true
+      end
+
+      private
+
+      def sweep_visited_origins
+        origins = browser.visited_origins.to_a
+        return if origins.empty?
+
+        result = browser.command("Network.getCookies", urls: origins)
+        cookies = result["cookies"] || []
+        cookies.each do |cookie|
+          # CDP needs either domain or url; build a url from the cookie's
+          # own domain+path so we don't mismatch (e.g. cookie domain `.x.test`
+          # against an origin we tracked as `https://x.test:443`).
+          url = cookie_url(cookie)
+          params = { name: cookie["name"] }
+          params[:url] = url if url
+          params[:domain] = cookie["domain"] unless url
+          browser.command("Network.deleteCookies", **params)
+        end
+      rescue StandardError
+        # Connection lost or origin no longer valid; nothing more to do.
+      end
+
+      def cookie_url(cookie)
+        domain = cookie["domain"].to_s.sub(/\A\./, "")
+        return nil if domain.empty?
+
+        scheme = cookie["secure"] ? "https" : "http"
+        path = cookie["path"] || "/"
+        "#{scheme}://#{domain}#{path}"
+      end
+
+      # set() takes keyword args, but YAML round-trips give us a hash with the
+      # raw CDP keys (camelCase). Normalize and forward.
+      def restore_cookie(hash)
+        attrs = hash.transform_keys(&:to_s)
+        params = {
+          name: attrs["name"],
+          value: attrs["value"],
+          path: attrs["path"] || "/",
+          secure: attrs["secure"] || false,
+          http_only: attrs["httpOnly"] || false,
+        }
+        params[:domain] = attrs["domain"] if attrs["domain"]
+        exp = attrs["expires"]
+        params[:expires] = Time.at(exp) if exp.is_a?(Numeric) && exp.positive?
+        set(**params)
+      end
+    end
+  end
+end