bidi2pdf 0.1.6 → 0.1.8

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

data/lib/bidi2pdf/launcher.rb

@@ -5,6 +5,36 @@ require_relative "session_runner"
 require_relative "bidi/session"
 
 module Bidi2pdf
+  # Represents a launcher for managing browser sessions and executing tasks
+  # using the Bidi2pdf library. This class handles the setup and teardown
+  # of browser sessions, as well as the execution of tasks within those sessions.
+  #
+  # @example Launching a session
+  #   launcher = Bidi2pdf::Launcher.new(
+  #     url: "http://example.com",
+  #     inputfile: "input.pdf",
+  #     output: "output.pdf",
+  #     cookies: [],
+  #     headers: {},
+  #     auth: nil,
+  #     headless: true
+  #   )
+  #   launcher.launch
+  #   launcher.stop
+  #
+  # @param [String] url The URL to navigate to in the browser session.
+  # @param [String] inputfile The path to the input file to be processed.
+  # @param [String] output The path to the output file to be generated.
+  # @param [Array<Hash>] cookies An array of cookies to set in the browser session.
+  # @param [Hash] headers A hash of HTTP headers to include in the browser session.
+  # @param [Hash, nil] auth Authentication credentials (e.g., username and password).
+  # @param [Boolean] headless Whether to run the browser in headless mode. Defaults to true.
+  # @param [Integer] port The port to use for the browser session. Defaults to 0.
+  # @param [Boolean] wait_window_loaded Whether to wait for the window to fully load. Defaults to false.
+  # @param [Boolean] wait_network_idle Whether to wait for the network to become idle. Defaults to false.
+  # @param [Hash] print_options Options for printing the page. Defaults to an empty hash.
+  # @param [String, nil] remote_browser_url The URL of a remote browser to connect to. Defaults to nil.
+  # @param [Symbol] network_log_format The format for network logs. Defaults to :console.
   class Launcher
     # rubocop:disable Metrics/ParameterLists
     def initialize(url:, inputfile:, output:, cookies:, headers:, auth:, headless: true, port: 0, wait_window_loaded: false,

data/lib/bidi2pdf/notifications/event.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  # rubocop: disable Lint/RescueException
+  module Notifications
+    class Event
+      attr_reader :name, :transaction_id
+      attr_accessor :payload
+
+      def initialize(name, start, ending, transaction_id, payload)
+        @name = name
+        @payload = payload
+        @time = start ? start.to_f * 1_000.0 : start
+        @transaction_id = transaction_id
+        @end = ending ? ending.to_f * 1_000.0 : ending
+      end
+
+      def record # :nodoc:
+        start!
+        begin
+          yield payload if block_given?
+        rescue Exception => e
+          payload[:exception] = [e.class.name, e.message]
+          payload[:exception_object] = e
+          raise e
+        ensure
+          finish!
+        end
+      end
+
+      def start! = @time = now
+
+      def finish! = @end = now
+
+      def duration = @end - @time
+
+      def time
+        @time / 1000.0 if @time
+      end
+
+      def end
+        @end / 1000.0 if @end
+      end
+
+      private
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC, :float_millisecond)
+    end
+  end
+end
+
+# rubocop: enable Lint/RescueException

data/lib/bidi2pdf/notifications/instrumenter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Bidi2pdf
+  # This module provides a way to instrument events in the Bidi2pdf library.
+  # It it's heavyly inspired by ActiveSupport::Notifications.
+  # and thought to be used in a similar way.
+  # In Rails environment, ActiveSupport::Notifications should be use instead.
+  # via configuration: Bidi2pdf.notification_service = ActiveSupport::Notifications
+
+  # rubocop: disable Lint/RescueException, Lint/SuppressedException
+  module Notifications
+    class Instrumenter
+      attr_reader :id
+
+      def initialize
+        @id = SecureRandom.uuid
+      end
+
+      def notify(name, payload, &)
+        event = create_event(name, payload)
+        result = nil
+        begin
+          result = event.record(&)
+        rescue Exception => e
+        end
+
+        subscriber_exceptions = notify_subscribers(name, event)
+
+        raise Bidi2pdf::NotificationsError.new(subscriber_exceptions), cause: subscriber_exceptions.first if subscriber_exceptions.any?
+        raise e if e
+
+        result
+      end
+
+      private
+
+      def create_event(name, payload)
+        Event.new(name, nil, nil, @id, payload)
+      end
+
+      # rubocop:disable  Style/CaseEquality
+      def notify_subscribers(name, event)
+        exceptions = []
+
+        Notifications.subscribers.each do |pattern, blocks|
+          next unless pattern === name
+
+          blocks.each do |subscriber|
+            subscriber.call(event)
+          rescue Exception => e
+            exceptions << e
+          end
+        end
+
+        exceptions
+      end
+
+      # rubocop:enable Style/CaseEquality
+    end
+  end
+end
+
+# rubocop: enable Lint/RescueException, Lint/SuppressedException

data/lib/bidi2pdf/notifications/logging_subscriber.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module Notifications
+    # for reuse within ActiveSupport::LogSubscriber
+    module LoggingSubscriberActions
+      def handle_response(event)
+        payload = event.payload
+
+        if payload[:error]
+          logger.error "Received error: #{payload[:error].inspect} for cmd: #{payload[:id] || "-"}"
+        elsif !payload[:handled]
+          Bidi2pdf.logger.warn "Unknown response: #{payload[:data].inspect}"
+        end
+      end
+
+      def send_cmd(event)
+        logger.debug "Sending command: #{event.payload[:cmd].method_name} id: ##{event.payload[:cmd_payload][:id]}"
+
+        logger.debug1 do
+          payload = redact_sensitive_fields(event.payload[:cmd_payload])
+          "Sending command: #{payload.inspect} (#{event.duration.round(1)}ms)"
+        end
+      end
+
+      def send_cmd_and_wait(event)
+        return unless event.payload[:exception]
+
+        payload = redact_sensitive_fields(event.payload[:cmd]&.params || {})
+        logger.error "Error sending command: #{payload} (#{event.duration.round(1)}ms) - #{event.payload[:exception].inspect}"
+      end
+
+      def session_close(event)
+        return unless event.payload[:error]
+
+        logger.error "Session close error: #{event.payload[:error].inspect}, attempt: #{event.payload[:attempt]}, retry: #{event.payload[:retry]}"
+      end
+
+      # rubocop: disable Metrics/AbcSize
+      def network_event_received(event)
+        return unless logger.debug2?
+
+        msg = case event.payload[:method]
+              when "network.beforeRequestSent"
+                "Request url '#{event.payload[:url]}' started"
+
+              when "network.responseStarted"
+                nil
+              when "network.responseCompleted"
+                "Request url '#{event.payload[:url]}' completed"
+              when "network.fetchError"
+                "Request url '#{event.payload[:url]}' error."
+              else
+                "Unknown network event: #{event.payload[:method]} for url '#{event.payload[:url]}'"
+              end
+
+        logger.debug2 msg if msg
+      end
+
+      # rubocop:disable  Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+      def network_idle(event)
+        return unless logger.info?
+
+        requests = event.payload[:requests]
+        transfered = requests.map { |request| request.bytes_received || 0 }.sum
+        status_counts = requests
+                          .group_by { |evt| evt.http_status_code || 0 }
+                          .transform_keys { |code| code.zero? || code.nil? ? "pending" : code.to_s }
+                          .transform_values(&:count)
+                          .map { |code, count| "#{code}: #{count}" }
+                          .join(", ")
+
+        logger.info "Network was idle after #{event.duration.round(1)}ms, #{requests.size} requests, " \
+                      "transferred #{transfered} bytes (status codes: #{status_counts})"
+      end
+
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity
+
+      def page_loaded(event)
+        logger.info "Page loaded: #{event.duration.round(1)}ms"
+      end
+
+      def print(event)
+        logger.info "Page printed: #{event.duration.round(1)}ms"
+      end
+
+      private
+
+      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
+        end
+      end
+    end
+
+    class LoggingSubscriber
+      include LoggingSubscriberActions
+
+      attr_accessor :logger
+
+      # rubocop: disable Metrics/AbcSize, Metrics/CyclomaticComplexity,  Metrics/PerceivedComplexity
+      def initialize(logger: Logger.new($stdout))
+        @logger = logger
+        Bidi2pdf.notification_service&.subscribe("handle_response.bidi2pdf", &method(:handle_response))
+        Bidi2pdf.notification_service&.subscribe("send_cmd.bidi2pdf", &method(:send_cmd))
+        Bidi2pdf.notification_service&.subscribe("send_cmd_and_wait.bidi2pdf", &method(:send_cmd_and_wait))
+        Bidi2pdf.notification_service&.subscribe("session_close.bidi2pdf", &method(:session_close))
+        Bidi2pdf.notification_service&.subscribe("network_idle.bidi2pdf", &method(:network_idle))
+        Bidi2pdf.notification_service&.subscribe("page_loaded.bidi2pdf", &method(:page_loaded))
+        Bidi2pdf.notification_service&.subscribe("network_event_received.bidi2pdf", &method(:network_event_received))
+        Bidi2pdf.notification_service&.subscribe("print.bidi2pdf", &method(:network_event_received))
+      end
+
+      def unsubscribe
+        Bidi2pdf.notification_service&.unsubscribe("handle_response.bidi2pdf", &method(:handle_response))
+        Bidi2pdf.notification_service&.unsubscribe("send_cmd.bidi2pdf", &method(:send_cmd))
+        Bidi2pdf.notification_service&.unsubscribe("send_cmd_and_wait.bidi2pdf", &method(:send_cmd_and_wait))
+        Bidi2pdf.notification_service&.unsubscribe("session_close.bidi2pdf", &method(:session_close))
+        Bidi2pdf.notification_service&.unsubscribe("network_idle.bidi2pdf", &method(:network_idle))
+        Bidi2pdf.notification_service&.unsubscribe("page_loaded.bidi2pdf", &method(:page_loaded))
+        Bidi2pdf.notification_service&.unsubscribe("network_event_received.bidi2pdf", &method(:network_event_received))
+        Bidi2pdf.notification_service&.unsubscribe("print.bidi2pdf", &method(:network_event_received))
+      end
+
+      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity,  Metrics/PerceivedComplexity
+    end
+  end
+end

data/lib/bidi2pdf/notifications.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "chromedriver_manager"
+require_relative "session_runner"
+require_relative "bidi/session"
+require_relative "notifications/event"
+require_relative "notifications/instrumenter"
+
+require "securerandom"
+
+module Bidi2pdf
+  # This module provides a way to instrument events in the Bidi2pdf library.
+  # It it's heavyly inspired by ActiveSupport::Notifications.
+  # and thought to be used in a similar way.
+  # In Rails environment, ActiveSupport::Notifications should be used instead.
+  # via configuration: config.notification_service = ActiveSupport::Notifications
+
+  module Notifications
+    Thread.attr_accessor :bidi2pdf_notification_instrumenter
+
+    @subscribers = Concurrent::Hash.new { |h, k| h[k] = [] }
+
+    class << self
+      attr_reader :subscribers
+
+      def instrument(name, payload = {})
+        payload = payload.dup
+
+        if listening?(name)
+          notify(name, payload) { yield payload if block_given? }
+        elsif block_given?
+          yield payload
+        end
+      end
+
+      def subscribe(event_pattern, &block)
+        pattern = normalize_pattern(event_pattern)
+
+        @subscribers[pattern] << block
+
+        block
+      end
+
+      def unsubscribe(event_pattern, block = nil)
+        pattern = normalize_pattern(event_pattern)
+
+        if block
+          @subscribers[pattern].delete(block)
+        else
+          @subscribers[pattern].clear
+        end
+      end
+
+      # rubocop: disable Style/CaseEquality
+      def listening?(name)
+        @subscribers.any? do |pattern, blocks|
+          pattern === name && blocks.any?
+        end
+      end
+
+      # rubocop: enable Style/CaseEquality
+
+      private
+
+      def bidi2pdf_notification_instrumenter = Thread.current.bidi2pdf_notification_instrumenter ||= Instrumenter.new
+
+      def notify(name, payload, &) = bidi2pdf_notification_instrumenter.notify(name, payload, &)
+
+      def normalize_pattern(pat)
+        case pat
+        when String, Regexp then pat
+        else
+          raise ArgumentError, "Pattern must be String or Regexp"
+        end
+      end
+    end
+  end
+end

data/lib/bidi2pdf/session_runner.rb

@@ -1,6 +1,38 @@
 # frozen_string_literal: true
 
 module Bidi2pdf
+  # Represents a runner for managing browser sessions and executing tasks
+  # using the Bidi2pdf library. This class handles the setup, configuration,
+  # and execution of browser-related workflows, including navigation, cookie
+  # management, and printing.
+  #
+  # @example Running a session
+  #   session_runner = Bidi2pdf::SessionRunner.new(
+  #     session: session,
+  #     url: "http://example.com",
+  #     inputfile: "input.html",
+  #     output: "output.pdf",
+  #     cookies: { "key" => "value" },
+  #     headers: { "Authorization" => "Bearer token" },
+  #     auth: { username: "user", password: "pass" },
+  #     wait_window_loaded: true,
+  #     wait_network_idle: true,
+  #     print_options: { landscape: true },
+  #     network_log_format: :json
+  #   )
+  #   session_runner.run
+  #
+  # @param [Object] session The browser session object to use.
+  # @param [String, nil] url The URL to navigate to in the browser session.
+  # @param [String, nil] inputfile The path to the input file to be processed if no URL is provided.
+  # @param [String, nil] output The path to the output file to be generated.
+  # @param [Hash] cookies A hash of cookies to set in the browser session. Defaults to an empty hash.
+  # @param [Hash] headers A hash of HTTP headers to include in the browser session. Defaults to an empty hash.
+  # @param [Hash, nil] auth Authentication credentials (e.g., username and password). Defaults to an empty hash.
+  # @param [Boolean] wait_window_loaded Whether to wait for the window to fully load. Defaults to false.
+  # @param [Boolean] wait_network_idle Whether to wait for the network to become idle. Defaults to false.
+  # @param [Hash] print_options Options for printing the page. Defaults to an empty hash.
+  # @param [Symbol] network_log_format The format for network logs. Defaults to :console.
   class SessionRunner
     # rubocop: disable Metrics/ParameterLists
     def initialize(session:, url:, inputfile:, output:, cookies: {}, headers: {}, auth: {}, wait_window_loaded: false,
@@ -39,6 +71,7 @@ module Bidi2pdf
 
       @window = window
       @tab = tab
+      @user_context = user_context
 
       add_cookies(tab)
 
@@ -99,15 +132,14 @@ module Bidi2pdf
 
       if @wait_window_loaded
         Bidi2pdf.logger.info "Waiting for window to be loaded"
-        @tab.execute_script <<-EOF_SCRIPT
-            new Promise(resolve => { const check = () => window.loaded ? resolve('done') : setTimeout(check, 100); check(); });
-        EOF_SCRIPT
+        @tab.wait_until_page_loaded
       end
 
       @tab.print(@output, print_options: @print_options)
     ensure
       @tab.close
       @window.close
+      @user_context.close
     end
 
     # rubocop: enable Metrics/AbcSize