bidi2pdf 0.1.6 → 0.1.7

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 = 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

data/lib/bidi2pdf/verbose_logger.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  class VerboseLogger < SimpleDelegator
+    VERBOSITY_LEVELS = {
+      none: 0,
+      low: 1,
+      medium: 2,
+      high: 3
+    }.freeze
+
+    attr_reader :logger, :verbosity
+
+    def initialize(logger, verbosity = :low)
+      super(logger)
+      self.verbosity = verbosity
+      @logger = logger
+    end
+
+    def verbosity=(verbosity)
+      min_verbosity = VERBOSITY_LEVELS.values.min
+
+      @verbosity = if verbosity.is_a?(Numeric)
+                     verbosity = verbosity.to_i
+                     max_verbosity = VERBOSITY_LEVELS.values.max
+
+                     verbosity.clamp(min_verbosity, max_verbosity)
+                   else
+                     VERBOSITY_LEVELS.fetch verbosity.to_sym, min_verbosity
+                   end
+    end
+
+    def verbosity_sym
+      VERBOSITY_LEVELS.find { |_, v| v == verbosity }.first
+    end
+
+    def debug1(progname = nil, &)
+      return unless debug1?
+
+      logger.debug("[D1] #{progname}", &)
+    end
+
+    def debug1?
+      verbosity >= 1
+    end
+
+    def debug1!
+      @verbosity = VERBOSITY_LEVELS[:high]
+    end
+
+    def debug2(progname = nil, &)
+      return unless debug2?
+
+      logger.debug("[D2] #{progname}", &)
+    end
+
+    def debug2?
+      verbosity >= 2
+    end
+
+    def debug2!
+      @verbosity = VERBOSITY_LEVELS[:high]
+    end
+
+    def debug3(progname = nil, &)
+      return unless debug3?
+
+      logger.debug("[D3] #{progname}", &)
+    end
+
+    def debug3?
+      verbosity >= 3
+    end
+
+    def debug3!
+      @verbosity = VERBOSITY_LEVELS[:high]
+    end
+  end
+end

data/lib/bidi2pdf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bidi2pdf
-  VERSION = "0.1.6"
+  VERSION = "0.1.7"
 end

data/lib/bidi2pdf.rb

@@ -1,14 +1,30 @@
 # frozen_string_literal: true
 
-require_relative "bidi2pdf/utils"
 require_relative "bidi2pdf/process_tree"
 require_relative "bidi2pdf/launcher"
 require_relative "bidi2pdf/bidi/session"
 require_relative "bidi2pdf/dsl"
+require_relative "bidi2pdf/notifications"
+require_relative "bidi2pdf/notifications/logging_subscriber"
+require_relative "bidi2pdf/verbose_logger"
 
 require "logger"
 
 module Bidi2pdf
+  PAPER_FORMATS_CM = {
+    letter: { width: 21.59, height: 27.94 },
+    legal: { width: 21.59, height: 35.56 },
+    tabloid: { width: 27.94, height: 43.18 },
+    ledger: { width: 43.18, height: 27.94 },
+    a0: { width: 84.1, height: 118.9 },
+    a1: { width: 59.4, height: 84.1 },
+    a2: { width: 42.0, height: 59.4 },
+    a3: { width: 29.7, height: 42.0 },
+    a4: { width: 21.0, height: 29.7 },
+    a5: { width: 14.8, height: 21.0 },
+    a6: { width: 10.5, height: 14.8 }
+  }.freeze
+
   class Error < StandardError; end
 
   class SessionNotStartedError < Error; end
@@ -25,19 +41,95 @@ module Bidi2pdf
 
   class PrintError < Error; end
 
-  @logger = Logger.new($stdout)
-  @network_events_logger = Logger.new($stdout)
-  @logger.level = Logger::INFO
-  @network_events_logger.level = Logger::FATAL
+  class ScriptInjectionError < Error; end
+
+  class StyleInjectionError < Error; end
+
+  class NotificationsError < Error
+    attr_reader :causes
 
-  @default_timeout = 60
+    def initialize(causes)
+      @causes = causes
+      exception_class_names = causes.map { |e| e.class.name }
+      super("Notifications errors: #{exception_class_names.join(", ")}")
+    end
+  end
 
   class << self
-    attr_accessor :logger, :default_timeout, :network_events_logger
+    attr_accessor :default_timeout, :enable_default_logging_subscriber
+    attr_reader :logging_subscriber, :logger, :network_events_logger, :browser_console_logger, :notification_service
 
     # Allow configuration through a block
     def configure
       yield self if block_given?
+
+      init
+    end
+
+    def init
+      self.logging_subscriber = (Notifications::LoggingSubscriber.new(logger: logger) if enable_default_logging_subscriber)
+      begin
+        require "websocket-native"
+
+        logger.debug "websocket-native available; use enhance performance."
+      rescue LoadError => e
+        raise unless e.message =~ /websocket-native/
+
+        logger.warn "websocket-native not available; installing it may enhance performance."
+      end
+    end
+
+    def translate_paper_format(format)
+      format = format.to_s.downcase.to_sym
+
+      dim = PAPER_FORMATS_CM[format]
+
+      raise ArgumentError, "Invalid paper format: #{format}" unless dim
+
+      width = dim[:width] || 0
+      height = dim[:height] || 0
+
+      { width: width, height: height }
+    end
+
+    def logger=(new_logger)
+      @logger = Bidi2pdf::VerboseLogger.new new_logger
+    end
+
+    def network_events_logger=(new_network_events_logger)
+      @network_events_logger = Bidi2pdf::VerboseLogger.new(new_network_events_logger)
+    end
+
+    def browser_console_logger=(new_browser_console_logger)
+      @browser_console_logger = Bidi2pdf::VerboseLogger.new(new_browser_console_logger)
     end
+
+    def logging_subscriber=(new_logging_subscriber)
+      @logging_subscriber&.unsubscribe
+      @logging_subscriber = new_logging_subscriber
+    end
+
+    def notification_service=(new_notification_service)
+      @logging_subscriber&.unsubscribe
+
+      @notification_service = new_notification_service
+    end
+  end
+
+  configure do |config|
+    config.logger = Logger.new($stdout)
+    config.logger.level = Logger::INFO
+
+    config.network_events_logger = Logger.new($stdout)
+    config.network_events_logger.level = Logger::FATAL
+
+    config.browser_console_logger = Logger.new($stdout)
+    config.browser_console_logger.level = Logger::WARN
+
+    config.enable_default_logging_subscriber = true
+
+    config.default_timeout = 60
+
+    config.notification_service = Notifications
   end
 end

data/sig/bidi2pdf/bidi/client.rbs

@@ -34,7 +34,7 @@ module Bidi2pdf
 
       def wait_until_open: (?timeout: untyped) -> untyped
 
-      def send_cmd: (untyped method, ?::Hash[untyped, untyped] params) -> untyped
+      def send_cmd: (Bidi2pdf::Bidi::Commands::Base cmd) -> untyped
 
       # rubocop:disable Metrics/AbcSize
       def send_cmd_and_wait: (untyped method, ?::Hash[untyped, untyped] params, ?timeout: untyped) ?{ (untyped) -> untyped } -> untyped