ferrum_pdf 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad27a3b666b15d934cc1bbf678ac52bfe86fc421723c89a60a123b3599aa2c39
-  data.tar.gz: 0a9bf56518d53ff03f84b9a9143280f97effe45b26edda3695a767d871bb0f73
+  metadata.gz: 9b709d6f3d6b9472b389f08891e3ec59f90a2e0a962f034acd31a2ee4efdb79c
+  data.tar.gz: c1353b79300829afd212880fbcb76633e3fe7da2c2facc3b96d8305a7c5fc6ae
 SHA512:
-  metadata.gz: 9a2fa255b8d7484952959023ac2ca320ce68259857adbba20fbb0dc9c455e40e6db6a7088daf22b8f70f85da2d31f8fc2c1550a6f6a2ad97cb9920a1841bfd2b
-  data.tar.gz: ed0d20754dee52a621880ef3ffc95894749b8ddfc5796226029d2417c2b6c18e4b29fb94bbae0dd3249d9f7e56e936c6b429f7640ebc7eb33bc5ba72556fb9dc
+  metadata.gz: a4145a37dc89ac2dbaeb0512fffafbd6056291e0521734ed57affd66a45d32489fd412d0f8fbbde7b53046ffbc8d030f602ee6914224ea76bdb1e95c78adf50f
+  data.tar.gz: 57c44da1352bac877910af6193f7104da77580bd9edaafa1d3dbbb4faa2175d8ec05215bccc40c7f85fa4e93d84089f15c1e2c606bcf886a46625f3c2b3ba61a

data/README.md

@@ -6,7 +6,7 @@ Inspired by [Grover](https://github.com/Studiosity/grover).
 
 ## Installation
 
-First, make sure Chrome is installed
+First, make sure Chrome is installed.
 
 Run the following or add the gem to your Gemfile:
 
@@ -16,7 +16,7 @@ bundle add "ferrum_pdf"
 
 ## Usage
 
-You can use FerrumPdf to render [PDFs](#pdfs) and [Screenshots](#screenshots)
+You can use FerrumPdf to render [PDFs](#-pdfs) and [Screenshots](#-screenshots)
 
 ### 📄 PDFs
 
@@ -63,14 +63,17 @@ FerrumPdf.render_pdf(html: content)
 FerrumPdf.render_pdf(url: "https://google.com")
 ```
 
-You can also pass host and protocol to convert any relative paths to full URLs. This is helpful for converting relative asset paths to full URLs.
+The full list of options:
 
 ```ruby
 FerrumPdf.render_pdf(
-  html: content, # Provide HTML
-  url: "https://example.com", # or provide a URL to the content
-  host: request.base_url + "/", # Used for setting the host for relative paths
-  protocol: request.protocol, # Used for handling relative protocol paths
+  url: "https://example.com/page", # Provide a URL to the content
+
+  html: content, # or provide HTML
+  base_url: request.base_url, # Preprocesses `html` to convert relative paths and protocols. Example: "https://example.org"
+
+  authorize: { user: "username", password: "password" }, # Used for authenticating with basic auth
+  wait_for_idle_options: { connections: 0, duration: 0.05, timeout: 5 }, # Used for setting network wait_for_idle options
 
   pdf_options: {
     landscape: false, # paper orientation
@@ -109,10 +112,10 @@ See [Chrome DevTools Protocol docs](https://chromedevtools.github.io/devtools-pr
 
 There are two ways to render Screenshots:
 
-* [FerrumPdf.render_screenshot](#render-screenshot)
+* [FerrumPdf.render_screenshot](#render-screenshots)
 * [render_screenshot in Rails](#render-screenshots-from-rails-controllers)
 
-#### Render Screenshot from Rails controller
+#### Render Screenshots from Rails controllers
 
 Use the `render_screenshot` helper in Rails controllers to render a PDF from the current action.
 
@@ -155,14 +158,15 @@ FerrumPdf.render_screenshot(html: content)
 FerrumPdf.render_screenshot(url: "https://google.com")
 ```
 
-You can also pass host and protocol to convert any relative paths to full URLs. This is helpful for converting relative asset paths to full URLs.
+The full list of options
 
 ```ruby
 FerrumPdf.render_screenshot(
-  html: "",
-  url: "",
-  root_url: "",
-  protocol: "",
+  url: "https://example.com/page", # Provide a URL to the content
+
+  html: content, # or provide HTML
+  base_url: request.base_url, # Preprocesses `html` to convert relative paths and protocols. Example: "https://example.org"
+
   screenshot_options: {
     format: "png" # or "jpeg"
     quality: nil # Integer 0-100 works for jpeg only
@@ -175,9 +179,89 @@ FerrumPdf.render_screenshot(
 )
 ```
 
+## Configuring the Browser
+
+You can set the default browser options with the configure block.
+
+See [Ferrum's Customization docs](https://github.com/rubycdp/ferrum?tab=readme-ov-file#customization) for a full list of options.
+
+```ruby
+FerrumPdf.configure do |config|
+  config.window_size = [1920, 1080]
+
+  # config.process_timeout = 30 # defaults to 10
+  # config.browser_path = '/usr/bin/chromium'
+
+  # For use with Docker, but ensure you trust any sites visited
+  # config.browser_options = {
+  #   "no-sandbox" => true
+  # }
+end
+```
+
+For Docker, `seccomp` is recommend over `--no-sandbox` for security: https://github.com/jlandure/alpine-chrome?tab=readme-ov-file#3-ways-to-securely-use-chrome-headless-with-this-image
+
+To add Chrome to your Docker image:
+
+```dockerfile
+RUN apt-get update && apt-get install gnupg wget -y && \
+    wget --quiet --output-document=- https://dl-ssl.google.com/linux/linux_signing_key.pub | gpg --dearmor > /etc/apt/trusted.gpg.d/google-archive.gpg && \
+    sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google.list' && \
+    apt-get update && \
+    apt-get install google-chrome-stable -y && \
+    rm -rf /var/lib/apt/lists/*
+```
+
+### Multiple Browser Support
+
+```ruby
+# Create two browsers using the FerrumPdf config, but overriding `window_size`
+FerrumPdf.add_browser(:small, window_size: [1024, 768]))
+FerrumPdf.add_browser(:large, window_size: [1920, 1080]))
+
+FerrumPdf.render_pdf(url: "https://example.org", browser: :small)
+FerrumPdf.render_pdf(url: "https://example.org", browser: :large)
+```
+
+You can also create a `Ferrum::Browser` instance and pass it in as `browser`:
+
+```ruby
+FerrumPdf.render_pdf(url: "https://example.org", browser: Ferrum::Browser.new)
+```
+
+## Debugging
+
+One option for debugging is to use Chrome in regular, non-headless mode:
+
+```ruby
+FerrumPdf.configure do |config|
+  config.headless = false
+end
+```
+
+FerrumPdf also allows you to pass a block for debugging. This block is executed after loading the page but before rendering the PDF or screenshot.
+
+```ruby
+FerrumPdf.render_pdf(url: "https://gooogle.com") do |browser, page|
+  # Open Chrome DevTools to remotely inspect the browser
+  browser.debug
+
+  # Or pause and poke around
+  binding.irb
+end
+```
+
+The block will receive the `Ferrum::Browser` and `Ferrum::Page` objects which you can use for debugging.
+
 ## Contributing
 
 If you have an issue you'd like to submit, please do so using the issue tracker in GitHub. In order for us to help you in the best way possible, please be as detailed as you can.
 
+To run the test suite, run:
+
+```bash
+bin/test
+```
+
 ## License
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/ferrum_pdf/assets_helper.rb

@@ -0,0 +1,65 @@
+module FerrumPdf
+  module AssetsHelper
+    class BaseAsset
+      def initialize(asset)
+        @asset = asset
+      end
+    end
+
+    class PropshaftAsset < BaseAsset
+      def content_type
+        @asset.content_type.to_s
+      end
+
+      def content
+        @asset.content
+      end
+    end
+
+    class SprocketsAsset < BaseAsset
+      def content_type
+        @asset.content_type
+      end
+
+      def content
+        @asset.source
+      end
+    end
+
+    class AssetFinder
+      class << self
+        def find(path)
+          if Rails.application.assets.respond_to?(:load_path)
+            propshaft_asset(path)
+          elsif Rails.application.assets.respond_to?(:find_asset)
+            sprockets_asset(path)
+          else
+            nil
+          end
+        end
+
+        def propshaft_asset(path)
+          (asset = Rails.application.assets.load_path.find(path)) ? PropshaftAsset.new(asset) : nil
+        end
+
+        def sprockets_asset(path)
+          (asset = Rails.application.assets.find_asset(path)) ? SprocketsAsset.new(asset) : nil
+        end
+      end
+    end
+
+    def ferrum_pdf_inline_stylesheet(path)
+      (asset = AssetFinder.find(path)) ? "<style>#{asset.content}</style>".html_safe : nil
+    end
+
+    def ferrum_pdf_inline_javascript(path)
+      (asset = AssetFinder.find(path)) ? "<script>#{asset.content}</script>".html_safe : nil
+    end
+
+    def ferrum_pdf_base64_asset(path)
+      return nil unless (asset = AssetFinder.find(path))
+
+      "data:#{asset.content_type};base64,#{Base64.encode64(asset.content).gsub(/\s+/, '')}"
+    end
+  end
+end

data/lib/ferrum_pdf/controller.rb

@@ -2,25 +2,25 @@ module FerrumPdf
   module Controller
     extend ActiveSupport::Concern
 
-    def render_pdf(pdf_options: {}, **rendering)
+    def render_pdf(pdf_options: {}, **rendering, &block)
       content = render_to_string(**rendering.with_defaults(formats: [ :html ]))
 
       FerrumPdf.render_pdf(
         html: content,
-        host: request.base_url + "/",
-        protocol: request.protocol,
-        pdf_options: pdf_options
+        base_url: request.base_url,
+        pdf_options: pdf_options,
+        &block
       )
     end
 
-    def render_screenshot(screenshot_options: {}, **rendering)
+    def render_screenshot(screenshot_options: {}, **rendering, &block)
       content = render_to_string(**rendering.with_defaults(formats: [ :html ]))
 
       FerrumPdf.render_screenshot(
         html: content,
-        host: request.base_url + "/",
-        protocol: request.protocol,
-        screenshot_options: screenshot_options
+        base_url: request.base_url,
+        screenshot_options: screenshot_options,
+        &block
       )
     end
   end

data/lib/ferrum_pdf/html_preprocessor.rb

@@ -5,15 +5,20 @@ module FerrumPdf
   # @see https://github.com/pdfkit/pdfkit
   module HTMLPreprocessor
     # Change relative paths to absolute, and relative protocols to absolute protocols
-    def self.process(html, root_url, protocol)
-      html = translate_relative_paths(html, root_url) if root_url
+    #
+    #   process("Some HTML", "https://example.org")
+    #
+    def self.process(html, base_url)
+      base_url += "/" unless base_url.end_with? "/"
+      protocol = base_url.split("://").first
+      html = translate_relative_paths(html, base_url) if base_url
       html = translate_relative_protocols(html, protocol) if protocol
       html
     end
 
-    def self.translate_relative_paths(html, root_url)
+    def self.translate_relative_paths(html, base_url)
       # Try out this regexp using rubular http://rubular.com/r/hiAxBNX7KE
-      html.gsub(%r{(href|src)=(['"])/([^/"']([^"']*|[^"']*))?['"]}, "\\1=\\2#{root_url}\\3\\2")
+      html.gsub(%r{(href|src)=(['"])/([^/"']([^"']*|[^"']*))?['"]}, "\\1=\\2#{base_url}\\3\\2")
     end
     private_class_method :translate_relative_paths
 

data/lib/ferrum_pdf/railtie.rb

@@ -1,5 +1,11 @@
 module FerrumPdf
   class Railtie < ::Rails::Railtie
+    initializer "ferrum_pdf.assets_helper" do
+      ActiveSupport.on_load(:action_view) do
+        include FerrumPdf::AssetsHelper if FerrumPdf.include_assets_helper_module
+      end
+    end
+
     initializer "ferrum_pdf.controller" do
       ActiveSupport.on_load(:action_controller) do
         include FerrumPdf::Controller if FerrumPdf.include_controller_module

data/lib/ferrum_pdf/version.rb

@@ -1,3 +1,3 @@
 module FerrumPdf
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/lib/ferrum_pdf.rb

@@ -9,41 +9,96 @@ module FerrumPdf
     <div class='text right'><span class='pageNumber'></span>/<span class='totalPages'></span></div>
   HTML
 
+  autoload :AssetsHelper, "ferrum_pdf/assets_helper"
   autoload :Controller, "ferrum_pdf/controller"
   autoload :HTMLPreprocessor, "ferrum_pdf/html_preprocessor"
 
-  mattr_accessor :include_controller_module
-  @@include_controller_module = true
+  mattr_accessor :include_assets_helper_module, default: true
+  mattr_accessor :include_controller_module, default: true
+  mattr_accessor :browsers, default: {}
+  mattr_accessor :config, default: ActiveSupport::OrderedOptions.new.merge(
+    window_size: [ 1920, 1080 ]
+  )
 
   class << self
-    def browser(**options)
-      @browser ||= Ferrum::Browser.new(options)
+    def configure
+      yield config
     end
 
-    def render_pdf(html: nil, url: nil, host: nil, protocol: nil, pdf_options: {})
-      render(host: host, protocol: protocol, html: html, url: url) do |page|
+    def add_browser(name, **options)
+      @@browsers[name] = Ferrum::Browser.new(@@config.merge(options))
+    end
+
+    # Renders HTML or URL to PDF
+    #
+    #   render_pdf(url: "https://example.org/receipts/example.pdf")
+    #   render_pdf(html: "<h1>Hello world</h1>")
+    #
+    # For rendering HTML, we also need the base_url for preprocessing URLs with relative paths & protocols
+    #
+    #   render_pdf(html: "<h1>Hello world</h1>", base_url: "https://example.org/")
+    #
+    def render_pdf(pdf_options: {}, **load_page_args)
+      load_page(**load_page_args) do |browser, page|
+        yield browser, page if block_given?
         page.pdf(**pdf_options.with_defaults(encoding: :binary))
       end
     end
 
-    def render_screenshot(html: nil, url: nil, host: nil, protocol: nil, screenshot_options: {})
-      render(host: host, protocol: protocol, html: html, url: url) do |page|
+    # Renders HTML or URL to Screenshot
+    #
+    # render_screenshot(url: "https://example.org/receipts/example.pdf")
+    # render_screenshot(html: "<h1>Hello world</h1>")
+    #
+    # For rendering HTML, we also need the base_url for preprocessing URLs with relative paths & protocols
+    #
+    #   render_screenshot(html: "<h1>Hello world</h1>", base_url: "https://example.org/")
+    #
+    def render_screenshot(screenshot_options: {}, **load_page_args)
+      load_page(**load_page_args) do |browser, page|
+        yield browser, page if block_given?
         page.screenshot(**screenshot_options.with_defaults(encoding: :binary, full: true))
       end
     end
 
-    def render(host:, protocol:, html: nil, url: nil)
+    # Loads page into the browser to be used for rendering PDFs or screenshots
+    #
+    # This automatically applies HTML preprocessing if `html:` is present
+    #
+    def load_page(url: nil, html: nil, base_url: nil, authorize: nil, wait_for_idle_options: nil, browser: :default, retries: 1)
+      try = 0
+
+      # Lookup browser if a name was passed
+      browser = @@browsers[browser] || add_browser(browser) if browser.is_a? Symbol
+
+      # Automatically restart the browser if it was disconnected
+      browser.restart unless browser.client.present?
+
+      # Closes page automatically after block finishes
+      # https://github.com/rubycdp/ferrum/blob/main/lib/ferrum/browser.rb#L169
       browser.create_page do |page|
+        page.network.authorize(**authorize) { |req| req.continue } if authorize
+
+        # Load content
         if html
-          page.content = FerrumPdf::HTMLPreprocessor.process(html, host, protocol)
-          page.network.wait_for_idle
+          page.content = FerrumPdf::HTMLPreprocessor.process(html, base_url)
         else
           page.go_to(url)
         end
-        yield page
+
+        # Wait for everything to load
+        page.network.wait_for_idle(**wait_for_idle_options)
+
+        yield browser, page
       end
     rescue Ferrum::DeadBrowserError
-      retry
+      try += 1
+      if try <= retries
+        browser.restart
+        retry
+      else
+        raise
+      end
     end
   end
 end

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ferrum_pdf
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Chris Oliver
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-22 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -50,6 +49,7 @@ files:
 - README.md
 - Rakefile
 - lib/ferrum_pdf.rb
+- lib/ferrum_pdf/assets_helper.rb
 - lib/ferrum_pdf/controller.rb
 - lib/ferrum_pdf/html_preprocessor.rb
 - lib/ferrum_pdf/railtie.rb
@@ -62,7 +62,6 @@ metadata:
   homepage_uri: https://github.com/excid3/ferrum_pdf
   source_code_uri: https://github.com/excid3/ferrum_pdf
   changelog_uri: https://github.com/excid3/ferrum_pdf/blob/main/CHANGELOG.md
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -77,8 +76,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.16
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: PDFs & screenshots for Rails using Ferrum & headless Chrome
 test_files: []