gotenberg-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6afda17f3ec1d2563dd371cfa5a36c9e368dc507062db2aa1e3dd8ae10b0b5f2
+  data.tar.gz: c988d6aa39af30f7f1e0c52b8348e483a33665aa6e55f5b00c094160de55e252
+SHA512:
+  metadata.gz: 87351a0801cbf3e392f29e8824ce1dcae7b743efb1afd23ddeef0f67a4fc1f4420c44761eaa6f2aca319862b628c487fbbc7b5a7bb30f440da0f26ab6c1d3479
+  data.tar.gz: 290ef76a4572942e746029014b411241bf64eed842c309cdcb9b45a6a9ed43e3f697c014bcbfd98203824046ee060f2ed5f2ad641b61f450814c7f932a89b13c

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shinichi Maeshima
+
+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,98 @@
+# Gotenberg Rails
+
+Render Rails HTML as PDFs with [Gotenberg](https://gotenberg.dev/).
+
+## Installation
+
+Add the gem to your Gemfile:
+
+```ruby
+gem "gotenberg-rails"
+```
+
+Run Gotenberg:
+
+```sh
+docker run --rm -p 3000:3000 gotenberg/gotenberg:8
+```
+
+## Usage
+
+Render a PDF from a Rails controller:
+
+```ruby
+def show
+  respond_to do |format|
+    format.html
+    format.pdf do
+      render gotenberg_pdf: {}, disposition: :inline, filename: "invoice.pdf"
+    end
+  end
+end
+```
+
+Customize the rendered template and Gotenberg options:
+
+```ruby
+def show
+  render gotenberg_pdf: {
+    print_background: true,
+    paper_width: "8.27",
+    paper_height: "11.7",
+    margin_top: "0.4",
+    margin_bottom: "0.4",
+    margin_left: "0.4",
+    margin_right: "0.4"
+  },
+  layout: "pdf",
+  template: "invoices/show",
+  disposition: :inline,
+  filename: "invoice.pdf"
+end
+```
+
+You can also render directly:
+
+```ruby
+Gotenberg::Rails.render_pdf(html: html)
+Gotenberg::Rails.render_pdf(html: html, display_url: "https://example.com/invoice")
+Gotenberg::Rails.render_pdf(url: "https://example.com/invoice")
+```
+
+When rendering HTML, `display_url` is used to rewrite relative image, link, JavaScript, stylesheet, and CSS `url(...)` references to absolute URLs before sending the HTML to Gotenberg. Controller rendering uses `request.original_url` automatically.
+
+Options are sent to Gotenberg as Chromium form fields. Ruby-style snake case keys are converted to Gotenberg camel case keys:
+
+```ruby
+Gotenberg::Rails.render_pdf(
+  html: html,
+  pdf_options: {
+    print_background: true,
+    emulated_media_type: "screen",
+    wait_delay: "2s",
+    fail_on_http_status_codes: [499, 599],
+    metadata: { Title: "Invoice" }
+  }
+)
+```
+
+## Configuration
+
+```ruby
+Gotenberg::Rails.configure do |config|
+  config.endpoint = ENV.fetch("GOTENBERG_ENDPOINT", "http://gotenberg:3000")
+  config.open_timeout = 5
+  config.request_timeout = 30
+  config.headers = { "X-Request-Source" => "rails" }
+  config.pdf_options = {
+    print_background: true,
+    prefer_css_page_size: true
+  }
+end
+```
+
+Gotenberg receives rendered HTML as an `index.html` upload. Use absolute URLs for stylesheets, images, and fonts that Gotenberg must fetch from your Rails app.
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/lib/gotenberg/rails/client.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "stringio"
+require "uri"
+
+module Gotenberg
+  module Rails
+    class Client
+      HTML_PATH = "/forms/chromium/convert/html"
+      URL_PATH = "/forms/chromium/convert/url"
+
+      attr_reader :endpoint, :open_timeout, :request_timeout, :headers
+
+      def initialize(endpoint:, open_timeout:, request_timeout:, headers: {})
+        @endpoint = endpoint.to_s.delete_suffix("/")
+        @open_timeout = open_timeout
+        @request_timeout = request_timeout
+        @headers = headers
+      end
+
+      def render_pdf(html: nil, url: nil, pdf_options: {}, filename: nil, trace: nil)
+        if html && url
+          raise ArgumentError, "Provide either :html or :url, not both"
+        elsif html
+          post(HTML_PATH, html_form(html, pdf_options), filename:, trace:)
+        elsif url
+          post(URL_PATH, url_form(url, pdf_options), filename:, trace:)
+        else
+          raise ArgumentError, "Provide :html or :url"
+        end
+      end
+
+      private
+
+      def html_form(html, pdf_options)
+        [
+          ["files", StringIO.new(html.to_s), { filename: "index.html", content_type: "text/html" }],
+          *option_fields(pdf_options)
+        ]
+      end
+
+      def url_form(url, pdf_options)
+        [
+          ["url", url.to_s],
+          *option_fields(pdf_options)
+        ]
+      end
+
+      def option_fields(options)
+        options.compact.map do |key, value|
+          [camelize_option(key), encode_option(value)]
+        end
+      end
+
+      def camelize_option(key)
+        key.to_s.gsub(/_([a-z])/) { Regexp.last_match(1).upcase }
+      end
+
+      def encode_option(value)
+        case value
+        when Array, Hash
+          JSON.generate(value)
+        else
+          value.to_s
+        end
+      end
+
+      def post(path, form, filename:, trace:)
+        uri = URI.join("#{endpoint}/", path.delete_prefix("/"))
+        request = Net::HTTP::Post.new(uri)
+        headers.each { |key, value| request[key] = value }
+        request["Gotenberg-Output-Filename"] = filename if filename
+        request["Gotenberg-Trace"] = trace if trace
+        request.set_form(form, "multipart/form-data")
+
+        response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https") do |connection|
+          connection.open_timeout = open_timeout
+          connection.read_timeout = request_timeout
+          connection.request(request)
+        end
+
+        return response.body if response.is_a?(Net::HTTPSuccess)
+
+        raise ConversionError, response
+      end
+    end
+  end
+end

data/lib/gotenberg/rails/configuration.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Gotenberg
+  module Rails
+    class Configuration
+      attr_accessor :endpoint, :request_timeout, :open_timeout, :pdf_options, :headers
+
+      def initialize
+        @endpoint = ENV.fetch("GOTENBERG_ENDPOINT", "http://localhost:3000")
+        @request_timeout = 60
+        @open_timeout = 10
+        @pdf_options = {}
+        @headers = {}
+      end
+    end
+  end
+end

data/lib/gotenberg/rails/error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Gotenberg
+  module Rails
+    class Error < StandardError; end
+
+    class ConversionError < Error
+      attr_reader :response
+
+      def initialize(response)
+        @response = response
+        super("Gotenberg conversion failed with #{response.code}: #{response.body}")
+      end
+    end
+  end
+end

data/lib/gotenberg/rails/html_preprocessor.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+require "uri"
+
+module Gotenberg
+  module Rails
+    class HtmlPreprocessor
+      URL_ATTRIBUTES = %w[action href poster src].freeze
+      DATA_URL_ATTRIBUTES = {
+        "object" => %w[data]
+      }.freeze
+      SRCSET_ATTRIBUTES = %w[srcset].freeze
+      SKIPPED_SCHEMES = %w[cid data javascript mailto tel].freeze
+      CSS_URL_PATTERN = /url\(\s*(['"]?)([^'")]+)\1\s*\)/i
+
+      attr_reader :html, :display_url
+
+      def initialize(html, display_url:)
+        @html = html.to_s
+        @display_url = display_url
+      end
+
+      def call
+        return html if display_url.nil? || display_url.to_s.empty?
+
+        document = Nokogiri::HTML5(html)
+        base_url = document.at_css("base[href]")&.[]("href") || display_url
+
+        preprocess_url_attributes(document, base_url)
+        preprocess_srcset_attributes(document, base_url)
+        preprocess_css_urls(document, base_url)
+
+        document.to_html
+      end
+
+      private
+
+      def preprocess_url_attributes(document, base_url)
+        URL_ATTRIBUTES.each do |attribute|
+          document.css("[#{attribute}]").each do |node|
+            node[attribute] = absolute_url(node[attribute], base_url)
+          end
+        end
+
+        DATA_URL_ATTRIBUTES.each do |selector, attributes|
+          attributes.each do |attribute|
+            document.css("#{selector}[#{attribute}]").each do |node|
+              node[attribute] = absolute_url(node[attribute], base_url)
+            end
+          end
+        end
+      end
+
+      def preprocess_srcset_attributes(document, base_url)
+        SRCSET_ATTRIBUTES.each do |attribute|
+          document.css("[#{attribute}]").each do |node|
+            node[attribute] = absolutize_srcset(node[attribute], base_url)
+          end
+        end
+      end
+
+      def preprocess_css_urls(document, base_url)
+        document.css("[style]").each do |node|
+          node["style"] = absolutize_css_urls(node["style"], base_url)
+        end
+
+        document.css("style").each do |node|
+          node.content = absolutize_css_urls(node.content, base_url)
+        end
+      end
+
+      def absolutize_srcset(value, base_url)
+        value.to_s.split(",").map do |candidate|
+          url, descriptor = candidate.strip.split(/\s+/, 2)
+          [absolute_url(url, base_url), descriptor].compact.join(" ")
+        end.join(", ")
+      end
+
+      def absolutize_css_urls(value, base_url)
+        value.to_s.gsub(CSS_URL_PATTERN) do
+          quote = Regexp.last_match(1)
+          url = Regexp.last_match(2)
+          "url(#{quote}#{absolute_url(url, base_url)}#{quote})"
+        end
+      end
+
+      def absolute_url(value, base_url)
+        url = value.to_s.strip
+        return value if url.empty? || url.start_with?("#") || skipped_scheme?(url)
+
+        URI.join(base_url, url).to_s
+      rescue URI::InvalidURIError
+        value
+      end
+
+      def skipped_scheme?(url)
+        scheme = URI.parse(url).scheme
+        scheme && SKIPPED_SCHEMES.include?(scheme.downcase)
+      rescue URI::InvalidURIError
+        false
+      end
+    end
+  end
+end

data/lib/gotenberg/rails/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "action_controller/railtie"
+
+module Gotenberg
+  module Rails
+    class Railtie < ::Rails::Railtie
+      initializer "gotenberg_rails.renderer" do
+        ActiveSupport.on_load(:action_controller) do
+          Gotenberg::Rails::Renderer.register
+        end
+      end
+    end
+  end
+end

data/lib/gotenberg/rails/renderer.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Gotenberg
+  module Rails
+    module Renderer
+      def self.register
+        ActionController::Renderers.add :gotenberg_pdf do |options, render_options|
+          pdf_options = options || {}
+          filename = render_options[:filename] || pdf_options.delete(:filename) || "#{controller_name}.pdf"
+          disposition = render_options[:disposition] || pdf_options.delete(:disposition) || "attachment"
+          display_url = render_options[:display_url] || pdf_options.delete(:display_url) || request.original_url
+
+          html = render_to_string(render_options.except(:display_url, :filename, :disposition).merge(formats: [:html]))
+          pdf = Gotenberg::Rails.render_pdf(html:, display_url:, pdf_options:, filename:)
+
+          send_data pdf,
+                    filename: filename,
+                    type: "application/pdf",
+                    disposition: disposition
+        end
+      end
+    end
+  end
+end

data/lib/gotenberg/rails/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Gotenberg
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/gotenberg/rails.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/hash/except"
+require_relative "rails/client"
+require_relative "rails/configuration"
+require_relative "rails/error"
+require_relative "rails/html_preprocessor"
+require_relative "rails/renderer"
+require_relative "rails/version"
+
+require_relative "rails/railtie" if defined?(::Rails::Railtie)
+
+module Gotenberg
+  module Rails
+    class << self
+      attr_writer :configuration, :client
+
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield configuration
+      end
+
+      def client
+        @client ||= Client.new(
+          endpoint: configuration.endpoint,
+          open_timeout: configuration.open_timeout,
+          request_timeout: configuration.request_timeout,
+          headers: configuration.headers
+        )
+      end
+
+      def render_pdf(html: nil, url: nil, display_url: nil, pdf_options: {}, **options)
+        merged_options = configuration.pdf_options.merge(pdf_options || {})
+        html = HtmlPreprocessor.new(html, display_url:).call if html
+
+        client.render_pdf(html:, url:, pdf_options: merged_options, **options)
+      end
+
+      def reset_configuration!
+        @configuration = Configuration.new
+        @client = nil
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: gotenberg-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Shinichi Maeshima
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actionpack
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.2'
+- !ruby/object:Gem::Dependency
+  name: nokogiri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.8.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.8.5
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '13.0'
+description: A small Rails renderer and Ruby API for converting HTML or URLs to PDF
+  using Gotenberg.
+email:
+- netwillnet@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/gotenberg/rails.rb
+- lib/gotenberg/rails/client.rb
+- lib/gotenberg/rails/configuration.rb
+- lib/gotenberg/rails/error.rb
+- lib/gotenberg/rails/html_preprocessor.rb
+- lib/gotenberg/rails/railtie.rb
+- lib/gotenberg/rails/renderer.rb
+- lib/gotenberg/rails/version.rb
+homepage: https://github.com/willnet/gotenberg-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/willnet/gotenberg-rails
+  source_code_uri: https://github.com/willnet/gotenberg-rails
+  changelog_uri: https://github.com/willnet/gotenberg-rails/releases
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Render Rails HTML as PDFs with Gotenberg.
+test_files: []