bidi2pdf 0.1.3 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 715f3587349e1680386f0c485f45b91a6096143c07cc8b531ca7e284a9516615
-  data.tar.gz: 8914fd60cdb04510070dee6b6d7134a94666584583681e26e830824bbf457059
+  metadata.gz: b92ff566ca3ae322033cd9602818c94ae30da2594c7075bbb86f4c16351d58ce
+  data.tar.gz: 1b4d46aa7fe35c1810522a51400c3558f04d8fdc4093c7b3efa0f507a4959392
 SHA512:
-  metadata.gz: a8e17273531b0131ef9e8b5454154996dbd340d18cbf16a151478b91234e1e53005e0ffb057e16d540f6870b8915bafbdf03831afc2d9b4e9d861494ca13c38f
-  data.tar.gz: d0a4d3b193fc51b681a2e3b54da5cc7cccf05cf578b908144eb7ca5988327f0ee938b07dce88ca826d37889a469e3f32a7da61c68bbb05b5913731aeb0cc9e38
+  metadata.gz: 63aa303c4dc6245510cb212adaf22523190d8e00892f4ffe9dc9ba9b65e966f74517ee748f4a232736701a3271ae086879fcbf0adc02ce9f9cd82d103ea3e70d
+  data.tar.gz: 320a0a03c399541157bd192b6389fecf5541c994cdcaa186694085887ecc8de0829b63badc2be5fa0cd2b8c9baa4ee60bfe7a2f457743d4f21506f1d4bb44850

data/.rubocop.yml

@@ -20,11 +20,29 @@ RSpec/ExampleLength:
 Layout/MultilineMethodCallIndentation:
   Enabled: false
 
+Layout/FirstArgumentIndentation:
+  Enabled: false
+
+Layout/ClosingParenthesisIndentation:
+  Enabled: false
+
 Layout/FirstHashElementIndentation:
   EnforcedStyle: consistent
 
 Layout/FirstArrayElementIndentation:
-  EnforcedStyle: consistent
+  Enabled: false
+
+Layout/MultilineOperationIndentation:
+  Enabled: false
+
+Layout/BeginEndAlignment:
+  Enabled: false
+
+Layout/ArrayAlignment:
+  Enabled: false
+
+Layout/LineLength:
+  Enabled: false
 
 RSpec/MultipleMemoizedHelpers:
   Max: 10

data/CHANGELOG.md

@@ -6,12 +6,49 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.5..HEAD
 
-## [Unreleased]
+<!-- generated by git-cliff end -->
 
-[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.2..HEAD
+## [0.1.5] - 2025-04-10
 
-<!-- generated by git-cliff end -->
+### 📝 Docs
+
+- Improve README structure and update content by @dieter-medium
+- Add step-by-step usage guide to README by @dieter-medium
+
+### 🚀 Added
+
+- Add support for rendering local HTML files or in memory HTML by @dieter-medium
+- Add DSL and specs for generating PDFs with browser tabs by @dieter-medium
+- Enhance print method with block support for PDF handling by @dieter-medium
+
+## [0.1.4] - 2025-04-10
+
+### 🎨 Refactored
+
+- Modularize browser commands and remove redundancy by @dieter-medium
+- Implement interceptor validation and unit tests by @dieter-medium
+- Connection handling in ConnectionManager by @dieter-medium
+- Interceptors to enforce common interface methods by @dieter-medium
+- Interceptors to simplify client responsibilities by @dieter-medium
+- Enhance error handling and modularize interceptors by @dieter-medium
+
+### 🐛 Fixed
+
+- Resolve race condition between event subscription and emission by @dieter-medium
+- Close custom session on stop function by @dieter-medium
+- Add custom error classes for session management and improve error handling and testability by @dieter-medium
+- Add Chromedriver container support and helper methods for RSpec integration by @dieter-medium
+
+### 🔄 Changed
+
+- Enhance command manager with response handling by @dieter-medium
+
+### 🚀 Added
+
+- Add randomization to user data directory path by @dieter-medium
+- Introduce command abstraction for improved modularity by @dieter-medium
 
 ## [0.1.3] - 2025-04-06
 

data/README.md

@@ -3,52 +3,58 @@
 [![Gem Version](https://badge.fury.io/rb/bidi2pdf.svg)](https://badge.fury.io/rb/bidi2pdf)
 [![Test Coverage](https://api.codeclimate.com/v1/badges/6425d9893aa3a9ca243e/test_coverage)](https://codeclimate.com/github/dieter-medium/bidi2pdf/test_coverage)
 
-# Bidi2pdf
+---
 
-Bidi2pdf is a Ruby gem that generates high-quality PDFs from web pages using Chrome's BiDi (BiDirectional) protocol. It
-offers precise control over PDF generation with support for modern web technologies.
+# 📄 Bidi2pdf – Bulletproof PDF generation via Chrome's BiDi Protocol
 
-## Features
+**Bidi2pdf** is a powerful Ruby gem that transforms modern web pages into high-fidelity PDFs using Chrome’s *
+*BiDirectional (BiDi)** protocol. Whether you're automating reports, archiving websites, or shipping documentation,
+Bidi2pdf gives you **precision, flexibility, and full control**.
 
-- **Simple CLI** - Generate PDFs with a single command
-- **Rich Configuration** - Customize with cookies, headers, and authentication
-- **Waiting Conditions** - Wait for window loaded or network idle
-- **Headless Support** - Run without a visible browser
-- **Docker Ready** - Easy containerization
-- **Modern Architecture** - Uses Chrome's BiDi protocol for better control
+---
 
-## Installation
+## ✨ Key Features
 
-Add to your application's Gemfile:
+✅ **One-liner CLI** – From URL to PDF in a single command  
+✅ **Full customization** – Inject cookies, headers, auth credentials  
+✅ **Smart waiting** – Wait for complete page load or network idle  
+✅ **Headless support** – Run quietly in the background  
+✅ **Docker-ready** – Plug and play with containers  
+✅ **Modern architecture** – Built on Chrome's next-gen BiDi protocol
+
+---
+
+## 🚀 Installation
+
+### Bundler
 
 ```ruby
 gem 'bidi2pdf'
 ```
 
-Or install manually:
+### Standalone
 
 ```bash
-$ gem install bidi2pdf
+gem install bidi2pdf
 ```
 
-### Dependencies
+### Requirements
 
-- **Ruby**: 3.3 or higher
-- **Bidi2pdf** automatically manages ChromeDriver binaries through
-  the [chromedriver-binary](https://github.com/dieter-medium/chromedriver-binary) gem, which:
-  Downloads and installs the ChromeDriver version matching your installed Chrome/Chromium browser
-  Eliminates the need to manually install or update ChromeDriver
-  Ensures compatibility between Chrome and ChromeDriver versions
+- **Ruby** ≥ 3.3
+- **Chrome/Chromium**
+- Automatic ChromeDriver management via [chromedriver-binary](https://github.com/dieter-medium/chromedriver-binary)
 
-## Usage
+---
 
-### Basic Command Line Usage
+## ⚙️ Basic Usage
+
+### Command-line
 
 ```bash
 bidi2pdf render --url https://example.com --output example.pdf
 ```
 
-### Advanced Options
+### Advanced CLI Options
 
 ```bash
 bidi2pdf render \
@@ -62,14 +68,18 @@ bidi2pdf render \
   --log-level debug
 ```
 
-### Ruby API
+---
+
+## 🧠 Programmatic API
+
+### Classic Approach
 
 ```ruby
 require 'bidi2pdf'
 
 launcher = Bidi2pdf::Launcher.new(
   url: 'https://example.com',
-  output: 'example.pdf', # nil for base64 encoded string as result of launcher.launch
+  output: 'example.pdf',
   cookies: { 'session' => 'abc123' },
   headers: { 'X-API-KEY' => 'token' },
   auth: { username: 'admin', password: 'password' },
@@ -78,25 +88,90 @@ launcher = Bidi2pdf::Launcher.new(
 )
 
 launcher.launch
+```
+
+### DSL – Quick & Clean
+
+```ruby
+require "bidi2pdf"
+
+Bidi2pdf::DSL.with_tab(headless: true) do |tab|
+  tab.open_page("https://example.com")
+  tab.wait_until_all_finished
+  tab.print("example.pdf")
+end
+```
+
+---
+
+## 🧬 Deep Integration Example
+
+Get fine-grained control using Chrome sessions, tabs, and BiDi commands:
+
+<details>
+<summary>🔍 Show full example</summary>
+
+```ruby
+require "bidi2pdf"
+
+# 1. Remote or local session?
+session = Bidi2pdf::Bidi::Session.new(
+  session_url: "http://localhost:9092/session",
+  headless: true,
+)
+
+# Alternative: local session via ChromeDriver
+# manager = Bidi2pdf::ChromedriverManager.new(headless: false)
+# manager.start
+# session = manager.session
+
+session.start
+session.client.on_close { puts "WebSocket session closed" }
+
+# 2. Create browser/tab
+browser = session.browser
+context = browser.create_user_context
+window = context.create_browser_window
+tab = window.create_browser_tab
+
+# 3. Inject configuration
+tab.set_cookie(name: "auth", value: "secret", domain: "example.com", secure: true)
+tab.add_headers(url_patterns: [{ type: "pattern", protocol: "https", hostname: "example.com", port: "443" }],
+                headers: [{ name: "X-API-KEY", value: "12345678" }])
+tab.basic_auth(url_patterns: [{ type: "pattern", protocol: "https", hostname: "example.com", port: "443" }],
+               username: "username", password: "secret")
 
-# see Bidi2pdf::SessionRunner for more options
+# 4. Render PDF
+tab.open_page "https://example.com"
+
+# Alternative: send html code to the browser
+# tab.view_html_page("<html>...</html>")
+
+tab.wait_until_all_finished
+tab.print("my.pdf")
+
+# 5. Cleanup
+tab.close
+window.close
+session.close
 ```
 
-## Docker Support
+</details>
+
+---
+
+## 🐳 Docker Support
 
-Build and run with Docker:
+### Build & Run
 
 ```bash
-# Build gem and Docker image
 rake build
 docker build -t bidi2pdf -f docker/Dockerfile .
-
-# Generate PDF using Docker
 docker run -it --rm -v ./output:/reports bidi2pdf \
   bidi2pdf render --url=https://example.com --output /reports/example.pdf
 ```
 
-### Test it with docker compose
+### Docker Compose
 
 ```bash
 rake build
@@ -105,6 +180,10 @@ docker compose -f docker/docker-compose.yml up -d
 # simple example
 docker compose -f docker/docker-compose.yml exec app bidi2pdf render --url=http://nginx/sample.html --wait_window_loaded --wait_network_idle --output /reports/simple.pdf
 
+# with a local file
+docker compose -f docker/docker-compose.yml exec app bidi2pdf render --url=file:///reports/sample.html--wait_network_idle --output /reports/simple.pdf
+
+
 # basic auth example
 docker compose -f docker/docker-compose.yml exec app bidi2pdf render --url=http://nginx/basic/sample.html --auth admin:secret --wait_window_loaded --wait_network_idle --output /reports/basic.pdf
 
@@ -120,31 +199,42 @@ docker compose -f docker/docker-compose.yml exec app bidi2pdf render --url=http:
 docker compose -f docker/docker-compose.yml down
 ```
 
-## Configuration Options
+---
+
+## 🧩 Configuration Options
+
+| Flag                   | Description                                |
+|------------------------|--------------------------------------------|
+| `--url`                | Target URL (required)                      |
+| `--output`             | Output PDF file (default: output.pdf)      |
+| `--cookie`             | Set cookie in `name=value` format          |
+| `--header`             | Inject custom header `name=value`          |
+| `--auth`               | Basic auth as `user:pass`                  |
+| `--headless`           | Run Chrome headless (default: true)        |
+| `--port`               | ChromeDriver port (0 = auto)               |
+| `--wait_window_loaded` | Wait until `window.loaded` is set to true  |
+| `--wait_network_idle`  | Wait until network is idle                 |
+| `--log_level`          | Log level: debug, info, warn, error, fatal |
+| `--remote_browser_url` | Connect to remote Chrome session           |
+| `--default_timeout`    | Operation timeout (default: 60s)           |
 
-| Option                 | Description                                                                                                         |
-|------------------------|---------------------------------------------------------------------------------------------------------------------|
-| `--url`                | The URL to render (required)                                                                                        |
-| `--output`             | Output PDF filename (default: output.pdf)                                                                           |
-| `--cookie`             | Cookies in name=value format                                                                                        |
-| `--header`             | HTTP headers in name=value format                                                                                   |
-| `--auth`               | Basic auth credentials (user:pass)                                                                                  |
-| `--headless`           | Run Chrome in headless mode (default: true)                                                                         |
-| `--port`               | Port for ChromeDriver (0 = auto)                                                                                    |
-| `--wait_window_loaded` | Wait for the window to be fully loaded. You need to set a variable `window.loaded`. See ./spec/fixtures/sample.html |
-| `--wait_network_idle`  | Wait for network to be idle                                                                                         |
-| `--log_level`          | Log level (debug, info, warn, error, fatal)                                                                         |
-| `--remote_browser_url` | URL of the remote Chrome instance (default: nil)                                                                    |
-| `--default_timeout`    | Default timeout for operations (default: 60 seconds)                                                                |
+---
 
-## Development
+## 🛠 Development
 
-After checking out the repo:
+```bash
+# Setup
+bin/setup
+
+# Run tests
+rake spec
+
+# Open interactive console
+bin/console
+```
 
-1. Run `bin/setup` to install dependencies
-2. Run `rake spec` to run the tests
-3. Run `bin/console` for an interactive prompt
+---
 
-## License
+## 📜 License
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).

data/docker/Dockerfile.chromedriver

@@ -1,5 +1,7 @@
 FROM ruby:3.3
 
+ARG CHROMEDRIVER_PORT=3000
+
 # Install dependencies
 RUN apt-get update && \
     apt-get install -y \
@@ -30,4 +32,7 @@ USER appuser
 
 RUN gem install chromedriver-binary && ruby -e 'require "chromedriver/binary"; puts Chromedriver::Binary::ChromedriverDownloader.update'
 
+ENV CHROMEDRIVER_PORT=${CHROMEDRIVER_PORT}
+EXPOSE ${CHROMEDRIVER_PORT}
+
 CMD ["/usr/local/bin/entrypoint.sh"]

data/docker/entrypoint.sh

@@ -1,3 +1,13 @@
 #!/bin/bash
 
-/home/appuser/.webdrivers/chromedriver --port=3000 --headless --whitelisted-ips="" --allowed-origins="*" --disable-dev-shm-usage --verbose
+USER_DATA_DIR=/home/appuser/.cache
+mkdir -p ${USER_DATA_DIR}
+
+/home/appuser/.webdrivers/chromedriver --port=${CHROMEDRIVER_PORT} \
+                                       --headless \
+                                       --whitelisted-ips="" \
+                                       --allowed-origins="*" \
+                                       --disable-dev-shm-usage \
+                                       --disable-gpu \
+                                       --user-data-dir=${USER_DATA_DIR} \
+                                       --verbose

data/lib/bidi2pdf/bidi/add_headers_interceptor.rb

@@ -1,13 +1,21 @@
 # frozen_string_literal: true
 
+require_relative "interceptor"
+
 module Bidi2pdf
   module Bidi
     class AddHeadersInterceptor
-      attr_reader :id, :headers
+      include Interceptor
+
+      class << self
+        def phases = [Bidi2pdf::Bidi::Commands::AddIntercept::BEFORE_REQUEST]
+
+        def events = ["network.beforeRequestSent"]
+      end
+
+      attr_reader :headers, :url_patterns, :context
 
-      def initialize(id, headers:, client:)
-        @id = id
-        @client = client
+      def initialize(headers:, url_patterns:, context:)
         @headers = headers.map do |header|
           {
             name: header[:name],
@@ -17,26 +25,15 @@ module Bidi2pdf
             }
           }
         end
-      end
 
-      def handle_event(response)
-        event_response = response["params"]
-
-        return unless event_response["intercepts"]&.include?(id) && event_response["isBlocked"]
-
-        network_id = event_response["request"]["request"]
-
-        Bidi2pdf.logger.debug "Interceptor #{id} handle event: #{network_id}"
-
-        client.send_cmd "network.continueRequest", {
-          request: network_id,
-          headers: headers
-        }
+        @url_patterns = url_patterns
+        @context = context
       end
 
-      private
-
-      attr_reader :client
+      def process_interception(_event_response, _navigation_id, network_id, _url)
+        cmd = Bidi2pdf::Bidi::Commands::NetworkContinue.new request: network_id, headers: headers
+        client.send_cmd cmd
+      end
     end
   end
 end

data/lib/bidi2pdf/bidi/auth_interceptor.rb

@@ -1,67 +1,60 @@
 # frozen_string_literal: true
 
+require_relative "interceptor"
+
 module Bidi2pdf
   module Bidi
     class AuthInterceptor
-      attr_reader :id, :username, :password, :network_ids
+      include Interceptor
+
+      class << self
+        def phases = [Bidi2pdf::Bidi::Commands::AddIntercept::AUTH_REQUIRED]
+
+        def events = ["network.authRequired"]
+      end
 
-      def initialize(id, username:, password:, client:)
-        @id = id
-        @client = client
+      attr_reader :headers, :url_patterns, :context, :username, :password, :network_ids
+
+      def initialize(username:, password:, url_patterns:, context:)
+        @url_patterns = url_patterns
+        @context = context
         @username = username
         @password = password
         @network_ids = []
       end
 
-      # rubocop:disable Metrics/AbcSize
-      def handle_event(response)
-        event_response = response["params"]
-
-        return unless event_response["intercepts"]&.include?(id) && event_response["isBlocked"]
-
-        navigation_id = event_response["navigation"]
-        network_id = event_response["request"]["request"]
-        url = event_response["request"]["url"]
-
-        handle_bad_credentials(navigation_id, network_id, url)
+      def process_interception(_event_response, navigation_id, network_id, url)
+        return if handled_bad_credentials(navigation_id, network_id, url)
 
         network_ids << network_id
 
-        Bidi2pdf.logger.debug "Auth-Interceptor #{id} handle event: #{navigation_id}/#{network_id}/#{url}"
-
-        client.send_cmd("network.continueWithAuth", {
-          request: network_id,
-          action: "provideCredentials",
-          credentials: {
-            type: "password",
-            username: username,
-            password: password
-          }
-        })
-      end
+        cmd = Bidi2pdf::Bidi::Commands::ProvideCredentials.new request: network_id, username: username, password: password
 
-      # rubocop:enable Metrics/AbcSize
+        client.send_cmd(cmd)
+      rescue StandardError => e
+        Bidi2pdf.logger.error "Error handling auth event: #{e.message}"
+        Bidi2pdf.logger.error e.backtrace.join("\n")
+        raise e
+      end
 
       private
 
-      def handle_bad_credentials(navigation_id, network_id, url)
-        return unless network_ids.include?(network_id)
+      def handled_bad_credentials(navigation_id, network_id, url)
+        return false unless network_ids.include?(network_id)
 
         network_ids.delete(network_id)
 
-        Bidi2pdf.logger.debug "Auth-Interceptor #{id} already handled event: #{navigation_id}/#{network_id}/#{url}"
+        Bidi2pdf.logger.debug "Auth-Interceptor #{interceptor_id} already handled event: #{navigation_id}/#{network_id}/#{url}"
 
-        # rubocop: disable Layout/LineLength
         Bidi2pdf.logger.error "It seems that the same request is being intercepted multiple times. Check your credentials or the URL you are trying to access. If you are using a proxy, make sure it is configured correctly."
         # rubocop: enable Layout/LineLength
 
-        client.send_cmd("network.continueWithAuth", {
-          request: network_id,
-          action: "cancel"
-        })
-      end
+        cmd = Bidi2pdf::Bidi::Commands::CancelAuth.new request: network_id
+
+        client.send_cmd(cmd)
 
-      attr_reader :client
+        true
+      end
     end
   end
 end