weasy_pdf 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 7ce26a8ece90c530b6b5066c8b472213772024754487d1c499eaa176ea998303
+  data.tar.gz: f67004ea643989f581f5247016e4f324629fa6a250f02cc2cd2075ee119d74cf
+SHA512:
+  metadata.gz: da3107e0b8a6d0b35f2217f4c96bf2ec412a8a6616de8b0d1c93fac805e92d6fbab6f902ba14e09f4745d2c5acae9bfa25c9c057f630464e04e9d5fbc2c2f080
+  data.tar.gz: 274b8f9f21837733e59926205339b19a8196595d07a1708d4f510c68564d0801d202e846b15a8a9b6a96f4adda8a29a6caa783f07b83024772d01f6795b0af90

data/CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-18
+
+### Added
+
+- Initial release — drop-in replacement for Wicked PDF using WeasyPrint as backend
+- `WeasyPDF.new` shortcut for direct instantiation; `WeasyPDF::Renderer` for explicit usage
+- `WeasyPDF::Renderer` generates PDFs from HTML strings, files, and URLs
+- Native vite_ruby support: CDN in production, inlined CSS in development, disk-read in CI
+- Automatic Rails integration via Railtie (no ApplicationController changes needed)
+- Rack middleware `WeasyPDF::Middleware` for transparent `.pdf` URL conversion
+- `[page]`/`[topage]` token mapping to CSS `counter(page)`/`counter(pages)`
+- Configuration via `WeasyPDF.configure` with `attr_accessor` + hash-style `[]`/`[]=`
+- All wkhtmltopdf-only options accepted silently for zero-friction migration
+- `weasy_pdf_stylesheet_link_tag`, `weasy_pdf_image_tag`, `weasy_pdf_asset_path`,
+  `weasy_pdf_asset_base64`, `weasy_pdf_url_base64` view helpers
+- `header:`/`footer:` with `:left`/`:center`/`:right` text via CSS `@page` margin boxes
+- `header: { html: ... }` raises `WeasyPDF::Error` immediately with a migration hint
+
+### Development tooling
+
+- StandardRB for linting (zero-config)
+- SimpleCov with branch coverage (`bundle exec rake test` reports it)
+- RBS signatures for `WeasyPDF`, `Renderer`, `Configuration` (sig/)
+- CI matrix: Ruby 3.2/3.3/3.4 × Rails 7.1/7.2/8.0/8.1
+- `bin/console` for interactive gem development
+
+### Not included (intentional divergence from Wicked PDF)
+
+- JavaScript helpers (`wicked_pdf_javascript_*`) — WeasyPrint does not execute JS
+- Webpacker/Shakapacker pack helpers — no `*_pack_tag` equivalents
+- HTML template headers/footers — not possible via WeasyPrint CLI; raises with a clear error
+- `ostruct` runtime dependency — uses `attr_accessor` instead

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diego Enjamio
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,281 @@
+# weasy_pdf
+
+Generate PDFs from Rails views using [WeasyPrint](https://weasyprint.org/) — modern CSS, no JavaScript, no Chromium.
+
+```ruby
+gem 'weasy_pdf'
+```
+
+> Migrating from `wicked_pdf`? Jump to [Migration](#migration-from-wicked-pdf) — typically a one-line Gemfile change plus a `sed` over your views.
+
+## Requirements
+
+- Ruby >= 3.2
+- Rails >= 7.1
+- WeasyPrint installed on the system:
+
+```bash
+apt install weasyprint    # Debian/Ubuntu
+brew install weasyprint   # macOS
+pip install weasyprint    # latest version
+```
+
+## Quick start
+
+```ruby
+class InvoicesController < ApplicationController
+  def show
+    @invoice = Invoice.find(params[:id])
+    render pdf: "invoice_#{@invoice.number}", template: 'invoices/show'
+  end
+end
+```
+
+No initializer, no `ApplicationController` changes — the Railtie wires everything automatically.
+
+## Configuration
+
+Optional — sensible defaults are used if you skip this:
+
+```ruby
+# config/initializers/weasy_pdf.rb
+WeasyPDF.configure do |config|
+  config.default_options = {
+    page_size:   'A4',
+    margin_top:  '15mm',
+    media_type:  'print',
+  }
+
+  # base_url prepends to relative URLs in the rendered HTML when no asset
+  # can be resolved from disk. Useful in development.
+  config.base_url = Rails.env.development? ? 'http://localhost:3000' : nil
+
+  config.timeout = 60
+end
+```
+
+## Usage
+
+### Controllers
+
+```ruby
+render pdf:       'invoice',
+       template:  'invoices/show',
+       layout:    'pdf',
+       page_size: 'A4',
+       margin:    { top: 15, bottom: 15 },
+       header:    { right: '[page] of [topage]', font_size: 9 },
+       show_as_html: params.key?('debug')
+```
+
+### Jobs / Mailers
+
+```ruby
+pdf = render_to_string pdf: 'invoice', template: 'invoices/show', layout: 'pdf'
+```
+
+### Direct instantiation
+
+```ruby
+WeasyPDF.new.pdf_from_string('<h1>Hello</h1>')
+WeasyPDF.new.pdf_from_html_file('/path/to/file.html')
+WeasyPDF.new.pdf_from_url('https://example.com')
+```
+
+### PDF layout
+
+```erb
+<!DOCTYPE html>
+<html>
+  <head>
+    <%= weasy_pdf_stylesheet_link_tag 'pdf' %>
+  </head>
+  <body>
+    <%= weasy_pdf_image_tag 'logo.png', width: 150 %>
+    <%= yield %>
+  </body>
+</html>
+```
+
+## Asset helpers
+
+```erb
+<%= weasy_pdf_stylesheet_link_tag 'pdf' %>
+<%= weasy_pdf_image_tag 'logo.png', width: 150 %>
+<%= weasy_pdf_asset_path 'logo.png' %>
+<%= weasy_pdf_asset_base64 'logo.png' %>
+<%= weasy_pdf_url_base64 'https://example.com/img.png' %>
+```
+
+## Asset support
+
+**Vite-first** (auto-detected when `vite_ruby` is present) with fallback to precompiled assets from `public/`.
+
+Each asset is resolved in this order:
+
+1. **Vite manifest** (if `vite_ruby` loaded):
+
+   | Environment | Behavior |
+   |---|---|
+   | Production CDN | `<link href="https://cdn.../pdf-abc.css">` — WeasyPrint downloads it |
+   | Dev + Vite server running | Inlines CSS via HTTP from localhost:5173 |
+   | No Vite server (CI/test) | Reads from `public/vite/assets/` |
+
+2. **Disk fallback** — searches `public/vite/assets/`, `public/assets/`, `public/`.
+3. **`base_url` fallback** — prepends `base_url` to the asset path.
+4. **Returns input unchanged** — logs a warning so misconfigurations are visible.
+
+## Headers and footers
+
+CSS `@page` margin boxes — text and counters only:
+
+```ruby
+render pdf:    'report',
+       header: { left: 'Acme', center: 'Confidential', right: '[page] of [topage]' },
+       footer: { center: '[page]', font_size: 8 }
+```
+
+| Token | CSS output |
+|---|---|
+| `[page]` | `counter(page)` |
+| `[topage]` | `counter(pages)` |
+| `[section]`, `[title]`, `[date]`, `[time]`, `[webpage]` | Removed — no CSS equivalent |
+
+For complex headers (logos, styled HTML), use [WeasyPrint running elements](https://weasyprint.readthedocs.io/en/stable/tutorial.html#headers-and-footers):
+
+```css
+.pdf-header { position: running(header); }
+@page { @top-center { content: element(header); } }
+```
+
+```erb
+<div class="pdf-header">
+  <img src="<%= weasy_pdf_asset_path('logo.png') %>" height="30">
+  <span>Invoice #<%= @invoice.number %></span>
+</div>
+```
+
+## Page sizes and orientation
+
+`page_size:` accepts any [CSS Paged Media](https://www.w3.org/TR/css-page-3/#page-size-prop) keyword:
+
+| Family | Sizes |
+|---|---|
+| ISO A | `A0` … `A10` (default: **A4**) |
+| ISO B | `B0` … `B10` |
+| ISO C | `C0` … `C10` |
+| US | `Letter`, `Legal`, `Ledger` |
+| JIS | `JIS-B0` … `JIS-B5` |
+
+Custom dimensions (numbers default to mm; strings pass through):
+
+```ruby
+render pdf: 'receipt', page_width: 80, page_height: 200            # 80mm × 200mm
+render pdf: 'badge',   page_width: '4in', page_height: '6in'        # any CSS unit
+```
+
+Orientation:
+
+```ruby
+render pdf: 'report', page_size: 'A4', orientation: 'Landscape'
+```
+
+`page_width` / `page_height` take precedence over `page_size` / `orientation`.
+
+## Rack Middleware
+
+```ruby
+# config/application.rb
+config.middleware.use WeasyPDF::Middleware
+config.middleware.use WeasyPDF::Middleware, { page_size: 'A4' }, only: [/^\/invoices/]
+```
+
+Requests to `/invoices/1.pdf` are transparently rendered as PDF.
+
+## Limitations
+
+| | |
+|---|---|
+| JavaScript execution | Not supported — WeasyPrint is JS-free. Render server-side first. |
+| HTML template headers/footers | Not supported — raises `WeasyPDF::Error` pointing to running elements |
+| Webpacker / Shakapacker `*_pack_tag` helpers | Not supported — no equivalents |
+| `pdf_from_url` | Basic HTTP only — no auth, no JS rendering |
+| `outline`, `dpi`, `proxy`, `cookie`, `extra` | Accepted silently (migration compat), not passed to WeasyPrint |
+
+## Migration from Wicked PDF
+
+> Not migrating from `wicked_pdf`? You can stop reading here.
+
+### Why migrate
+
+| | wicked_pdf | weasy_pdf |
+|---|---|---|
+| Backend | wkhtmltopdf (archived 2023) | WeasyPrint (active) |
+| CSS engine | WebKit 2013 — no flexbox/grid | Modern CSS |
+| RAM per worker | ~75–200MB + known leaks | ~35–80MB, clean exit |
+| Vite | Manual workarounds | Native (auto-detected) |
+| Runtime deps | `activesupport`, `ostruct` | `activesupport` |
+
+### Steps
+
+**1. Gemfile**
+
+```diff
+- gem 'wicked_pdf'
+- gem 'wkhtmltopdf-binary'
++ gem 'weasy_pdf'
+```
+
+**2. Initializer**
+
+```bash
+mv config/initializers/wicked_pdf.rb config/initializers/weasy_pdf.rb
+sed -i 's/WickedPdf/WeasyPDF/g' config/initializers/weasy_pdf.rb
+```
+
+**3. Bulk-rename helpers in views**
+
+```bash
+find app/views -name '*.erb' | xargs sed -i 's/wicked_pdf_/weasy_pdf_/g'
+```
+
+**4. Delete dead helper calls**
+
+After step 3 your views may contain `weasy_pdf_javascript_*` or `weasy_pdf_*_pack_tag` calls
+that **don't exist** in weasy_pdf and would raise `NoMethodError` at render time:
+
+```bash
+grep -rE 'weasy_pdf_(javascript_|.*_pack_)' app/views
+```
+
+WeasyPrint doesn't execute JavaScript and Webpacker isn't supported — removing them is correct.
+
+**5. HTML template headers**
+
+`header: { html: { template: ... } }` now raises `WeasyPDF::Error` with a migration hint.
+Replace with [running elements](#headers-and-footers).
+
+**6. Controllers — no changes**
+
+`render pdf:`, `render_to_string pdf:`, all PDF options work identically.
+
+**7. Dockerfile**
+
+```dockerfile
+RUN apt-get update && apt-get install -y --no-install-recommends \
+      weasyprint fonts-dejavu-core fonts-liberation \
+    && rm -rf /var/lib/apt/lists/*
+```
+
+### Performance differences
+
+Neither backend is universally faster — pick by workload:
+
+- **Long-running Sidekiq workers** → weasy_pdf (no RAM leaks)
+- **High-concurrency web requests** → weasy_pdf (lower per-process RAM)
+- **Documents using flexbox / grid / modern CSS** → weasy_pdf (wkhtmltopdf can't render them)
+- **One-shot CLI on simple HTML** → roughly comparable, document complexity dominates
+
+## License
+
+MIT

data/lib/weasy_pdf/command_builder.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module WeasyPDF
+  # Pure value transformation: binary + resolved options → shell command Array.
+  # No global state — callers resolve configuration (base_url, etc.) before
+  # passing options in, so this class is testable without WeasyPDF.configuration.
+  class CommandBuilder
+    def initialize(binary, options = {})
+      @binary = binary
+      @options = options
+    end
+
+    def build(input_path, output_path)
+      cmd = [@binary]
+      cmd += ["--encoding", @options[:encoding]] if @options[:encoding]
+      cmd += ["--zoom", @options[:zoom].to_s] if @options[:zoom] && @options[:zoom] != 1
+      cmd += ["--media-type", @options[:media_type]] if @options[:media_type]
+      cmd += ["--base-url", @options[:base_url].to_s] if @options[:base_url]
+      Array(@options[:stylesheets]).each { |s| cmd += ["--stylesheet", s] }
+      cmd + [input_path, output_path]
+    end
+  end
+end

data/lib/weasy_pdf/configuration.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module WeasyPDF
+  class Configuration
+    DEFAULTS = {
+      page_size: "A4",
+      orientation: "Portrait",
+      margin_top: "10mm",
+      margin_bottom: "10mm",
+      margin_left: "10mm",
+      margin_right: "10mm",
+      encoding: "utf-8",
+      zoom: 1,
+      media_type: "print" # WeasyPrint defaults to 'screen'; 'print' activates @media print rules
+    }.freeze
+
+    BINARY_CANDIDATES = %w[
+      /usr/local/bin/weasyprint
+      /usr/bin/weasyprint
+      /opt/weasyprint/bin/weasyprint
+      /opt/homebrew/bin/weasyprint
+    ].freeze
+
+    attr_accessor :exe_path, :default_options, :base_url, :timeout, :temp_path
+
+    def initialize
+      @exe_path = find_binary
+      @default_options = DEFAULTS.dup
+      @base_url = nil
+      @timeout = 60
+      @temp_path = default_temp_path
+    end
+
+    def [](key)
+      public_send(key)
+    end
+
+    def []=(key, value)
+      public_send(:"#{key}=", value)
+    end
+
+    private
+
+    def find_binary
+      BINARY_CANDIDATES.each { |path| return path if File.executable?(path) }
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |dir|
+        full = File.join(dir, "weasyprint")
+        return full if File.executable?(full)
+      end
+      "weasyprint"
+    end
+
+    def default_temp_path
+      if defined?(Rails)
+        Rails.root.join("tmp", "weasy_pdf")
+      else
+        require "pathname"
+        Pathname.new("/tmp/weasy_pdf")
+      end
+    end
+  end
+end

data/lib/weasy_pdf/middleware.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module WeasyPDF
+  # Rack middleware that converts HTML responses to PDF when the URL ends in .pdf.
+  #
+  # Usage in config/application.rb:
+  #   config.middleware.use WeasyPDF::Middleware
+  #   config.middleware.use WeasyPDF::Middleware, { page_size: 'A4' }, { only: [/^\/invoices/] }
+  class Middleware
+    def initialize(app, options = {}, conditions = {})
+      @app = app
+      @options = options
+      @conditions = conditions
+    end
+
+    def call(env)
+      request = Rack::Request.new(env)
+      render_as_pdf?(request) ? serve_pdf(env, request) : @app.call(env)
+    end
+
+    private
+
+    def render_as_pdf?(request)
+      request.path.end_with?(".pdf") && path_allowed?(request.path)
+    end
+
+    def path_allowed?(path)
+      if @conditions[:only]
+        Array(@conditions[:only]).any? { |pattern| path.match?(pattern) }
+      elsif @conditions[:except]
+        Array(@conditions[:except]).none? { |pattern| path.match?(pattern) }
+      else
+        true
+      end
+    end
+
+    def serve_pdf(env, request)
+      html_env = env.merge(
+        "PATH_INFO" => request.path.sub(/\.pdf\z/, ""),
+        "HTTP_ACCEPT" => "text/html",
+        "QUERY_STRING" => request.query_string
+      )
+
+      status, headers, body = @app.call(html_env)
+      return [status, headers, body] unless status == 200
+
+      html = body.respond_to?(:body) ? body.body : body.join
+
+      begin
+        pdf = WeasyPDF::Renderer.new(@options).pdf_from_string(html)
+        [
+          200,
+          {
+            "Content-Type" => "application/pdf",
+            "Content-Disposition" => "inline; filename=\"#{pdf_filename(request.path)}\"",
+            "Content-Length" => pdf.bytesize.to_s
+          },
+          [pdf]
+        ]
+      rescue WeasyPDF::Error => e
+        [500, {"Content-Type" => "text/plain"}, ["WeasyPDF error: #{e.message}"]]
+      end
+    end
+
+    def pdf_filename(path)
+      "#{File.basename(path, ".pdf")}.pdf"
+    end
+  end
+end

data/lib/weasy_pdf/pdf_helper.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module WeasyPDF
+  module PdfHelper
+    def self.prepended(base)
+      # Guard prevents after_action from being registered twice when PdfHelper
+      # is prepended to both ActionController::Base and a concrete subclass.
+      return unless base == ActionController::Base
+
+      base.class_eval do
+        after_action :clean_temp_files
+      end
+    end
+
+    def render(*args)
+      if args.first.is_a?(Hash) && args.first.key?(:pdf)
+        render_with_weasy_pdf(args.first)
+      else
+        super
+      end
+    end
+
+    def render_to_string(*args)
+      if args.first.is_a?(Hash) && args.first.key?(:pdf)
+        render_to_string_with_weasy_pdf(args.first)
+      else
+        super
+      end
+    end
+
+    RAILS_RENDER_KEYS = %i[
+      template layout file inline locals formats handlers assigns
+    ].freeze
+
+    def render_with_weasy_pdf(options)
+      options = options.dup
+
+      filename = options.delete(:pdf) || "document"
+      show_as_html = options.delete(:show_as_html)
+      disposition = options.delete(:disposition) || "inline"
+
+      return render(options.slice(*RAILS_RENDER_KEYS).merge(content_type: "text/html")) if show_as_html
+
+      pdf = make_pdf(options)
+
+      send_data pdf,
+        filename: "#{filename}.pdf",
+        type: "application/pdf",
+        disposition: disposition
+    end
+
+    def render_to_string_with_weasy_pdf(options)
+      make_pdf(options.except(:pdf, :disposition, :show_as_html))
+    end
+
+    private
+
+    def make_pdf(options)
+      validate_header_footer!(options)
+
+      render_opts = options.slice(*RAILS_RENDER_KEYS).merge(formats: [:html])
+      html = render_to_string(**render_opts)
+      pdf_options = options.except(*RAILS_RENDER_KEYS)
+
+      WeasyPDF::Renderer.new(pdf_options).pdf_from_string(html)
+    end
+
+    # Wicked PDF supported rendering an ERB template or a URL as the header/footer,
+    # compositing it as a separate PDF page. WeasyPrint only supports CSS @page margin
+    # boxes, which accept text and CSS counters — not arbitrary HTML.
+    # Raise early so the caller knows to use :left/:center/:right strings instead.
+    def validate_header_footer!(options)
+      %i[header footer].each do |hf|
+        next unless options[hf].is_a?(Hash) && options[hf][:html].is_a?(Hash)
+
+        raise WeasyPDF::Error,
+          "#{hf}: :html templates and URLs are not supported. " \
+          "WeasyPrint uses CSS @page margin boxes, not separate HTML pages. " \
+          "Use :left, :center, or :right with plain text and [page]/[topage] counters. " \
+          "For complex layouts, see WeasyPrint running elements: " \
+          "https://weasyprint.readthedocs.io/en/stable/tutorial.html#headers-and-footers"
+      end
+      options
+    end
+
+    def clean_temp_files
+      # No-op — kept for API compatibility with Wicked PDF.
+      # Renderer cleans its own tempfiles via ensure blocks.
+    end
+  end
+end

data/lib/weasy_pdf/railtie.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module WeasyPDF
+  class Railtie < Rails::Railtie
+    initializer "weasy_pdf.pdf_helper" do
+      ActiveSupport.on_load(:action_controller_base) do
+        prepend WeasyPDF::PdfHelper
+      end
+    end
+
+    initializer "weasy_pdf.view_helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include WeasyPDF::ViewHelpers::Assets
+        include WeasyPDF::ViewHelpers::ViteAssets if defined?(ViteRuby)
+      end
+    end
+
+    initializer "weasy_pdf.mime_type" do
+      Mime::Type.register("application/pdf", :pdf) \
+        unless Mime::Type.lookup_by_extension(:pdf)
+    end
+  end
+end