bidi2pdf 0.1.5 → 0.1.7

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,17 @@ 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,
+           default: "console",
+           enum: %w[console pdf],
+           desc: "Choose network log format: console or pdf", aliases: "-f"
 
     option :background, type: :boolean, default: true, desc: "Print background graphics"
     option :margin_top, type: :numeric, default: 1.0, desc: "Top margin in inches"
@@ -64,6 +75,12 @@ module Bidi2pdf
     option :scale, type: :numeric, default: 1.0, desc: "Scale between 0.1 and 2.0"
     option :shrink_to_fit, type: :boolean, default: true, desc: "Shrink content to fit page"
 
+    class << self
+      def exit_on_failure?
+        true
+      end
+    end
+
     def render
       load_config
 
@@ -198,16 +215,20 @@ module Bidi2pdf
                         headless: merged_options[:headless],
                         wait_window_loaded: merged_options[:wait_window_loaded],
                         wait_network_idle: merged_options[:wait_network_idle],
-                        print_options: print_options
+                        print_options: print_options,
+                        network_log_format: merged_options[:network_log_format]
                       )
                     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]
 
         Chromedriver::Binary.configure do |c|
@@ -216,6 +237,8 @@ module Bidi2pdf
       end
     end
 
+    # rubocop: enable Metrics/MethodLength
+
     def log_level
       case merged_options[:log_level]
       when "debug" then Logger::DEBUG
@@ -250,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,10 +5,40 @@ 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,
-                   wait_network_idle: false, print_options: {}, remote_browser_url: nil)
+                   wait_network_idle: false, print_options: {}, remote_browser_url: nil, network_log_format: :console)
       @url = url
       @inputfile = inputfile
       @port = port
@@ -23,6 +53,7 @@ module Bidi2pdf
       @print_options = print_options || {}
       @remote_browser_url = remote_browser_url
       @custom_session = nil
+      @network_log_format = network_log_format
     end
 
     # rubocop:enable Metrics/ParameterLists
@@ -38,7 +69,8 @@ module Bidi2pdf
         auth: @auth,
         wait_window_loaded: @wait_window_loaded,
         wait_network_idle: @wait_network_idle,
-        print_options: @print_options
+        print_options: @print_options,
+        network_log_format: @network_log_format
       )
       runner.run
     end

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