/
',
display_header_footer: true
}
# Directory the rendered HTML is temporarily written to before Chrome
# loads it (via a file:// URL, so relative asset paths resolve).
# Defaults to Rails.root/tmp.
config.tmp_dir = Rails.root.join("tmp", "pdfs")
# Only set this if pdf_options never flows from unfiltered request
# params in your app. Defaults to false. See Security.
# config.allow_request_templates = true
# Upper bound (ms) on a request-supplied javascript_delay, so one
# caller can't stall the shared browser pool for everyone. Defaults
# to 10_000.
# config.max_javascript_delay_ms = 10_000
end
A single headless Chrome process is started lazily and reused across requests in the same Ruby process (each conversion gets its own isolated browser context), since launching Chrome per-request is comparatively expensive. It's restarted automatically if Chrome crashes or stops responding. See [Architecture](docs/architecture.md#browserpool) for the design and its scaling limits.
##### Make sure you have configured your `asset_host` in application's Rails environment, otherwise assets might not be loaded properly — this is a bigger deal than it sounds for this gem specifically; see [the asset_host gotcha](docs/rails-integration.md#the-asset_host-gotcha).
`config.action_controller.asset_host = "YOUR_ASSETS_HOST"`
## Contributing
See [Contributing & Releasing](docs/contributing.md) for running the test suite and extending the
gem.
## License
MIT — see [LICENSE.txt](LICENSE.txt).
---
# docs/architecture.md
# 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)(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)
— 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
(one Ferrum::Browser per process)"] Pool --> C1["Context A
(create_page new_context: true)"] Pool --> C2["Context B
(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. --- # docs/rails-integration.md # 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`. --- # docs/security.md # 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 `
"
}
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.
---
# docs/contributing.md
# 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.