bidi2pdf 0.1.6 → 0.1.7

data/lib/bidi2pdf/bidi/client.rb

@@ -10,23 +10,47 @@ require_relative "commands"
 
 module Bidi2pdf
   module Bidi
+    # Represents a WebSocket client for managing communication with a remote server
+    # using the Bidi2pdf library. This class handles the setup, connection, and
+    # communication with the WebSocket server, including sending commands and
+    # handling responses.
+    #
+    # @example Creating and starting a client
+    #   client = Bidi2pdf::Bidi::Client.new("ws://example.com/socket")
+    #   client.start
+    #
+    # @example Sending a command
+    #   command = Bidi2pdf::Bidi::Commands::ScriptEvaluate.new context: browsing_context_id, expression: script
+    #   client.send_cmd(command)
+    #
+    # @example Subscribing to events
+    #   client.on_event("eventName") do |event_data|
+    #     puts "Received event: #{event_data}"
+    #   end
+    #
+    # @param [String] ws_url The WebSocket URL to connect to.
     class Client
-      include Bidi2pdf::Utils
-
+      # @return [String] The WebSocket URL.
       attr_reader :ws_url
 
+      # Initializes a new WebSocket client.
+      #
+      # @param [String] ws_url The WebSocket URL to connect to.
       def initialize(ws_url)
         @ws_url = ws_url
         @started = false
         @connection_manager = ConnectionManager.new(logger: Bidi2pdf.logger)
       end
 
+      # Starts the WebSocket client and establishes a connection.
+      #
+      # @return [WebSocket::Client::Simple] The WebSocket connection object.
       def start
         return @socket if started?
 
         WebSocket::Client::Simple.connect(ws_url) do |socket|
           @socket = socket
-          @command_manager = CommandManager.new(@socket, logger: Bidi2pdf.logger)
+          @command_manager = CommandManager.new(@socket)
 
           dispatcher.on_open { @connection_manager.mark_connected }
           dispatcher.on_message { |data| handle_response_to_cmd(data) }
@@ -38,8 +62,15 @@ module Bidi2pdf
         @socket
       end
 
+      # Checks if the WebSocket client has started.
+      #
+      # @return [Boolean] True if the client has started, false otherwise.
       def started? = @started
 
+      # Waits until the WebSocket connection is open.
+      #
+      # @param [Integer] timeout The timeout duration in seconds.
+      # @raise [Bidi2pdf::WebsocketError] If the connection is not established within the timeout.
       def wait_until_open(timeout: Bidi2pdf.default_timeout)
         @connection_manager.wait_until_open(timeout: timeout)
       rescue Bidi2pdf::WebsocketError => e
@@ -48,40 +79,72 @@ module Bidi2pdf
         raise e
       end
 
+      # Sends a command to the WebSocket server.
+      #
+      # @param [Bidi2pdf::Bidi::Commands::Base] cmd The command to send.
+      # @raise [Bidi2pdf::ClientError] If the client has not started.
       def send_cmd(cmd)
         raise Bidi2pdf::ClientError, "Client#start must be called before" unless started?
 
         @command_manager.send_cmd(cmd)
       end
 
-      def send_cmd_and_wait(cmd, timeout: Bidi2pdf.default_timeout, &block)
+      # Sends a command to the WebSocket server and waits for a response.
+      #
+      # @param [Object] cmd The command to send.
+      # @param [Integer] timeout The timeout duration in seconds.
+      # @yield [response] A block to handle the response.
+      # @raise [Bidi2pdf::ClientError] If the client has not started.
+      def send_cmd_and_wait(cmd, timeout: Bidi2pdf.default_timeout, &)
         raise Bidi2pdf::ClientError, "Client#start must be called before" unless started?
 
-        timed("Command #{cmd.inspect}") do
-          @command_manager.send_cmd_and_wait(cmd, timeout: timeout, &block)
-        end
+        @command_manager.send_cmd_and_wait(cmd, timeout: timeout, &)
       end
 
-      def on_message(&block) = dispatcher.on_message(&block)
-
-      def on_open(&block) = dispatcher.on_open(&block)
-
-      def on_close(&block) = dispatcher.on_close(&block)
-
-      def on_error(&block) = dispatcher.on_error(&block)
-
+      # Registers a callback for incoming WebSocket messages.
+      #
+      # @yield [message] A block to handle the incoming message.
+      def on_message(&) = dispatcher.on_message(&)
+
+      # Registers a callback for when the WebSocket connection is opened.
+      #
+      # @yield A block to execute when the connection is opened.
+      def on_open(&) = dispatcher.on_open(&)
+
+      # Registers a callback for when the WebSocket connection is closed.
+      #
+      # @yield A block to execute when the connection is closed.
+      def on_close(&) = dispatcher.on_close(&)
+
+      # Registers a callback for WebSocket errors.
+      #
+      # @yield [error] A block to handle the error.
+      def on_error(&) = dispatcher.on_error(&)
+
+      # Subscribes to specific WebSocket events.
+      #
+      # @param [Array<String>] names The names of the events to subscribe to.
+      # @yield [event_data] A block to handle the event data.
       def on_event(*names, &block)
         names.each { |name| dispatcher.on_event(name, &block) }
         cmd = Bidi2pdf::Bidi::Commands::SessionSubscribe.new(events: names)
         send_cmd(cmd) if names.any?
       end
 
+      # Removes a message listener.
+      #
+      # @param [Proc] block The listener block to remove.
       def remove_message_listener(block) = dispatcher.remove_message_listener(block)
 
+      # Removes event listeners for specific events.
+      #
+      # @param [Array<String>] names The names of the events to unsubscribe from.
+      # @param [Proc] block The listener block to remove.
       def remove_event_listener(*names, &block)
         names.each { |event_name| dispatcher.remove_event_listener(event_name, block) }
       end
 
+      # Closes the WebSocket connection.
       def close
         return unless @socket
 
@@ -93,19 +156,18 @@ module Bidi2pdf
 
       private
 
+      # Returns the WebSocket dispatcher for managing events and messages.
+      #
+      # @return [WebSocketDispatcher] The dispatcher instance.
       def dispatcher
         @dispatcher ||= WebSocketDispatcher.new(@socket)
       end
 
+      # Handles responses to commands sent to the WebSocket server.
+      #
+      # @param [Hash] data The response data.
       def handle_response_to_cmd(data)
-        handled = @command_manager.handle_response(data)
-        return if handled
-
-        if data["error"]
-          Bidi2pdf.logger.error "Error response: #{data["error"].inspect}"
-        else
-          Bidi2pdf.logger.warn "Unknown response: #{data.inspect}"
-        end
+        @command_manager.handle_response(data)
       end
     end
   end

data/lib/bidi2pdf/bidi/command_manager.rb

@@ -14,9 +14,8 @@ module Bidi2pdf
 
       initialize_counter
 
-      def initialize(socket, logger:)
+      def initialize(socket)
         @socket = socket
-        @logger = logger
 
         @pending_responses = {}
         @initiated_cmds = {}
@@ -25,30 +24,40 @@ module Bidi2pdf
       def send_cmd(cmd, store_response: false)
         id = next_id
 
-        if store_response
-          init_queue_for id
-        else
-          @initiated_cmds[id] = true
-        end
+        Bidi2pdf.notification_service.instrument("send_cmd.bidi2pdf", id: id, cmd: cmd) do |instrumentation_payload|
+          if store_response
+            init_queue_for id
+          else
+            @initiated_cmds[id] = true
+          end
+
+          payload = cmd.as_payload(id)
 
-        payload = cmd.as_payload(id)
+          instrumentation_payload[:cmd_payload] = payload
 
-        @logger.debug "Sending command: #{redact_sensitive_fields(payload).inspect}"
-        @socket.send(payload.to_json)
+          @socket.send(payload.to_json)
+        end
 
         id
       end
 
-      def send_cmd_and_wait(cmd, timeout: Bidi2pdf.default_timeout)
-        id = send_cmd(cmd, store_response: true)
-        response = pop_response id, timeout: timeout
+      def send_cmd_and_wait(cmd, timeout: Bidi2pdf.default_timeout, &block)
+        Bidi2pdf.notification_service.instrument("send_cmd_and_wait.bidi2pdf", cmd: cmd, timeout: timeout) do |instrumentation_payload|
+          id = send_cmd(cmd, store_response: true)
 
-        raise_timeout_error(id, cmd) if response.nil?
-        raise CmdError, "Error response: #{response["error"]} #{cmd.inspect}" if response["error"]
+          instrumentation_payload[:id] = id
 
-        block_given? ? yield(response) : response
-      ensure
-        @pending_responses.delete(id)
+          response = pop_response id, timeout: timeout
+
+          instrumentation_payload[:response] = response
+
+          raise CmdTimeoutError, "Timeout waiting for response to command ID #{id}" if response.nil?
+          raise CmdError, "Error response: #{response["error"]} #{cmd.inspect}" if response["error"]
+
+          block ? block.call(response) : response
+        ensure
+          @pending_responses.delete(id)
+        end
       end
 
       def pop_response(id, timeout:)
@@ -60,45 +69,34 @@ module Bidi2pdf
       end
 
       def handle_response(data)
-        if (id = data["id"])
-          if @pending_responses.key?(id)
-            @pending_responses[id]&.push(data)
-            return true
-          elsif @initiated_cmds.key?(id)
-            @logger.error "Received error: #{data["error"]} for cmd: #{id}" if data["error"]
-
-            return @initiated_cmds.delete(id)
-          end
-        end
+        Bidi2pdf.notification_service.instrument("handle_response.bidi2pdf", data: data) do |instrumentation_payload|
+          instrumentation_payload[:error] = data["error"] if data["error"]
 
-        false
-      end
+          if (id = data["id"])
+            instrumentation_payload[:handled] = true
+            instrumentation_payload[:id] = id
 
-      private
+            if @pending_responses.key?(id)
+              @pending_responses[id]&.push(data)
+              return true
+            elsif @initiated_cmds.key?(id)
+              @initiated_cmds.delete(id)
 
-      def init_queue_for(id) = @pending_responses[id] = Thread::Queue.new
+              return true
+            end
+          end
 
-      def next_id = self.class.next_id
+          instrumentation_payload[:handled] = false
 
-      def redact_sensitive_fields(obj, sensitive_keys = %w[value token password authorization username])
-        case obj
-        when Hash
-          obj.transform_values.with_index do |v, idx|
-            k = obj.keys[idx]
-            sensitive_keys.include?(k.to_s.downcase) ? "[REDACTED]" : redact_sensitive_fields(v, sensitive_keys)
-          end
-        when Array
-          obj.map { |item| redact_sensitive_fields(item, sensitive_keys) }
-        else
-          obj
+          false
         end
       end
 
-      def raise_timeout_error(id, cmd)
-        @logger.error "Timeout waiting for response to command #{id}, cmd: #{cmd.inspect}"
+      private
 
-        raise CmdTimeoutError, "Timeout waiting for response to command ID #{id}"
-      end
+      def init_queue_for(id) = @pending_responses[id] = Thread::Queue.new
+
+      def next_id = self.class.next_id
     end
   end
 end

data/lib/bidi2pdf/bidi/commands/base.rb

@@ -3,11 +3,25 @@
 module Bidi2pdf
   module Bidi
     module Commands
+      # Base module for defining WebSocket commands in the Bidi2pdf library.
+      # This module provides common functionality for creating, comparing, and
+      # inspecting WebSocket command payloads.
       module Base
+        # Abstract method that must be implemented in subclasses to define the
+        # WebSocket command method name.
+        #
+        # @raise [NotImplementedError] If the method is not implemented in a subclass.
         def method_name = raise(NotImplementedError, "method_name must be implemented in subclass")
 
+        # Returns the parameters for the WebSocket command.
+        #
+        # @return [Hash] The parameters for the command. Defaults to an empty hash.
         def params = {}
 
+        # Constructs the payload for the WebSocket command.
+        #
+        # @param [Integer] id The unique identifier for the command.
+        # @return [Hash] The payload containing the command ID, method name, and parameters.
         def as_payload(id)
           {
             id: id,
@@ -16,6 +30,10 @@ module Bidi2pdf
           }
         end
 
+        # Compares the current command with another command for equality.
+        #
+        # @param [Object] other The other command to compare.
+        # @return [Boolean] True if the commands are equal, false otherwise.
         # rubocop: disable Metrics/AbcSize
         def ==(other)
           return false unless other.respond_to?(:method_name) && other.respond_to?(:params)
@@ -29,17 +47,26 @@ module Bidi2pdf
 
         # rubocop: enable Metrics/AbcSize
 
-        # Hash equality comparison
+        # Checks if the current command is hash-equal to another command.
+        #
+        # @param [Object] other The other command to compare.
+        # @return [Boolean] True if the commands are hash-equal, false otherwise.
         def eql?(other)
           return false unless other.is_a?(Bidi2pdf::Bidi::Commands::Base)
 
           self == other
         end
 
+        # Computes the hash value for the command.
+        #
+        # @return [Integer] The hash value based on the method name and parameters.
         def hash
           [method_name, params].hash
         end
 
+        # Returns a string representation of the command, with sensitive fields redacted.
+        #
+        # @return [String] The string representation of the command.
         def inspect
           attributes = redact_sensitive_fields({ method_name: method_name, params: params })
 
@@ -48,6 +75,11 @@ module Bidi2pdf
 
         private
 
+        # Redacts sensitive fields in a given object.
+        #
+        # @param [Object] obj The object to redact.
+        # @param [Array<String>] sensitive_keys The list of sensitive keys to redact. Defaults to common sensitive keys.
+        # @return [Object] The object with sensitive fields redacted.
         def redact_sensitive_fields(obj, sensitive_keys = %w[value token password authorization username])
           case obj
           when Hash
@@ -62,6 +94,12 @@ module Bidi2pdf
           end
         end
 
+        # Logs and raises a timeout error for a command.
+        #
+        # @param [Integer] id The unique identifier for the command.
+        # @param [String] method The method name of the command.
+        # @param [Hash] params The parameters of the command.
+        # @raise [CmdTimeoutError] If the command times out.
         def raise_timeout_error(id, method, params)
           @logger.error "Timeout waiting for response to command #{id}, cmd: #{method}, params: #{redact_sensitive_fields(params).inspect}"
 

data/lib/bidi2pdf/bidi/commands/browser_remove_user_context.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module Bidi
+    module Commands
+      class BrowserRemoveUserContext
+        include Base
+
+        attr_reader :user_context_id
+
+        def initialize(user_context_id: nil)
+          @user_context_id = user_context_id
+        end
+
+        def params
+          {
+            userContext: @user_context_id
+          }.compact
+        end
+
+        def method_name
+          "browser.removeUserContext"
+        end
+      end
+    end
+  end
+end

data/lib/bidi2pdf/bidi/commands/browsing_context_print.rb

@@ -13,6 +13,10 @@ module Bidi2pdf
           @print_options = print_options || { background: true }
 
           PrintParametersValidator.validate!(@print_options)
+
+          return unless @print_options[:page]&.key?(:format)
+
+          @print_options[:page] = Bidi2pdf.translate_paper_format @print_options[:page][:format]
         end
 
         def params

data/lib/bidi2pdf/bidi/commands/print_parameters_validator.rb

@@ -17,6 +17,7 @@ module Bidi2pdf
       #   },
       #   orientation: "portrait" or "landscape" (optional, default: "portrait"),
       #   page: {
+      #     format: String (optional, use either format or width/height),
       #     width: Float >= 0.0352 (optional, default: 21.59),
       #     height: Float >= 0.0352 (optional, default: 27.94)
       #   },
@@ -97,18 +98,22 @@ module Bidi2pdf
           end
         end
 
+        # rubocop: disable Metrics/CyclomaticComplexity
         def validate_page_size
           return unless @params.key?(:page)
 
           page = @params[:page]
           raise ArgumentError, ":page must be a Hash" unless page.is_a?(Hash)
 
+          Bidi2pdf.translate_paper_format @params[:page][:format] if @params[:page][:format]
+
           %i[width height].each do |dim|
             next unless page.key?(dim)
 
             val = page[dim]
             raise ArgumentError, "page[:#{dim}] must be a float >= 0.0352" unless val.is_a?(Numeric) && val >= 0.0352
           end
+          # rubocop: enable Metrics/CyclomaticComplexity
         end
       end
     end

data/lib/bidi2pdf/bidi/commands.rb

@@ -13,6 +13,7 @@ module Bidi2pdf
       require_relative "commands/get_user_contexts"
       require_relative "commands/script_evaluate"
       require_relative "commands/browser_create_user_context"
+      require_relative "commands/browser_remove_user_context"
       require_relative "commands/browser_close"
       require_relative "commands/browsing_context_close"
       require_relative "commands/browsing_context_navigate"

data/lib/bidi2pdf/bidi/event_manager.rb

@@ -43,7 +43,7 @@ module Bidi2pdf
 
       def log_msg(prefix, data)
         message = truncate_large_values(data)
-        Bidi2pdf.logger.debug "#{prefix}: #{message.inspect}"
+        Bidi2pdf.logger.debug3 "#{prefix}: #{message.inspect}"
       end
 
       # rubocop: disable all

data/lib/bidi2pdf/bidi/interceptor.rb

@@ -46,7 +46,7 @@ module Bidi2pdf
         url = event_response["request"]["url"]
 
         # Log the interception
-        Bidi2pdf.logger.debug "Interceptor #{interceptor_id} handling event: #{navigation_id}/#{network_id}/#{url}"
+        Bidi2pdf.logger.debug1 "Interceptor #{interceptor_id} handling event: #{navigation_id}/#{network_id}/#{url}"
 
         process_interception(event_response, navigation_id, network_id, url)
       rescue StandardError => e

data/lib/bidi2pdf/bidi/js_logger_helper.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module Bidi
+    module JsLoggerHelper
+      private
+
+      def format_stack_trace(trace)
+        trace["callFrames"].each_with_index.map do |frame, index|
+          function = frame["functionName"].to_s.empty? ? "(anonymous)" : frame["functionName"]
+          "##{index} #{function} at #{frame["url"]}:#{frame["lineNumber"]}:#{frame["columnNumber"]}"
+        end.join("\n")
+      end
+    end
+  end
+end

data/lib/bidi2pdf/bidi/logger_events.rb

@@ -1,14 +1,16 @@
 # frozen_string_literal: true
 
 require_relative "network_event"
+require_relative "browser_console_logger"
 
 module Bidi2pdf
   module Bidi
     class LoggerEvents
-      attr_reader :context_id
+      attr_reader :context_id, :browser_console_logger
 
       def initialize(context_id)
         @context_id = context_id
+        @browser_console_logger = BrowserConsoleLogger.new(Bidi2pdf.browser_console_logger)
       end
 
       def handle_event(data)
@@ -18,9 +20,11 @@ module Bidi2pdf
         if event.dig("source", "context") == context_id
           handle_response(method, event)
         else
-          Bidi2pdf.logger.debug "Ignoring Log event: #{method}, context_id: #{context_id}, params: #{event}"
+          # this should be Bidi2pdf.logger and not Bidi2pdf.browser_console_logger
+          Bidi2pdf.logger.debug2 "Ignoring Log event: #{method}, context_id: #{context_id}, params: #{event}"
         end
       rescue StandardError => e
+        # this should be Bidi2pdf.logger and not Bidi2pdf.browser_console_logger
         Bidi2pdf.logger.error "Error handling Log event: #{e.message}\n#{e.backtrace&.join("\n")}"
       end
 
@@ -29,58 +33,34 @@ module Bidi2pdf
         text = event["text"]
         args = event["args"] || []
         stack_trace = event["stackTrace"]
-        timestamp = format_timestamp(event["timestamp"])
-        prefix = log_prefix(timestamp)
-
-        log_message(level, prefix, text)
-        log_args(prefix, args)
-        log_stack_trace(prefix, stack_trace) if stack_trace && level == :error
-      end
-
-      private
-
-      def log_message(level, prefix, text)
-        return unless text
-
-        Bidi2pdf.logger.send(level, "#{prefix} #{text}")
-      end
-
-      def log_args(prefix, args)
-        return if args.empty?
-
-        Bidi2pdf.logger.debug("#{prefix} Args: #{args.inspect}")
-      end
-
-      def log_stack_trace(prefix, trace)
-        formatted_trace = format_stack_trace(trace)
-        Bidi2pdf.logger.error("#{prefix} Stack trace captured:\n#{formatted_trace}")
-      end
-
-      def format_timestamp(timestamp)
-        return "N/A" unless timestamp
-
-        Time.at(timestamp.to_f / 1000).utc.strftime("%Y-%m-%d %H:%M:%S.%L UTC")
-      end
-
-      def format_stack_trace(trace)
-        trace["callFrames"].each_with_index.map do |frame, index|
-          function = frame["functionName"].to_s.empty? ? "(anonymous)" : frame["functionName"]
-          "##{index} #{function} at #{frame["url"]}:#{frame["lineNumber"]}:#{frame["columnNumber"]}"
-        end.join("\n")
+        timestamp = event["timestamp"]
+
+        Bidi2pdf.notification_service.instrument("browser_console_log_received.bidi2pdf",
+                                                 {
+                                                   level: level,
+                                                   text: text,
+                                                   args: args,
+                                                   stack_trace: stack_trace,
+                                                   timestamp: timestamp
+                                                 })
+
+        browser_console_logger.builder
+                              .with_level(level)
+                              .with_timestamp(timestamp)
+                              .with_text(text)
+                              .with_args(args)
+                              .with_stack_trace(stack_trace)
+                              .log_event
       end
 
       def resolve_log_level(js_level)
         case js_level
-        when "info", "warn", "error"
+        when "info", "warn", "error", "trace"
           js_level.to_sym
         else
           :debug
         end
       end
-
-      def log_prefix(timestamp)
-        "[#{timestamp}][Browser Console Log]"
-      end
     end
   end
 end

data/lib/bidi2pdf/bidi/network_event.rb

@@ -67,6 +67,21 @@ module Bidi2pdf
           "end=#{end_str}, " \
           "duration=#{took_str}>"
       end
+
+      def dup
+        self.class.new(
+          id: @id,
+          url: @url,
+          timestamp: @start_timestamp,
+          timing: @timing&.dup,
+          state: @state,
+          http_status_code: @http_status_code,
+          http_method: @http_method
+        ).tap do |duped|
+          duped.instance_variable_set(:@end_timestamp, @end_timestamp)
+          duped.instance_variable_set(:@bytes_received, @bytes_received)
+        end
+      end
     end
   end
 end

data/lib/bidi2pdf/bidi/network_event_formatters/network_event_console_formatter.rb

@@ -7,7 +7,7 @@ module Bidi2pdf
       class NetworkEventConsoleFormatter
         include NetworkEventFormatterUtils
 
-        attr_reader :color_enabled
+        attr_reader :color_enabled, :logger
 
         # ANSI styles
         RESET = "\e[0m"
@@ -19,12 +19,13 @@ module Bidi2pdf
         CYAN = "\e[36m"
         GRAY = "\e[90m"
 
-        def initialize(color: true)
+        def initialize(color: true, logger: Bidi2pdf.network_events_logger)
           @color_enabled = color
+          @logger = logger
         end
 
         def log(events)
-          events.each { |event| pretty_log(event).each_line { |line| Bidi2pdf.network_events_logger.info(line.chomp) } }
+          events.each { |event| pretty_log(event).each_line { |line| logger.info(line.chomp) } }
         end
 
         def pretty_log(event)