htmlToPdf 2.0.0 → 3.0.0

data/Rakefile

@@ -1,2 +1,6 @@
 require "bundler/gem_tasks"
+require "rspec/core/rake_task"
 
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/config.ru

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+require "rubygems"
+require "bundler"
+
+Bundler.require :default, :development
+
+Combustion.initialize! :all
+run Combustion::Application

data/docs/architecture.md

@@ -0,0 +1,99 @@
+# HtmlToPdf architecture
+
+[← Back to README](../README.md)
+
+## Why headless Chrome instead of wkhtmltopdf
+
+wkhtmltopdf renders with a frozen, years-out-of-date WebKit build — no flexbox fixes, no CSS Grid,
+no modern font handling, and the upstream project has been unmaintained for years. Headless Chrome
+is the actual rendering engine your users browse your app with, kept current by Chrome's own
+release cycle, so "what the PDF looks like" and "what the page looks like in a browser" stop being
+two different questions. The tradeoff is the dependency: a real Chrome/Chromium install instead of
+a single static binary. See [Rails integration](rails-integration.md#production-deployment-chrome-in-docker)
+for what that costs you in a container image.
+
+## Request lifecycle
+
+For one `GET /widgets/1.pdf` request, with `include HtmlToPdf` + `around_action :html_to_pdf` on
+the controller:
+
+```mermaid
+sequenceDiagram
+    participant Rails as Rails callback chain
+    participant HTP as html_to_pdf
+    participant Action as Controller action
+    participant Pool as BrowserPool
+    participant Chrome as Ferrum::Browser (Chrome)
+
+    Rails->>HTP: around_action reaches html_to_pdf
+    HTP->>HTP: initialize_downloads(pdf_options)<br/>(resolves @layout, @print_options, @javascript_delay)
+    HTP->>Rails: request.format = :html, yield
+    Rails->>Action: remaining before_actions, then the action body
+    Action-->>Rails: implicit render (discarded — see below)
+    Rails-->>HTP: yield returns, request.format restored
+    HTP->>HTP: render_to_string(layout: @layout)<br/>— the HTML that actually gets converted
+    HTP->>Pool: render_pdf(source_file)
+    Pool->>Chrome: create_page(new_context: true) { |page| ... }
+    Chrome-->>Pool: page.go_to("file://...") + page.pdf(**print_options)
+    Pool-->>HTP: PDF bytes
+    HTP->>Rails: send_file_headers! + self.response_body =
+```
+
+The forced-`:html` `yield` is the load-bearing part of this design, and the reason this is an
+`around_action` rather than a `before_action`: it lets the *rest* of the callback chain and the
+action run in their normal place — any other `before_action` (a `set_record`-style one, say) runs
+exactly where it always would, with its instance variables available by the time
+`render_to_string` runs afterward. Format is forced to `:html` for the `yield` only so Rails'
+*own* implicit-render machinery resolves the actual `.html.erb` template instead of raising
+`UnknownFormat` for a `.pdf` template that doesn't exist — that render's output is thrown away;
+`render_to_string`, called after format is restored, is what actually gets written to disk and
+converted. See [The DoubleRenderError trap](https://ramlaxmanyadav.github.io/htmlToPdf/rails-double-render-pdf.html)
+for the bug this design replaced and exactly why the obvious-looking alternative doesn't work.
+
+## BrowserPool
+
+```mermaid
+flowchart LR
+    R1["Request A"] --> Pool
+    R2["Request B"] --> Pool
+    Pool["BrowserPool<br/>(one Ferrum::Browser per process)"]
+    Pool --> C1["Context A<br/>(create_page new_context: true)"]
+    Pool --> C2["Context B<br/>(create_page new_context: true)"]
+    C1 --> Chrome["Chrome OS process"]
+    C2 --> Chrome
+```
+
+Launching Chrome costs several hundred milliseconds, so `HtmlToPdf::BrowserPool` keeps one
+`Ferrum::Browser` alive per Ruby process (lazily started on first use, guarded by a `Mutex` for
+the memoization itself — not for every command; Ferrum's own CDP client assigns command IDs under
+its own mutex and matches responses by ID, so concurrent `with_page` calls from multiple Puma
+threads are safe to issue against the one shared browser). Every call still gets `create_page(new_context:
+true) { |page| ... }` — a fresh, isolated browser context (separate cookies/storage/cache) per
+conversion, disposed automatically when the block returns. That block form matters: calling
+`create_page(new_context: true)` *without* a block and closing the page yourself leaks the context
+— Ferrum only disposes it in the `ensure` attached to the block form.
+
+If a command raises `Ferrum::DeadBrowserError`, `ProcessTimeoutError`, `TimeoutError`, or
+`NoSuchPageError` (Chrome crashed or stopped responding), `BrowserPool` quits the dead browser,
+drops the memoized reference, and retries the whole `with_page` call once against a freshly
+launched browser before giving up and re-raising.
+
+**Scaling note:** this is one Chrome process per Ruby process, not per request. That's the right
+tradeoff for the common case (a web app rendering PDFs on demand), but it does mean every thread in
+that process shares one browser — a page that hangs indefinitely ties up that shared resource for
+everyone until Ferrum's own timeout fires. If you're rendering PDFs at high, sustained concurrency,
+that's a capacity ceiling worth knowing is there rather than discovering under load.
+
+## print_options and security
+
+`HtmlToPdf::PrintOptions.build` is the one place `pdf_options` (a request-param-shaped hash) turns
+into the keyword arguments handed to `Ferrum::Page#pdf` / Chrome's `Page.printToPDF`. Precedence,
+highest first: `pdf_options[:print_options]`, then `pdf_options[:padding]`, then
+`config.default_options` — each source is resolved (paper `:format` → `:paper_width`/
+`:paper_height`, unit conversion) independently before merging, so a gem-wide default can't
+silently clobber an explicit per-request value for the same underlying dimension.
+
+Chrome's print options are a fixed, narrow set of layout flags — margins, paper size, scale — with
+one deliberate exception: `header_template`/`footer_template` are raw HTML Chrome renders as-is.
+See [Security](security.md) for why those two keys are filtered out of request-supplied
+`print_options` by default, and what `config.allow_request_templates` actually opts you into.

data/docs/contributing.md

@@ -0,0 +1,60 @@
+# Contributing & Releasing
+
+[← Back to README](../README.md)
+
+## Running the test suite
+
+```
+bundle install
+bundle exec rake   # alias for `rake spec`
+```
+
+The suite needs a real Chrome or Chromium install for the specs tagged `:chrome` (most of
+`spec/htmlToPdf/browser_pool_spec.rb`, and all of `spec/integration/controller_spec.rb`, which
+drives a real Rails dispatch via a minimal [combustion](https://github.com/pat/combustion) app
+under `spec/internal`) — those specs are automatically excluded with a clear message if
+`Ferrum::Browser.new` can't find a binary, so the rest of the suite (the `PrintOptions` and
+`Configuration` unit specs, and the stubbed-Ferrum half of `BrowserPool`'s specs) still runs
+without one. `spec/integration/controller_spec.rb` also shells out to `pdftotext` (part of
+`poppler-utils`) to assert on actual rendered PDF content — install it locally the same way CI
+does (`apt-get install poppler-utils` on Debian/Ubuntu, `brew install poppler` on macOS) to run
+those checks.
+
+`spec/internal` is the combustion-managed dummy Rails app — only the files this gem's own specs
+actually exercise exist there (a couple of controllers, views, and routes), not a full scaffolded
+app.
+
+## Extending it
+
+- `lib/htmlToPdf/print_options.rb` is where `pdf_options`/`config.default_options` turn into the
+  keyword arguments `Ferrum::Page#pdf` expects — see
+  [Architecture](architecture.md#print_options-and-security) before adding a new option, especially
+  anything that (like `header_template`) is raw HTML rather than a validated value.
+- `lib/htmlToPdf/browser_pool.rb` owns the one pooled `Ferrum::Browser` per process — see
+  [Architecture](architecture.md#browserpool) for the context-leak trap the block form of
+  `create_page` exists to avoid.
+- `lib/htmlToPdf.rb` is the controller-facing `around_action` itself — read
+  [Rails integration](rails-integration.md) and the
+  ["DoubleRenderError" guide](https://ramlaxmanyadav.github.io/htmlToPdf/rails-double-render-pdf.html)
+  before changing its control flow; the bug those describe only shows up against a real Rails
+  dispatch, not a stub, which is exactly why `spec/integration/controller_spec.rb` exists.
+
+## Releasing
+
+Two GitHub Actions workflows handle this repo's own CI/CD:
+
+- [`.github/workflows/ci.yml`](../.github/workflows/ci.yml) — runs the spec suite, a syntax sweep,
+  and a `gem build` sanity check on every push/PR to `master`, across every Ruby version
+  `required_ruby_version` claims to support (3.1 through 3.4).
+- [`.github/workflows/release.yml`](../.github/workflows/release.yml) — pushing a tag matching `v*`
+  re-runs the test suite, then publishes to RubyGems via
+  [Trusted Publishing](https://guides.rubygems.org/trusted-publishing/) (OIDC — no API key stored
+  as a GitHub secret, nothing to leak or rotate).
+
+Trusted Publishing needs a one-time setup on rubygems.org before the release workflow can actually
+publish anything (this can't be done from the repo itself — it's a rubygems.org account action):
+sign in, go to the htmlToPdf gem's page → **Trusted Publishers** → add one with owner
+`ramlaxmanyadav`, repository `htmlToPdf`, workflow filename `release.yml`, no environment. After
+that, `git tag vX.Y.Z && git push origin vX.Y.Z` is the entire release process — bump
+`lib/htmlToPdf/version.rb`, update `CHANGELOG.md`, commit, tag, push the tag, and the workflow does
+the rest.

data/docs/rails-integration.md

@@ -0,0 +1,111 @@
+# HtmlToPdf in Rails
+
+[← Back to README](../README.md)
+
+## Wiring it up
+
+```ruby
+class ApplicationController < ActionController::Base
+  include HtmlToPdf
+  around_action :html_to_pdf
+end
+```
+
+It has to be `include` + `around_action`, not just a `before_action` — see
+[Architecture](architecture.md#request-lifecycle) for exactly why, and
+[The DoubleRenderError trap](https://ramlaxmanyadav.github.io/htmlToPdf/rails-double-render-pdf.html)
+for the bug this replaced. `HtmlToPdf` is a plain `ActiveSupport::Concern` with no `included do`
+block, so including it only defines the method — nothing runs for any controller until you also
+declare the `around_action` yourself, scoped however you like:
+
+```ruby
+# Only the actions that actually support a PDF export, not every action on the controller.
+around_action :html_to_pdf, only: [:index, :show]
+```
+
+## Callback ordering
+
+Because this is a real `around_action`, every other callback runs in its normal, declared
+position — a `before_action` declared *after* `html_to_pdf` still runs before the view is
+captured, same as it would for an ordinary HTML request:
+
+```ruby
+class InvoicesController < ApplicationController
+  around_action :html_to_pdf, only: [:show]
+  before_action :set_invoice, only: [:show]   # runs normally; @invoice is set before capture
+
+  def show
+  end
+
+  private
+
+  def set_invoice
+    @invoice = Invoice.find(params[:id])
+  end
+end
+```
+
+`rescue_from` works the same way — an exception raised inside the action during the `yield`
+propagates normally and is handled by whatever `rescue_from` the controller has configured, exactly
+as it would outside a PDF request.
+
+## Custom layout and filename per request
+
+```erb
+<%= link_to "Download PDF", invoice_path(@invoice, format: :pdf, pdf_options: {
+  title: "invoice-#{@invoice.number}",
+  layout: "pdf"
+}) %>
+```
+
+`pdf_options[:layout]` overrides `config.default_layout` for just this render — handy for a
+print-specific layout with no navigation chrome, as opposed to your app's normal layout. See the
+[README](../README.md#usage) for the full `pdf_options`/`print_options` reference.
+
+## Production deployment: Chrome in Docker
+
+The most common point of friction isn't the gem, it's "Chrome isn't in my container image."
+Ferrum needs a real Chrome/Chromium binary on the machine actually rendering PDFs. For a
+Debian/Ubuntu-based image:
+
+```dockerfile
+RUN apt-get update -qq && apt-get install -y --no-install-recommends \
+      chromium \
+    && rm -rf /var/lib/apt/lists/*
+```
+
+If your container runs as root (common for a minimal/CI image, uncommon for a real production
+image — prefer a non-root user there if you can), Chrome refuses to start without its sandbox
+disabled:
+
+```ruby
+# config/initializers/html_to_pdf.rb
+HtmlToPdf.configure do |config|
+  config.browser_options = { browser_options: { "no-sandbox" => nil } } if ENV["CHROME_NO_SANDBOX"]
+end
+```
+
+Don't set `no-sandbox` unconditionally on a machine where you don't control what else runs — it's
+specifically a root-in-a-throwaway-container accommodation, not a default.
+
+## The asset_host gotcha
+
+`HtmlToPdf` writes the rendered view to a temporary `.html` file and points Chrome at it via a
+`file://` URL (so relative paths still have a real base URI to resolve against — see
+[Architecture](architecture.md#request-lifecycle)). A stylesheet tag that emits a root-relative URL
+(`/assets/application-abcd1234.css`, Rails' normal default) resolves against that `file://` origin
+to `file:///assets/application-abcd1234.css` — which doesn't exist — and the CSS silently fails to
+load. The PDF comes out completely unstyled, with no error anywhere.
+
+The fix is `config.asset_host`, set to something that actually resolves over real HTTP. Hardcoding
+a host only works until someone runs the app on a different port, so derive it from the request
+instead:
+
+```ruby
+# config/environments/development.rb
+config.asset_host = Proc.new { |_source, request| request ? "#{request.scheme}://#{request.host_with_port}" : nil }
+```
+
+Production usually already has a real `asset_host` pointed at a CDN for unrelated reasons — if
+yours doesn't yet, this is exactly the same fix, just pointed at your own domain instead of
+`localhost`.

data/docs/security.md

@@ -0,0 +1,81 @@
+# Security model
+
+[← Back to README](../README.md)
+
+`pdf_options` is typically read straight from request params (`params[:pdf_options]`) — the README
+example passes it through a `link_to` query string. That means anything accepted under
+`pdf_options[:print_options]` is, by default, something an unauthenticated caller can set on any
+action that exposes the `pdf` format. The design goal is that the worst a caller can do with that
+is make an ugly PDF, never run arbitrary code or reach another host.
+
+## What's safe by construction
+
+Every `print_options` key except two (below) is a validated number, boolean, or enum:
+
+- `format` is checked against a fixed table of named paper sizes (`PrintOptions::PAPER_SIZES`) and
+  raises `ArgumentError` on anything else — it can't be used to inject arbitrary strings into
+  Chrome's protocol layer.
+- `margin_*`/`paper_width`/`paper_height` go through `PrintOptions.to_inches`, which only accepts a
+  number or a `number + unit` string (`mm`/`cm`/`in`/`px`) — again, `ArgumentError` on anything else.
+- `landscape`, `print_background`, `display_header_footer`, `prefer_css_page_size` are passed
+  straight through to Chrome's `Page.printToPDF`, which itself only accepts booleans for these.
+
+This is a meaningfully narrower surface than the gem's wkhtmltopdf-based predecessor, which
+forwarded `wkhtmltopdf_options` as literal CLI flags to a subprocess — any key a caller supplied
+became an actual argv entry to a binary. `print_options` is a fixed hash of typed values sent over
+the Chrome DevTools Protocol; there's no argv for a caller to inject into.
+
+## The one exception: header_template / footer_template
+
+These two are raw HTML — Chrome renders them as-is inside the printed header/footer. Unlike every
+other key, there's no validation that could make an arbitrary string safe here: a caller who
+controls `header_template` can embed anything, including
+`<img src="http://169.254.169.254/latest/meta-data/...">` or any other internal-network URL,
+and the Chrome process (which has real network access) will fetch it — a server-side request
+forgery vector, not merely an HTML-injection one.
+
+Because of that, `header_template`/`footer_template` are **stripped from request-supplied
+`print_options` by default**. They're only honored from `config.default_options` — Ruby code you
+wrote, not request input:
+
+```ruby
+# config/initializers/html_to_pdf.rb — this is fine, it's your own code
+HtmlToPdf.configure do |config|
+  config.default_options = {
+    header_template: "<span></span>",
+    footer_template: "<div style='font-size:10px;text-align:center;'><span class=\"pageNumber\"></span></div>"
+  }
+end
+```
+
+If you genuinely need a caller to control the header/footer HTML — and have your own separate
+sanitization in place before `pdf_options` ever reaches `html_to_pdf` — that's what
+`config.allow_request_templates` is for:
+
+```ruby
+# Only do this if pdf_options never flows from unfiltered request params in your app.
+HtmlToPdf.configure { |config| config.allow_request_templates = true }
+```
+
+Default is `false`. Leave it there unless you've specifically reviewed what feeds `pdf_options` in
+your app.
+
+## javascript_delay has a ceiling
+
+`render_pdf` sleeps for `javascript_delay` milliseconds between page load and capture, while
+holding the pooled browser's page/context open (see [Architecture](architecture.md#browserpool)).
+Without a cap, one caller passing an enormous value would stall every other PDF render sharing that
+browser for however long they chose — a single-request denial of service against a resource every
+thread in the process shares. `config.max_javascript_delay_ms` (default `10_000`, i.e. 10 seconds)
+clamps it; raise it only if you trust whatever can set `javascript_delay` in your app.
+
+## The baseline that doesn't change
+
+None of the above touches the actual page content itself: `html_to_pdf` renders your view's own
+HTML, exactly as your app would render it for a normal request. If that view embeds
+caller-controlled content unescaped, or makes requests to caller-controlled URLs, that's the same
+risk any server-rendered HTML page has — PDF conversion doesn't add to it, but it doesn't take it
+away either. The guidance already in the README stands: don't expose the `pdf` format on an action
+where you wouldn't be comfortable letting a caller influence layout, and don't pass
+request-controlled values into `pdf_options` on a publicly reachable action without thinking about
+what in there is actually safe to expose.

data/htmlToPdf.gemspec

@@ -8,8 +8,8 @@ Gem::Specification.new do |spec|
   spec.version       = HtmlToPdf::VERSION
   spec.authors       = ["Ram Laxman Yadav"]
   spec.email         = ["yadavramlaxman@gmail.com"]
-  spec.summary       = %q{Render Rails controller actions to PDF using wkhtmltopdf}
-  spec.description   = %q{HtmlToPdf lets any Rails controller action be downloaded as a PDF. Request the action with a PDF format and the gem renders the view exactly as the browser would, then converts it to PDF via wkhtmltopdf. Supports Rails 7.x and 8.x.}
+  spec.summary       = %q{Render Rails controller actions to PDF using headless Chrome}
+  spec.description   = %q{HtmlToPdf lets any Rails controller action be downloaded as a PDF. Request the action with a PDF format and the gem renders the view exactly as the browser would, then converts it to PDF via a pooled headless Chrome instance (through the ferrum gem). Supports Rails 7.x and 8.x.}
   spec.homepage      = "https://github.com/ramlaxmanyadav/htmlToPdf"
   spec.license       = "MIT"
   spec.required_ruby_version = ">= 3.1"
@@ -17,6 +17,20 @@ Gem::Specification.new do |spec|
   spec.files         = `git ls-files -z`.split("\x0")
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
 
-  spec.add_development_dependency "bundler", ">= 2.4"
-  spec.add_development_dependency "rake", ">= 13.0"
+  spec.add_dependency "ferrum", ">= 0.13", "< 1.0"
+  spec.add_dependency "activesupport", ">= 7.0", "< 9"
+
+  spec.metadata["source_code_uri"]   = spec.homepage
+  spec.metadata["changelog_uri"]     = "#{spec.homepage}/blob/master/CHANGELOG.md"
+  spec.metadata["bug_tracker_uri"]   = "#{spec.homepage}/issues"
+  spec.metadata["documentation_uri"] = "https://ramlaxmanyadav.github.io/htmlToPdf/"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  spec.add_development_dependency "bundler", ">= 2.4", "< 5"
+  spec.add_development_dependency "rake", ">= 13.0", "< 14"
+  spec.add_development_dependency "rspec", "~> 3.13"
+  spec.add_development_dependency "rspec-rails", "~> 7.0"
+  spec.add_development_dependency "combustion", "~> 1.5"
+  spec.add_development_dependency "rails", ">= 7.0", "< 9"
+  spec.add_development_dependency "puma", ">= 5.0", "< 7"
 end

data/lib/htmlToPdf/browser_pool.rb

@@ -0,0 +1,50 @@
+require "ferrum"
+
+module HtmlToPdf
+  # Keeps a single headless Chrome process alive per Ruby process (starting
+  # Chrome per-request costs several hundred ms) and hands out a fresh,
+  # isolated browser context per conversion so pages never share cookies or
+  # state. Automatically restarts the browser once if Chrome has crashed or
+  # stopped responding.
+  module BrowserPool
+    MUTEX = Mutex.new
+
+    RECOVERABLE_ERRORS = [
+      Ferrum::DeadBrowserError,
+      Ferrum::ProcessTimeoutError,
+      Ferrum::TimeoutError,
+      Ferrum::NoSuchPageError
+    ].freeze
+
+    module_function
+
+    def with_page
+      attempts = 0
+      begin
+        attempts += 1
+        # The block form is required: it's the only way Ferrum disposes the
+        # browser context afterward. Closing just the page (as a bare
+        # `create_page(new_context: true)` + `page.close` would) leaks a
+        # context per call, which adds up fast in a long-lived pooled browser.
+        browser.create_page(new_context: true) { |page| yield page }
+      rescue *RECOVERABLE_ERRORS
+        reset!
+        retry if attempts < 2
+        raise
+      end
+    end
+
+    def browser
+      MUTEX.synchronize do
+        @browser ||= Ferrum::Browser.new(**HtmlToPdf.configuration.browser_options)
+      end
+    end
+
+    def reset!
+      MUTEX.synchronize do
+        @browser&.quit
+        @browser = nil
+      end
+    end
+  end
+end

data/lib/htmlToPdf/configuration.rb

@@ -1,12 +1,37 @@
 module HtmlToPdf
   class Configuration
-    attr_accessor :wkhtmltopdf_path, :default_layout, :default_options, :tmp_dir
+    # Hash of keyword options passed straight to Ferrum::Browser.new, e.g.
+    # { browser_path: '/usr/bin/chromium', timeout: 20, process_timeout: 30,
+    #   browser_options: { 'no-sandbox' => nil } } (the last is for running as
+    # root in Docker). Leave empty to let Ferrum auto-detect a local Chrome/
+    # Chromium install.
+    attr_accessor :browser_options
+
+    attr_accessor :default_layout, :default_options, :tmp_dir
+
+    # header_template/footer_template are raw HTML that Chrome renders
+    # as-is — unlike every other print option, they're not a validated
+    # number/enum/boolean, so letting a request control them lets a caller
+    # embed arbitrary markup (e.g. <img src="http://internal-host/...">,
+    # an SSRF vector against your network from the Chrome process). They're
+    # only honored from config.default_options (trusted application code)
+    # unless this is explicitly enabled. Only set this if pdf_options never
+    # flows from unfiltered request params in your app.
+    attr_accessor :allow_request_templates
+
+    # Upper bound (ms) on pdf_options[:print_options][:javascript_delay].
+    # render_pdf sleeps for this long while holding the pooled browser's
+    # page/context open, so an uncapped caller-supplied value would let one
+    # request stall every other PDF render sharing that browser.
+    attr_accessor :max_javascript_delay_ms
 
     def initialize
-      @wkhtmltopdf_path = 'wkhtmltopdf'
-      @default_layout   = 'application'
-      @default_options  = {}
-      @tmp_dir          = nil
+      @browser_options          = {}
+      @default_layout           = 'application'
+      @default_options          = { print_background: true }
+      @tmp_dir                  = nil
+      @allow_request_templates  = false
+      @max_javascript_delay_ms  = 10_000
     end
   end
 

data/lib/htmlToPdf/print_options.rb

@@ -0,0 +1,122 @@
+require "active_support/core_ext/object/blank"
+
+module HtmlToPdf
+  # Normalizes the Hash passed as pdf_options[:print_options] (plus the
+  # default_options configured globally and the :padding shorthand) into the
+  # keyword arguments Ferrum::Page#pdf / Chrome's Page.printToPDF expect.
+  #
+  # Chrome's print options are a fixed, narrow set of layout flags (margins,
+  # paper size, scale, etc.) rather than arbitrary CLI arguments, so this
+  # can't be used to inject arbitrary binary flags even when pdf_options
+  # comes from params. header_template/footer_template are the one exception
+  # — see TEMPLATE_KEYS below — and are filtered out of request-supplied
+  # options unless explicitly allowed.
+  module PrintOptions
+    SIZE_KEYS = %i[paper_width paper_height margin_top margin_bottom margin_left margin_right].freeze
+
+    # Matches Chrome's own predefined paper sizes (inches).
+    PAPER_SIZES = {
+      'letter'  => [8.50, 11.00],
+      'legal'   => [8.50, 14.00],
+      'tabloid' => [11.00, 17.00],
+      'ledger'  => [17.00, 11.00],
+      'a0'      => [33.10, 46.80],
+      'a1'      => [23.40, 33.10],
+      'a2'      => [16.54, 23.40],
+      'a3'      => [11.70, 16.54],
+      'a4'      => [8.27, 11.70],
+      'a5'      => [5.83, 8.27],
+      'a6'      => [4.13, 5.83]
+    }.freeze
+
+    UNIT_TO_INCHES = { 'in' => 1.0, 'cm' => 1 / 2.54, 'mm' => 1 / 25.4, 'px' => 1 / 96.0 }.freeze
+
+    # Raw HTML Chrome renders as-is, unlike every other print option. Only
+    # trusted (config.default_options) by default — see
+    # Configuration#allow_request_templates.
+    TEMPLATE_KEYS = %i[header_template footer_template].freeze
+
+    module_function
+
+    # Returns [cdp_options, javascript_delay_in_ms]. javascript_delay isn't a
+    # Chrome print flag (Page.printToPDF has no such parameter and rejects
+    # unknown ones) — it's our own convenience, applied as a pause between
+    # page load and capture, for pages that render content asynchronously.
+    #
+    # Precedence, highest first: pdf_options[:print_options], then
+    # pdf_options[:padding], then config.default_options. default_options and
+    # print_options are each resolved (legacy aliases/format) independently
+    # before merging, so e.g. a gem-wide default :format can't clobber an
+    # explicit per-request :paper_width/:paper_height, and a gem-wide default
+    # margin doesn't block a per-request :padding from overriding it.
+    def build(pdf_options)
+      defaults = resolve_source(HtmlToPdf.configuration.default_options)
+      request_options = resolve_source(pdf_options[:print_options] || {})
+      strip_request_templates!(request_options)
+      apply_padding!(request_options, pdf_options[:padding])
+
+      options = defaults.merge(request_options)
+      convert_sizes!(options)
+      javascript_delay = clamp_javascript_delay(options.delete(:javascript_delay))
+      [options, javascript_delay]
+    end
+
+    def resolve_source(hash)
+      options = underscore_keys(hash)
+      apply_format!(options)
+      options
+    end
+
+    def underscore_keys(hash)
+      hash.each_with_object({}) { |(key, value), acc| acc[key.to_s.tr('-', '_').to_sym] = value }
+    end
+
+    def strip_request_templates!(request_options)
+      return if HtmlToPdf.configuration.allow_request_templates
+
+      TEMPLATE_KEYS.each { |key| request_options.delete(key) }
+    end
+
+    def clamp_javascript_delay(value)
+      return nil unless value
+
+      [[value.to_i, 0].max, HtmlToPdf.configuration.max_javascript_delay_ms].min
+    end
+
+    def apply_padding!(options, padding)
+      return if padding.blank?
+
+      %i[margin_top margin_bottom margin_left margin_right].each do |key|
+        options[key] = padding unless options.key?(key)
+      end
+    end
+
+    def apply_format!(options)
+      format = options.delete(:format)
+      return unless format
+
+      dimensions = PAPER_SIZES[format.to_s.downcase]
+      raise ArgumentError, "Unknown paper format: #{format.inspect}" unless dimensions
+
+      options[:paper_width], options[:paper_height] = dimensions
+    end
+
+    def convert_sizes!(options)
+      SIZE_KEYS.each do |key|
+        next unless options.key?(key)
+
+        options[key] = to_inches(options[key])
+      end
+    end
+
+    def to_inches(value)
+      return value.to_f if value.is_a?(Numeric)
+
+      match = value.to_s.strip.match(/\A(-?[\d.]+)\s*(in|cm|mm|px)?\z/i)
+      raise ArgumentError, "Unrecognized size value: #{value.inspect}" unless match
+
+      number, unit = match.captures
+      number.to_f * UNIT_TO_INCHES.fetch(unit&.downcase || 'in')
+    end
+  end
+end

data/lib/htmlToPdf/version.rb

@@ -1,3 +1,3 @@
 module HtmlToPdf
-  VERSION = "2.0.0"
+  VERSION = "3.0.0"
 end