sghtmltopdf 0.7.0-x64-mingw-ucrt

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3ee5fa24b7c3cf88df0fad8c10f969ca1bb3ceedb7734b3e73c7b5513ccdde8f
+  data.tar.gz: 9cea0287b96cf71414ee9e17e086c9296dc6e86657585b0188930eb6eb92765d
+SHA512:
+  metadata.gz: 552bf52d735af9995279fd78356434958ac68db8f143c2e9489508d49f701cd1ee7f344c2216659424f997faef1339e8f8f9b40db81656c796b21c0812dfb660
+  data.tar.gz: 6afe30d9f30f724e224d256db40ec242d25563e42c449879cd95d82d78538f84c9732c9f8eb91174dc4e64c9b01b8c409b35873ad13d555367bcc7baa4c716d1

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yo_waka
+
+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,150 @@
+# sghtmltopdf
+
+Ruby binding for [sghtmltopdf](https://github.com/waka/sghtmltopdf), an HTML-to-PDF renderer written in Rust that does not depend on Chromium, WebKit, or Gecko.
+
+The engine runs inside your process through a native extension (magnus + rb-sys) — no subprocess, no temporary files — and releases the GVL while rendering, so other Puma threads keep running.
+
+[Documentation](https://waka.github.io/sghtmltopdf/en/usage/ruby_rails.html) · [Repository](https://github.com/waka/sghtmltopdf) · [CHANGELOG](https://github.com/waka/sghtmltopdf/blob/main/CHANGELOG.md)
+
+## Install
+
+```ruby
+# Gemfile
+gem "sghtmltopdf"
+```
+
+Precompiled native gems are published for `x86_64-linux`, `aarch64-linux`, `x86_64-linux-musl`, `aarch64-linux-musl`, `arm64-darwin`, `x86_64-darwin`, and Windows `x64-mingw-ucrt`.
+There is no build step on those platforms.
+
+Elsewhere the source gem does not carry the Rust core and will refuse to build with an explanatory message.
+Point those environments at a separate `sghtmltopdf server` process instead; see [Delegating to a server](#delegating-to-a-server).
+
+Requires Ruby >= 3.2. The precompiled gems bundle extensions for Ruby 3.2, 3.3,
+3.4, and 4.0. On Windows, use 64-bit RubyInstaller UCRT (`x64-mingw-ucrt`).
+
+For contributors building from a repository checkout on Windows, use RubyInstaller
+with its Devkit, the Rust GNU toolchain (`stable-x86_64-pc-windows-gnu`), and LLVM
+with `libclang.dll`. Set `RUSTUP_TOOLCHAIN=stable-x86_64-pc-windows-gnu`, set
+`LIBCLANG_PATH` to the LLVM `bin` directory, add it to `PATH`, and set
+`BINDGEN_EXTRA_CLANG_ARGS=--target=x86_64-w64-windows-gnu`.
+Run the build through `ridk exec bundle exec rake compile`. The precompiled gem
+does not need these tools.
+
+## Usage
+
+```ruby
+pdf = Sghtmltopdf.render("<h1>Invoice</h1>", page_size: "A4", margin_top: "20mm")
+```
+
+Option names are the CLI long options without `--` and with `-` replaced by `_`, so `--page-size A4` becomes `page_size: "A4"`.
+The [option reference](https://waka.github.io/sghtmltopdf/en/usage/cli/reference.html) lists all of them.
+
+Write straight to a file (written to a temporary file and renamed on success, so a failure never leaves a broken PDF behind), or take the bytes in chunks:
+
+```ruby
+Sghtmltopdf.render_to_file(html, "invoice.pdf", page_size: "A4")
+
+Sghtmltopdf.render(html) { |bytes| io.write(bytes) }
+```
+
+## Header and footer HTML
+
+Pass markup directly without creating temporary files:
+
+```ruby
+Sghtmltopdf.render(html,
+  header_html_content: '<div>Invoice [title]</div>',
+  footer_html_content: '<div>Page [page] of [topage]</div>')
+```
+
+These options work with `render`, block output, `render_to_file`, global
+configuration, and server delegation. The shared CLI options are
+`--header-html-content` and `--footer-html-content`.
+
+`header_html` and `footer_html` still accept file paths. Supplying both a path
+and content for the same side raises `Sghtmltopdf::UsageError`, including when
+one comes from global configuration. `nil` or `false` disables a configured
+option; an empty string is an explicitly empty header or footer. Either HTML
+form takes precedence over simple text options for that side.
+
+Content uses the same placeholder expansion and margin clipping as file input.
+Embedded `data:` images are supported; external resources remain blocked.
+With server delegation, markup travels in URL query parameters, so URL length
+limits may apply and request logs may contain the markup.
+
+## Rails
+
+Adding the gem is enough; the Railtie wires everything up, and nothing is loaded when Rails is absent.
+
+```ruby
+# config/initializers/sghtmltopdf.rb
+Sghtmltopdf.configure do |c|
+  c.page_size   = "A4"
+  c.gothic_font = Rails.root.join("vendor/fonts/NotoSansJP-Regular.ttf")
+end
+```
+
+A `:pdf` renderer is registered, in the spirit of [wicked_pdf](https://github.com/mileszs/wicked_pdf) — the same keys, so an existing controller often needs no change at all:
+
+```ruby
+class InvoicesController < ApplicationController
+  def show
+    render pdf: "invoice",              # filename; ".pdf" is appended
+      template: "invoices/show",
+      layout: "pdf",
+      page_size: "A4", margin_top: "20mm"
+  end
+end
+```
+
+View-rendering keys (`template`, `layout`, `locals`, …) go to `render_to_string`, response keys (`filename`, `disposition`, `status`) go to `send_data`, `show_as_html: true` returns the HTML instead of a PDF, and everything else is passed to the converter.
+
+`render_to_string(pdf: "invoice", template: "invoices/show")` returns PDF bytes without setting the controller response. You can then pass those bytes to `send_data` or save them elsewhere; response options such as `filename`, `disposition`, and `status` only apply to `render pdf:`.
+Converter keys are flat CLI flag names, so wicked_pdf's nested `margin: {top: 10}` becomes `margin_top: "10mm"` (with the unit spelled out); the [migration guide](https://waka.github.io/sghtmltopdf/en/migration/wicked-pdf.html) maps every key one by one.
+
+### Assets
+
+PDF rendering does not go through the HTTP server, so `/assets/…` URLs are resolved as local files: the Railtie defaults `base_url` to `Rails.root/public` and restricts local reads to `public/` and the asset pipeline load paths via `allow_path`.
+That is enough for a precompiled production app; in development the digested `/assets/…` path names no file on disk, so these helpers look the asset up in the pipeline instead — the CSS expanded into a `<style>`, the image referenced by the path the engine can read:
+
+```erb
+<%= sghtmltopdf_stylesheet_link_tag "pdf" %>
+<%= sghtmltopdf_image_tag "logo.png" %>
+```
+
+`sghtmltopdf_stylesheet_link_tag` does not copy the CSS verbatim: it points every `url()` at a file the engine can read and splices in every `@import`.
+The asset pipeline rewrites `url()` through `asset_path` while precompiling, which turns a `@font-face` source into a digested `/assets/…` path, or into an absolute URL once `asset_host` is set — neither can be fetched while rendering, and a `@font-face` that fails to load falls back to the engine default rather than to the next `font-family`.
+
+A file `allow_path` does not cover is embedded as a `data:` URI instead, so that it cannot silently vanish from the PDF; pass `inline: true` to embed unconditionally.
+
+### Streaming the response
+
+To send pages as soon as their layout is final, pass a block and use `ActionController::Live` — this also makes `Rack::Timeout` and `Thread#kill` effective at chunk boundaries:
+
+```ruby
+class InvoicesController < ApplicationController
+  include ActionController::Live
+
+  def show
+    response.headers["Content-Type"] = "application/pdf"
+    html = render_to_string(template: "invoices/show", layout: "pdf")
+    Sghtmltopdf.render(html) { |bytes| response.stream.write(bytes) }
+  ensure
+    response.stream.close
+  end
+end
+```
+
+## Delegating to a server
+
+If the gem cannot run where your app runs, or you would rather not spend the app's CPU on rendering, set `server_url` and the same calls are delegated over HTTP to a separate `sghtmltopdf server` process.
+
+```ruby
+Sghtmltopdf.configure { |c| c.server_url = "http://pdf:8080" }
+```
+
+The [official Docker image](https://waka.github.io/sghtmltopdf/en/getting-started/docker.html) runs that server and bundles Japanese fonts.
+
+## License
+
+MIT License ([LICENSE](LICENSE)).

data/lib/sghtmltopdf/configuration.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Sghtmltopdf
+  # The global default options.
+  #
+  #   Sghtmltopdf.configure do |c|
+  #     c.page_size   = "A4"
+  #     c.gothic_font = "/path/to/NotoSansJP-Regular.ttf"
+  #   end
+  #
+  # A value set here can be overridden by an argument to `render`/`render_to_file`
+  # (merged in the order global, then call-time).
+  #
+  # Key names are not validated. The option definitions live in one place on the Rust side
+  # (`cli/options.rs`), so an unknown key makes clap raise a `UsageError` at render time.
+  class Configuration
+    def initialize(options = {})
+      @options = {}
+      # Values set explicitly (@options) are kept separately from the defaults injected by
+      # the Railtie and others (@defaults). Reads always prefer @options, so nothing depends
+      # on the order the initialisers run in.
+      @defaults = {}
+      options.each { |key, value| self[key] = value }
+    end
+
+    def [](key)
+      key = Options.canonical_key(key)
+      @options.key?(key) ? @options[key] : @defaults[key]
+    end
+
+    def []=(key, value)
+      @options[Options.canonical_key(key)] = value
+    end
+
+    # @param with_defaults [Boolean] whether to include the injected defaults.
+    #   Set it to `false` when delegating to the HTTP server: the Rails-oriented defaults
+    #   (`base_url` and `allow`) exist for local file resolution and are keys server mode
+    #   cannot take from a request
+    def to_h(with_defaults: true)
+      with_defaults ? @defaults.merge(@options) : @options.dup
+    end
+
+    # Inject the defaults. Used by the Railtie to set the Rails-oriented defaults.
+    # They are weaker than explicitly set values (`[]=` wins regardless of order).
+    def apply_defaults(defaults)
+      defaults.each { |key, value| @defaults[Options.canonical_key(key)] = value }
+      self
+    end
+
+    # Accepts both `c.page_size = "A4"` and `c.page_size`.
+    def method_missing(name, *args)
+      key = name.to_s
+      if key.end_with?("=")
+        raise ArgumentError, "#{name} takes one argument" unless args.size == 1
+
+        self[key.chomp("=")] = args.first
+      else
+        raise ArgumentError, "#{name} takes no arguments" unless args.empty?
+
+        self[key]
+      end
+    end
+
+    def respond_to_missing?(_name, _include_private = false)
+      true
+    end
+  end
+end

data/lib/sghtmltopdf/options.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "date"
+# `Time#iso8601` comes from here before Ruby 3.4 (Rails loads it, a plain Ruby script may not).
+require "time"
+require "uri"
+
+module Sghtmltopdf
+  # Converts an options hash into:
+  #
+  # * the CLI argument list (argv) passed to the native extension ... [.to_argv]
+  # * the query string passed to HTTP server mode                 ... [.to_query]
+  module Options
+
+    # The keys interpreted on the Ruby side alone. They are not conversion options, so they
+    # appear in neither the argv nor the query.
+    TRANSPORT_KEYS = %i[server_url server_open_timeout server_read_timeout chunk_size].freeze
+
+    # Alias keys (values are the canonical names). The CLI accepts `--allow` as an
+    # alias of `--allow-path`, but the Ruby side must not carry both keys around.
+    # If the defaults use one key and the call uses the other, a hash merge does
+    # not override: both end up in argv (repeating the same flag means "union",
+    # not "replace").
+    ALIAS_KEYS = {allow: :allow_path}.freeze
+
+    module_function
+
+    # Map an alias key to its canonical name.
+    def canonical_key(key)
+      key = key.to_sym
+      ALIAS_KEYS.fetch(key, key)
+    end
+
+    # Normalize all keys of a hash.
+    def canonicalize(options)
+      options.to_h { |key, value| [canonical_key(key), value] }
+    end
+
+    # @param options [Hash] the Ruby options hash
+    # @return [Array<String>] the conversion options passed to the core's `Converter`.
+    #   The HTML and the destination travel over FFI, so there is no program name, input
+    #   path or `--output` here.
+    def to_argv(options)
+      argv = []
+      each_pair(options) do |name, value|
+        argv.push("--#{name}")
+        argv.push(value) unless value.nil?
+      end
+      argv
+    end
+
+    # @param options [Hash] the Ruby options hash
+    # @return [String] the query string for `POST /pdf` (with no leading `?`)
+    def to_query(options)
+      parts = []
+      each_pair(options) do |name, value|
+        # A valueless flag becomes just the key (the server treats no value as true).
+        parts << (value.nil? ? escape(name) : "#{escape(name)}=#{escape(value)}")
+      end
+      parts.join("&")
+    end
+
+    # Convert one key and value into an argv fragment.
+    #
+    #   page_size: "A4"     → ["--page-size", "A4"]
+    #   grayscale: true     → ["--grayscale"]
+    #   grayscale: false    → []
+    #   allow: ["/a", "/b"] → ["--allow", "/a", "--allow", "/b"]
+    def args_for(key, value)
+      pairs_for(key, value).flat_map { |name, arg| arg.nil? ? ["--#{name}"] : ["--#{name}", arg] }
+    end
+
+    # Turn one key and value into a list of "flag name and value" pairs. A pair whose value is
+    # `nil` is a flag taking no value (`--toc` and the like).
+    def pairs_for(key, value)
+      name = flag_name(key)
+      return font_pairs(value) if name == "font"
+
+      case value
+      when nil, false then []
+      when true then [[name, nil]]
+      # An array means the same option repeated. The same rule applies to each element.
+      when Array then value.flat_map { |element| pairs_for(key, element) }
+      # `creation_date:` takes a moment in time. The CLI wants it as ISO 8601, so it is
+      # converted to UTC here rather than left to `to_s`, which would drop the zone for a Time
+      # and the subsecond part of a DateTime.
+      when Time, DateTime then [[name, value.to_time.getutc.iso8601]]
+      when Date then [[name, value.iso8601]]
+      when Hash
+        # Nesting such as wicked_pdf's `margin: {top: 10}` is not accepted. There is no
+        # corresponding CLI flag, and flattening it mechanically would let even misspelled
+        # keys through silently. When migrating, use the correspondence table in the
+        # migration guide to rewrite them. A unitless number is read as mm, as in wicked_pdf (`cli/units.rs`).
+        example = value.keys.first
+        raise ArgumentError,
+          "a Hash cannot be passed for #{key} (only :font takes a path and an index). " \
+          "Give nested options as flat keys" \
+          "#{": for example #{key}_#{example}: \"...\"" if example}"
+      else [[name, value.to_s]]
+      end
+    end
+
+    # `--font` and `--font-index` are paired by their order of appearance (the CLI ties each
+    # `--font-index` to "the last `--font` before it" via `ArgMatches#indices_of`).
+    # So a face index always goes immediately after its own `--font`.
+    #
+    #   font: "a.ttf"                        → ["--font", "a.ttf"]
+    #   font: {path: "a.ttc", index: 1}      → ["--font", "a.ttc", "--font-index", "1"]
+    #   font: ["a.ttf", {path: "b.ttc", index: 2}]
+    #     → ["--font", "a.ttf", "--font", "b.ttc", "--font-index", "2"]
+    def font_args(value)
+      font_pairs(value).flat_map { |name, arg| ["--#{name}", arg] }
+    end
+
+    def font_pairs(value)
+      case value
+      when nil, false then []
+      when Array then value.flat_map { |element| font_pairs(element) }
+      when Hash
+        path = value[:path] || value["path"]
+        raise ArgumentError, "a font Hash needs a path: #{value.inspect}" if path.nil?
+
+        index = value[:index] || value["index"]
+        pairs = [["font", path.to_s]]
+        pairs << ["font-index", index.to_s] unless index.nil?
+        pairs
+      else [["font", value.to_s]]
+      end
+    end
+
+    # `:page_size` becomes `page-size`.
+    def flag_name(key)
+      key.to_s.tr("_", "-")
+    end
+
+    # Enumerate only the conversion options, as pairs, in the order they were given.
+    def each_pair(options, &block)
+      options.each do |key, value|
+        key = canonical_key(key)
+        next if TRANSPORT_KEYS.include?(key)
+
+        pairs_for(key, value).each(&block)
+      end
+    end
+
+    def escape(value)
+      URI.encode_www_form_component(value.to_s)
+    end
+  end
+end

data/lib/sghtmltopdf/railtie.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+require_relative "renderer"
+require_relative "view_helpers"
+
+module Sghtmltopdf
+  class Railtie < ::Rails::Railtie
+    # The directories the engine may read from: `public/`, where the
+    # precompiled assets are, plus the asset pipeline load paths, where their
+    # sources are in development. The pipeline paths reach outside `Rails.root`
+    # for the assets a gem or an engine provides, which is why the whole of
+    # `Rails.root` is not a substitute for them.
+    #
+    # `config.assets` raises rather than answering `nil` when no pipeline gem is
+    # installed, hence `try`.
+    def self.default_options(app)
+      public_dir = File.join(app.root.to_s, "public")
+      pipeline = Array(app.config.try(:assets)&.paths).map(&:to_s)
+      allow = [public_dir, *pipeline].select { |dir| File.directory?(dir) }.uniq
+
+      defaults = {}
+      # An empty list would mean "no --allow-path", which is not the same thing as
+      # "allow nothing": it hands the boundary back to `base_url`. Leaving the
+      # key out says that, and says it in one place.
+      defaults[:allow_path] = allow unless allow.empty?
+      defaults[:base_url] = public_dir if File.directory?(public_dir)
+      defaults
+    end
+
+    # Read in `after_initialize`, not inside the initializer. The pipeline fills
+    # `config.assets.paths` in its own initializer (for Propshaft,
+    # `propshaft.append_assets_path`), and that one runs later.
+    #
+    # This runs after `config/initializers`, but `apply_defaults` is always
+    # weaker than explicitly set values, so it never overrides user settings.
+    initializer "sghtmltopdf.defaults" do |app|
+      app.config.after_initialize do
+        Sghtmltopdf.config.apply_defaults(Sghtmltopdf::Railtie.default_options(app))
+      end
+    end
+
+    initializer "sghtmltopdf.renderer" do
+      ActiveSupport.on_load(:action_controller) do
+        Sghtmltopdf::Renderer.register!
+      end
+
+      ActiveSupport.on_load(:action_view) do
+        include Sghtmltopdf::ViewHelpers
+      end
+    end
+  end
+end

data/lib/sghtmltopdf/renderer.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Sghtmltopdf
+  # Sorts the options of `render pdf: "invoice"` into three groups:
+  #
+  # * those passed to Rails view rendering (`render_to_string`)
+  # * those passed to building the response (`send_data`)
+  # * those passed to PDF conversion (`Sghtmltopdf.render`)
+  #
+  #
+  # It is a pure Ruby class with no dependency on Rails, so it can be unit tested without Rails.
+  class Renderer
+    module RenderToString
+      def render_to_string(*args, &block)
+        options = args.first.is_a?(Hash) ? args.first : args[1]
+        return super unless options.is_a?(Hash) && options.key?(:pdf)
+
+        normalized_args = args.map { |arg| arg.is_a?(Hash) ? arg.dup : arg }
+        options = _normalize_args(*normalized_args, &block)
+        renderer = Renderer.new(options.delete(:pdf), options, default_name: action_name)
+        html = super(**renderer.render_options, &block)
+        renderer.body_for(html)
+      end
+    end
+
+    # The keys passed straight to `render_to_string`.
+    RAILS_RENDER_KEYS = %i[
+      action assigns body collection file formats handlers html inline layout
+      locals object partial plain prefixes template variants
+    ].freeze
+
+    # The keys used to build the response (passed to `send_data`).
+    RESPONSE_KEYS = %i[disposition filename status].freeze
+
+    # The keys the renderer itself interprets (for debugging: return the HTML rather than a PDF).
+    RENDERER_KEYS = %i[show_as_html].freeze
+
+    PDF_CONTENT_TYPE = "application/pdf"
+    HTML_CONTENT_TYPE = "text/html"
+
+    attr_reader :name, :options
+
+    # @param name [String, Symbol, nil] the value given to `pdf:` (the basis of the file name)
+    # @param options [Hash] the other options given to `render`
+    # @param default_name [String, nil] the file name when `name` is empty
+    #   (the controller's `action_name` is expected)
+    def initialize(name, options = {}, default_name: nil)
+      @name = blank?(name) ? (default_name || "document").to_s : name.to_s
+      @options = options.to_h { |key, value| [key.to_sym, value] }
+    end
+
+    # Register the renderer with `ActionController::Renderers.add(:pdf)`.
+    # Called from the Railtie's Action Controller load hook (`on_load`).
+    def self.register!
+      ::ActionController::Rendering.prepend(RenderToString)
+      ::ActionController::Renderers.add(:pdf) do |name, options|
+        renderer = ::Sghtmltopdf::Renderer.new(name, options, default_name: action_name)
+        html = render_to_string(**renderer.render_options)
+        send_data(renderer.body_for(html), **renderer.send_data_options)
+      end
+    end
+
+    # The options used to render the view.
+    def render_options
+      options.select { |key, _| RAILS_RENDER_KEYS.include?(key) }
+    end
+
+    # The options used for the PDF conversion.
+    def convert_options
+      known = RAILS_RENDER_KEYS + RESPONSE_KEYS + RENDERER_KEYS
+      options.reject { |key, _| known.include?(key) }
+    end
+
+    # Turn the rendered HTML into the response body.
+    def body_for(html)
+      show_as_html? ? html : Sghtmltopdf.render(html, **convert_options)
+    end
+
+    def send_data_options
+      opts = {type: content_type, disposition: disposition}
+      opts[:filename] = filename unless show_as_html?
+      opts[:status] = options[:status] if options.key?(:status)
+      opts
+    end
+
+    def content_type
+      show_as_html? ? HTML_CONTENT_TYPE : PDF_CONTENT_TYPE
+    end
+
+    # `filename: "x.pdf"` wins over `pdf: "x"`. The extension is not doubled up.
+    def filename
+      base = blank?(options[:filename]) ? name : options[:filename].to_s
+      base.downcase.end_with?(".pdf") ? base : "#{base}.pdf"
+    end
+
+    # The default is `inline` (opened in the browser), as in wicked_pdf.
+    def disposition
+      blank?(options[:disposition]) ? "inline" : options[:disposition].to_s
+    end
+
+    # The equivalent of wicked_pdf's `show_as_html`. It returns the HTML rather than a PDF, so
+    # the layout can be inspected in the browser's developer tools.
+    def show_as_html?
+      value = options[:show_as_html]
+      !(value.nil? || value == false || value == "false")
+    end
+
+    private
+
+    def blank?(value)
+      value.nil? || (value.respond_to?(:empty?) && value.empty?)
+    end
+  end
+end

data/lib/sghtmltopdf/server_client.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Sghtmltopdf
+  class ServerError < Error; end
+
+  # The client delegating conversion to HTTP server mode (`sghtmltopdf server`).
+  #
+  #   Sghtmltopdf.configure { |c| c.server_url = "http://pdf.internal:8080" }
+  #   pdf = Sghtmltopdf.render(html, page_size: "A4")
+  class ServerClient
+    DEFAULT_OPEN_TIMEOUT = 5
+    DEFAULT_READ_TIMEOUT = 120
+
+    # The rough size of each read. With `?stream=1` this is the unit handed to the block.
+    CHUNK_SIZE = 64 * 1024
+
+    attr_reader :uri, :open_timeout, :read_timeout
+
+    # @param url [String] the server's base URL (`http://host:port`)
+    def initialize(url, open_timeout: nil, read_timeout: nil)
+      @uri = parse(url)
+      @open_timeout = (open_timeout || DEFAULT_OPEN_TIMEOUT).to_f
+      @read_timeout = (read_timeout || DEFAULT_READ_TIMEOUT).to_f
+    end
+
+    # Convert HTML to PDF.
+    #
+    # Given a block it uses `?stream=1` (chunked transfer encoding) and hands over chunks as
+    # the server settles each page. With no block it returns the whole PDF as a String.
+    def render(html, options, &block)
+      request = build_request(html, options, stream: !block.nil?)
+      pdf = nil
+      start do |http|
+        # With a block, `request` returns the response object, so the result is received in an
+        # outer variable.
+        http.request(request) do |response|
+          ensure_success!(response)
+          if block
+            response.read_body { |chunk| block.call(chunk.b) }
+          else
+            pdf = read_all(response)
+          end
+        end
+      end
+      pdf
+    end
+
+    # Write the conversion result to `path`. To leave no broken PDF on a failure part-way
+    # through, it writes to a temporary file and renames (matching the behaviour of the
+    # native extension's `FileSink`).
+    def render_to_file(html, options, path)
+      tmp = "#{path}.#{Process.pid}.tmp"
+      begin
+        File.open(tmp, "wb") do |file|
+          render(html, options) { |chunk| file.write(chunk) }
+        end
+      rescue SystemCallError => e
+        File.unlink(tmp) if File.exist?(tmp)
+        raise InputError, "failed to write to #{path}: #{e.message}"
+      rescue StandardError
+        File.unlink(tmp) if File.exist?(tmp)
+        raise
+      end
+      File.rename(tmp, path)
+      nil
+    end
+
+    private
+
+    def parse(url)
+      uri = URI.parse(url.to_s)
+      unless uri.is_a?(URI::HTTP) && uri.host
+        raise ArgumentError, "server_url must be an http(s) URL: #{url.inspect}"
+      end
+
+      uri
+    end
+
+    def build_request(html, options, stream:)
+      query = Options.to_query(options)
+      query = stream ? [query, "stream=1"].reject(&:empty?).join("&") : query
+      target = uri.dup
+      target.path = "/pdf"
+      target.query = query.empty? ? nil : query
+
+      request = Net::HTTP::Post.new(target)
+      request["Content-Type"] = "text/html; charset=utf-8"
+      request.body = html.to_s.b
+      request
+    end
+
+    def start(&block)
+      Net::HTTP.start(
+        uri.host, uri.port,
+        use_ssl: uri.scheme == "https",
+        open_timeout: open_timeout,
+        read_timeout: read_timeout,
+        &block
+      )
+    rescue Net::OpenTimeout, Net::ReadTimeout => e
+      raise ServerError, "the connection to #{base} timed out: #{e.class}"
+    rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError => e
+      raise ServerError, "the connection to #{base} failed: #{e.message}"
+    end
+
+    # An error response's body is a `text/plain` message (the same wording as the CLI).
+    def ensure_success!(response)
+      return if response.is_a?(Net::HTTPOK)
+
+      message = read_all(response).force_encoding(Encoding::UTF_8).strip
+      raise error_class(response), "#{base}: #{message}"
+    end
+
+    def error_class(response)
+      case response.code.to_i
+      when 400 then UsageError
+      when 413 then InputError
+      when 500 then RenderError
+      # A 404 or 405 means a wrong path or method, most likely because the other end is not
+      # an sghtmltopdf server. A 503 or 504 means the queue overflowed or the queue wait timed out.
+      else ServerError
+      end
+    end
+
+    def read_all(response)
+      buffer = +""
+      response.read_body { |chunk| buffer << chunk }
+      buffer.b
+    end
+
+    def base
+      "#{uri.scheme}://#{uri.host}:#{uri.port}"
+    end
+  end
+end

data/lib/sghtmltopdf/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Sghtmltopdf
+  VERSION = "0.7.0"
+end

data/lib/sghtmltopdf/view_helpers.rb

@@ -0,0 +1,405 @@
+# frozen_string_literal: true
+
+module Sghtmltopdf
+  # Action View helpers.
+  #
+  # Rendering a PDF never goes through an HTTP server, so a URL such as
+  # `/assets/…` is resolved as a local file (`--base-url` defaults to
+  # `Rails.root/public`, see [Railtie.default_options]). In production, where
+  # the assets are precompiled, that makes a plain `stylesheet_link_tag` work as
+  # it is; in development, where nothing has been written to `public/` yet, it
+  # cannot be resolved: the digest and the `/assets/` mount point are made up by
+  # the pipeline at request time, so no file of that name is on disk.
+  #
+  # Hence helpers that look the asset up in the pipeline and hand the engine
+  # something it can actually read:
+  #
+  #   <%= sghtmltopdf_stylesheet_link_tag "pdf" %>
+  #   <%= sghtmltopdf_image_tag "logo.png" %>
+  #
+  # (the counterparts of wicked_pdf's `wicked_pdf_stylesheet_link_tag` and
+  # `wicked_pdf_image_tag`).
+  module ViewHelpers
+    # Local file path of an asset, or `nil` when it cannot be found.
+    #
+    # Looks in
+    #
+    #   1. `public/` (precompiled; production)
+    #   2. the asset pipeline load paths (development; Propshaft or Sprockets)
+    #
+    # in that order. The pipeline lookup goes through `respond_to?` so that
+    # neither gem becomes a dependency (best effort).
+    def sghtmltopdf_asset_path(source)
+      path = source.to_s
+      # A source that is already a URL (or a `data:` URI) is not an asset of
+      # this application. Without this, `from_public_dir` would strip the host
+      # off `https://example.com/logo.png` and hand back `public/logo.png`.
+      return nil if path.match?(%r{\A(?:[a-z][a-z0-9+.\-]*:|//)}i)
+      return path if path.start_with?("/") && File.file?(path)
+
+      from_public_dir(path) || from_asset_pipeline(path)
+    end
+
+    # Expands the CSS itself into a `<style>`. Takes several sources; any that
+    # cannot be found are skipped silently (rendering still goes ahead).
+    #
+    # The file is not copied verbatim: its `url()`s are pointed at files the
+    # engine can read and its `@import`s are spliced in, see
+    # [#inline_stylesheet].
+    def sghtmltopdf_stylesheet_link_tag(*sources)
+      css = sources.flatten.filter_map do |source|
+        path = sghtmltopdf_asset_path(with_extension(source, ".css"))
+        inline_stylesheet(path) if path
+      end
+      return "".html_safe if css.empty?
+
+      content_tag(:style, css.join("\n").html_safe, type: "text/css")
+    end
+
+    # An `<img>` whose `src` the engine can read.
+    #
+    # The file is referenced by path, which keeps the HTML small: relative to
+    # `base_url` when it sits under it (the precompiled case), and the absolute
+    # filesystem path otherwise (the development case, where the file is still
+    # in the pipeline's load path). The engine reads an absolute `src` as a
+    # filesystem path once it fails to resolve under `base_url` (#44), so both
+    # forms reach the same file.
+    #
+    # A path only works if the engine is allowed to read there, so it is used
+    # only when `allow_path` (or `base_url`, with none set) covers the file.
+    # Everything else falls back to a `data:` URI, which depends on no
+    # configuration at all and therefore cannot fail: without that fallback a
+    # blocked path would just disappear from the PDF, since a failed asset fetch
+    # is ignored by default.
+    #
+    # `inline: true` forces embedding.
+    def sghtmltopdf_image_tag(source, options = {})
+      options = options.symbolize_keys
+      inline = options.delete(:inline)
+      path = sghtmltopdf_asset_path(source)
+      # Not an asset of this application (a remote URL, say): leave it to Rails.
+      return image_tag(source, options) if path.nil?
+
+      if !inline && (src = engine_readable_src(path))
+        # `image_tag` would rewrite the source (prefixing `/images/`, the asset
+        # host, and so on), so the tag is built directly. That skips the one
+        # option `image_tag` does more than copy, so `size:` is expanded here.
+        return tag.img(**expand_size(options).merge(src: src))
+      end
+      # A `data:` URI matches `AssetUrlHelper::URI_REGEXP`, so `image_tag`
+      # passes it through untouched and its own options keep working.
+      image_tag(data_uri(path), options)
+    end
+
+    private
+
+    # `path` read as CSS, with every `url()` pointed at a file the engine can
+    # read and every `@import` spliced in.
+    #
+    # Both have to happen here because the engine keeps one base for the whole
+    # document: every CSS source is concatenated before it is parsed, so a
+    # `url()` is resolved against the HTML's `base_url` whatever stylesheet it
+    # came from. Only this side knows where each file sits on disk, so each
+    # one's references are resolved against its own directory before its text
+    # is spliced into the next.
+    #
+    # What has to be undone is mostly the asset pipeline's own work: it
+    # rewrites every `url()` through `asset_path` while precompiling, which
+    # yields a digested `/assets/…` path, or an absolute URL once `asset_host`
+    # is set. Rendering never goes through the HTTP server, so neither can be
+    # fetched.
+    #
+    # `chain` holds the files already being expanded, innermost last.
+    def inline_stylesheet(path, chain = [])
+      css = File.read(path)
+      dir = File.dirname(path)
+      chain += [real_path(path)].compact
+      comments = comment_ranges(css)
+      out = +""
+      cursor = 0
+      while (import = IMPORT_STATEMENT.match(css, cursor))
+        commented = comments.any? { |range| range.cover?(import.begin(0)) }
+        expanded = imported_stylesheet(import[:href], dir, chain) unless commented
+        out << rewrite_css_urls(css[cursor...import.begin(0)].to_s, dir)
+        cursor = import.end(0)
+        out << (expanded || import[0])
+      end
+      out << rewrite_css_urls(css[cursor..].to_s, dir)
+    end
+
+    # The expanded content of an `@import` target, or `nil` to leave the
+    # statement as it is, which hands it to the engine untouched. That happens
+    # when it names no asset of this application, when the nesting is too deep,
+    # and when it points back at a file already being expanded.
+    #
+    # Media conditions on the statement are dropped. The engine replaces the
+    # whole statement with the imported text too, so nothing changes by doing
+    # it here.
+    def imported_stylesheet(href, dir, chain)
+      return nil if chain.length >= MAX_IMPORT_DEPTH
+
+      target = css_url_target(unquote(href), dir)
+      return nil if target.nil?
+
+      real = real_path(target)
+      return nil if real.nil? || chain.include?(real)
+
+      inline_stylesheet(target, chain)
+    end
+
+    # Byte ranges of the `/* … */` comments in `css`. A commented-out `@import`
+    # must not be spliced in.
+    def comment_ranges(css)
+      css.enum_for(:scan, CSS_COMMENT).map { Regexp.last_match.begin(0)...Regexp.last_match.end(0) }
+    end
+
+    # Every `url()` in `css` pointed at something the engine can read: a path
+    # when it may read the file there, a `data:` URI when it may not.
+    #
+    # A reference that names no file of this application is left alone, which
+    # covers `data:` URIs, bare fragments, and genuinely remote resources such
+    # as a font served by a CDN.
+    def rewrite_css_urls(css, dir)
+      css.gsub(CSS_URL) do
+        match = Regexp.last_match
+        target = css_url_target(unquote(match[:href]), dir)
+        target ? css_url(engine_readable_src(target) || data_uri(target)) : match[0]
+      end
+    end
+
+    # The local file a CSS reference names, or `nil` when it names none.
+    def css_url_target(ref, dir)
+      path = ref.split(/[?#]/, 2).first.to_s
+      return nil if path.empty? || path.match?(/\Adata:/i)
+
+      if path.match?(%r{\A(?:[a-z][a-z0-9+.\-]*:|//)}i)
+        # Only an http(s) or protocol-relative URL can be one of ours. The host
+        # is not compared against `asset_host`: it may be a callable or carry a
+        # `%d` wildcard, so there is no general way to recognise it. Finding the
+        # path on disk is the test instead, and what that finds is the very file
+        # the reference names.
+        return nil unless path.match?(%r{\A(?:https?:)?//}i)
+
+        path = path.sub(%r{\A(?:https?:)?//[^/]*}i, "")
+        return nil if path.empty?
+      end
+
+      path.start_with?("/") ? from_site_root(path) : from_stylesheet_dir(path, dir)
+    end
+
+    # A site-root-relative reference (`/assets/pdf-<digest>.css`) mapped onto a
+    # file. `relative_url_root` comes off first: the pipeline writes it in front
+    # of every URL, but it is a mount point, not a directory under `public/`.
+    def from_site_root(path)
+      root = ::Rails.application.config.try(:relative_url_root).to_s
+      path = path.delete_prefix(root) unless root.empty?
+      candidate = File.join(::Rails.public_path.to_s, path)
+      return candidate if File.file?(candidate)
+
+      # Nothing is precompiled in development, so the load path is asked as
+      # well. The mount point is not part of a logical path either.
+      logical = path.delete_prefix("/")
+      prefix = ::Rails.application.config.try(:assets)&.prefix.to_s.delete_prefix("/")
+      from_asset_pipeline(logical) ||
+        (prefix.empty? ? nil : from_asset_pipeline(logical.delete_prefix("#{prefix}/")))
+    end
+
+    # A reference relative to the stylesheet that wrote it, which is what CSS
+    # says it means and what the pipeline assumed while compiling the file.
+    #
+    # The load path is tried too. An uncompiled stylesheet sitting at the root
+    # of its own load path names assets by logical path, which is spelled the
+    # same way but is looked up across every root.
+    def from_stylesheet_dir(path, dir)
+      candidate = File.expand_path(path, dir)
+      return candidate if File.file?(candidate)
+
+      from_asset_pipeline(path.delete_prefix("./"))
+    end
+
+    # A `url()` whose argument is always quoted, so that a path holding a space
+    # or a parenthesis survives.
+    def css_url(value)
+      %(url("#{value.gsub(/["\\]/) { |char| "\\#{char}" }}"))
+    end
+
+    def unquote(value)
+      value = value.to_s.strip
+      quoted = value.match(/\A(["'])(.*)\1\z/m)
+      quoted ? quoted[2] : value
+    end
+
+    # Matches the engine's own cap (`core/src/style/import.rs`). Past it the
+    # statement is left in place and the engine decides what to do with it.
+    MAX_IMPORT_DEPTH = 16
+    private_constant :MAX_IMPORT_DEPTH
+
+    # `@import` up to its terminating `;`, in both the `url()` and the bare
+    # string form. Media conditions are matched so they are consumed, not kept.
+    IMPORT_STATEMENT = /
+      @import \s+
+      (?: url\( \s* (?<href> "[^"]*" | '[^']*' | [^)"'\s]* ) \s* \)
+        | (?<href> "[^"]*" | '[^']*' ) )
+      [^;]* ;
+    /xi
+    private_constant :IMPORT_STATEMENT
+
+    # A `url()` token. The lookbehind keeps identifiers ending in "url" out.
+    CSS_URL = /(?<![\w-])url\( \s* (?<href> "[^"]*" | '[^']*' | [^)"'\s]* ) \s* \)/xi
+    private_constant :CSS_URL
+
+    CSS_COMMENT = %r{/\*.*?\*/}m
+    private_constant :CSS_COMMENT
+
+    # Takes the path part of the URL `asset_path` returns (which may carry an
+    # asset host) and maps it onto a real file under `public/`.
+    def from_public_dir(source)
+      relative = asset_url_for(source).to_s.sub(%r{\Ahttps?://[^/]+}, "").split(/[?#]/).first.to_s
+      return nil if relative.empty?
+
+      candidate = File.join(::Rails.public_path.to_s, relative)
+      File.file?(candidate) ? candidate : nil
+    end
+
+    # `asset_path` for `source`, falling back to `source` itself.
+    #
+    # Both pipelines raise rather than return a path for an asset outside their
+    # load path (`Propshaft::MissingAssetError`,
+    # `Sprockets::Rails::Helper::AssetNotFound`). A file that lives only in
+    # `public/` is exactly that, so the raw source is tried against `public/`.
+    def asset_url_for(source)
+      return source unless respond_to?(:asset_path)
+
+      asset_path(source)
+    rescue StandardError
+      source
+    end
+
+    def from_asset_pipeline(source)
+      assets = ::Rails.application.try(:assets)
+      return nil if assets.nil?
+
+      # Propshaft
+      if assets.respond_to?(:load_path)
+        found = assets.load_path.find(source)
+        return found.path.to_s if found.respond_to?(:path)
+      end
+      # Sprockets
+      if assets.respond_to?(:[])
+        found = assets[source]
+        return found.filename.to_s if found.respond_to?(:filename)
+      end
+      nil
+    end
+
+    # `data:<type>;base64,<data>` for a local file. `pack("m0")` is strict
+    # base64 (no line breaks) and needs no require, unlike `Base64`, which is no
+    # longer a default gem on Ruby 3.4.
+    def data_uri(path)
+      base64 = [File.binread(path)].pack("m0")
+      "data:#{mime_type_of(path)};base64,#{base64}"
+    end
+
+    # The `src` to reference `file` by, or `nil` when the engine would not be
+    # allowed to read it there.
+    def engine_readable_src(file)
+      return nil unless engine_can_read?(file)
+
+      relative_to_base_url(file) || real_path(file)
+    end
+
+    # Whether the engine's rules for local files let it read `file`.
+    #
+    # `allow_path` decides on its own once it is set: the engine stops treating
+    # `base_url` as the boundary and consults the allowed directories only.
+    # A run that has no local access at all, or one delegated to a server that
+    # may not even share this filesystem, can read nothing here.
+    def engine_can_read?(file)
+      config = Sghtmltopdf.config
+      return false if config[:disable_local_file_access] || config[:server_url]
+
+      file = real_path(file)
+      return false if file.nil?
+
+      dirs = Array(config[:allow_path]).filter_map { |dir| real_path(dir) }
+      dirs = [real_path(config[:base_url])].compact if dirs.empty?
+      dirs.any? { |dir| file.start_with?(dir + File::SEPARATOR) }
+    end
+
+    # The path of `file` relative to the configured `base_url`, or `nil` when
+    # `base_url` is not a directory holding it (it may be an http(s) URL, or the
+    # file may live outside it, as an asset pipeline one in development does).
+    def relative_to_base_url(file)
+      base = real_path(Sghtmltopdf.config[:base_url])
+      full = real_path(file)
+      return nil if base.nil? || full.nil?
+
+      prefix = base + File::SEPARATOR
+      full.start_with?(prefix) ? full.delete_prefix(prefix) : nil
+    end
+
+    # `path` with symlinks resolved, or `nil` when it is not a local path at
+    # all. The engine canonicalizes both sides before comparing them, so a
+    # symlink pointing out of an allowed directory does not count as inside it.
+    def real_path(path)
+      path = path.to_s
+      return nil if path.empty? || path.match?(%r{\Ahttps?://}i)
+
+      File.realpath(path)
+    rescue SystemCallError
+      nil
+    end
+
+    # `image_tag`'s `size:` shorthand: "40x30", or "40" for a square. The tag is
+    # built without `image_tag` here, so the expansion has to happen here too.
+    def expand_size(options)
+      return options unless options.key?(:size)
+
+      if options[:height] || options[:width]
+        raise ArgumentError, "Cannot pass a :size option with a :height or :width option"
+      end
+
+      size = options[:size].to_s
+      options = options.except(:size)
+      case size
+      when /\A(\d+(?:\.\d+)?)x(\d+(?:\.\d+)?)\z/ then options.merge(width: $1, height: $2)
+      when /\A\d+(?:\.\d+)?\z/ then options.merge(width: size, height: size)
+      else options
+      end
+    end
+
+    # Media type from the file extension. The engine detects the format from the
+    # bytes, so this only has to be honest, not exhaustive.
+    def mime_type_of(path)
+      MIME_TYPES.fetch(File.extname(path).downcase.delete_prefix("."), "application/octet-stream")
+    end
+
+    MIME_TYPES = {
+      "png" => "image/png",
+      "jpg" => "image/jpeg",
+      "jpeg" => "image/jpeg",
+      "gif" => "image/gif",
+      "webp" => "image/webp",
+      "avif" => "image/avif",
+      "bmp" => "image/bmp",
+      "ico" => "image/vnd.microsoft.icon",
+      "tif" => "image/tiff",
+      "tiff" => "image/tiff",
+      "svg" => "image/svg+xml",
+      # Reached through a stylesheet's `url()`, not through `image_tag`.
+      "otf" => "font/otf",
+      "ttf" => "font/ttf",
+      "ttc" => "font/collection",
+      "woff" => "font/woff",
+      "woff2" => "font/woff2",
+      "eot" => "application/vnd.ms-fontobject",
+      "css" => "text/css"
+    }.freeze
+    private_constant :MIME_TYPES
+
+    def with_extension(source, extension)
+      name = source.to_s
+      name.end_with?(extension) ? name : "#{name}#{extension}"
+    end
+  end
+end

data/lib/sghtmltopdf.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require_relative "sghtmltopdf/version"
+require_relative "sghtmltopdf/options"
+require_relative "sghtmltopdf/configuration"
+require_relative "sghtmltopdf/renderer"
+
+# A precompiled gem puts the `.so` in a directory per Ruby minor version
+# (rake-compiler's cross-build convention). During development `rake compile` puts it in
+# `lib/sghtmltopdf/sghtmltopdf.so`, so both are tried.
+begin
+  RUBY_VERSION =~ /(\d+\.\d+)/
+  require "sghtmltopdf/#{Regexp.last_match(1)}/sghtmltopdf"
+rescue LoadError
+  require "sghtmltopdf/sghtmltopdf"
+end
+
+# It inherits `Error` (defined by the native extension), so it comes after the extension is loaded.
+require_relative "sghtmltopdf/server_client"
+
+module Sghtmltopdf
+  # The rough number of bytes handed over per call to a block-taking `render` (local conversion only).
+  # Calling the block on every settled page would mean reacquiring the GVL too often, so this
+  # much is accumulated first.
+  DEFAULT_CHUNK_SIZE = 64 * 1024
+
+  class << self
+    # Convert HTML and return the PDF bytes (an ASCII-8BIT String).
+    #
+    # Given a block, it calls the block per chunk rather than assembling the whole PDF first
+    # (returning nil). It is the hook for streaming into Rack's `response.stream` or into an
+    # S3 multipart upload (matching the engine's design, which is unaware of the output sink).
+    #
+    #   Sghtmltopdf.render(html) { |bytes| response.stream.write(bytes) }
+    #
+    # Both locally and when delegating to a server, it can be written out without waiting for
+    # the whole PDF to be assembled (locally page by page as they settle; from a server, the
+    # `?stream=1` chunked transfer encoding passed straight through).
+    #
+    # Only the PDF writing is incremental, though: HTML parsing and layout still happen for
+    # the whole document first. The first chunk arrives late in the conversion, and the peak
+    # memory is no different from the block-less case. To settle pages while the HTML is being
+    # read, use it together with `streaming: true`
+    # (which trades constraints for a large reduction in memory).
+    #
+    # The rough bytes per call can be changed with `chunk_size:` (64KiB by default; local
+    # conversion only; a smaller value means reacquiring the GVL more often).
+    def render(html, **options, &block)
+      options = Options.canonicalize(options)
+      client = server_client(options)
+      return client.render(html.to_s, server_options(options), &block) if client
+      return Native.render(html.to_s, argv_for(options)) if block.nil?
+
+      Native.render_each(html.to_s, argv_for(options), block, chunk_size(options))
+      nil
+    end
+
+    # Convert HTML and write it to `path`.
+    #
+    # It writes to a temporary file and renames only on success, so a failure part-way through
+    # leaves no broken PDF at the destination (the same when delegating to a server).
+    def render_to_file(html, path, **options)
+      options = Options.canonicalize(options)
+      client = server_client(options)
+      return client.render_to_file(html.to_s, server_options(options), path.to_s) if client
+
+      Native.render_to_file(html.to_s, argv_for(options), path.to_s)
+      nil
+    end
+
+    # The global default options.
+    def configure
+      yield config
+      config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    # Mainly for tests. Resets the configuration to empty.
+    def reset_config!
+      @config = Configuration.new
+    end
+
+    private
+
+    # Merge in the order global settings, then call-time options, and turn that into argv.
+    def argv_for(options)
+      Options.to_argv(config.to_h.merge(options))
+    end
+
+    # With a `server_url` it delegates to the server. The timeout merges in the same order.
+    def server_client(options)
+      merged = config.to_h.merge(options)
+      url = merged[:server_url]
+      return nil if url.nil? || url.to_s.empty?
+
+      ServerClient.new(
+        url,
+        open_timeout: merged[:server_open_timeout],
+        read_timeout: merged[:server_read_timeout]
+      )
+    end
+
+    # The rough bytes handed to the block per call (local conversion only).
+    def chunk_size(options)
+      value = config.to_h.merge(options)[:chunk_size]
+      value.nil? ? DEFAULT_CHUNK_SIZE : Integer(value)
+    end
+
+    # The options passed to the server. The injected defaults are removed
+    # (the Rails-oriented `base_url` and `allow` are defaults for local file resolution, and
+    # server mode cannot take them from a request, giving a 400.
+    # An explicitly set value is sent as-is and the server decides whether to accept it).
+    def server_options(options)
+      config.to_h(with_defaults: false).merge(options)
+    end
+  end
+end
+
+require_relative "sghtmltopdf/railtie" if defined?(::Rails::Railtie)

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: sghtmltopdf
+version: !ruby/object:Gem::Version
+  version: 0.7.0
+platform: x64-mingw-ucrt
+authors:
+- yo_waka
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2026-11-01 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Ruby binding for sghtmltopdf, a successor to wkhtmltopdf: an HTML-to-PDF
+  rendering engine written in Rust that needs no browser process. The engine
+  runs in-process through a native extension and releases the GVL while
+  rendering. On Rails it registers a wicked_pdf compatible renderer, so
+  `render pdf: "invoice"` works with the keys you already use.
+email:
+- y.wakahara@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/sghtmltopdf.rb
+- lib/sghtmltopdf/3.2/sghtmltopdf.so
+- lib/sghtmltopdf/3.3/sghtmltopdf.so
+- lib/sghtmltopdf/3.4/sghtmltopdf.so
+- lib/sghtmltopdf/4.0/sghtmltopdf.so
+- lib/sghtmltopdf/configuration.rb
+- lib/sghtmltopdf/options.rb
+- lib/sghtmltopdf/railtie.rb
+- lib/sghtmltopdf/renderer.rb
+- lib/sghtmltopdf/server_client.rb
+- lib/sghtmltopdf/version.rb
+- lib/sghtmltopdf/view_helpers.rb
+homepage: https://github.com/waka/sghtmltopdf
+licenses:
+- MIT
+metadata:
+  source_code_uri: https://github.com/waka/sghtmltopdf
+  changelog_uri: https://github.com/waka/sghtmltopdf/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/waka/sghtmltopdf/issues
+  rubygems_mfa_required: 'true'
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+  - - "<"
+    - !ruby/object:Gem::Version
+      version: 4.1.dev
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key: 
+specification_version: 4
+summary: HTML to PDF renderer that does not depend on Chromium, WebKit, or Gecko
+test_files: []