bidi2pdf 0.1.6 → 0.1.7

data/lib/bidi2pdf/bidi/network_events.rb

@@ -21,13 +21,13 @@ module Bidi2pdf
         if event["context"] == context_id
           handle_response(method, event)
         else
-          Bidi2pdf.logger.debug "Ignoring Network event: #{method}, #{context_id}, params: #{event}"
+          Bidi2pdf.logger.debug3 "Ignoring Network event: #{method}, #{context_id}, params: #{event}"
         end
       rescue StandardError => e
         Bidi2pdf.logger.error "Error handling network event: #{e.message}"
       end
 
-      # rubocop:disable Metrics/AbcSize
+      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
       def handle_response(method, event)
         return unless event && event["request"]
 
@@ -43,23 +43,33 @@ module Bidi2pdf
 
         timestamp = event["timestamp"]
 
-        if method == "network.beforeRequestSent"
-          events[id] ||= NetworkEvent.new(
-            id: id,
-            url: url,
-            timestamp: timestamp,
-            timing: timing,
-            state: method,
-            http_method: http_method
-          )
-        elsif events.key?(id)
-          events[id].update_state(method, timestamp: timestamp, timing: timing, http_status_code: http_status_code, bytes_received: bytes_received)
-        else
-          Bidi2pdf.logger.warn "Received response for unknown request ID: #{id}, URL: #{url}"
+        Bidi2pdf.notification_service.instrument("network_event_received.bidi2pdf",
+                                                 {
+                                                   id: id,
+                                                   method: method,
+                                                   url: url,
+                                                   http_status_code: http_status_code
+                                                 }) do |instrumentation_payload|
+          if method == "network.beforeRequestSent"
+            events[id] ||= NetworkEvent.new(
+              id: id,
+              url: url,
+              timestamp: timestamp,
+              timing: timing,
+              state: method,
+              http_method: http_method
+            )
+          elsif events.key?(id)
+            events[id].update_state(method, timestamp: timestamp, timing: timing, http_status_code: http_status_code, bytes_received: bytes_received)
+          else
+            Bidi2pdf.logger.warn "Received response for unknown request ID: #{id}, URL: #{url}"
+          end
+
+          instrumentation_payload[:event] = events[id]&.dup
         end
       end
 
-      # rubocop:enable Metrics/AbcSize
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
 
       def all_events
         events.values.sort_by(&:start_timestamp)
@@ -77,7 +87,7 @@ module Bidi2pdf
         end
       end
 
-      def wait_until_network_idle(timeout: 10, poll_interval: 0.1)
+      def wait_until_network_idle(timeout: 10, poll_interval: 0.01)
         start_time = Time.now
 
         loop do

data/lib/bidi2pdf/bidi/session.rb

@@ -7,14 +7,47 @@ require_relative "client"
 require_relative "browser"
 require_relative "user_context"
 
+# Represents a session for managing browser interactions and communication
+# using the Bidi2pdf library. This class handles the setup, configuration,
+# and execution of browser-related workflows, including session creation,
+# WebSocket communication, and browser management.
+#
+# @example Creating and starting a session
+#   session = Bidi2pdf::Bidi::Session.new(session_url: "http://example.com/session", headless: true)
+#   session.start
+#
+# @example Retrieving user contexts
+#   session.user_contexts
+#
+# @example Closing the session
+#   session.close
+#
+# @param [String] session_url The URL for the session.
+# @param [Boolean] headless Whether to run the browser in headless mode. Defaults to true.
+# @param [Array<String>] chrome_args Additional Chrome arguments. Defaults to predefined arguments.
 module Bidi2pdf
   module Bidi
     class Session
+      # Events to subscribe to during the session.
       SUBSCRIBE_EVENTS = %w[script].freeze
+
+      # Default Chrome arguments for the session.
       DEFAULT_CHROME_ARGS = %w[--disable-gpu --disable-popup-blocking --disable-hang-monitor].freeze
 
-      attr_reader :session_uri, :started, :chrome_args
+      # @return [URI] The URI of the session.
+      attr_reader :session_uri
+
+      # @return [Boolean] Whether the session has started.
+      attr_reader :started
+
+      # @return [Array<String>] The Chrome arguments for the session.
+      attr_reader :chrome_args
 
+      # Initializes a new session.
+      #
+      # @param [String] session_url The URL for the session.
+      # @param [Boolean] headless Whether to run the browser in headless mode. Defaults to true.
+      # @param [Array<String>] chrome_args Additional Chrome arguments. Defaults to predefined arguments.
       def initialize(session_url:, headless: true, chrome_args: DEFAULT_CHROME_ARGS)
         @session_uri = URI(session_url)
         @headless = headless
@@ -22,6 +55,9 @@ module Bidi2pdf
         @chrome_args = chrome_args.dup
       end
 
+      # Starts the session and initializes the client.
+      #
+      # @raise [StandardError] If an error occurs during session start.
       def start
         return if started?
 
@@ -32,41 +68,68 @@ module Bidi2pdf
         raise e
       end
 
+      # Returns the WebSocket client for the session.
+      #
+      # @return [Bidi2pdf::Bidi::Client, nil] The WebSocket client, or nil if the session is not started.
       def client
         @client ||= started? ? create_client : nil
       end
 
+      # Returns the browser instance for the session.
+      #
+      # @return [Bidi2pdf::Bidi::Browser] The browser instance.
       def browser
         @browser ||= create_browser
       end
 
+      # Closes the session and cleans up resources.
+      # rubocop:disable Metrics/AbcSize
       def close
         return unless started?
 
         2.times do |attempt|
-          client&.send_cmd_and_wait(Bidi2pdf::Bidi::Commands::SessionEnd.new, timeout: 1) do |response|
-            Bidi2pdf.logger.info "Session ended: #{response}"
-
-            cleanup
+          success = Bidi2pdf.notification_service.instrument("session_close.bidi2pdf", { session_uri: session_uri.to_s, attempt: attempt + 1 }) do |payload|
+            client&.send_cmd_and_wait(Bidi2pdf::Bidi::Commands::SessionEnd.new, timeout: 1) do |response|
+              payload[:response] = response
+              cleanup
+            end
+
+            true
+          rescue CmdTimeoutError => e
+            payload[:error] = e
+            payload[:retry] = attempt < 1 # whether we'll retry again
+
+            false
           end
-          break
-        rescue CmdTimeoutError
-          Bidi2pdf.logger.error "Session end command timed out. Retrying... (#{attempt + 1})"
+
+          break if success
         end
+      ensure
+        @started = false
       end
 
+      # rubocop: enable Metrics/AbcSize
+
+      # Retrieves user contexts for the session.
       def user_contexts
         send_cmd(Bidi2pdf::Bidi::Commands::GetUserContexts.new) { |resp| Bidi2pdf.logger.debug "User contexts: #{resp}" }
       end
 
+      # Retrieves the status of the session.
       def status
         send_cmd(Bidi2pdf::Bidi::Commands::SessionStatus.new) { |resp| Bidi2pdf.logger.info "Session status: #{resp.inspect}" }
       end
 
+      # Checks if the session has started.
+      #
+      # @return [Boolean] True if the session has started, false otherwise.
       def started?
         @started
       end
 
+      # Retrieves the WebSocket URL for the session.
+      #
+      # @return [String] The WebSocket URL.
       def websocket_url
         return @websocket_url if @websocket_url
 
@@ -79,11 +142,18 @@ module Bidi2pdf
 
       private
 
-      def send_cmd(command, &block)
-        client&.send_cmd_and_wait(command, &block)
+      # Sends a command to the WebSocket client.
+      #
+      # @param [Object] command The command to send.
+      # @yield [response] A block to handle the response.
+      def send_cmd(command, &)
+        client&.send_cmd_and_wait(command, &)
       end
 
-      # rubocop: disable Metrics/AbcSize
+      # Creates a new browser instance.
+      #
+      # @return [Bidi2pdf::Bidi::Browser] The browser instance.
+      # rubocop:disable Metrics/AbcSize
       def create_browser
         start
         client.start
@@ -103,12 +173,18 @@ module Bidi2pdf
         Bidi::Browser.new(client)
       end
 
-      # rubocop: enable Metrics/AbcSize
+      # rubocop:enable Metrics/AbcSize
 
+      # Creates a new WebSocket client.
+      #
+      # @return [Bidi2pdf::Bidi::Client] The WebSocket client.
       def create_client
         Bidi::Client.new(websocket_url).tap(&:start)
       end
 
+      # Creates a new session and retrieves the WebSocket URL.
+      #
+      # @return [String] The WebSocket URL.
       def create_new_session
         session_data = exec_api_call(session_request)
         Bidi2pdf.logger.debug "Session data: #{session_data}"
@@ -124,6 +200,9 @@ module Bidi2pdf
         ws_url
       end
 
+      # Builds the session request payload.
+      #
+      # @return [Hash] The session request payload.
       def session_request
         session_chrome_args = chrome_args.dup
         session_chrome_args << "--headless" if @headless
@@ -142,6 +221,10 @@ module Bidi2pdf
         }
       end
 
+      # Executes an API call with the given payload.
+      #
+      # @param [Hash] payload The payload for the API call.
+      # @return [Hash] The parsed response data.
       def exec_api_call(payload)
         response = Net::HTTP.post(session_uri, payload.to_json, "Content-Type" => "application/json")
         body = response.body
@@ -158,11 +241,20 @@ module Bidi2pdf
         build_error(error_type, "#{error_description(error_type)} #{e.message}", e.backtrace)
       end
 
+      # Logs an API error.
+      #
+      # @param [String] message The error message.
+      # @param [Integer] code The response code.
+      # @param [String] body The response body.
       def log_api_error(message, code, body)
         Bidi2pdf.logger.error "#{message}. Response code: #{code}"
         Bidi2pdf.logger.error "Response body: #{body}"
       end
 
+      # Determines the error category based on the exception.
+      #
+      # @param [Exception] exception The exception to categorize.
+      # @return [String] The error category.
       def error_category(exception)
         case exception
         when Errno::ECONNREFUSED then "Connection refused"
@@ -171,6 +263,10 @@ module Bidi2pdf
         end
       end
 
+      # Retrieves the error description for a given error type.
+      #
+      # @param [String] type The error type.
+      # @return [String] The error description.
       def error_description(type)
         {
           "Connection refused" => "Could not connect to the session URL:",
@@ -179,6 +275,12 @@ module Bidi2pdf
         }[type]
       end
 
+      # Builds an error response.
+      #
+      # @param [String] error The error type.
+      # @param [String] message The error message.
+      # @param [Array<String>, nil] backtrace The error backtrace.
+      # @return [Hash] The error response.
       def build_error(error, message, backtrace = nil)
         {
           "value" => {
@@ -189,6 +291,10 @@ module Bidi2pdf
         }
       end
 
+      # Handles an error response from the session.
+      #
+      # @param [Hash] value The error response value.
+      # @raise [SessionNotStartedError] If the session could not be started.
       def handle_error(value)
         error = value["error"]
         return unless error
@@ -208,6 +314,7 @@ module Bidi2pdf
               "Session not started. Check logs for more details. Error: #{error} message: #{msg}"
       end
 
+      # Cleans up resources associated with the session.
       def cleanup
         @client&.close
         @client = @websocket_url = @browser = nil

data/lib/bidi2pdf/bidi/user_context.rb

@@ -4,14 +4,41 @@ require_relative "browser_tab"
 
 module Bidi2pdf
   module Bidi
+    # Represents a user context for managing browser interactions and cookies
+    # using the Bidi2pdf library. This class provides methods for creating
+    # user contexts, setting cookies, and creating browser windows.
+    #
+    # @example Creating a user context
+    #   user_context = Bidi2pdf::Bidi::UserContext.new(client)
+    #
+    # @example Setting a cookie
+    #   user_context.set_cookie(
+    #     name: "session",
+    #     value: "abc123",
+    #     domain: "example.com",
+    #     source_origin: "http://example.com"
+    #   )
+    #
+    # @example Creating a browser window
+    #   browser_window = user_context.create_browser_window
+    #
+    # @param [Object] client The WebSocket client for communication.
     class UserContext
+      # @return [Object] The WebSocket client.
       attr_reader :client
 
+      # Initializes a new user context.
+      #
+      # @param [Object] client The WebSocket client for communication.
       def initialize(client)
         @client = client
         @context_id = nil
       end
 
+      # Retrieves the user context ID, creating it if it does not exist.
+      #
+      # @return [String] The user context ID.
+      # @raise [RuntimeError] If an error occurs while creating the user context.
       def context_id
         @context_id ||= begin
                           res = client.send_cmd_and_wait(Bidi2pdf::Bidi::Commands::BrowserCreateUserContext.new) do |response|
@@ -26,6 +53,17 @@ module Bidi2pdf
                         end
       end
 
+      # Sets a cookie in the user context.
+      #
+      # @param [String] name The name of the cookie.
+      # @param [String] value The value of the cookie.
+      # @param [String] domain The domain for the cookie.
+      # @param [String] source_origin The source origin for the cookie.
+      # @param [String] path The path for the cookie. Defaults to "/".
+      # @param [Boolean] secure Whether the cookie is secure. Defaults to true.
+      # @param [Boolean] http_only Whether the cookie is HTTP-only. Defaults to false.
+      # @param [String] same_site The SameSite attribute for the cookie. Defaults to "strict".
+      # @param [Integer] ttl The time-to-live for the cookie in seconds. Defaults to 30.
       def set_cookie(
         name:,
         value:,
@@ -55,6 +93,9 @@ module Bidi2pdf
         end
       end
 
+      # Creates a new browser window in the user context.
+      #
+      # @return [BrowserTab] The newly created browser tab.
       def create_browser_window
         cmd = Bidi2pdf::Bidi::Commands::CreateWindow.new(user_context_id: context_id)
 
@@ -64,6 +105,27 @@ module Bidi2pdf
           BrowserTab.new(client, browsing_context_id, context_id)
         end
       end
+
+      # Closes the user context.
+      #
+      # This method removes the user context from the browser, effectively cleaning up
+      # any associated resources. If the user context does not exist, the method does nothing.
+      #
+      # @return [nil]
+      # @raise [RuntimeError] If an error occurs while removing the user context.
+      def close
+        return unless context_id
+
+        res = client.send_cmd_and_wait(Bidi2pdf::Bidi::Commands::BrowserRemoveUserContext.new(user_context_id: context_id)) do |response|
+          raise "Error removing user context: #{response.inspect}" if response["error"]
+
+          response["result"]
+        end
+
+        Bidi2pdf.logger.debug "User context deleted: #{res.inspect}"
+
+        @context_id = nil
+      end
     end
   end
 end

data/lib/bidi2pdf/bidi/web_socket_dispatcher.rb

@@ -22,15 +22,15 @@ module Bidi2pdf
 
       # Add listeners
 
-      def on_message(&block) = socket_events.on(:message, &block)
+      def on_message(&) = socket_events.on(:message, &)
 
-      def on_event(name, &block) = session_events.on(name, &block)
+      def on_event(name, &) = session_events.on(name, &)
 
-      def on_open(&block) = socket_events.on(:open, &block)
+      def on_open(&) = socket_events.on(:open, &)
 
-      def on_close(&block) = socket_events.on(:close, &block)
+      def on_close(&) = socket_events.on(:close, &)
 
-      def on_error(&block) = socket_events.on(:error, &block)
+      def on_error(&) = socket_events.on(:error, &)
 
       def remove_message_listener(block) = socket_events.off(:message, block)
 
@@ -52,10 +52,10 @@ module Bidi2pdf
           method = data["method"]
 
           if method
-            Bidi2pdf.logger.debug "Dispatching session event: #{method}"
+            Bidi2pdf.logger.debug3 "Dispatching session event: #{method}"
             that.session_events.dispatch(method, data)
           else
-            Bidi2pdf.logger.debug "Dispatching socket message"
+            Bidi2pdf.logger.debug3 "Dispatching socket message"
             that.socket_events.dispatch(:message, data)
           end
         end

data/lib/bidi2pdf/chromedriver_manager.rb

@@ -5,13 +5,17 @@ require "securerandom"
 
 module Bidi2pdf
   class ChromedriverManager
-    attr_reader :port, :pid, :started
+    include Chromedriver::Binary::Platform
 
-    def initialize(port: 0, headless: true)
+    attr_reader :port, :pid, :started, :headless, :chrome_args, :shutdown_mutex
+
+    def initialize(port: 0, headless: true, chrome_args: Bidi::Session::DEFAULT_CHROME_ARGS)
       @port = port
       @headless = headless
       @session = nil
       @started = false
+      @chrome_args = chrome_args
+      @shutdown_mutex ||= Mutex.new
     end
 
     def start
@@ -23,11 +27,7 @@ module Bidi2pdf
       cmd = build_cmd
       Bidi2pdf.logger.info "Starting Chromedriver with command: #{cmd}"
 
-      r, w = IO.pipe
-      @pid = Process.spawn(cmd, out: w, err: w)
-      w.close # close writer in parent
-
-      parse_port_from_output(r)
+      spawn_process(cmd)
 
       Bidi2pdf.logger.info "Started Chromedriver on port #{@port}, PID #{@pid}"
       wait_until_chromedriver_ready
@@ -40,7 +40,7 @@ module Bidi2pdf
     def session
       return unless @started
 
-      @session ||= Bidi::Session.new(session_url: session_url, headless: @headless)
+      @session ||= Bidi::Session.new(session_url: session_url, headless: @headless, chrome_args: @chrome_args)
     end
 
     def session_url
@@ -50,27 +50,54 @@ module Bidi2pdf
     end
 
     def stop(timeout: 5)
-      return unless @pid
+      shutdown_mutex.synchronize do
+        return unless @pid
 
-      @started = false
+        @started = false
 
-      close_session
+        close_session
 
-      debug_show_all_children
+        debug_show_all_children
 
-      old_childprocesses = term_chromedriver
+        old_childprocesses = term_chromedriver
 
-      detect_zombie_processes old_childprocesses
+        detect_zombie_processes old_childprocesses
 
-      return unless process_alive?
+        return unless process_alive?
 
-      kill_chromedriver timeout: timeout
-    ensure
-      @pid = nil
+        kill_chromedriver timeout: timeout
+      ensure
+        @pid = nil
+        @started = false
+      end
     end
 
     private
 
+    def spawn_process(cmd)
+      r, w = IO.pipe
+
+      options = {
+        out: w,
+        err: w,
+        close_others: true,
+        chdir: Dir.tmpdir
+      }
+
+      if platform == "win"
+        options[:new_pgroup] = true
+      else
+        options[:pgroup] = true
+      end
+
+      env = {}
+
+      @pid = Process.spawn(env, cmd, **options)
+      w.close # close writer in parent
+
+      parse_port_from_output(r)
+    end
+
     def detect_zombie_processes(old_childprocesses)
       Bidi2pdf.logger.debug "Old child processes for #{@pid}: #{old_childprocesses.map(&:pid).join(", ")}"
 
@@ -99,7 +126,7 @@ module Bidi2pdf
       Bidi2pdf::ProcessTree.new(@pid).traverse do |process, level|
         indent = "  " * level
         prefix = level.zero? ? "" : "└─ "
-        Bidi2pdf.logger.debug "#{indent}#{prefix}PID #{process.pid} (#{process.name})"
+        Bidi2pdf.logger.debug2 "#{indent}#{prefix}PID #{process.pid} (#{process.name})"
       end
     end
 
@@ -114,7 +141,7 @@ module Bidi2pdf
       Bidi2pdf::ProcessTree.new(@pid).children(@pid).tap do |_child_processes|
         Bidi2pdf.logger.info "Stopping Chromedriver (PID #{@pid})"
 
-        Process.kill("TERM", @pid)
+        Process.kill("TERM", -@pid) # - meanskill linux pgroup
       end
     rescue Errno::ESRCH
       Bidi2pdf.logger.debug "Process already gone"
@@ -159,7 +186,7 @@ module Bidi2pdf
     def parse_port_from_output(io, timeout: 5)
       Thread.new do
         io.each_line do |line|
-          Bidi2pdf.logger.debug line.chomp
+          Bidi2pdf.logger.debug1 line.chomp
 
           next unless line =~ /ChromeDriver was started successfully on port (\d+)/
 

data/lib/bidi2pdf/cli.rb

@@ -51,6 +51,11 @@ module Bidi2pdf
     option :log_level,
            type: :string,
            default: "info", enum: %w[debug info warn error fatal unknown], desc: "Set log level"
+    verbosity_levels = Bidi2pdf::VerboseLogger::VERBOSITY_LEVELS.keys.sort_by { |k| Bidi2pdf::VerboseLogger::VERBOSITY_LEVELS[k] }
+    option :verbosity,
+           type: :string,
+           default: verbosity_levels.first, enum: Bidi2pdf::VerboseLogger::VERBOSITY_LEVELS.keys.sort_by { |k| Bidi2pdf::VerboseLogger::VERBOSITY_LEVELS[k] }.map(&:to_s),
+           desc: "Set debug verbosity level", aliases: "-v"
     option :log_network_traffic, type: :boolean, default: false, desc: "Log network traffic", aliases: "-n"
     option :network_log_format,
            type: :string,
@@ -216,12 +221,12 @@ module Bidi2pdf
                     end
     end
 
-    # rubocop:enable Metrics/AbcSize
-
     def configure
       Bidi2pdf.configure do |config|
         config.logger.level = log_level
 
+        config.logger.verbosity = merged_options[:verbosity]
+
         config.network_events_logger.level = Logger::INFO if merged_options[:log_network_traffic]
 
         config.default_timeout = merged_options[:default_timeout]
@@ -232,6 +237,8 @@ module Bidi2pdf
       end
     end
 
+    # rubocop: enable Metrics/MethodLength
+
     def log_level
       case merged_options[:log_level]
       when "debug" then Logger::DEBUG
@@ -266,3 +273,4 @@ module Bidi2pdf
     end
   end
 end
+# rubocop:enable Metrics/AbcSize

data/lib/bidi2pdf/dsl.rb

@@ -4,7 +4,39 @@ require "bidi2pdf"
 
 module Bidi2pdf
   module DSL
+    # Provides a DSL for managing browser sessions and tabs
+    # using the Bidi2pdf library. This module includes a method to create and manage
+    # browser tabs within a controlled session.
+
     # rubocop: disable  Metrics/AbcSize
+    #
+    # Executes a block of code within the context of a browser tab.
+    #
+    # This method handles the setup and teardown of a browser session, user context,
+    # browser window, and tab. It ensures that resources are properly cleaned up
+    # after the block is executed.
+    #
+    # @param [String, nil] remote_browser_url The URL of a remote browser to connect to.
+    #   If provided, the session will connect to this browser in headless mode.
+    # @param [Integer] port The port to use for the local browser session. Defaults to 0 (chooses a random port).
+    # @param [Boolean] headless Whether to run the browser in headless mode. Defaults to true.
+    # @param [Array<String>] chrome_args Additional arguments to pass to the Chrome browser.
+    #   Defaults to the `DEFAULT_CHROME_ARGS` from the `Bidi2pdf::Bidi::Session` class.
+    #
+    # @yield [tab] The browser tab created within the session.
+    # @yieldparam [Object] tab The browser tab object.
+    #
+    # @example Using a local browser session
+    #   Bidi2pdf::DSL.with_tab(port: 9222, headless: false) do |tab|
+    #     # Perform actions with the tab
+    #   end
+    #
+    # @example Using a remote browser session
+    #   Bidi2pdf::DSL.with_tab(remote_browser_url: "http://remote-browser:9222/session") do |tab|
+    #     # Perform actions with the tab
+    #   end
+    #
+    # @return [void]
     def self.with_tab(remote_browser_url: nil, port: 0, headless: true, chrome_args: Bidi2pdf::Bidi::Session::DEFAULT_CHROME_ARGS.dup)
       manager = nil
       session = nil
@@ -35,6 +67,7 @@ module Bidi2pdf
       ensure
         tab&.close
         window&.close
+        context&.close
         session&.close
         manager&.stop
       end