htmlToPdf 2.0.0 → 3.0.0

data/lib/htmlToPdf.rb

@@ -1,90 +1,97 @@
 require "securerandom"
+require "active_support/concern"
+require "active_support/core_ext/object/blank"
 require "htmlToPdf/version"
 require "htmlToPdf/configuration"
+require "htmlToPdf/browser_pool"
+require "htmlToPdf/print_options"
 
 module HtmlToPdf
+  extend ActiveSupport::Concern
+
+  # Wire up with `include HtmlToPdf` then `around_action :html_to_pdf` (not
+  # `before_action`) in the controller(s) that should support it — typically
+  # ApplicationController. An around_action is required: it lets the rest of
+  # the callback chain and the action itself run normally via `yield` (so
+  # other before_actions' instance variables are available), rather than
+  # re-invoking the action out-of-band the way earlier versions of this gem
+  # did.
+  def html_to_pdf
+    unless pdf_request?
+      yield
+      return
+    end
 
-  def html_to_pdf()
     pdf_options = params[:pdf_options] ? params[:pdf_options] : {}
-    if request.format == 'application/pdf'
-      initialize_downloads(pdf_options)
-      _tmp_dir = HtmlToPdf.configuration.tmp_dir || File.join(Rails.root, 'tmp')
-      FileUtils.mkdir_p(_tmp_dir)
-      _unique_id = "#{Time.now.to_i}_#{SecureRandom.hex(8)}"
-      _source_file = File.join(_tmp_dir, "#{_unique_id}.html")
-      _destination_file = File.join(_tmp_dir, "#{_unique_id}.pdf")
-      _controller = ("#{controller_name}Controller").camelize.constantize.new
-      _controller.request = request
-      _controller.response = response
-      _controller.params = params
-      _controller.method(action_name).call
-
-      _controller.instance_variables.each do |var|
-        instance_variable_set(var, _controller.instance_variable_get(var))
-      end
+    initialize_downloads(pdf_options)
+
+    # Run the real callback chain/action with the format forced to :html, so
+    # Rails' own implicit rendering resolves the normal HTML template instead
+    # of raising UnknownFormat for a nonexistent .pdf template. That render's
+    # output is discarded — render_to_string below (not response.body) is
+    # what actually gets converted — this only needs to happen so the action
+    # itself runs in its ordinary place in the chain.
+    original_format = request.format
+    request.format = :html
+    begin
+      yield
+    ensure
+      request.format = original_format
+    end
 
-      _html = render_to_string(template: "#{controller_name}/#{action_name}", :layout => @layout, locals: { url: Rails.application.routes.url_helpers })
-      file_content = _html.gsub(/\\"/, "")
+    html = render_to_string(template: "#{controller_name}/#{action_name}", layout: @layout, locals: { url: Rails.application.routes.url_helpers })
+    file_content = html.gsub(/\\"/, "")
 
+    tmp_dir = HtmlToPdf.configuration.tmp_dir || File.join(Rails.root, 'tmp')
+    FileUtils.mkdir_p(tmp_dir)
+    source_file = File.join(tmp_dir, "#{Time.now.to_i}_#{SecureRandom.hex(8)}.html")
+    File.write(source_file, file_content)
 
-      File.open(_source_file, "w+") do |f|
-        f.write(file_content)
-      end
-      system(HtmlToPdf.configuration.wkhtmltopdf_path, *wkhtmltopdf_args, _source_file, _destination_file)
-      File.delete(_source_file) if File.exist?(_source_file)
-      send_data File.open(_destination_file, "rb") { |f| f.read }, :disposition => 'attachment', :filename => "#{sanitized_pdf_name}.pdf"
-      File.delete(_destination_file)
+    begin
+      pdf_bytes = render_pdf(source_file)
+    ensure
+      File.delete(source_file) if File.exist?(source_file)
     end
+
+    deliver_pdf(pdf_bytes)
   end
 
   def initialize_downloads(pdf_options = {})
     pdf_options ||= {}
     @name = pdf_options[:title].nil? ? "#{Time.now.to_i.to_s}" : pdf_options[:title]
     @layout = pdf_options[:layout].nil? ? HtmlToPdf.configuration.default_layout : pdf_options[:layout]
-    @wkhtmltopdf_options = build_wkhtmltopdf_options(pdf_options)
+    @print_options, @javascript_delay = HtmlToPdf::PrintOptions.build(pdf_options)
   end
 
   def sanitized_pdf_name
     @name.to_s.gsub(/[^a-zA-Z0-9_\- ]/, '').strip.presence || Time.now.to_i.to_s
   end
 
-  # Merges, in increasing precedence: HtmlToPdf.configuration.default_options,
-  # pdf_options[:padding] (shorthand applied to all four margins), then
-  # pdf_options[:wkhtmltopdf_options] (any wkhtmltopdf flag, e.g. orientation:
-  # 'Landscape', page_size: 'A4', grayscale: true). Keys are dasherized so
-  # either underscore or dash form works.
-  def build_wkhtmltopdf_options(pdf_options)
-    options = dasherize_keys(HtmlToPdf.configuration.default_options)
-
-    if pdf_options[:padding].present?
-      padding = pdf_options[:padding].to_s
-      %w[margin-top margin-bottom margin-left margin-right].each { |flag| options[flag] = padding }
+  # Renders the given HTML file to PDF bytes via a pooled headless Chrome
+  # instance. Navigating to a file:// URL (rather than feeding Chrome the
+  # markup directly) gives relative asset paths a real base URI to resolve
+  # against, matching how a browser would load the page.
+  def render_pdf(source_file)
+    HtmlToPdf::BrowserPool.with_page do |page|
+      page.go_to("file://#{source_file}")
+      sleep(@javascript_delay / 1000.0) if @javascript_delay.to_i.positive?
+      page.pdf(encoding: :binary, **(@print_options || {}))
     end
-
-    options.merge!(dasherize_keys(pdf_options[:wkhtmltopdf_options] || {}))
-    options
   end
 
-  def dasherize_keys(hash)
-    hash.each_with_object({}) { |(key, value), acc| acc[key.to_s.tr('_', '-')] = value }
-  end
-
-  # Query-string values arrive as strings (e.g. grayscale: true serializes to
-  # "true" in a link_to href and comes back as that literal string), so plain
-  # booleans aren't enough to detect a falsy/truthy flag.
-  FALSEY_VALUES = [nil, false, '', '0', 'false', 'off'].freeze
-  TRUTHY_FLAG_VALUES = [true, 'true'].freeze
-
-  def wkhtmltopdf_args
-    (@wkhtmltopdf_options || {}).each_with_object([]) do |(flag, value), args|
-      normalized = value.is_a?(String) ? value.downcase : value
-      next if FALSEY_VALUES.include?(normalized)
+  private
 
-      args << "--#{flag}"
-      args << value.to_s unless TRUTHY_FLAG_VALUES.include?(normalized)
-    end
+  def pdf_request?
+    request.format == 'application/pdf'
   end
 
+  # Equivalent to send_data, but assigns response_body directly instead of
+  # going through #render. #render refuses a second render in the same
+  # action (AbstractController::DoubleRenderError) — and by this point one
+  # already happened, deliberately, via the forced-:html yield above.
+  def deliver_pdf(pdf_bytes)
+    send_file_headers!(disposition: 'attachment', filename: "#{sanitized_pdf_name}.pdf")
+    self.status = 200
+    self.response_body = pdf_bytes
+  end
 end
-
-ActionController::Base.send(:include, HtmlToPdf)

data/spec/htmlToPdf/browser_pool_spec.rb

@@ -0,0 +1,89 @@
+require "spec_helper"
+
+RSpec.describe HtmlToPdf::BrowserPool do
+  after { described_class.reset! }
+
+  describe "pooling (stubbed Ferrum, no real Chrome)" do
+    let(:fake_browser) { instance_double(Ferrum::Browser, quit: nil) }
+
+    before do
+      allow(Ferrum::Browser).to receive(:new).and_return(fake_browser)
+    end
+
+    it "memoizes one browser across multiple with_page calls" do
+      allow(fake_browser).to receive(:create_page).and_yield(double("page")).twice
+
+      described_class.with_page { |_page| nil }
+      described_class.with_page { |_page| nil }
+
+      expect(Ferrum::Browser).to have_received(:new).once
+    end
+
+    it "quits and drops the memoized browser on reset!" do
+      described_class.browser
+
+      described_class.reset!
+
+      expect(fake_browser).to have_received(:quit)
+      allow(Ferrum::Browser).to receive(:new).and_return(fake_browser)
+      described_class.browser
+      expect(Ferrum::Browser).to have_received(:new).twice
+    end
+
+    it "retries once after a recoverable error, then succeeds on the new browser" do
+      call_count = 0
+      allow(fake_browser).to receive(:create_page) do |&block|
+        call_count += 1
+        raise Ferrum::DeadBrowserError if call_count == 1
+
+        block.call(double("page"))
+      end
+
+      result = described_class.with_page { |_page| :ok }
+
+      expect(result).to eq(:ok)
+      expect(call_count).to eq(2)
+    end
+
+    it "gives up and raises after the retry also fails" do
+      allow(fake_browser).to receive(:create_page).and_raise(Ferrum::DeadBrowserError)
+
+      expect { described_class.with_page { |_page| nil } }.to raise_error(Ferrum::DeadBrowserError)
+    end
+
+    it "does not retry a non-recoverable error" do
+      allow(fake_browser).to receive(:create_page).and_raise(ArgumentError, "boom")
+
+      expect { described_class.with_page { |_page| nil } }.to raise_error(ArgumentError)
+      expect(fake_browser).to have_received(:create_page).once
+    end
+
+    it "passes configuration.browser_options straight to Ferrum::Browser.new" do
+      HtmlToPdf.configure { |c| c.browser_options = { timeout: 42 } }
+      allow(fake_browser).to receive(:create_page).and_yield(double("page"))
+
+      described_class.with_page { |_page| nil }
+
+      expect(Ferrum::Browser).to have_received(:new).with(timeout: 42)
+    end
+  end
+
+  describe "against a real Chrome process", :chrome do
+    it "reuses the same browser process across renders" do
+      pids = Array.new(3) do
+        described_class.with_page do |page|
+          page.go_to("about:blank")
+          described_class.browser.process.pid
+        end
+      end
+
+      expect(pids.uniq.size).to eq(1)
+    end
+
+    it "does not leak a browser context per render (block form disposes it)" do
+      5.times { described_class.with_page { |page| page.go_to("about:blank") } }
+
+      expect(described_class.browser.contexts.size).to eq(0)
+    end
+  end
+end

data/spec/htmlToPdf/configuration_spec.rb

@@ -0,0 +1,51 @@
+require "spec_helper"
+
+RSpec.describe HtmlToPdf::Configuration do
+  describe "defaults" do
+    subject(:config) { described_class.new }
+
+    it "has no browser_options, letting Ferrum auto-detect Chrome" do
+      expect(config.browser_options).to eq({})
+    end
+
+    it "defaults to the application layout" do
+      expect(config.default_layout).to eq("application")
+    end
+
+    it "prints backgrounds by default" do
+      expect(config.default_options).to eq(print_background: true)
+    end
+
+    it "does not honor request-supplied header/footer templates by default" do
+      expect(config.allow_request_templates).to eq(false)
+    end
+
+    it "caps javascript_delay at 10 seconds by default" do
+      expect(config.max_javascript_delay_ms).to eq(10_000)
+    end
+  end
+
+  describe "HtmlToPdf.configure" do
+    after { HtmlToPdf.reset_configuration! }
+
+    it "yields the shared configuration for mutation" do
+      HtmlToPdf.configure { |c| c.default_layout = "pdf" }
+
+      expect(HtmlToPdf.configuration.default_layout).to eq("pdf")
+    end
+
+    it "memoizes the same configuration instance across calls" do
+      expect(HtmlToPdf.configuration).to equal(HtmlToPdf.configuration)
+    end
+  end
+
+  describe ".reset_configuration!" do
+    it "replaces the configuration with fresh defaults" do
+      HtmlToPdf.configure { |c| c.default_layout = "pdf" }
+
+      HtmlToPdf.reset_configuration!
+
+      expect(HtmlToPdf.configuration.default_layout).to eq("application")
+    end
+  end
+end

data/spec/htmlToPdf/print_options_spec.rb

@@ -0,0 +1,154 @@
+require "spec_helper"
+
+RSpec.describe HtmlToPdf::PrintOptions do
+  def build(pdf_options)
+    described_class.build(pdf_options)
+  end
+
+  describe "precedence" do
+    it "lets a per-request :padding override a gem-wide default margin" do
+      HtmlToPdf.configure { |c| c.default_options = { margin_top: "1in" } }
+
+      options, = build(padding: "20mm")
+
+      expect(options[:margin_top]).to be_within(0.0001).of(20 / 25.4)
+    end
+
+    it "lets an explicit print_options margin win over :padding" do
+      options, = build(padding: "20mm", print_options: { margin_top: "5mm" })
+
+      expect(options[:margin_top]).to be_within(0.0001).of(5 / 25.4)
+      expect(options[:margin_bottom]).to be_within(0.0001).of(20 / 25.4)
+    end
+
+    it "lets explicit paper_width/paper_height override a gem-wide default :format" do
+      HtmlToPdf.configure { |c| c.default_options = { format: "A4" } }
+
+      options, = build(print_options: { paper_width: 5, paper_height: 5 })
+
+      expect(options[:paper_width]).to eq(5.0)
+      expect(options[:paper_height]).to eq(5.0)
+    end
+
+    it "resolves a per-request :format, overriding the default" do
+      HtmlToPdf.configure { |c| c.default_options = { format: "A4" } }
+
+      options, = build(print_options: { format: "Letter" })
+
+      expect(options[:paper_width]).to eq(8.50)
+      expect(options[:paper_height]).to eq(11.00)
+    end
+
+    it "falls back to the resolved default format when nothing is passed" do
+      HtmlToPdf.configure { |c| c.default_options = { format: "A4" } }
+
+      options, = build({})
+
+      expect(options[:paper_width]).to eq(8.27)
+      expect(options[:paper_height]).to eq(11.70)
+    end
+  end
+
+  describe "unit conversion" do
+    %w[mm cm in px].each do |unit|
+      it "accepts #{unit} units on size keys" do
+        options, = build(print_options: { margin_top: "10#{unit}" })
+
+        expect(options[:margin_top]).to be_a(Float)
+      end
+    end
+
+    it "treats a bare number as inches" do
+      options, = build(print_options: { margin_top: 2 })
+
+      expect(options[:margin_top]).to eq(2.0)
+    end
+
+    it "raises on an unrecognized size value" do
+      expect { build(print_options: { margin_top: "lots" }) }.to raise_error(ArgumentError)
+    end
+  end
+
+  describe "paper format" do
+    it "raises on an unknown format name" do
+      expect { build(print_options: { format: "Poster" }) }.to raise_error(ArgumentError)
+    end
+
+    it "is case-insensitive" do
+      options, = build(print_options: { format: "a4" })
+
+      expect(options[:paper_width]).to eq(8.27)
+    end
+  end
+
+  describe "header_template / footer_template" do
+    it "strips them from request-supplied print_options by default" do
+      options, = build(print_options: { header_template: "<script>evil()</script>" })
+
+      expect(options).not_to have_key(:header_template)
+    end
+
+    it "still honors them from config.default_options, which is trusted app code" do
+      HtmlToPdf.configure { |c| c.default_options = { header_template: "<span>trusted</span>" } }
+
+      options, = build({})
+
+      expect(options[:header_template]).to eq("<span>trusted</span>")
+    end
+
+    it "honors a request-supplied template only when explicitly opted in" do
+      HtmlToPdf.configure { |c| c.allow_request_templates = true }
+
+      options, = build(print_options: { footer_template: "<span>ok</span>" })
+
+      expect(options[:footer_template]).to eq("<span>ok</span>")
+    end
+  end
+
+  describe "javascript_delay" do
+    it "is extracted out of the CDP options hash" do
+      options, delay = build(print_options: { javascript_delay: 250 })
+
+      expect(options).not_to have_key(:javascript_delay)
+      expect(delay).to eq(250)
+    end
+
+    it "is clamped to config.max_javascript_delay_ms" do
+      HtmlToPdf.configure { |c| c.max_javascript_delay_ms = 1_000 }
+
+      _, delay = build(print_options: { javascript_delay: 999_999 })
+
+      expect(delay).to eq(1_000)
+    end
+
+    it "never goes negative" do
+      _, delay = build(print_options: { javascript_delay: -500 })
+
+      expect(delay).to eq(0)
+    end
+
+    it "is nil when not given" do
+      _, delay = build({})
+
+      expect(delay).to be_nil
+    end
+  end
+
+  describe "legacy flag names" do
+    it "no longer recognizes wkhtmltopdf-style orientation/page_size" do
+      options, = build(print_options: { orientation: "Landscape", page_size: "A4" })
+
+      expect(options[:landscape]).to be_nil
+      expect(options[:orientation]).to eq("Landscape")
+      expect(options[:paper_width]).to be_nil
+    end
+  end
+
+  describe "key formatting" do
+    it "accepts dasherized keys the same as underscored ones" do
+      options, = build(print_options: { "margin-top" => "10mm" })
+
+      expect(options[:margin_top]).to be_within(0.0001).of(10 / 25.4)
+    end
+  end
+end

data/spec/integration/controller_spec.rb

@@ -0,0 +1,75 @@
+require "spec_helper"
+
+# These exercise the controller hook (include HtmlToPdf + around_action)
+# against a real Rails dispatch, not a stub. An earlier version of this gem
+# hooked in as a before_action that quietly rebuilt the controller and
+# re-ran the action on the copy; Rails' own `response=` setter is documented
+# to mark the response as already rendered the moment it's assigned, and
+# copying the throwaway controller's instance variables back onto the real
+# one carried that flag along, so `send_data` raised DoubleRenderError on
+# every single PDF request once run against a real app rather than a stub.
+# It also meant a before_action declared after html_to_pdf never got to run
+# before the view was captured. These specs pin both down so they can't
+# silently come back.
+RSpec.describe "HtmlToPdf controller integration", type: :request do
+  around do |example|
+    HtmlToPdf.configure { |c| c.default_options = { print_background: true } }
+    example.run
+  ensure
+    HtmlToPdf::BrowserPool.reset!
+  end
+
+  it "does not raise DoubleRenderError and returns a real PDF" do
+    get "/widgets/42", params: { format: :pdf }
+
+    expect(response).to have_http_status(:ok)
+    expect(response.media_type).to eq("application/pdf")
+    expect(response.body.byteslice(0, 4)).to eq("%PDF")
+  end
+
+  it "runs a before_action declared after the around_action before capturing the view" do
+    get "/widgets/42", params: { format: :pdf }
+
+    pdf_text = extract_text(response.body)
+    expect(pdf_text).to include("Widget #42")
+  end
+
+  it "runs the action body exactly once" do
+    WidgetsController.show_invocations = 0
+
+    get "/widgets/7", params: { format: :pdf }
+
+    expect(WidgetsController.show_invocations).to eq(1)
+  end
+
+  it "leaves ordinary HTML requests completely unaffected" do
+    get "/widgets/42"
+
+    expect(response).to have_http_status(:ok)
+    expect(response.media_type).to eq("text/html")
+    expect(response.body).to include("Widget #42")
+  end
+
+  it "honors a custom layout passed via pdf_options" do
+    get "/widgets/5", params: { format: :pdf, pdf_options: { layout: "pdf" } }
+
+    expect(extract_text(response.body)).to include("PDF LAYOUT")
+  end
+
+  it "still runs rescue_from for an exception raised inside the action" do
+    get "/booms/1", params: { format: :pdf }
+
+    expect(response).to have_http_status(:unprocessable_content)
+    expect(response.body).to eq("handled")
+  end
+
+  def extract_text(pdf_bytes)
+    require "tempfile"
+    file = Tempfile.new(["spec", ".pdf"], binmode: true)
+    file.write(pdf_bytes)
+    file.flush
+    `pdftotext #{file.path} -`
+  ensure
+    file&.close!
+  end
+end

data/spec/internal/app/controllers/application_controller.rb

@@ -0,0 +1,3 @@
+class ApplicationController < ActionController::Base
+  include HtmlToPdf
+end

data/spec/internal/app/controllers/booms_controller.rb

@@ -0,0 +1,16 @@
+class BoomsController < ApplicationController
+  class Boom < StandardError; end
+
+  around_action :html_to_pdf, only: [:show]
+  rescue_from Boom, with: :handle_boom
+
+  def show
+    raise Boom, "deliberate failure for spec coverage"
+  end
+
+  private
+
+  def handle_boom
+    render plain: "handled", status: :unprocessable_content
+  end
+end

data/spec/internal/app/controllers/widgets_controller.rb

@@ -0,0 +1,25 @@
+class WidgetsController < ApplicationController
+  around_action :html_to_pdf, only: [:show]
+
+  # Declared after the around_action, matching the real-world ordering that
+  # exposed the original gem's bug: anything this sets must still be visible
+  # to the view when the request is being converted to a PDF.
+  before_action :set_widget, only: [:show]
+
+  cattr_accessor :show_invocations
+  self.show_invocations = 0
+
+  def index
+    render plain: "widgets index"
+  end
+
+  def show
+    self.class.show_invocations += 1
+  end
+
+  private
+
+  def set_widget
+    @widget = "Widget ##{params[:id]}"
+  end
+end

data/spec/internal/app/views/layouts/application.html.erb

@@ -0,0 +1,4 @@
+<!DOCTYPE html>
+<html>
+  <body><%= yield %></body>
+</html>

data/spec/internal/app/views/layouts/pdf.html.erb

@@ -0,0 +1,4 @@
+<!DOCTYPE html>
+<html>
+  <body><strong>PDF LAYOUT</strong><%= yield %></body>
+</html>

data/spec/internal/app/views/widgets/show.html.erb

@@ -0,0 +1,2 @@
+<h1><%= @widget %></h1>
+<p>Rendered at <%= Time.now.to_i %></p>

data/spec/internal/config/routes.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+Rails.application.routes.draw do
+  resources :widgets, only: [:index, :show]
+  resources :booms, only: [:show]
+end

data/spec/internal/log/.gitignore

@@ -0,0 +1 @@
+*.log

data/spec/spec_helper.rb

@@ -0,0 +1,31 @@
+require "combustion"
+Combustion.initialize! :action_controller, :action_view
+
+require "rspec/rails"
+require "htmlToPdf"
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |c|
+    c.syntax = :expect
+  end
+
+  config.before do
+    HtmlToPdf.reset_configuration!
+  end
+
+  # Specs tagged :chrome exercise a real headless Chrome/Chromium process.
+  # Skip them with a clear reason rather than a confusing Ferrum crash when
+  # no browser is installed, so running the suite stays contributor-friendly
+  # on a machine that just doesn't have Chrome.
+  chrome_available =
+    begin
+      browser = Ferrum::Browser.new
+      true
+    rescue Ferrum::BinaryNotFoundError
+      false
+    ensure
+      browser&.quit
+    end
+
+  config.filter_run_excluding(chrome: true) unless chrome_available
+end