page_print 0.1.9 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 989676fa7f23af91a250034ce2b63479b27f2d2bda3bf3c56983c36497fb4723
-  data.tar.gz: 5e18cd17dae7825eee333a11279503d136f74fc41b56eab2d5b4601fa15a5ba7
+  metadata.gz: ca32ba67da6a5c3cfe5c66b3eac1242ffc1068ccce7838820d4550fffbe9d73d
+  data.tar.gz: 90ad2b4d3612d123f562ebd43098ed110c2ccb608d058409c496ce76e455e25d
 SHA512:
-  metadata.gz: b4574c7f4b22644193c516ffc81f66bad89ac725ebc9ffe9903924ebb99c694647d6ab203c1961f3b0f1e4182971b79cc871877bda7e79ad6266453e8597d4cd
-  data.tar.gz: dd4aa832adacdcdcb77baa1022d04fdfe00eef0bc5dd7c3d73bda1b4355efe2770a7bd67cd7411355ca6acb75039542c7e7ebdab01e47aaa7f05b9cbc4122e9c
+  metadata.gz: 68dc83310a8f0d25281d22f1d66c771c2d87a855c4802690df8ecf2e3bc74127602d405ccc4746ddf4d1495f94aa079aa3cc4668f023ca68bccec3360096b46a
+  data.tar.gz: 3fa636884d4c816a4aea7c3b34262a3f21c1d09e59c44cc8b0fde3c2bb145cdfbc26a5a9468c636d92057cfa8736906c671933e0b97f1b2ba1bafd183f21d3d5

data/README.md

@@ -1,284 +1,205 @@
 # PagePrint
 
+Fast, in-process HTML-to-PDF rendering for Ruby, powered by [PlutoBook](https://github.com/plutoprint/plutobook).
+
 > [!IMPORTANT]
-> PagePrint is not production-ready yet. The gem is still in active testing, especially around native packaging and platform compatibility.
+> PagePrint is still pre-1.0 and is not yet recommended as a drop-in production dependency without application-specific testing. Native packaging and platform compatibility are still being validated. See the [production guide](docs/production.md) before deploying it.
 
-`page_print` renders HTML strings to PDF files from Ruby using the `plutobook` library through a native C extension.
+PagePrint turns an HTML string into PDF bytes—or writes it directly to a file—through a small native C extension. It is designed for server-generated documents such as invoices, reports, labels, and statements where the HTML is known in advance and does not depend on JavaScript.
 
-It exists as a faster, simpler alternative to PDFKit and other `wkhtmltopdf`-based gems. There is no external renderer process to shell out to, and the public Ruby API is intentionally small.
 
-## Installation
+## Why PagePrint?
 
-Add PagePrint to your Gemfile:
+PDFKit and Wicked PDF render documents by launching the `wkhtmltopdf` executable. PagePrint instead embeds a purpose-built paged-media renderer in the Ruby process.
 
-```ruby
-gem "page_print"
-```
+That gives PagePrint a few useful properties:
 
-Or install from RubyGems directly:
+- **No renderer subprocess:** no executable discovery, shelling out, or process startup per render.
+- **A small Ruby API:** pass HTML in and receive PDF bytes, or write directly to a path.
+- **Print-oriented CSS:** PlutoBook supports paged-media features such as `@page`, page counters, and running headers and footers.
+- **Controlled resource loading:** PagePrint does not fetch unresolved HTTP URLs. Your application decides which stylesheets, images, and fonts may be loaded.
+- **Rails asset integration:** Propshaft and `public/assets` resources work without HTTP requests back into the application.
 
-```sh
-gem install page_print
-```
+### How does it compare with PDFKit and Wicked PDF?
 
-Native gems are published for `x86_64-linux` and `arm64-darwin`. Other platforms build from source and require PlutoBook development headers and library files.
+PDFKit and Wicked PDF are Ruby integrations for `wkhtmltopdf`; their rendering behavior and operational requirements come from that executable.
 
-## Rails Usage
+| | PagePrint / PlutoBook | PDFKit or Wicked PDF / `wkhtmltopdf` |
+| --- | --- | --- |
+| Runtime model | Native library in the Ruby process | External `wkhtmltopdf` executable |
+| Rendering engine | Purpose-built for static documents and CSS paged media | Legacy Qt WebKit browser engine |
+| JavaScript | Not supported | Supported by legacy Qt WebKit |
+| Network access | Denied unless your fetcher supplies the resource | Built in |
+| CSS compatibility | Print-focused and partial; no CSS Grid | Limited by the old WebKit engine |
+| Operational footprint | Native gem and bundled libraries on supported platforms | `wkhtmltopdf` binary plus Qt/WebKit dependencies |
+| Upstream status | PagePrint currently packages PlutoBook 0.19.0 | `wkhtmltopdf` was archived in 2023 |
 
-PagePrint is optimized for Rails applications using Propshaft. In Rails, PagePrint installs a default Propshaft-backed resource fetcher and uses the current request URL as the default `base_url`.
+PagePrint is a strong fit when you control the templates, value predictable print layout, and do not need JavaScript. Stay with a `wkhtmltopdf`-based gem if your existing templates depend on its JavaScript or WebKit-specific rendering behavior. When migrating, compare representative output carefully because changing engines can alter pagination, fonts, and layout.
 
-Render a PDF from a controller:
+The `wkhtmltopdf` project was [archived in 2023](https://github.com/wkhtmltopdf/wkhtmltopdf) and its own [status document](https://github.com/wkhtmltopdf/wkhtmltopdf/blob/master/docs/status.md) describes its Qt 4 / WebKit stack as unsupported and outdated. PlutoBook is purpose-built for static paged output, but has a narrower feature set; review its [feature matrix](https://github.com/plutoprint/plutobook/blob/main/FEATURES.md) before migrating a complex template.
+
+## Installation
+
+Add the gem to your `Gemfile`:
 
 ```ruby
-class PrintsController < ApplicationController
-  def pdf
-    html = render_to_string(template: "prints/pdf", formats: [:html], layout: "pdf")
-    pdf = PagePrint.render(
-      html,
-      page_size: :a4,
-      margins: :normal,
-      media: :print,
-      metadata: { title: "Print PDF", author: "PagePrint" }
-    )
-
-    send_data pdf, filename: "print.pdf", type: "application/pdf", disposition: "inline"
-  end
-end
+gem "page_print"
 ```
 
-Use normal Rails asset helpers in the PDF template or layout:
+Then run:
 
-```erb
-<%= stylesheet_link_tag "pdf" %>
-<%= image_tag "logo.png" %>
+```sh
+bundle install
 ```
 
-During controller actions, PagePrint defaults `base_url` to `request.base_url`. The default Rails resource fetcher resolves `/assets/...` through Propshaft or `public/assets`, avoiding HTTP requests back to the Rails app.
-
-You can still override `base_url` explicitly:
+PagePrint requires Ruby 3.2 or newer. Native gems with vendored PlutoBook libraries are published for:
 
-```ruby
-pdf = PagePrint.render(html, base_url: "https://example.com")
-```
+- `x86_64-linux`
+- `arm64-darwin` (Apple Silicon)
 
-Override the fetcher only when needed:
+Other platforms build from source and require PlutoBook development headers and libraries. See [Installing on other platforms](docs/production.md#installing-on-other-platforms).
 
-```ruby
-# config/initializers/page_print.rb
-PagePrint.configure do |config|
-  config.resource_fetcher = MyResourceFetcher.new
-end
-```
+## Quick start
 
-## Ruby Usage
+Require PagePrint and render an HTML string:
 
 ```ruby
 require "page_print"
-require "tmpdir"
 
 html = <<~HTML
+  <!doctype html>
   <html>
+    <head>
+      <meta charset="utf-8">
+      <style>
+        @page {
+          size: A4;
+
+          @bottom-center {
+            content: counter(page) " / " counter(pages);
+            color: #666;
+            font-size: 10pt;
+          }
+        }
+
+        body { font-family: sans-serif; }
+      </style>
+    </head>
     <body>
-      <h1>Hello</h1>
-      <p>This PDF was generated by PagePrint.</p>
+      <h1>Invoice #1042</h1>
+      <p>Thank you for your business.</p>
     </body>
   </html>
 HTML
 
-output_path = File.join(Dir.tmpdir, "page_print-output.pdf")
-
-PagePrint.render_to_file(html, output_path, base_url: "https://example.com")
+pdf = PagePrint.render(html, page_size: :a4, margins: :normal)
 ```
 
-To get the generated PDF as a binary string instead of writing directly to a file:
+For large documents, write directly to a file instead of retaining the PDF in a Ruby string:
 
 ```ruby
-pdf = PagePrint.render(html, base_url: "https://example.com")
+PagePrint.render_to_file(html, "invoice.pdf", page_size: :a4, margins: :normal)
 ```
 
-Use custom page dimensions and margins when a preset is not enough:
+`render_to_file` returns `true`; `render` returns an `ASCII-8BIT` Ruby string containing the PDF.
 
-```ruby
-pdf = PagePrint.render(
-  html,
-  page_size: { width: 100, height: 150, unit: :mm },
-  margins: { top: 5, right: 6, bottom: 7, left: 8, unit: :mm }
-)
-```
+## Rails
 
-You can configure default options once, for example to provide a resource fetcher used by all renders:
+PagePrint integrates automatically with Rails applications that use Propshaft. Render a template to HTML, pass it to PagePrint, then send the resulting bytes:
 
 ```ruby
-PagePrint.configure do |config|
-  config.resource_fetcher = lambda do |url|
-    next unless url == "asset:pdf.css"
+class InvoicesController < ApplicationController
+  def show
+    html = render_to_string(template: "invoices/show", formats: [:html], layout: "pdf")
+    pdf = PagePrint.render(html, page_size: :a4, margins: :normal, metadata: { title: "Invoice ##{params[:id]}", author: "Example Ltd" })
 
-    { content: "body { font-family: sans-serif; }", mime_type: "text/css" }
+    send_data pdf, filename: "invoice-#{params[:id]}.pdf", type: "application/pdf", disposition: "inline"
   end
 end
 ```
 
-## Options
-
-Supported keyword options:
-
-- `base_url:` string used to resolve relative URLs in the HTML
-- `page_size:` one of `:a3`, `:a4`, `:a5`, `:b4`, `:b5`, `:letter`, `:legal`, `:ledger`, or `{ width:, height:, unit: }`
-- `margins:` one of `:none`, `:normal`, `:narrow`, `:moderate`, `:wide`, or `{ top:, right:, bottom:, left:, unit: }`
-- `media:` one of `:print`, `:screen`
-- `resource_fetcher:` callable that receives a URL and returns `nil` or `{ content:, mime_type:, text_encoding: nil }`
-- `metadata:` hash with `:title`, `:author`, `:subject`, `:keywords`, `:creation_date`, or `:modification_date`
-
-Unresolved URLs are not fetched over the network. Provide assets through `resource_fetcher`, or return `nil` to skip a URL.
-
-`metadata[:creation_date]` and `metadata[:modification_date]` should be ISO-8601 strings, for example `2026-05-10T12:00:00Z`.
-
-Custom dimensions and margins require `unit:`. Supported units are `:pt`, `:pc`, `:in`, `:cm`, `:mm`, and `:px`.
-
-## Benchmarking
-
-```sh
-RUNS=30 WARMUPS=3 bundle exec ruby benchmark/pdf_renderers.rb
-```
-
-Measured on 2026-05-30 with Ruby 3.4.7 on Apple Silicon:
-
-| Renderer | Avg wall | P95 wall | Avg CPU | Avg peak RSS | Avg PDF |
-| --- | ---: | ---: | ---: | ---: | ---: |
-| `page_print` | 78.2ms | 89.6ms | 93.4ms | 42.1MB | 33.0KB |
-| PDFKit | 782.2ms | 2127.1ms | 824.8ms | 59.4MB | 27.9KB |
-
-For options and CSV output, see `benchmark/README.md`.
-
-## Requirements
-
-- Ruby 3.2+
-- Native gems are published for `x86_64-linux` and `arm64-darwin`.
-- Native gems vendor PlutoBook but compile the small Ruby extension during install so it links against your local Ruby.
-- Source builds on unsupported platforms require PlutoBook development headers and library files.
-
-Supported platforms:
-
-| Platform | Install Type |
-| --- | --- |
-| `x86_64-linux` | Vendored PlutoBook, local Ruby extension build |
-| `arm64-darwin` | Vendored PlutoBook, local Ruby extension build |
-| Other platforms | Source build |
-
-Source build requirements on macOS with Homebrew:
-
-```sh
-brew install plutobook pkg-config
-```
+Normal asset helpers can be used in the PDF template:
 
-If `pkg-config` cannot find `plutobook`, install the gem with explicit include and library paths:
-
-```sh
-gem install page_print -- --with-plutobook-include=/path/to/include --with-plutobook-lib=/path/to/lib
-```
-
-Native gems bundle PlutoBook and required non-system shared libraries. Optional PlutoBook features for curl, TurboJPEG, and WebP are disabled in native gems to keep the bundled dependency set smaller.
-
-## Notes
-
-- The extension supports writing to a file path with `render_to_file` or returning PDF bytes with `render`.
-- JavaScript execution is intentionally unsupported.
-- Native gems disable PlutoBook's optional curl, TurboJPEG, and WebP features.
-
-## Development
-
-Install development dependencies:
-
-```sh
-bundle install
-```
-
-Compile the native extension into `lib/page_print`:
-
-```sh
-bundle exec rake compile
+```erb
+<%= stylesheet_link_tag "pdf" %>
+<%= image_tag "logo.png", alt: "Example Ltd" %>
 ```
 
-Open an interactive Ruby session against the local checkout:
+During a controller action, PagePrint uses `request.base_url` to resolve relative URLs. Its Rails resource fetcher reads `/assets/...` from Propshaft or `public/assets`; it does not make an HTTP request back to Rails.
 
-```sh
-bundle exec irb -Ilib
-```
+## Assets and network access
 
-Then load the gem from the repo and try it:
+PagePrint intentionally does not download unresolved resources. Supply a `resource_fetcher` when non-Rails HTML needs external styles, images, or fonts:
 
 ```ruby
-require "page_print"
-require "tmpdir"
-
-output_path = File.join(Dir.tmpdir, "page_print-output.pdf")
-
-PagePrint.render_to_file("<html><body><h1>Hello</h1></body></html>", output_path, page_size: :letter, margins: :narrow, media: :screen)
-```
-
-You can also do a quick one-shot smoke test from the shell:
+assets = {
+  "asset:pdf.css" => {
+    content: File.binread("app/assets/stylesheets/pdf.css"),
+    mime_type: "text/css"
+  }
+}
 
-```sh
-bundle exec ruby -Ilib -e 'require "tmpdir"; require "page_print"; output_path = File.join(Dir.tmpdir, "page_print-output.pdf"); p PagePrint.render_to_file("<html><body><h1>Hello</h1></body></html>", output_path, page_size: :letter, margins: :narrow, media: :screen)'
-```
-
-Or use the development console, which compiles the native extension first and then starts IRB with `PagePrint` loaded:
-
-```sh
-bin/console
+pdf = PagePrint.render(
+  "<link rel=\"stylesheet\" href=\"asset:pdf.css\"><h1>Report</h1>",
+  resource_fetcher: ->(url) { assets[url] }
+)
 ```
 
-## Running Tests
-
-Run the test suite only:
+The fetcher receives each resolved URL and returns `{ content:, mime_type: }` or `nil`. Returning `nil` skips the resource. This makes resource access explicit, but it does not make untrusted HTML safe; see [Security](docs/production.md#security).
 
-```sh
-bundle exec rake test
-```
+## Configuration
 
-Or run the default rake task, which compiles the extension and then runs tests:
+The common rendering options are:
 
-```sh
-bundle exec rake
+```ruby
+PagePrint.render(
+  html,
+  base_url: "https://example.test",
+  page_size: :letter,
+  margins: :narrow,
+  media: :print,
+  metadata: { title: "Quarterly report" },
+  resource_fetcher: fetcher
+)
 ```
 
-## Local Build
+Defaults are A4 paper, normal margins, and print media. See the [configuration reference](docs/configuration.md) for every preset, custom dimensions, metadata fields, global configuration, and resource fetcher behavior.
 
-Build and install locally:
+## Performance
 
-```sh
-gem build page_print.gemspec
-gem install ./page_print-*.gem
-```
+The repository includes a reproducible benchmark against PDFKit using the same static HTML input. On May 30, 2026, the recorded run used Ruby 3.4.7 on an Apple Silicon development machine:
 
-## Releasing
+| Renderer | Average wall time | P95 wall time | Average peak RSS |
+| --- | ---: | ---: | ---: |
+| PagePrint | 78.2 ms | 89.6 ms | 42.1 MB |
+| PDFKit | 782.2 ms | 2,127.1 ms | 59.4 MB |
 
-Publish a new version with:
+These numbers are illustrative, not a capacity guarantee. Rendering cost varies significantly with fonts, images, document length, and host configuration. Run the benchmark—or your own production templates—on the deployment target before sizing infrastructure.
 
 ```sh
-bin/bump 0.1.6
+RUNS=30 WARMUPS=3 bundle exec ruby benchmark/pdf_renderers.rb
 ```
 
-That updates `lib/page_print/version.rb` and `Gemfile.lock`, commits `Release 0.1.6`, creates annotated tag `v0.1.6`, and pushes `main` plus the tag. Requires a clean worktree on `main`.
+See [benchmark/README.md](benchmark/README.md) for methodology and CSV output.
 
-The Package workflow then builds the source and platform gems, pushes them to RubyGems (trusted publishing / OIDC, GitHub environment `release`), and creates a GitHub Release with the gem artifacts and commit notes since the previous `v*` tag.
+## Documentation
 
-## Building Native Gems
+- [Configuration and API reference](docs/configuration.md)
+- [Production guide](docs/production.md)
+- [Benchmark methodology](benchmark/README.md)
+- [PlutoBook feature matrix](https://github.com/plutoprint/plutobook/blob/main/FEATURES.md)
 
-Build an `x86_64-linux` platform gem with a vendored PlutoBook library:
-
-```sh
-bundle exec rake package:linux
-```
+## Development
 
-Build an Apple Silicon macOS platform gem with a vendored PlutoBook library:
+Install dependencies, compile the extension, and run the test suite:
 
 ```sh
-bundle exec rake package:darwin_arm64
+bundle install
+bundle exec rake
 ```
 
-These tasks check out PlutoBook `v0.19.0`, build it into `lib/page_print/vendor/<platform>`, and write a platform gem to `pkg/`. Platform gems compile the Ruby extension during gem install to avoid tying the gem to the build machine's Ruby version.
+Use `bin/console` for an IRB session with the extension compiled and PagePrint loaded.
 
-Native gems bundle PlutoBook and its non-system shared library dependencies. Optional PlutoBook features for curl, TurboJPEG, and WebP are disabled to keep the bundled dependency set smaller.
+## License
 
-The packaging tasks expect PlutoBook's build dependencies to be installed on the build machine, including Meson, Ninja, pkg-config, Cairo, FreeType, HarfBuzz, Fontconfig, Expat, and ICU.
+PagePrint is available under the [MIT License](LICENSE).

data/docs/configuration.md

@@ -0,0 +1,204 @@
+# Configuration and API reference
+
+PagePrint exposes two rendering methods and a small set of keyword options.
+
+## Rendering methods
+
+### `PagePrint.render(html, **options)`
+
+Renders a non-empty HTML string and returns the PDF as an `ASCII-8BIT` Ruby string.
+
+```ruby
+pdf = PagePrint.render("<h1>Report</h1>")
+```
+
+### `PagePrint.render_to_file(html, path, **options)`
+
+Renders a non-empty HTML string directly to `path` and returns `true`. The destination directory must already exist and be writable.
+
+```ruby
+PagePrint.render_to_file("<h1>Report</h1>", "/tmp/report.pdf")
+```
+
+Writing directly to a file avoids keeping the finished PDF in a Ruby string and is preferable for large documents or background jobs.
+
+## Options
+
+Both rendering methods accept the same options.
+
+| Option | Default | Accepted values |
+| --- | --- | --- |
+| `base_url:` | `nil` outside Rails | A string or `nil` |
+| `page_size:` | `:a4` | A page preset or custom dimensions |
+| `margins:` | `:normal` | A margin preset or custom dimensions |
+| `media:` | `:print` | `:print` or `:screen` |
+| `resource_fetcher:` | Configured global fetcher or `nil` | Any callable, `nil`, or `false` |
+| `metadata:` | `nil` | A metadata hash or `nil` |
+
+Unknown options raise `ArgumentError`; values of the wrong type raise `TypeError`.
+
+### Base URL
+
+`base_url` resolves relative URLs found in the HTML:
+
+```ruby
+html = '<link rel="stylesheet" href="/assets/report.css"><h1>Report</h1>'
+PagePrint.render(html, base_url: "https://example.test", resource_fetcher: fetcher)
+```
+
+The fetcher receives `https://example.test/assets/report.css`. A base URL resolves the URL; it does not enable network access.
+
+Set an application-wide default when rendering outside Rails:
+
+```ruby
+PagePrint.configure do |config|
+  config.base_url = "https://example.test"
+end
+```
+
+An explicit `base_url:` takes precedence over the configured value.
+
+### Page size
+
+Available presets:
+
+```text
+:a3  :a4  :a5  :b4  :b5  :letter  :legal  :ledger
+```
+
+Custom dimensions require a width, height, and unit:
+
+```ruby
+PagePrint.render(
+  html,
+  page_size: { width: 100, height: 150, unit: :mm }
+)
+```
+
+Width and height must be greater than zero.
+
+### Margins
+
+Available presets:
+
+```text
+:none  :normal  :narrow  :moderate  :wide
+```
+
+Custom margins require all four sides and a unit:
+
+```ruby
+PagePrint.render(
+  html,
+  margins: { top: 5, right: 6, bottom: 7, left: 8, unit: :mm }
+)
+```
+
+Margin values must be zero or greater.
+
+Page sizes and margins support these units:
+
+```text
+:pt  :pc  :in  :cm  :mm  :px
+```
+
+### Media type
+
+Use `:print` to apply print styles and `:screen` to apply screen styles:
+
+```ruby
+PagePrint.render(html, media: :screen)
+```
+
+### PDF metadata
+
+Metadata keys and values must be symbols and strings, respectively. A value may also be `nil`.
+
+```ruby
+PagePrint.render(
+  html,
+  metadata: {
+    title: "Quarterly report",
+    author: "Example Ltd",
+    subject: "Q2 results",
+    keywords: "finance,quarterly",
+    creation_date: "2026-05-10T12:00:00Z",
+    modification_date: nil
+  }
+)
+```
+
+Supported keys are:
+
+- `:title`
+- `:author`
+- `:subject`
+- `:keywords`
+- `:creation_date`
+- `:modification_date`
+
+Use ISO 8601 strings for creation and modification dates.
+
+## Resource fetchers
+
+A resource fetcher is a callable that receives a resolved URL. It must return either `nil` or a hash containing binary `content` and its `mime_type`. `text_encoding` is optional.
+
+```ruby
+fetcher = lambda do |url|
+  case url
+  when "asset:report.css"
+    {
+      content: File.binread("app/assets/stylesheets/report.css"),
+      mime_type: "text/css",
+      text_encoding: "utf-8"
+    }
+  when "asset:logo.png"
+    {
+      content: File.binread("app/assets/images/logo.png"),
+      mime_type: "image/png"
+    }
+  end
+end
+
+PagePrint.render(html, resource_fetcher: fetcher)
+```
+
+Returning `nil` skips the URL. PagePrint does not fall back to an HTTP request. Exceptions raised by the fetcher are propagated to the caller.
+
+Configure a default fetcher for every render:
+
+```ruby
+PagePrint.configure do |config|
+  config.resource_fetcher = MyResourceFetcher.new
+end
+```
+
+Pass `resource_fetcher: false` or `nil` to disable a configured fetcher for one render.
+
+Keep fetchers narrowly scoped. Prefer an allowlist or a fixed asset map over fetching arbitrary URLs supplied by HTML.
+
+## Rails behavior
+
+When Rails is loaded, PagePrint installs two defaults:
+
+1. During controller actions, the current `request.base_url` becomes the default base URL for that request.
+2. `PagePrint::RailsResourceFetcher` resolves URLs under `/assets/` from `public/assets` or Propshaft.
+
+An explicit `base_url:` or `resource_fetcher:` still takes precedence. To replace the Rails fetcher globally:
+
+```ruby
+# config/initializers/page_print.rb
+PagePrint.configure do |config|
+  config.resource_fetcher = MyResourceFetcher.new
+end
+```
+
+The built-in Rails fetcher only handles `/assets/...` URLs. Other paths are skipped.
+
+## CSS and rendering support
+
+PagePrint delegates HTML and CSS support to PlutoBook. It supports print-oriented features including `@page`, page counters, and running headers and footers, but it is not a full web browser. JavaScript and CSS Grid are not supported.
+
+Consult the upstream [PlutoBook feature matrix](https://github.com/plutoprint/plutobook/blob/main/FEATURES.md) when designing or migrating templates. Test representative documents after every renderer or font change because pagination can change even when the HTML does not.
+
+[Back to the README](../README.md)

data/docs/production.md

@@ -0,0 +1,148 @@
+# Production guide
+
+PagePrint is pre-1.0 software. Treat adoption as an application-specific engineering decision: validate the native package, representative documents, throughput, memory use, fonts, and failure behavior on the same platform used in production.
+
+## Production readiness checklist
+
+Before deploying PagePrint:
+
+- [ ] Confirm the deployment platform has a native gem or can build PlutoBook from source.
+- [ ] Render representative short, long, image-heavy, and multilingual documents in CI.
+- [ ] Visually compare pagination, fonts, images, headers, and footers against approved fixtures.
+- [ ] Verify every stylesheet, image, and font is available through the Rails integration or an allowlisted resource fetcher.
+- [ ] Confirm templates do not depend on JavaScript, CSS Grid, or other unsupported browser features.
+- [ ] Load-test with production-sized documents and the same worker/thread configuration used in deployment.
+- [ ] Set application-level job timeouts and monitor render latency, failures, and output size.
+- [ ] Prefer `render_to_file` for large PDFs, and clean up temporary output in both success and failure paths.
+- [ ] Pin the gem version and test upgrades before rollout; renderer upgrades can alter layout and pagination.
+
+## Platform support
+
+PagePrint requires Ruby 3.2 or newer.
+
+| Platform | Installation |
+| --- | --- |
+| `x86_64-linux` | Native gem with vendored PlutoBook libraries; the Ruby extension is compiled against the local Ruby |
+| `arm64-darwin` | Native gem with vendored PlutoBook libraries; the Ruby extension is compiled against the local Ruby |
+| Other platforms | Source build using an installed PlutoBook |
+
+The published native gems disable PlutoBook's optional curl, TurboJPEG, and WebP features to keep the bundled dependency set smaller. PagePrint uses its own Ruby resource fetcher boundary and does not expose PlutoBook's optional network fetcher.
+
+Your production image still needs a compiler and Ruby development headers because the small PagePrint extension is compiled during installation.
+
+### Installing on other platforms
+
+Install PlutoBook development headers and libraries before installing the gem. On macOS with Homebrew:
+
+```sh
+brew install plutobook pkg-config
+bundle install
+```
+
+If `pkg-config` cannot find PlutoBook, provide explicit paths:
+
+```sh
+gem install page_print -- \
+  --with-plutobook-include=/path/to/include \
+  --with-plutobook-lib=/path/to/lib
+```
+
+Use equivalent Bundler build configuration in repeatable deployments:
+
+```sh
+bundle config set --local build.page_print \
+  "--with-plutobook-include=/path/to/include --with-plutobook-lib=/path/to/lib"
+bundle install
+```
+
+Run a render smoke test while building the deployment artifact, rather than only checking that the gem can be required:
+
+```sh
+bundle exec ruby -e '
+  require "page_print"
+  pdf = PagePrint.render("<h1>Deployment check</h1>")
+  abort "invalid PDF" unless pdf.start_with?("%PDF")
+'
+```
+
+## Security
+
+PagePrint's resource policy is deny-by-default: an unresolved URL is not fetched over the network. Preserve that property in custom fetchers.
+
+- Do not build a fetcher that blindly downloads arbitrary URLs. Doing so can introduce server-side request forgery (SSRF), access to cloud metadata endpoints, and unbounded downloads.
+- Prefer a fixed asset map, an application-owned URI scheme, or strict allowlists for scheme, host, path, content type, and size.
+- Do not treat PagePrint as a sandbox for hostile HTML. It parses complex input in native code and should run with the minimum filesystem and process permissions needed by the application.
+- Never place secrets in HTML, asset URLs, metadata, or error logs.
+- Validate and limit user-controlled content before inserting it into a trusted template.
+
+PagePrint's disabled network fallback improves predictability and reduces accidental outbound access, but it is not a complete security boundary.
+
+## Template compatibility
+
+PagePrint is intended for static, server-rendered documents. It does not execute JavaScript. PlutoBook supports much of CSS 3 and selected CSS 4 functionality, but important gaps include CSS Grid and some advanced visual features.
+
+Before migrating from PDFKit, `wkhtmltopdf`, or a browser renderer:
+
+1. Inventory JavaScript, layout modules, fonts, SVG, and remote assets used by the templates.
+2. Check the [PlutoBook feature matrix](https://github.com/plutoprint/plutobook/blob/main/FEATURES.md).
+3. Render a fixture set with both engines.
+4. Compare page breaks and visual output, not only whether a PDF was produced.
+
+Use explicit `@page`, print styles, and embedded or controlled fonts. Font substitution is a common cause of different line wrapping and pagination across development and production.
+
+## Assets and networking
+
+For deterministic output, package document assets with the application and return them from a resource fetcher. Avoid making rendering depend on the availability or latency of another service.
+
+Rails applications using Propshaft get a default fetcher for `/assets/...`. Outside Rails, configure a fetcher once at process startup:
+
+```ruby
+PagePrint.configure do |config|
+  config.resource_fetcher = ProductionPdfAssets.new
+end
+```
+
+See the [resource fetcher reference](configuration.md#resource-fetchers) for the callable contract.
+
+## Capacity and concurrency
+
+HTML parsing, layout, and PDF writing are native CPU- and memory-intensive work. The extension releases Ruby's Global VM Lock during PlutoBook loading and writing, but Ruby callbacks such as a custom resource fetcher run with the lock.
+
+Do not size workers from the repository benchmark alone. Measure:
+
+- latency percentiles, not only averages;
+- peak resident memory with concurrent renders;
+- the largest realistic HTML, image, and PDF sizes;
+- application behavior when a render raises or a job times out;
+- both `render` and `render_to_file` if you expect large outputs.
+
+Use bounded job concurrency. For background processing, let the job system retry only failures known to be transient; invalid templates and unsupported resources will fail repeatedly.
+
+## Failure handling
+
+PagePrint validates option types and raises Ruby exceptions for invalid input, resource fetcher failures, HTML loading failures, and PDF write failures. Treat a successful method return—and, where appropriate, a `%PDF` signature and non-zero output size—as the completion signal.
+
+When writing temporary files:
+
+```ruby
+require "tempfile"
+
+Tempfile.create(["invoice", ".pdf"]) do |file|
+  PagePrint.render_to_file(html, file.path)
+  deliver(file.path)
+end
+```
+
+Do not expose native error text directly to end users. Record enough context to identify the template and render options, without logging document contents that may contain personal or confidential data.
+
+## Upgrade strategy
+
+Pin PagePrint in the application lockfile. Before upgrading PagePrint or PlutoBook:
+
+1. Build on every production platform.
+2. Run the complete PDF fixture suite.
+3. Compare visual output and page count.
+4. Repeat a focused load test.
+5. Roll out gradually while watching latency and render failures.
+
+[Back to the README](../README.md)

data/ext/page_print/page_print.c

@@ -2,7 +2,9 @@
 #include "ruby/encoding.h"
 #include "ruby/thread.h"
 #include <limits.h>
+#include <math.h>
 #include <stdint.h>
+#include <string.h>
 #include <plutobook/plutobook.h>
 
 #if defined(__GNUC__) || defined(__clang__)
@@ -55,6 +57,7 @@ typedef struct {
 
 typedef struct {
     VALUE object;
+    VALUE error;
     int state;
 } pageprint_resource_fetcher_t;
 
@@ -66,10 +69,12 @@ typedef struct {
 
 typedef struct {
     VALUE output;
+    VALUE error;
     int state;
 } pageprint_pdf_string_output_t;
 
 typedef struct {
+    pageprint_pdf_string_output_t *owner;
     VALUE output;
     const char *data;
     unsigned int length;
@@ -102,10 +107,49 @@ typedef struct {
     VALUE metadata;
 } pageprint_apply_metadata_args_t;
 
+typedef struct {
+    plutobook_t *book;
+    VALUE html;
+    VALUE base_url;
+    VALUE resource_fetcher;
+    VALUE metadata;
+    pageprint_resource_fetcher_t resource_fetcher_state;
+} pageprint_book_context_t;
+
+typedef struct {
+    pageprint_book_context_t book_context;
+    VALUE html;
+    VALUE path;
+    VALUE options;
+} pageprint_render_to_file_context_t;
+
+typedef struct {
+    pageprint_book_context_t book_context;
+    VALUE html;
+    VALUE options;
+    pageprint_pdf_string_output_t output;
+} pageprint_render_context_t;
+
 static VALUE pageprint_append_pdf_string(VALUE value);
 static plutobook_stream_status_t pageprint_write_pdf_string(void *closure, const char *data, unsigned int length);
 static plutobook_resource_data_t *pageprint_fetch_resource(void *closure, const char *url);
 
+static void pageprint_reject_embedded_nul(VALUE value, const char *name)
+{
+    if (memchr(RSTRING_PTR(value), '\0', (size_t)RSTRING_LEN(value))) {
+        rb_raise(rb_eArgError, "%s must not contain NUL bytes", name);
+    }
+}
+
+static VALUE pageprint_frozen_string_copy(VALUE value)
+{
+    VALUE copy = rb_str_dup(value);
+
+    rb_obj_freeze(copy);
+
+    return copy;
+}
+
 static void PAGEPRINT_NORETURN pageprint_raise_plutobook_error(VALUE error_class, const char *message)
 {
     const char *error_message = plutobook_get_error_message();
@@ -128,6 +172,12 @@ static void PAGEPRINT_NORETURN pageprint_raise_plutobook_error_with_path(VALUE e
     rb_raise(error_class, "%s %s", message, path);
 }
 
+static void PAGEPRINT_NORETURN pageprint_jump_callback_error(int state, VALUE error)
+{
+    rb_set_errinfo(error);
+    rb_jump_tag(state);
+}
+
 static double pageprint_unit_factor_from_value(VALUE value, const char *name)
 {
     ID value_id;
@@ -175,6 +225,14 @@ static plutobook_page_size_t pageprint_page_size_from_value(VALUE value)
         width_number = NUM2DBL(width);
         height_number = NUM2DBL(height);
 
+        if (!isfinite(width_number)) {
+            rb_raise(rb_eArgError, "page_size width must be finite");
+        }
+
+        if (!isfinite(height_number)) {
+            rb_raise(rb_eArgError, "page_size height must be finite");
+        }
+
         if (width_number <= 0) {
             rb_raise(rb_eArgError, "page_size width must be greater than 0");
         }
@@ -247,6 +305,10 @@ static plutobook_page_margins_t pageprint_margins_from_value(VALUE value)
         bottom_number = NUM2DBL(bottom);
         left_number = NUM2DBL(left);
 
+        if (!isfinite(top_number) || !isfinite(right_number) || !isfinite(bottom_number) || !isfinite(left_number)) {
+            rb_raise(rb_eArgError, "margins values must be finite");
+        }
+
         if (top_number < 0 || right_number < 0 || bottom_number < 0 || left_number < 0) {
             rb_raise(rb_eArgError, "margins values must be greater than or equal to 0");
         }
@@ -410,11 +472,17 @@ static void *pageprint_write_pdf_without_gvl(void *ptr)
 static void *pageprint_append_pdf_string_with_gvl(void *ptr)
 {
     pageprint_pdf_string_append_t *append = ptr;
+    pageprint_pdf_string_output_t *output = append->owner;
     int state = 0;
 
     rb_protect(pageprint_append_pdf_string, (VALUE)append, &state);
 
-    return (void *)(intptr_t)state;
+    if (state && !output->state) {
+        output->state = state;
+        output->error = rb_errinfo();
+    }
+
+    return NULL;
 }
 
 static void *pageprint_write_pdf_stream_without_gvl(void *ptr)
@@ -492,24 +560,31 @@ static void *pageprint_call_resource_fetcher_with_gvl(void *ptr)
 
     rb_protect(pageprint_call_resource_fetcher, (VALUE)args, &state);
 
-    return (void *)(intptr_t)state;
+    if (state && !args->fetcher->state) {
+        args->fetcher->state = state;
+        args->fetcher->error = rb_errinfo();
+    }
+
+    return NULL;
 }
 
 static plutobook_resource_data_t *pageprint_fetch_resource(void *closure, const char *url)
 {
     pageprint_resource_fetcher_t *fetcher = closure;
     pageprint_resource_fetch_args_t args;
-    int state;
+
+    if (fetcher->state) {
+        return NULL;
+    }
 
     if (!NIL_P(fetcher->object)) {
         args.fetcher = fetcher;
         args.url = url;
         args.resource = NULL;
 
-        state = (int)(intptr_t)rb_thread_call_with_gvl(pageprint_call_resource_fetcher_with_gvl, &args);
+        rb_thread_call_with_gvl(pageprint_call_resource_fetcher_with_gvl, &args);
 
-        if (state) {
-            fetcher->state = state;
+        if (fetcher->state) {
             plutobook_set_error_message("failed to fetch URL '%s'", url);
             return NULL;
         }
@@ -608,15 +683,11 @@ static pageprint_options_t pageprint_options_from_value(VALUE options)
     return result;
 }
 
-static plutobook_t *pageprint_create_book_from_html(VALUE html, VALUE options, pageprint_resource_fetcher_t *resource_fetcher)
+static void pageprint_create_book_from_html(VALUE html, VALUE options, pageprint_book_context_t *context)
 {
     pageprint_options_t pageprint_options;
-
-    const char *html_str;
     const char *base_url_str;
     long html_len;
-
-    plutobook_t *book;
     pageprint_load_html_args_t load_args;
 
     if (!RB_TYPE_P(html, T_STRING)) {
@@ -631,45 +702,49 @@ static plutobook_t *pageprint_create_book_from_html(VALUE html, VALUE options, p
         rb_raise(rb_eArgError, "html is too large");
     }
 
+    pageprint_reject_embedded_nul(html, "html");
     pageprint_options = pageprint_options_from_value(options);
+    context->html = pageprint_frozen_string_copy(html);
+    context->base_url = Qnil;
+    context->resource_fetcher = pageprint_options.resource_fetcher;
+    context->metadata = pageprint_options.metadata;
+
+    if (!NIL_P(pageprint_options.base_url)) {
+        pageprint_reject_embedded_nul(pageprint_options.base_url, "base_url");
+        context->base_url = pageprint_frozen_string_copy(pageprint_options.base_url);
+    }
 
-    html_str = RSTRING_PTR(html);
-    html_len = RSTRING_LEN(html);
+    html_len = RSTRING_LEN(context->html);
 
     /* 1. Create */
-    book = plutobook_create(pageprint_options.page_size, pageprint_options.margins, pageprint_options.media);
+    context->book = plutobook_create(pageprint_options.page_size, pageprint_options.margins, pageprint_options.media);
 
-    if (!book) {
+    if (!context->book) {
         rb_raise(rb_eRuntimeError, "failed to create plutobook");
     }
 
-    resource_fetcher->object = pageprint_options.resource_fetcher;
-    resource_fetcher->state = 0;
+    context->resource_fetcher_state.object = context->resource_fetcher;
+    context->resource_fetcher_state.error = Qnil;
+    context->resource_fetcher_state.state = 0;
 
-    plutobook_set_custom_resource_fetcher(book, pageprint_fetch_resource, resource_fetcher);
+    plutobook_set_custom_resource_fetcher(context->book, pageprint_fetch_resource, &context->resource_fetcher_state);
 
     /* 2. Load HTML */
     plutobook_clear_error_message();
 
     base_url_str = "";
-    if (!NIL_P(pageprint_options.base_url)) {
-        base_url_str = StringValueCStr(pageprint_options.base_url);
+    if (!NIL_P(context->base_url)) {
+        base_url_str = RSTRING_PTR(context->base_url);
     }
 
-    load_args.book = book;
-    load_args.html = html_str;
+    load_args.book = context->book;
+    load_args.html = RSTRING_PTR(context->html);
     load_args.length = (int)html_len;
     load_args.user_style = "";
     load_args.user_script = "";
     load_args.base_url = base_url_str;
     load_args.ok = 0;
 
-    RB_GC_GUARD(html);
-    RB_GC_GUARD(options);
-    RB_GC_GUARD(pageprint_options.base_url);
-    RB_GC_GUARD(pageprint_options.resource_fetcher);
-    RB_GC_GUARD(pageprint_options.metadata);
-
     rb_thread_call_without_gvl(
         pageprint_load_html_without_gvl,
         &load_args,
@@ -677,37 +752,41 @@ static plutobook_t *pageprint_create_book_from_html(VALUE html, VALUE options, p
         NULL
     );
 
-    if (!load_args.ok) {
-        plutobook_destroy(book);
+    RB_GC_GUARD(context->html);
+    RB_GC_GUARD(context->base_url);
 
-        if (resource_fetcher->state) {
-            rb_jump_tag(resource_fetcher->state);
+    if (!load_args.ok) {
+        if (context->resource_fetcher_state.state) {
+            pageprint_jump_callback_error(
+                context->resource_fetcher_state.state,
+                context->resource_fetcher_state.error
+            );
         }
 
         pageprint_raise_plutobook_error(rb_eRuntimeError, "failed to load HTML into plutobook");
     }
 
-    if (resource_fetcher->state) {
-        plutobook_destroy(book);
-        rb_jump_tag(resource_fetcher->state);
+    if (context->resource_fetcher_state.state) {
+        pageprint_jump_callback_error(
+            context->resource_fetcher_state.state,
+            context->resource_fetcher_state.error
+        );
     }
 
     {
         pageprint_apply_metadata_args_t metadata_args;
         int metadata_state = 0;
 
-        metadata_args.book = book;
-        metadata_args.metadata = pageprint_options.metadata;
+        metadata_args.book = context->book;
+        metadata_args.metadata = context->metadata;
 
         rb_protect(pageprint_apply_metadata_with_gvl, (VALUE)&metadata_args, &metadata_state);
+        RB_GC_GUARD(context->metadata);
 
         if (metadata_state) {
-            plutobook_destroy(book);
             rb_jump_tag(metadata_state);
         }
     }
-
-    return book;
 }
 
 static VALUE pageprint_append_pdf_string(VALUE value)
@@ -723,62 +802,54 @@ static plutobook_stream_status_t pageprint_write_pdf_string(void *closure, const
 {
     pageprint_pdf_string_output_t *output = closure;
     pageprint_pdf_string_append_t append;
-    int state;
 
+    if (output->state) {
+        return PLUTOBOOK_STREAM_STATUS_WRITE_ERROR;
+    }
+
+    append.owner = output;
     append.output = output->output;
     append.data = data;
     append.length = length;
 
-    state = (int)(intptr_t)rb_thread_call_with_gvl(pageprint_append_pdf_string_with_gvl, &append);
+    rb_thread_call_with_gvl(pageprint_append_pdf_string_with_gvl, &append);
 
-    if (state) {
-        output->state = state;
+    if (output->state) {
         return PLUTOBOOK_STREAM_STATUS_WRITE_ERROR;
     }
 
     return PLUTOBOOK_STREAM_STATUS_SUCCESS;
 }
 
-static VALUE pageprint_render_to_file(int argc, VALUE *argv, VALUE self) {
-    VALUE html;
-    VALUE path;
-    VALUE options;
-
-    const char *path_str;
-
-    plutobook_t *book;
-    pageprint_resource_fetcher_t resource_fetcher;
-    pageprint_write_pdf_args_t write_args;
-
-    rb_check_arity(argc, 2, 3);
+static VALUE pageprint_destroy_book(VALUE value)
+{
+    pageprint_book_context_t *context = (pageprint_book_context_t *)value;
+    plutobook_t *book = context->book;
 
-    html = argv[0];
-    path = argv[1];
-    options = argc == 3 ? argv[2] : Qnil;
+    context->book = NULL;
 
-    if (!RB_TYPE_P(path, T_STRING)) {
-        rb_raise(rb_eTypeError, "path must be a String");
+    if (book) {
+        plutobook_destroy(book);
     }
 
-    if (RSTRING_LEN(path) == 0) {
-        rb_raise(rb_eArgError, "path must not be empty");
-    }
+    return Qnil;
+}
 
-    path_str = StringValueCStr(path);
+static VALUE pageprint_render_to_file_body(VALUE value)
+{
+    pageprint_render_to_file_context_t *context = (pageprint_render_to_file_context_t *)value;
+    const char *path_str;
+    pageprint_write_pdf_args_t write_args;
 
-    book = pageprint_create_book_from_html(html, options, &resource_fetcher);
+    pageprint_create_book_from_html(context->html, context->options, &context->book_context);
+    path_str = RSTRING_PTR(context->path);
 
     plutobook_clear_error_message();
 
-    write_args.book = book;
+    write_args.book = context->book_context.book;
     write_args.path = path_str;
     write_args.ok = 0;
 
-    RB_GC_GUARD(html);
-    RB_GC_GUARD(options);
-    RB_GC_GUARD(resource_fetcher.object);
-    RB_GC_GUARD(path);
-
     rb_thread_call_without_gvl(
         pageprint_write_pdf_without_gvl,
         &write_args,
@@ -786,10 +857,17 @@ static VALUE pageprint_render_to_file(int argc, VALUE *argv, VALUE self) {
         NULL
     );
 
-    plutobook_destroy(book);
+    RB_GC_GUARD(context->path);
+    RB_GC_GUARD(context->book_context.resource_fetcher);
+    RB_GC_GUARD(context->book_context.resource_fetcher_state.error);
+    RB_GC_GUARD(context->html);
+    RB_GC_GUARD(context->options);
 
-    if (resource_fetcher.state) {
-        rb_jump_tag(resource_fetcher.state);
+    if (context->book_context.resource_fetcher_state.state) {
+        pageprint_jump_callback_error(
+            context->book_context.resource_fetcher_state.state,
+            context->book_context.resource_fetcher_state.error
+        );
     }
 
     if (!write_args.ok) {
@@ -799,36 +877,42 @@ static VALUE pageprint_render_to_file(int argc, VALUE *argv, VALUE self) {
     return Qtrue;
 }
 
-static VALUE pageprint_render(int argc, VALUE *argv, VALUE self) {
-    VALUE html;
-    VALUE options;
-    pageprint_pdf_string_output_t output;
+static VALUE pageprint_render_to_file(int argc, VALUE *argv, VALUE self)
+{
+    pageprint_render_to_file_context_t context = { 0 };
 
-    plutobook_t *book;
-    pageprint_resource_fetcher_t resource_fetcher;
-    pageprint_write_pdf_stream_args_t write_args;
+    rb_check_arity(argc, 2, 3);
 
-    rb_check_arity(argc, 1, 2);
+    context.html = argv[0];
+    context.options = argc == 3 ? argv[2] : Qnil;
+
+    if (!RB_TYPE_P(argv[1], T_STRING)) {
+        rb_raise(rb_eTypeError, "path must be a String");
+    }
+
+    if (RSTRING_LEN(argv[1]) == 0) {
+        rb_raise(rb_eArgError, "path must not be empty");
+    }
+
+    pageprint_reject_embedded_nul(argv[1], "path");
+    context.path = pageprint_frozen_string_copy(argv[1]);
 
-    html = argv[0];
-    options = argc == 2 ? argv[1] : Qnil;
-    output.output = rb_str_new(NULL, 0);
-    output.state = 0;
-    rb_enc_associate_index(output.output, rb_ascii8bit_encindex());
+    return rb_ensure(pageprint_render_to_file_body, (VALUE)&context, pageprint_destroy_book, (VALUE)&context.book_context);
+}
+
+static VALUE pageprint_render_body(VALUE value)
+{
+    pageprint_render_context_t *context = (pageprint_render_context_t *)value;
+    pageprint_write_pdf_stream_args_t write_args;
 
-    book = pageprint_create_book_from_html(html, options, &resource_fetcher);
+    pageprint_create_book_from_html(context->html, context->options, &context->book_context);
 
     plutobook_clear_error_message();
 
-    write_args.book = book;
-    write_args.output = &output;
+    write_args.book = context->book_context.book;
+    write_args.output = &context->output;
     write_args.ok = 0;
 
-    RB_GC_GUARD(html);
-    RB_GC_GUARD(options);
-    RB_GC_GUARD(resource_fetcher.object);
-    RB_GC_GUARD(output.output);
-
     rb_thread_call_without_gvl(
         pageprint_write_pdf_stream_without_gvl,
         &write_args,
@@ -836,21 +920,45 @@ static VALUE pageprint_render(int argc, VALUE *argv, VALUE self) {
         NULL
     );
 
-    plutobook_destroy(book);
-
-    if (resource_fetcher.state) {
-        rb_jump_tag(resource_fetcher.state);
+    RB_GC_GUARD(context->book_context.resource_fetcher);
+    RB_GC_GUARD(context->book_context.resource_fetcher_state.error);
+    RB_GC_GUARD(context->output.output);
+    RB_GC_GUARD(context->output.error);
+    RB_GC_GUARD(context->html);
+    RB_GC_GUARD(context->options);
+
+    if (context->book_context.resource_fetcher_state.state) {
+        pageprint_jump_callback_error(
+            context->book_context.resource_fetcher_state.state,
+            context->book_context.resource_fetcher_state.error
+        );
     }
 
-    if (output.state) {
-        rb_jump_tag(output.state);
+    if (context->output.state) {
+        pageprint_jump_callback_error(context->output.state, context->output.error);
     }
 
     if (!write_args.ok) {
         pageprint_raise_plutobook_error(rb_eRuntimeError, "failed to write PDF to string");
     }
 
-    return output.output;
+    return context->output.output;
+}
+
+static VALUE pageprint_render(int argc, VALUE *argv, VALUE self)
+{
+    pageprint_render_context_t context = { 0 };
+
+    rb_check_arity(argc, 1, 2);
+
+    context.html = argv[0];
+    context.options = argc == 2 ? argv[1] : Qnil;
+    context.output.output = rb_str_new(NULL, 0);
+    context.output.error = Qnil;
+    context.output.state = 0;
+    rb_enc_associate_index(context.output.output, rb_ascii8bit_encindex());
+
+    return rb_ensure(pageprint_render_body, (VALUE)&context, pageprint_destroy_book, (VALUE)&context.book_context);
 }
 
 void Init_page_print(void) {

data/lib/page_print/rails_resource_fetcher.rb

@@ -45,11 +45,14 @@ module PagePrint
       return unless public_path
 
       relative_path = path.delete_prefix('/')
-      file_path = public_path.join(relative_path).cleanpath
+      public_path = public_path.realpath
+      file_path = public_path.join(relative_path).realpath
       return unless inside_path?(file_path, public_path)
       return unless file_path.file?
 
       resource(File.binread(file_path), file_path.extname)
+    rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+      nil
     end
 
     def read_resolved_asset(path)

data/lib/page_print/version.rb

@@ -1,3 +1,3 @@
 module PagePrint
-  VERSION = '0.1.9'
+  VERSION = '0.1.10'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: page_print
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.1.10
 platform: ruby
 authors:
 - Dino Maric
@@ -20,6 +20,8 @@ extra_rdoc_files: []
 files:
 - LICENSE
 - README.md
+- docs/configuration.md
+- docs/production.md
 - ext/page_print/extconf.rb
 - ext/page_print/page_print.c
 - lib/page_print.rb