bidi2pdf-rails 0.0.1.alpha.1

data/README.md

@@ -0,0 +1,102 @@
+[![Build Status](https://github.com/dieter-medium/bidi2pdf-rails/actions/workflows/ruby.yml/badge.svg)](https://github.com/dieter-medium/bidi2pdf-rails/blob/main/.github/workflows/ruby.yml)
+[![Maintainability](https://api.codeclimate.com/v1/badges/6425d9893aa3a9ca243e/maintainability)](https://codeclimate.com/github/dieter-medium/bidi2pdf-rails/maintainability)
+[![Gem Version](https://badge.fury.io/rb/bidi2pdf-rails.svg)](https://badge.fury.io/rb/bidi2pdf-rails)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/6425d9893aa3a9ca243e/test_coverage)](https://codeclimate.com/github/dieter-medium/bidi2pdf-rails/test_coverage)
+[![Open Source Helpers](https://www.codetriage.com/dieter-medium/bidi2pdf-rails/badges/users.svg)](https://www.codetriage.com/dieter-medium/bidi2pdf-rails)
+
+# 📄 Bidi2pdfRails
+
+**Bidi2pdfRails** is the official Rails integration for [Bidi2pdf](https://github.com/dieter-medium/bidi2pdf) – a
+modern, browser-based solution for converting HTML to high-quality PDFs.  
+It leverages headless browsing and offers a simple, flexible interface for PDF generation directly from your Rails
+application.
+
+> **⚠️ Note:** This project is currently **under development** and **not yet recommended for production use**.
+
+---
+
+## 🚀 Why Bidi2pdfRails?
+
+- Utilizes modern browser technologies for accurate rendering (similar to `grover` or `wicked_pdf`)
+- Easy to integrate into existing Rails projects
+- Configurable options: URL, output path, rendering settings
+
+---
+
+## 🔧 Installation
+
+Add the following lines to your `Gemfile`:
+
+```ruby
+gem "bidi2pdf-rails"
+# As long as the gem is not published, use:
+gem "bidi2pdf-rails", github: "dieter-medium/bidi2pdf-rails", branch: "main"
+gem "bidi2pdf", github: "dieter-medium/bidi2pdf", branch: "main"
+
+# if you want a small performance boost, you can use the following:
+# gem "websocket-native"
+```
+
+Then install the dependencies:
+
+```bash
+bundle
+```
+
+Generate the initializer:
+
+```bash
+bin/rails generate bidi2pdf_rails:initializer
+```
+
+Alternatively, install it manually:
+
+```bash
+gem install bidi2pdf-rails
+```
+
+---
+
+## 🧪 Example & Getting Started
+
+You can find a full example inside the [`spec/dummy`](spec/dummy) directory of this repository.  
+This demonstrates how to use `Bidi2pdfRails` in a realistic mini Rails application setup.
+
+### Basic Usage
+
+```ruby
+# Render html via controller action `render_to_string`
+# Any controller action:
+def show
+  render pdf: "invoice",
+         template: "invoices/show",
+         layout: "pdf",
+         locals: { invoice: @invoice },
+         print_options: { landscape: true },
+         wait_for_network_idle: true,
+         asset_host: "https://assets.example.com"
+end
+
+# Render pdf via direct url call
+def show
+  # See: PdfRenderer for all options
+  render pdf: 'remote-report', url: "http://example.com", wait_for_page_loaded: false, print_options: { page: { format: :A4 } }
+end
+
+```
+
+---
+
+## 🙌 Contributing
+
+Want to contribute?  
+Pull requests, bug reports, and ideas are warmly welcome!
+
+*Contribution guidelines will be added soon.*
+
+---
+
+## 📄 License
+
+This gem is open-source and available under the terms of the [MIT License](https://opensource.org/licenses/MIT).  
+Free to use – with responsibility.

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new

data/lib/bidi2pdf-rails.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# just to get the nicer gem name
+require_relative "bidi2pdf_rails"

data/lib/bidi2pdf_rails/browser_console_log_subscriber.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "bidi2pdf/bidi/browser_console_logger"
+
+module Bidi2pdfRails
+  class BrowserConsoleLogSubscriber < ActiveSupport::LogSubscriber
+    def browser_console_log_received(event)
+      payload = event.payload
+      timestamp = Bidi2pdf::Bidi::BrowserConsoleLogger.format_timestamp(payload[:timestamp])
+
+      logger.tagged("bidi2pdf_rails", "browser_console", timestamp) do |tagged_logger|
+        verbose_logger = Bidi2pdf::VerboseLogger.new(tagged_logger, Bidi2pdfRails.verbosity)
+        Bidi2pdf::Bidi::BrowserConsoleLogger.new(verbose_logger)
+                                            .builder
+                                            .with_level(payload[:level])
+                                            .with_prefix("")
+                                            .with_text(payload[:text])
+                                            .with_args(payload[:args])
+                                            .with_stack_trace(payload[:stack_trace])
+                                            .log_event
+      end
+    end
+  end
+end

data/lib/bidi2pdf_rails/chromedriver_manager_singleton.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Bidi2pdfRails
+  module ChromedriverManagerSingleton
+    class << self
+      attr_reader :manager, :session
+
+      def initialize_manager
+        return unless running_as_server?
+
+        @mutex ||= Mutex.new
+        @mutex.synchronize do
+          return if @manager && @session
+
+          msg = Bidi2pdfRails.remote_browser_url ? "Remote session" : "ChromeDriver manager"
+
+          Bidi2pdfRails.logger.info "Initializing Bidi2pdf #{msg}"
+
+          if Bidi2pdfRails.use_remote_browser?
+            @session = Bidi::Session.new(
+              session_url: Bidi2pdfRails.remote_browser_url,
+              headless: Bidi2pdfRails.headless,
+              chrome_args: Bidi2pdfRails.chrome_session_args
+            )
+          else
+            @manager = Bidi2pdf::ChromedriverManager.new(
+              port: Bidi2pdfRails.chromedriver_port,
+              headless: Bidi2pdfRails.headless,
+              chrome_args: Bidi2pdfRails.chrome_session_args
+            )
+            @manager.start
+            @session = @manager.session
+          end
+
+          @session.start
+          @session.client.on_close { Bidi2pdfRails.logger.info "WebSocket session closed" }
+        end
+      end
+
+      def shutdown
+        return unless running_as_server?
+
+        @mutex ||= Mutex.new
+        @mutex.synchronize do
+          msg = Bidi2pdfRails.remote_browser_url ? "Remote session" : "ChromeDriver manager"
+          Bidi2pdfRails.logger.info "Shutting down Bidi2pdf #{msg}"
+          @session&.close
+          @manager&.stop
+          @session = nil
+          @manager = nil
+        end
+      end
+
+      def running_as_server?
+        return false if Rails.const_defined?(:Console)
+        return false if defined?(Rails::Generators)
+
+        return false if File.basename($0) == "rake"
+
+        # Covers common Rails server entrypoints
+        server_commands = %w[server puma unicorn passenger thin webrick rackup]
+        cmdline = File.basename($0)
+
+        server_commands.any? { |s| cmdline.include?(s) } ||
+          Rails.const_defined?("Server")
+      end
+    end
+  end
+end

data/lib/bidi2pdf_rails/main_log_subscriber.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Bidi2pdfRails
+  class MainLogSubscriber < ActiveSupport::LogSubscriber
+    @silenced_events = []
+
+    class << self
+      attr_accessor :silenced_events
+
+      def silence(event)
+        self.silenced_events << event
+      end
+
+      def silenced?(event)
+        self.silenced_events.any? { |silenced_event| silenced_event === event }
+      end
+    end
+
+    include Bidi2pdf::Notifications::LoggingSubscriberActions
+
+    def handle_printing(event)
+      logger.info "Page rendered and printed: #{event.duration.round(1)}ms"
+    end
+
+    def logger
+      Bidi2pdf::VerboseLogger.new(super.tagged("bidi2pdf_rails"), Bidi2pdfRails.verbosity)
+    end
+
+    def silenced?(event)
+      MainLogSubscriber.silenced?(event) || super(event)
+    end
+  end
+end

data/lib/bidi2pdf_rails/network_log_subscriber.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "bidi2pdf/bidi/network_event_formatters/network_event_console_formatter"
+
+module Bidi2pdfRails
+  class NetworkLogSubscriber < ActiveSupport::LogSubscriber
+    def network_event_received(event)
+      payload = event.payload
+
+      return if payload[:method] == "network.responseStarted" || payload[:method] == "network.beforeRequestSent"
+
+      logger.tagged("bidi2pdf_rails", "network") do |tagged_logger|
+        verbose_logger = Bidi2pdf::VerboseLogger.new(tagged_logger, Bidi2pdfRails.verbosity)
+        formatter = Bidi2pdf::Bidi::NetworkEventFormatters::NetworkEventConsoleFormatter.new(logger: verbose_logger)
+
+        formatter.log [payload[:event]]
+      end
+    end
+  end
+end

data/lib/bidi2pdf_rails/railtie.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require_relative "services/html_renderer"
+require_relative "services/pdf_renderer"
+require_relative "services/pdf_browser_session"
+require_relative "services/url_to_pdf_converter"
+require_relative "services/html_to_pdf_converter"
+
+module Bidi2pdfRails
+  class Railtie < ::Rails::Railtie
+    initializer "bidi2pdf_rails.add_mime_type" do
+      Mime::Type.register "application/pdf", :pdf unless Mime::Type.lookup_by_extension(:pdf)
+    end
+
+    initializer "bidi2pdf_rails.initialize_chromedriver_manager", after: :load_config_initializers do
+      Bidi2pdfRails.apply_bidi2pdf_config
+
+      # defer the initialization of the ChromedriverManager to the ActionController::Base class load event
+      ActiveSupport.on_load(:action_controller_base) do
+        ChromedriverManagerSingleton.initialize_manager
+      end
+    end
+
+    config.after_initialize do
+      # Set up shutdown hook for when the application stops
+      at_exit do
+        ChromedriverManagerSingleton.shutdown
+      end
+    end
+
+    initializer "bidi2pdf_rails.add_pdf_renderer" do
+      ActionController::Renderers.add :pdf do |filename, options|
+        options = options.dup
+
+        pdf_content = Services::PdfRenderer.new(filename, options, self).render_pdf
+
+        send_data pdf_content,
+                  type: Mime[:pdf],
+                  filename: "#{filename}.pdf",
+                  disposition: options.fetch(:disposition, "inline")
+      end
+    end
+  end
+end

data/lib/bidi2pdf_rails/services/html_renderer.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Bidi2pdfRails
+  module Services
+    # app/services/html_renderer.rb
+    class HtmlRenderer
+      def initialize(controller, options)
+        @controller = controller
+        @options = options.dup
+      end
+
+      def render
+        with_overridden_asset_host { @controller.render_to_string(@options.merge(formats: [:html])) }
+      end
+
+      private
+
+      def with_overridden_asset_host
+        original_asset_host = ActionController::Base.asset_host
+
+        if @options[:asset_host]
+          ActionController::Base.asset_host = @options[:asset_host]
+        elsif !Rails.application.config.action_controller.asset_host
+          ActionController::Base.asset_host = @controller.request.base_url
+        end
+
+        yield
+      ensure
+        ActionController::Base.asset_host = original_asset_host
+      end
+    end
+  end
+end

data/lib/bidi2pdf_rails/services/html_to_pdf_converter.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Bidi2pdfRails
+  module Services
+    class HtmlToPdfConverter
+      include PdfBrowserSession
+
+      def initialize(html, print_options: {}, wait_for_network_idle: true, wait_for_page_loaded: true, wait_for_page_check_script: nil)
+        @html = html
+        @print_options = print_options
+        @wait_for_network_idle = wait_for_network_idle
+        @wait_for_page_loaded = wait_for_page_loaded
+        @wait_for_page_check_script = wait_for_page_check_script
+      end
+
+      def generate
+        run_browser_session
+      end
+
+      private
+
+      def prepare_tab(tab)
+        tab.render_html_content(@html)
+        wait_for_tab(tab)
+      end
+    end
+  end
+end

data/lib/bidi2pdf_rails/services/pdf_browser_session.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Bidi2pdfRails
+  module Services
+    module PdfBrowserSession
+      def run_browser_session
+        pdf_data = nil
+
+        thread = Thread.new do
+          Rails.application.executor.wrap do
+            browser = ChromedriverManagerSingleton.session.browser
+            context = browser.create_user_context
+            window = context.create_browser_window
+            tab = window.create_browser_tab
+
+            begin
+              prepare_tab(tab)
+              pdf_data = tab.print(print_options: @print_options)
+            ensure
+              tab&.close
+              window&.close
+              context&.close
+            end
+          end
+        end
+
+        thread.join
+        Base64.decode64(pdf_data)
+      end
+
+      private
+
+      def wait_for_tab(tab)
+        tab.wait_until_network_idle if @wait_for_network_idle
+        tab.wait_until_page_loaded(check_script: @wait_for_page_check_script) if @wait_for_page_loaded
+      end
+    end
+  end
+end

data/lib/bidi2pdf_rails/services/pdf_renderer.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Bidi2pdfRails
+  module Services
+    # PdfRenderer is responsible for rendering a Rails view into a PDF using headless Chrome.
+    #
+    # It accepts a mix of HTML rendering options (passed to `render_to_string`) and PDF generation options.
+    #
+    # @example Basic usage
+    #   renderer = Bidi2pdfRails::Services::PdfRenderer.new("invoice", { template: "invoices/show" }, controller)
+    #   renderer.render_pdf
+    #
+    # @param filename [String] the base filename for the generated PDF (used for download naming)
+    # @param options [Hash] rendering options including both HTML and PDF-specific options
+    # @option options [String] :template The template to render (or other render_to_string keys like :partial, :layout, etc.)
+    # @option options [String] :asset_host Optional asset host override
+    # @option options [Hash] :print_options Options passed to the Chrome PDF print API
+    # @option options [Boolean] :wait_for_network_idle Wait for network to go idle before generating PDF (default: config default)
+    # @option options [Boolean] :wait_for_page_loaded Wait for page load event before generating PDF (default: config default)
+    # @option options [String] :wait_for_page_check_script JavaScript condition to wait for before generating PDF
+    #
+    class PdfRenderer
+      PDF_OPTIONS = %i[
+        print_options
+        asset_host
+        wait_for_network_idle
+        wait_for_page_loaded
+        wait_for_page_check_script
+      ].freeze
+
+      PRINT_URL_OPTIONS = %i[
+        url
+        auth
+        headers
+        cookies
+      ].freeze
+
+      def initialize(filename, options, controller)
+        @filename = filename
+        @pdf_options = options.slice(*PDF_OPTIONS)
+        @print_url_options = options.slice(*PRINT_URL_OPTIONS)
+        @html_options = options.except(*(PDF_OPTIONS + PRINT_URL_OPTIONS))
+        @controller = controller
+      end
+
+      def render_pdf
+        ActiveSupport::Notifications.instrument("handle_printing.bidi2pdf_rails") do
+          print_options = Bidi2pdfRails.print_options(@pdf_options[:print_options] || {})
+          wait_for_network_idle = @pdf_options.fetch(:wait_for_network_idle, Bidi2pdfRails.wait_for_network_idle)
+          wait_for_page_loaded = @pdf_options.fetch(:wait_for_page_loaded, Bidi2pdfRails.wait_for_page_loaded)
+          wait_for_page_check_script = @pdf_options.fetch(:wait_for_page_check_script, Bidi2pdfRails.wait_for_page_check_script)
+
+          if @print_url_options[:url]
+            headers = @print_url_options[:headers] || Bidi2pdfRails.headers
+            cookies = @print_url_options[:cookies] || Bidi2pdfRails.cookies
+            auth = @print_url_options[:auth] || Bidi2pdfRails.auth
+
+            UrlToPdfConverter.new(@print_url_options[:url],
+                                  headers: headers,
+                                  cookies: cookies,
+                                  auth: auth,
+                                  print_options: print_options,
+                                  wait_for_network_idle: wait_for_network_idle,
+                                  wait_for_page_loaded: wait_for_page_loaded,
+                                  wait_for_page_check_script: wait_for_page_check_script
+            ).generate
+          else
+            html = HtmlRenderer.new(@controller, @html_options).render
+
+            HtmlToPdfConverter.new(html,
+                                   print_options: print_options,
+                                   wait_for_network_idle: wait_for_network_idle,
+                                   wait_for_page_loaded: wait_for_page_loaded,
+                                   wait_for_page_check_script: wait_for_page_check_script
+            ).generate
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bidi2pdf_rails/services/url_to_pdf_converter.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Bidi2pdfRails
+  module Services
+    class UrlToPdfConverter
+      include PdfBrowserSession
+
+      def initialize(url, headers: {}, cookies: {}, auth: {}, print_options: {}, wait_for_network_idle: true, wait_for_page_loaded: true, wait_for_page_check_script: nil)
+        @url = url
+        @headers = headers || {}
+        @cookies = cookies || {}
+        @auth = auth || {}
+        @print_options = print_options
+        @wait_for_network_idle = wait_for_network_idle
+        @wait_for_page_loaded = wait_for_page_loaded
+        @wait_for_page_check_script = wait_for_page_check_script
+      end
+
+      def generate
+        run_browser_session
+      end
+
+      private
+
+      def prepare_tab(tab)
+        add_headers(tab)
+        add_basic_auth(tab)
+        add_cookies(tab)
+
+        tab.navigate_to(@url)
+        wait_for_tab(tab)
+      end
+
+      def add_cookies(tab)
+        @cookies.each do |name, value|
+          tab.set_cookie(
+            name: name,
+            value: value,
+            domain: domain,
+            secure: uri.scheme == "https"
+          )
+        end
+      end
+
+      def add_headers(tab)
+        @headers.each do |name, value|
+          tab.add_headers(
+            url_patterns: url_patterns,
+            headers: [{ name: name, value: value }]
+          )
+        end
+      end
+
+      def add_basic_auth(tab)
+        return unless @auth[:username] && @auth[:password]
+
+        tab.basic_auth(
+          url_patterns: url_patterns,
+          username: @auth[:username],
+          password: @auth[:password]
+        )
+      end
+
+      def uri
+        @uri ||= URI(@url)
+      end
+
+      def domain
+        uri.host
+      end
+
+      def url_patterns
+        [{
+           type: "pattern",
+           protocol: uri.scheme,
+           hostname: uri.host,
+           port: uri.port.to_s
+         }]
+      end
+    end
+  end
+end

data/lib/bidi2pdf_rails/version.rb

@@ -0,0 +1,3 @@
+module Bidi2pdfRails
+  VERSION = "0.0.1.alpha.1"
+end