bidi2pdf 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f132ccc5d9db5bb621f7e1a0adfa4150b77b4618542ba27873a602cf9c342a40
-  data.tar.gz: f3df228dc1de555d14baad4347a1b5b8d0bc8b63f88d6adfbcec86f0da571703
+  metadata.gz: 541e9193b3285383b2a82065b173af87c68edeb08ec157125761f44285118dff
+  data.tar.gz: ab12e33ad21e8377ef964aa12d0d9b0ba757ee941c217febe6d46fb1cc381d5e
 SHA512:
-  metadata.gz: d74e6e1b505493d47f66c2f1cb4d13bc07aacfa82dbba536439e3b458395bbcd7213103e5fbed167a65945af28bbfb239f6510e93bed2838fa583b95352df8d6
-  data.tar.gz: '096bb337a61db6d5392ba64c38bf4632695ca647b2fe95a227f3d56b189241cae1b19cc65e98115dff73997bb3df1cdcc2821058611683aa449acd11db4fe66f'
+  metadata.gz: 91be15b3310098c7f16153331fa0a27a8b869dfebc9f3720a7da26d2c59b8444f266e21e93d74891b423e50d8223b01b2198f230753d38ad523b8c846c12150f
+  data.tar.gz: 504516ecc1eac40e6c6e159c5f14aafdeb9d23bc587fcf6914ab60d8676a930a7866d6d0c07998398359c402780584f1e5b317c274dd6f3dba0ba50c1a73cbe6

data/CHANGELOG.md

@@ -6,10 +6,47 @@ 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.4..HEAD
+
+[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.5..HEAD
 
 <!-- generated by git-cliff end -->
 
+## [0.1.6]
+
+### ⚠️ Breaking Changes
+
+- Rename view_html_page to render_html by @dieter-medium
+- Rename wait_until_all_finished to wait_until_network_idle by @dieter-medium
+
+### 📝 Docs
+
+- Update Docker instructions in README by @dieter-medium
+
+### 🔄 Changed
+
+- Add details on network logging and console capture by @dieter-medium
+
+### 🚀 Added
+
+- Add PDF network log formatting and customizable outputs by @dieter-medium
+- Add option to log network traffic and handle failures within the cli command by @dieter-medium
+- Add structured network traffic logging by @dieter-medium
+- Add slim variant Dockerfile and build matrix for CI by @dieter-medium
+- Add official image at [Docker Hub](https://hub.docker.com/r/dieters877565/bidi2pdf) by @dieter-medium
+
+## [0.1.5] - 2025-04-10
+
+### 📝 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
@@ -79,3 +116,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [0.1.0] - 2025-03-26
 
 - Initial release
+
+[unreleased]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.6..HEAD
+
+[0.1.6]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.5..v0.1.6
+
+[0.1.5]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.4..v0.1.5
+
+[0.1.4]: https://github.com/dieter-medium/bidi2pdf/compare/v0.1.3..v0.1.4 

data/README.md

@@ -3,52 +3,60 @@
 [![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  
+✅ **Network logging** – Know which requests fail during rendering  
+✅ **Console log capture** – See what goes wrong inside the browser
+
+---
+
+## 🚀 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 +70,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 +90,111 @@ launcher = Bidi2pdf::Launcher.new(
 )
 
 launcher.launch
+```
+
+### DSL – Quick & Clean
+
+```ruby
+require "bidi2pdf"
+
+Bidi2pdf::DSL.with_tab(headless: true) do |tab|
+  tab.navigate_to("https://example.com")
+  tab.wait_until_network_idle
+  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
 
-# see Bidi2pdf::SessionRunner for more options
+# 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")
+
+# 4. Render PDF
+tab.navigate_to "https://example.com"
+
+# Alternative: send html code to the browser
+# tab.render_html_content("<html>...</html>")
+
+tab.wait_until_network_idle
+tab.print("my.pdf")
+
+# 5. Cleanup
+tab.close
+window.close
+session.close
 ```
 
-## Docker Support
+</details>
+
+---
+
+## 🐳 Docker Support
 
-Build and run with Docker:
+### 🛠️ Build & Run Locally
 
 ```bash
-# Build gem and Docker image
+# Prepare the environment
 rake build
+
+# Build the Docker image
 docker build -t bidi2pdf -f docker/Dockerfile .
 
-# Generate PDF using Docker
-docker run -it --rm -v ./output:/reports bidi2pdf \
+# Run the container and generate a PDF
+docker run -it --rm \
+  -v ./output:/reports \
+  bidi2pdf \
   bidi2pdf render --url=https://example.com --output /reports/example.pdf
+
 ```
 
-### Test it with docker compose
+### ⚡ Use the Prebuilt Image (Recommended for Fast Start)
+
+Grab it directly from [Docker Hub](https://hub.docker.com/r/dieters877565/bidi2pdf)
+
+```bash
+docker run -it --rm \
+  -v ./output:/reports \
+  dieters877565/bidi2pdf:main-slim \
+  bidi2pdf render --url=https://example.com --output /reports/example.pdf
+```
+
+✅ Tip: Mount your local directory (e.g. ./output) to /reports in the container to easily access the generated PDFs.
+
+### Docker Compose
 
 ```bash
 rake build
@@ -105,6 +203,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 +222,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
 
-| 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)                                                                |
+| 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)           |
 
-## Development
+---
 
-After checking out the repo:
+## 🛠 Development
+
+```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

@@ -1,9 +1,11 @@
 FROM ruby:3.3
 
+ENV DEBIAN_FRONTEND=noninteractive
+
 # Install dependencies
-RUN apt-get update && \
-    apt-get install -y \
-    chromium \
+RUN apt-get update && apt-get upgrade &&\
+    apt-get install -y --no-install-recommends\
+    chromium chromium-driver\
     libglib2.0-0 \
     libnss3 \
     libxss1 \
@@ -19,6 +21,12 @@ RUN apt-get update && \
 # Create a non-root user
 RUN groupadd -r appuser && useradd -r -g appuser -m -d /home/appuser appuser
 
+# ARM compatibility workaround:
+# On ARM architectures (such as Apple Silicon), downloading chromedriver via automated scripts may fail or cause ELF binary errors,
+# such as "rosetta error: failed to open elf at /lib64/ld-linux-x86-64.so.2".
+# To avoid these issues, we directly install 'chromium-driver' via the package manager and explicitly create a symlink in the expected location.
+
+RUN mkdir -p /home/appuser/.webdrivers && ln -s /usr/bin/chromedriver /home/appuser/.webdrivers/chromedriver
 
 # Set working directory
 WORKDIR /app

data/docker/Dockerfile.chromedriver

@@ -2,9 +2,11 @@ FROM ruby:3.3
 
 ARG CHROMEDRIVER_PORT=3000
 
+ENV DEBIAN_FRONTEND=noninteractive
+
 # Install dependencies
-RUN apt-get update && \
-    apt-get install -y \
+RUN apt-get update && apt-get upgrade && \
+    apt-get install -y --no-install-recommends\
     chromium \
     libglib2.0-0 \
     libnss3 \

data/docker/Dockerfile.slim

@@ -0,0 +1,75 @@
+FROM ruby:3.3-slim AS builder
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install dependencies
+RUN apt-get update && apt-get upgrade && \
+    apt-get install -y --no-install-recommends \
+    chromium \
+    libglib2.0-0 \
+    libnss3 \
+    libxss1 \
+    libasound2 \
+    libatk-bridge2.0-0 \
+    libgtk-3-0 \
+    libdrm2 \
+    curl \
+    unzip \
+    xvfb \
+    build-essential \
+    libpq-dev pkg-config \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy your gem into container
+COPY ./pkg/bidi2pdf-*.gem ./
+
+RUN gem install ./bidi2pdf-*.gem
+
+
+# Stage 2
+
+FROM ruby:3.3-slim
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Install dependencies
+RUN apt-get update && apt-get upgrade &&\
+    apt-get install -y --no-install-recommends\
+    chromium chromium-driver\
+    libglib2.0-0 \
+    libnss3 \
+    libxss1 \
+    libasound2 \
+    libatk-bridge2.0-0 \
+    libgtk-3-0 \
+    libdrm2 \
+    curl \
+    unzip \
+    xvfb \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /usr/local/bundle /usr/local/bundle
+
+# Create a non-root user
+RUN groupadd -r appuser && useradd -r -g appuser -m -d /home/appuser appuser
+
+# ARM compatibility workaround:
+# On ARM architectures (such as Apple Silicon), downloading chromedriver via automated scripts may fail or cause ELF binary errors,
+# such as "rosetta error: failed to open elf at /lib64/ld-linux-x86-64.so.2".
+# To avoid these issues, we directly install 'chromium-driver' via the package manager and explicitly create a symlink in the expected location.
+
+RUN mkdir -p /home/appuser/.webdrivers && ln -s /usr/bin/chromedriver /home/appuser/.webdrivers/chromedriver
+
+# Set working directory
+WORKDIR /app
+
+RUN chown -R appuser:appuser /app
+
+# Switch to non-root user
+USER appuser
+
+CMD ["/usr/bin/bash"]
+

data/lib/bidi2pdf/bidi/browser_tab.rb

@@ -3,13 +3,14 @@
 require "base64"
 
 require_relative "network_events"
+require_relative "logger_events"
 require_relative "auth_interceptor"
 require_relative "add_headers_interceptor"
 
 module Bidi2pdf
   module Bidi
     class BrowserTab
-      attr_reader :client, :browsing_context_id, :user_context_id, :tabs, :network_events, :open
+      attr_reader :client, :browsing_context_id, :user_context_id, :tabs, :network_events, :open, :logger_events
 
       def initialize(client, browsing_context_id, user_context_id)
         @client = client
@@ -17,6 +18,7 @@ module Bidi2pdf
         @user_context_id = user_context_id
         @tabs = []
         @network_events = NetworkEvents.new browsing_context_id
+        @logger_events = LoggerEvents.new browsing_context_id
         @open = true
       end
 
@@ -77,10 +79,13 @@ module Bidi2pdf
         ).tap { |interceptor| interceptor.register_with_client(client: client) }
       end
 
-      def open_page(url)
-        client.on_event("network.responseStarted", "network.responseCompleted", "network.fetchError",
+      def navigate_to(url)
+        client.on_event("network.beforeRequestSent", "network.responseStarted", "network.responseCompleted", "network.fetchError",
                         &network_events.method(:handle_event))
 
+        client.on_event("log.entryAdded",
+                        &logger_events.method(:handle_event))
+
         cmd = Bidi2pdf::Bidi::Commands::BrowsingContextNavigate.new url: url, context: browsing_context_id
 
         client.send_cmd_and_wait(cmd) do |response|
@@ -88,6 +93,13 @@ module Bidi2pdf
         end
       end
 
+      def render_html_content(html_content)
+        base64_encoded = Base64.strict_encode64(html_content)
+        data_url = "data:text/html;charset=utf-8;base64,#{base64_encoded}"
+
+        navigate_to(data_url)
+      end
+
       def execute_script(script)
         cmd = Bidi2pdf::Bidi::Commands::ScriptEvaluate.new context: browsing_context_id, expression: script
         client.send_cmd_and_wait(cmd) do |response|
@@ -97,8 +109,29 @@ module Bidi2pdf
         end
       end
 
-      def wait_until_all_finished(timeout: 10, poll_interval: 0.1)
-        network_events.wait_until_all_finished(timeout: timeout, poll_interval: poll_interval)
+      def wait_until_network_idle(timeout: 10, poll_interval: 0.1)
+        network_events.wait_until_network_idle(timeout: timeout, poll_interval: poll_interval)
+      end
+
+      def log_network_traffic(format: :console, output: nil, print_options: { background: true }, &block)
+        format = format.to_sym
+
+        if format == :console
+          network_events.log_network_traffic format: :console
+        elsif format == :pdf
+          html_content = network_events.log_network_traffic format: :html
+
+          return unless html_content
+
+          logging_tab = create_browser_tab
+
+          logging_tab.render_html_content(html_content)
+          logging_tab.wait_until_network_idle
+
+          logging_tab.print(output, print_options: print_options, &block)
+
+          logging_tab.close
+        end
       end
 
       def close
@@ -111,7 +144,8 @@ module Bidi2pdf
         @open = false
       end
 
-      def print(outputfile, print_options: { background: true })
+      # rubocop: disable Metrics/AbcSize, Metrics/PerceivedComplexity
+      def print(outputfile = nil, print_options: { background: true }, &block)
         cmd = Bidi2pdf::Bidi::Commands::BrowsingContextPrint.new context: browsing_context_id, print_options: print_options
 
         client.send_cmd_and_wait(cmd) do |response|
@@ -119,19 +153,25 @@ module Bidi2pdf
             pdf_base64 = response["result"]["data"]
 
             if outputfile
+              raise PrintError, "Folder does not exist: #{File.dirname(outputfile)}" unless File.directory?(File.dirname(outputfile))
+
               File.binwrite(outputfile, Base64.decode64(pdf_base64))
               Bidi2pdf.logger.info "PDF saved as '#{outputfile}'."
             else
               Bidi2pdf.logger.info "PDF generated successfully."
             end
 
-            return pdf_base64 unless outputfile
+            block.call(pdf_base64) if block_given?
+
+            return pdf_base64 unless outputfile || block_given?
           else
             Bidi2pdf.logger.error "Error printing: #{response}"
           end
         end
       end
 
+      # rubocop: enable Metrics/AbcSize, Metrics/PerceivedComplexity
+
       private
 
       def close_context

data/lib/bidi2pdf/bidi/commands/set_tab_cookie.rb

@@ -6,6 +6,14 @@ module Bidi2pdf
       class SetTabCookie
         include Base
 
+        class << self
+          attr_writer :time_provider
+
+          def time_provider
+            @time_provider ||= -> { Time.now }
+          end
+        end
+
         attr_reader :name, :value, :domain, :path, :secure, :http_only, :same_site, :ttl, :browsing_context_id
 
         def initialize(name:,
@@ -29,7 +37,7 @@ module Bidi2pdf
         end
 
         def expiry
-          Time.now.to_i + ttl
+          self.class.time_provider.call.to_i + ttl
         end
 
         def method_name