bidi2pdf 0.1.5 → 0.1.7

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

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module Bidi
+    module NetworkEventFormatters
+      # rubocop: disable  Metrics/AbcSize
+      class NetworkEventConsoleFormatter
+        include NetworkEventFormatterUtils
+
+        attr_reader :color_enabled, :logger
+
+        # ANSI styles
+        RESET = "\e[0m"
+        BOLD = "\e[1m"
+        DIM = "\e[2m"
+        RED = "\e[31m"
+        GREEN = "\e[32m"
+        YELLOW = "\e[33m"
+        CYAN = "\e[36m"
+        GRAY = "\e[90m"
+
+        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| logger.info(line.chomp) } }
+        end
+
+        def pretty_log(event)
+          status = event.http_status_code ? "HTTP #{event.http_status_code}" : "pending"
+          status_color = color_for_status(event.http_status_code)
+          start = event.format_timestamp(event.start_timestamp)
+          finish = event.end_timestamp ? event.format_timestamp(event.end_timestamp) : dim("...")
+          duration = event.duration_seconds ? cyan("#{event.duration_seconds}s") : dim("in progress")
+          timing_details = format_timing(event)
+          bytes = event.bytes_received ? format_bytes(event.bytes_received) : dim("N/A")
+          displayed_url = shorten_url(event.url)
+
+          <<~LOG.strip
+            #{bold("┌─ Network Event ──────────────────────────────────────")}
+            #{bold("│ Request: ")}#{event.http_method || "?"} #{displayed_url}#{"          "}
+            #{bold("│ State:   ")}#{event.state}
+            #{bold("│ Status:  ")}#{status_color}#{status}#{reset}
+            #{bold("│ Started: ")}#{start}
+            #{bold("│ Ended:   ")}#{finish}
+            #{bold("│ Duration:")} #{duration}
+            #{bold("│ Received:")} #{bytes}
+            #{timing_details}
+            #{bold("└──────────────────────────────────────────────────────")}
+          LOG
+        end
+
+        private
+
+        def format_timing(event)
+          return "" unless event.timing.is_a?(Hash)
+
+          keys = %w[
+          requestTime proxyStart proxyEnd dnsStart dnsEnd connectStart connectEnd
+          sslStart sslEnd workerStart workerReady sendStart sendEnd receiveHeadersEnd
+        ]
+
+          visible = keys.map do |key|
+            next unless event.timing[key]
+
+            label = key.gsub(/([A-Z])/, ' \1').capitalize
+            "#{dim("│")} #{label.ljust(20)}: #{event.timing[key].round(2)} ms#{reset}"
+          end.compact
+
+          return "" if visible.empty?
+
+          [dim("│").to_s, dim("│ Timing Phases:").to_s].concat(visible).join("\n")
+        end
+
+        # === Color Helpers ===
+
+        def color_for_status(code)
+          return gray unless code
+
+          case code.to_i
+          when 200..299 then green
+          when 300..499 then yellow
+          when 500..599 then red
+          else gray
+          end
+        end
+
+        def bold(str) = color_enabled ? "#{BOLD}#{str}#{RESET}" : str
+
+        def dim(str) = color_enabled ? "#{DIM}#{str}#{RESET}" : str
+
+        def green(str = "") = color_enabled ? "#{GREEN}#{str}" : str
+
+        def yellow(str = "") = color_enabled ? "#{YELLOW}#{str}" : str
+
+        def red(str = "") = color_enabled ? "#{RED}#{str}" : str
+
+        def cyan(str = "") = color_enabled ? "#{CYAN}#{str}" : str
+
+        def gray(str = "") = color_enabled ? "#{GRAY}#{str}" : str
+
+        def reset = color_enabled ? RESET : ""
+
+        # rubocop: enable  Metrics/AbcSize
+      end
+    end
+  end
+end

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

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module Bidi2pdf
+  module Bidi
+    module NetworkEventFormatters
+      module NetworkEventFormatterUtils
+        def format_bytes(size)
+          return "N/A" unless size.is_a?(Numeric)
+
+          units = %w[B KB MB GB TB]
+          idx = 0
+          while size >= 1024 && idx < units.size - 1
+            size /= 1024.0
+            idx += 1
+          end
+          format("%<size>.2f %<unit>s", size: size, unit: units[idx])
+        end
+
+        def parse_timing(event)
+          return [] unless event.timing.is_a?(Hash)
+
+          keys = %w[
+          requestTime proxyStart proxyEnd dnsStart dnsEnd connectStart connectEnd
+          sslStart sslEnd workerStart workerReady sendStart sendEnd receiveHeadersEnd
+        ]
+
+          keys.filter_map do |key|
+            next unless event.timing[key]
+
+            label = key.gsub(/([A-Z])/, ' \1').capitalize
+            { label: label, key: key, ms: event.timing[key].round(2) }
+          end
+        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 shorten_url(url)
+          sanitized_url = CGI.escapeHTML(url)
+
+          return sanitized_url unless sanitized_url.start_with?("data:text/html")
+
+          "data:text/html,..."
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module Bidi
+    module NetworkEventFormatters
+      class NetworkEventHtmlFormatter
+        include NetworkEventFormatterUtils
+
+        def render(events)
+          return unless Bidi2pdf.network_events_logger.info?
+
+          <<~HTML
+            <!DOCTYPE html>
+            <html lang="en" data-bs-theme="light">
+            <head>
+              <meta charset="UTF-8">
+              <title>Network Events</title>
+              <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
+              <style>
+                body { font-family: monospace; padding: 2rem; }
+                .event { background: var(--bs-body-bg); border: 1px solid var(--bs-border-color); padding: 1rem; margin-bottom: 2rem; border-radius: .5rem; box-shadow: 0 1px 3px rgba(0,0,0,0.1); }
+                .bar-container { position: relative; height: 20px; background: var(--bs-secondary-bg); border-radius: 4px; }
+                .bar { position: absolute; top: 0; height: 100%; background-color: #0d6efd; opacity: 0.8; }
+                .toc a { text-decoration: none; display: block; margin-bottom: 0.5rem; }
+
+                @media print {
+                  .no-break {
+                    page-break-inside: avoid;
+                  }
+            #{"    "}
+            #{"     "}
+                  .form-select, .form-label, #theme-select {
+                    display: none !important; /* Hide theme selector when printing */
+                  }
+                }
+
+                .event {
+                  word-break: break-word;
+                  overflow-wrap: anywhere;
+                }
+              </style>
+              <script>
+                function toggleTheme(value) {
+                  document.documentElement.setAttribute('data-bs-theme', value);
+                }
+              </script>
+            </head>
+            <body>
+              <h1>Network Events</h1>
+              <div class="mb-4">
+                <label for="theme-select" class="form-label">Theme:</label>
+                <select id="theme-select" class="form-select w-auto d-inline-block" onchange="toggleTheme(this.value)">
+                  <option value="light">Light</option>
+                  <option value="dark">Dark</option>
+                </select>
+              </div>
+
+              <h2>Index</h2>
+              <div class="toc mb-4">
+                #{events.map.with_index { |e, i| toc_entry(e, i) }.join("\n")}
+              </div>
+
+              #{events.map.with_index { |e, i| render_event(e, i) }.join("\n")}
+            </body>
+            </html>
+          HTML
+        end
+
+        def toc_entry(event, index)
+          "<a href=\"#event-#{index}\">[#{index + 1}] #{event.http_method} #{event.url}</a>"
+        end
+
+        # rubocop: disable Metrics/AbcSize
+        def render_event(event, index)
+          timing = parse_timing(event)
+          duration = event.duration_seconds || 0
+          duration_str = event.in_progress? ? "in progress" : "#{duration}s"
+          status = event.http_status_code || "?"
+          method = event.http_method || "?"
+          start = format_timestamp(event.start_timestamp)
+          finish = event.end_timestamp ? format_timestamp(event.end_timestamp) : "..."
+          bytes = event.bytes_received ? format_bytes(event.bytes_received) : "N/A"
+          bars = render_timing_bars(timing)
+          displayed_url = shorten_url(event.url)
+
+          <<~HTML
+            <div class="event no-break" id="event-#{index}">
+              <div><strong>Request:</strong> #{method} #{displayed_url}</div>
+              <div><strong>Status:</strong> HTTP #{status}</div>
+              <div><strong>State:</strong> #{event.state}</div>
+              <div><strong>Start:</strong> #{start}</div>
+              <div><strong>End:</strong> #{finish}</div>
+              <div><strong>Duration:</strong> #{duration_str}</div>
+              <div><strong>Received:</strong> #{bytes}</div>
+              #{bars}
+            </div>
+          HTML
+        end
+
+        # rubocop: enable Metrics/AbcSize
+
+        def render_timing_bars(timing)
+          return "" if timing.empty?
+
+          max_ms = timing.map { |t| t[:ms] }.max
+          scale = max_ms.zero? ? 0 : 100.0 / max_ms
+
+          bars = timing.map do |t|
+            width = (t[:ms] * scale).clamp(1, 100).round(2)
+            <<~HTML
+              <div>
+                <small>#{t[:label]} (#{t[:ms]} ms)</small>
+                <div class="bar-container mb-2">
+                  <div class="bar" style="width: #{width}%"></div>
+                </div>
+              </div>
+            HTML
+          end
+
+          "<div class=\"mt-3\"><strong>Timing Waterfall</strong>#{bars.join}</div>"
+        end
+      end
+    end
+  end
+end

data/lib/bidi2pdf/bidi/network_event_formatters.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module Bidi
+    module NetworkEventFormatters
+      require_relative "network_event_formatters/network_event_formatter_utils"
+      require_relative "network_event_formatters/network_event_console_formatter"
+      require_relative "network_event_formatters/network_event_html_formatter"
+    end
+  end
+end

data/lib/bidi2pdf/bidi/network_events.rb

@@ -1,15 +1,17 @@
 # frozen_string_literal: true
 
 require_relative "network_event"
+require_relative "network_event_formatters"
 
 module Bidi2pdf
   module Bidi
     class NetworkEvents
-      attr_reader :context_id, :events
+      attr_reader :context_id, :events, :network_event_formatter
 
       def initialize(context_id)
         @context_id = context_id
         @events = {}
+        @network_event_formatter = NetworkEventFormatters::NetworkEventConsoleFormatter.new
       end
 
       def handle_event(data)
@@ -19,46 +21,73 @@ 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"]
 
         request = event["request"]
+        response = event["response"]
+        http_status_code = response&.dig("status")
+        bytes_received = response&.dig("bytesReceived")
 
         id = request["request"]
         url = request["url"]
         timing = request["timings"]
+        http_method = request["method"]
 
         timestamp = event["timestamp"]
 
-        if method == "network.responseStarted"
-          events[id] ||= NetworkEvent.new(
-            id: id,
-            url: url,
-            timestamp: timestamp,
-            timing: timing,
-            state: method
-          )
-        elsif events.key?(id)
-          events[id].update_state(method, timestamp: timestamp, timing: timing)
-        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)
       end
 
-      def wait_until_all_finished(timeout: 10, poll_interval: 0.1)
+      def log_network_traffic(format: :console)
+        format = format.to_sym
+
+        if format == :console
+          NetworkEventFormatters::NetworkEventConsoleFormatter.new.log all_events
+        elsif format == :html
+          NetworkEventFormatters::NetworkEventHtmlFormatter.new.render(all_events)
+        else
+          raise ArgumentError, "Unknown network event format: #{format}"
+        end
+      end
+
+      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
-      SUBSCRIBE_EVENTS = %w[log script].freeze
+      # 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