sghtmltopdf 0.1.0

data/Cargo.toml

@@ -0,0 +1,3 @@
+[workspace]
+resolver = "2"
+members = ["ext/sghtmltopdf"]

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,109 @@
+# 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`, and `arm64-darwin`.
+There is no build step on those platforms.
+
+Elsewhere (Intel Mac, Windows) the gem cannot run in-process — 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.
+
+## 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) }
+```
+
+## 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.
+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 `Rails.root` via `allow`.
+That is enough for a precompiled production app; in development, these helpers inline the asset instead:
+
+```erb
+<%= sghtmltopdf_stylesheet_link_tag "pdf" %>
+<%= sghtmltopdf_image_tag "logo.png" %>
+```
+
+### 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/ext/sghtmltopdf/Cargo.toml

@@ -0,0 +1,20 @@
+[package]
+name = "sghtmltopdf"
+version = "0.1.0"
+edition = "2021"
+publish = false
+description = "Ruby binding for sghtmltopdf (see bindings/ruby)"
+
+[lib]
+# Rubyの拡張ライブラリ(.so/.bundle)として読み込まれる。
+crate-type = ["cdylib"]
+
+[dependencies]
+# `rb-sys` featureで`AsRawValue`/`FromRawValue`が使えるようになる
+magnus = { version = "0.8", features = ["rb-sys"] }
+# GVL解放(`rb_thread_call_without_gvl`)はmagnusに無いので直接呼ぶ。
+rb-sys = "0.9"
+# HTTPサーバ(tiny_http)は要らないので`server` featureは外す。
+sghtmltopdf-core = { path = "../../../../core", default-features = false, features = [
+    "cli",
+] }

data/ext/sghtmltopdf/extconf.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "mkmf"
+require "rb_sys/mkmf"
+
+core = File.expand_path("../../../../core", __dir__)
+unless File.exist?(File.join(core, "Cargo.toml"))
+  abort <<~MESSAGE
+    sghtmltopdf: Rustコア(#{core})が見つかりません。
+
+    このgemは対応プラットフォーム向けのprecompiled gemとして配布しています。
+    お使いの環境(#{RUBY_PLATFORM} / ruby #{RUBY_VERSION})向けのビルド済みgemが
+    無いためソースからのビルドが試みられましたが、ソースgemにはRustコアが
+    含まれていないためビルドできません。
+
+    対応プラットフォーム: x86_64-linux / aarch64-linux / x86_64-linux-musl / aarch64-linux-musl / arm64-darwin
+  MESSAGE
+end
+
+# `lib/sghtmltopdf/sghtmltopdf.so`として作る。
+create_rust_makefile("sghtmltopdf/sghtmltopdf")

data/ext/sghtmltopdf/src/callback_sink.rs

@@ -0,0 +1,323 @@
+//! 確定したPDFのバイト列を、Rubyのブロックへチャンクごとに渡す仕組み。
+//!
+//! # スレッドの分け方
+//!
+//! レンダリングはDOMの深さぶん再帰する(スタイル計算・レイアウト・描画)。
+//! Rubyのスレッドのマシンスタックは既定1MiB(`RubyVM::DEFAULT_PARAMS`の
+//! `thread_machine_stack_size`)しかなく、Pumaのワーカースレッド上でそのまま
+//! 走らせると深さ200弱でスタックを溢れさせる。しかもGVLを解放した状態で
+//! ガードページに触れるため、プロセスが落ちるのではなくスレッドが固まる。
+//!
+//! そこでレンダリングは[`sghtmltopdf_core::cli::STACK_SIZE`]のスタックを
+//! 明示的に確保した専用スレッドで走らせ、確定したチャンクはチャネル越しに
+//! 元のスレッドへ渡す。Rubyへ触れるのは元のスレッドだけに限る。
+//!
+//! ```text
+//! 元のスレッド(Rubyが作った / GVL解放中)     レンダリングスレッド(16MiB)
+//!   recv(chunk)  <---------- chunk ----------  Sink::write
+//!   with_gvl { block.call(chunk) }
+//!   send(ack)    ------------ ack ---------->  (次のチャンクへ)
+//! ```
+//!
+//! この向きでないと成立しない: [`crate::gvl::with_gvl`]の
+//! `rb_thread_call_with_gvl`は「そのスレッドが`rb_thread_call_without_gvl`で
+//! GVLを手放している」ことが前提で、Rubyの知らないスレッドから呼ぶことは
+//! できない。だからレンダリングスレッドはRubyに一切触れない。
+
+use std::io;
+use std::sync::mpsc::{Receiver, SyncSender};
+
+use magnus::rb_sys::{AsRawValue, FromRawValue};
+use magnus::{block::Proc, Error, ExceptionClass, RString, Ruby, Value};
+use rb_sys::VALUE;
+use sghtmltopdf_core::sink::Sink;
+
+use crate::gvl;
+
+/// ブロックが中断したときに`Sink::write`が返すエラー。
+///
+/// `convert::render`が`Sink<Output = (), Error = io::Error>`を要求するため、
+/// Ruby由来の情報をエラーの型に載せられない。本当の理由は
+/// [`PendingUnwind`]へ置き、こちらは「巻き戻すための合図」として使う。
+fn interrupted() -> io::Error {
+    io::Error::other("Rubyのブロックが中断しました")
+}
+
+/// `rb_gc_register_address`でGCから守った`VALUE`の置き場。
+///
+/// Rubyの保守的GCはマシンスタックを走査してVALUEを見つけるが、
+/// GVLを解放した時点のスタック位置までしか走査しない
+/// (解放時にマシンコンテキストが保存されるため)。`without_gvl`の内側で
+/// スタックに積んだ値はその先にあるので走査されない。解放区間をまたいで
+/// 生かしたいVALUEは、必ずここへ登録する。
+///
+/// 登録アドレスは`Box`で固定する。GCのコンパクションでオブジェクトが移動
+/// しても、登録したアドレスの中身は更新されるため、古い参照を掴まない。
+pub struct ValueSlot {
+    slot: Box<VALUE>,
+}
+
+impl ValueSlot {
+    pub fn new(value: VALUE) -> Self {
+        let mut slot = Box::new(value);
+        unsafe { rb_sys::rb_gc_register_address(&mut *slot) };
+        Self { slot }
+    }
+
+    /// GC登録済みスロットのアドレス。
+    pub fn addr(&self) -> *mut VALUE {
+        &*self.slot as *const VALUE as *mut VALUE
+    }
+
+    /// 現在の`VALUE`。GVLを保持している間だけ呼ぶこと。
+    pub fn get(&self) -> VALUE {
+        *self.slot
+    }
+}
+
+impl Drop for ValueSlot {
+    fn drop(&mut self) {
+        unsafe { rb_sys::rb_gc_unregister_address(&mut *self.slot) };
+    }
+}
+
+/// GVL解放区間へ運ぶための、[`ValueSlot`]のアドレス。
+#[derive(Clone, Copy)]
+pub struct BlockSlot(*mut VALUE);
+
+// SAFETY: 解放区間ではアドレスを数値として持ち回るだけで、`VALUE`として
+// 読むのは`with_gvl`の内側(＝GVLを保持している間)に限る。指す先は
+// `ValueSlot`がGCに登録済みで、`without_gvl`が返るまで生きている。
+unsafe impl Send for BlockSlot {}
+
+impl BlockSlot {
+    pub fn new(slot: &ValueSlot) -> Self {
+        Self(slot.addr())
+    }
+
+    /// GVLを保持している前提で`Proc`へ戻す。
+    fn proc(self) -> Option<Proc> {
+        let value = unsafe { Value::from_raw(*self.0) };
+        Proc::from_value(value)
+    }
+}
+
+/// ブロックが投げた例外・脱出を、GVL解放区間の外へ運ぶための受け皿。
+#[derive(Default)]
+pub struct PendingUnwind {
+    unwind: Option<Unwind>,
+}
+
+enum Unwind {
+    /// Rubyの例外オブジェクト。
+    Exception(ValueSlot),
+    /// Rust側(magnus)が組み立てたエラー。クラスとメッセージを別々に運ぶ。
+    Raise { class: ValueSlot, message: String },
+    /// `break`・`return`・`throw`など。値は`rb_jump_tag`へ渡すタグ。
+    Jump(i32),
+}
+
+impl PendingUnwind {
+    /// ブロックが中断していれば`true`。
+    pub fn is_pending(&self) -> bool {
+        self.unwind.is_some()
+    }
+
+    /// magnusの`Error`を、解放区間をまたげる形に変換して保存する。
+    /// GVLを保持している間に呼ぶこと(GCへの登録を行うため)。
+    fn store(&mut self, error: Error) {
+        use magnus::error::ErrorType;
+
+        let unwind = match error.error_type() {
+            ErrorType::Jump(tag) => Unwind::Jump(*tag as i32),
+            ErrorType::Error(class, message) => Unwind::Raise {
+                class: ValueSlot::new(class.as_raw()),
+                message: message.to_string(),
+            },
+            ErrorType::Exception(exception) => {
+                Unwind::Exception(ValueSlot::new(exception.as_raw()))
+            }
+        };
+        self.unwind = Some(unwind);
+    }
+
+    /// 保存した中断をRubyへ返す。GVLを保持している間に呼ぶこと。
+    ///
+    /// `break`などの脱出は`rb_jump_tag`で忠実に伝播させる。この関数は
+    /// そこから戻らないため、Rust側の後始末が済んでから呼ぶこと
+    /// (`ValueSlot`のGC登録解除もこの関数の中で済ませてある)。
+    pub fn into_error(self) -> Option<Error> {
+        match self.unwind? {
+            Unwind::Exception(slot) => {
+                let value = unsafe { Value::from_raw(slot.get()) };
+                // 登録を外すのは`Error`を組み立てたあと。ここから先は
+                // 呼び出し元がGVLを保持したままRubyへ戻るので、
+                // 保守的GCの走査範囲に入る。
+                let error = magnus::Exception::from_value(value).map(Error::from);
+                drop(slot);
+                Some(error.unwrap_or_else(|| {
+                    Error::new(
+                        Ruby::get()
+                            .expect("GVLを保持したまま呼ばれるはず")
+                            .exception_runtime_error(),
+                        "ブロックが投げた例外を復元できませんでした",
+                    )
+                }))
+            }
+            Unwind::Raise { class, message } => {
+                let value = unsafe { Value::from_raw(class.get()) };
+                let error = ExceptionClass::from_value(value).map(|c| Error::new(c, message));
+                drop(class);
+                Some(error.unwrap_or_else(|| {
+                    Error::new(
+                        Ruby::get()
+                            .expect("GVLを保持したまま呼ばれるはず")
+                            .exception_runtime_error(),
+                        "ブロックの中断を復元できませんでした",
+                    )
+                }))
+            }
+            // `rb_jump_tag`は戻らない(`-> !`)。`self`の他のフィールドは
+            // ここまでで全部落ちている。
+            Unwind::Jump(tag) => unsafe { rb_sys::rb_jump_tag(tag) },
+        }
+    }
+}
+
+/// 確定したバイト列を`chunk_size`ごとにチャネルへ流すSink。
+///
+/// レンダリングスレッド側で使う。Rubyには一切触れないので、`Send`であり
+/// GVLの制約とも無縁。1チャンク送るごとに受け取り側の応答を待つ
+/// (rendezvous)ことで、ブロックの処理より先に走ってメモリを溜め込まない。
+pub struct ChannelSink {
+    chunks: SyncSender<Vec<u8>>,
+    ack: Receiver<bool>,
+    buf: Vec<u8>,
+    chunk_size: usize,
+}
+
+impl ChannelSink {
+    fn new(chunks: SyncSender<Vec<u8>>, ack: Receiver<bool>, chunk_size: usize) -> Self {
+        Self {
+            chunks,
+            ack,
+            buf: Vec::new(),
+            // 0だと1バイトごとにGVLを取り直すことになるため下限を設ける。
+            chunk_size: chunk_size.max(1),
+        }
+    }
+
+    /// 1チャンク渡して、ブロックが受け取り終えるまで待つ。
+    ///
+    /// 送れない(受け取り側が降りた)場合と、ブロックが中断を返した場合は
+    /// どちらも[`interrupted`]で巻き戻す。中断の本当の理由は受け取り側の
+    /// [`PendingUnwind`]に入っている。
+    fn hand_off(&mut self, chunk: Vec<u8>) -> Result<(), io::Error> {
+        if self.chunks.send(chunk).is_err() {
+            return Err(interrupted());
+        }
+        match self.ack.recv() {
+            Ok(true) => Ok(()),
+            _ => Err(interrupted()),
+        }
+    }
+}
+
+impl Sink for ChannelSink {
+    type Output = ();
+    type Error = io::Error;
+
+    fn write(&mut self, bytes: &[u8]) -> Result<(), io::Error> {
+        self.buf.extend_from_slice(bytes);
+        while self.buf.len() >= self.chunk_size {
+            let chunk: Vec<u8> = self.buf.drain(..self.chunk_size).collect();
+            self.hand_off(chunk)?;
+        }
+        Ok(())
+    }
+
+    fn finish(mut self) -> Result<(), io::Error> {
+        if self.buf.is_empty() {
+            return Ok(());
+        }
+        let rest = std::mem::take(&mut self.buf);
+        self.hand_off(rest)
+    }
+}
+
+/// 1チャンクをRubyのブロックへ渡す。中断したら`false`を返す。
+///
+/// GVLを取り戻すのはこの中だけ。ブロックの呼び出しはmagnusの`Proc::call`が
+/// 内部で`rb_protect`しているので、例外が出てもlongjmpがRustのフレームを
+/// 飛び越えない。
+///
+/// エラーの保存もこの区間の中で済ませる。`with_gvl`からRubyのオブジェクト
+/// (例外)を持ち出すと、GVLを手放した瞬間にGCのスコープから外れてしまう
+/// ため(`gvl::with_gvl`のドキュメント)。持ち出すのは真偽値だけ。
+fn call_block(block: BlockSlot, pending: &mut PendingUnwind, bytes: Vec<u8>) -> bool {
+    gvl::with_gvl(move || {
+        let ruby = Ruby::get().expect("with_gvlの内側なのでGVLを持っている");
+        let result = match block.proc() {
+            Some(proc) => {
+                let chunk: RString = ruby.str_from_slice(&bytes);
+                proc.call::<_, Value>((chunk,)).map(|_| ())
+            }
+            None => Err(Error::new(
+                ruby.exception_runtime_error(),
+                "ブロックが失われました",
+            )),
+        };
+        match result {
+            Ok(()) => true,
+            Err(error) => {
+                // GCへの登録もGVLを持っているこの場で行う。
+                pending.store(error);
+                false
+            }
+        }
+    })
+}
+
+/// `render`をレンダリング専用スレッドで走らせ、出てきたチャンクをこのスレッド
+/// からRubyのブロックへ渡し続ける。
+///
+/// GVLを解放している区間(`without_gvl`の内側)から、その解放したスレッド上で
+/// 呼ぶこと。モジュールdocの図のうち左側がこの関数にあたる。
+pub fn pump_to_block<F>(
+    block: BlockSlot,
+    pending: &mut PendingUnwind,
+    chunk_size: usize,
+    render: F,
+) -> Result<(), sghtmltopdf_core::cli::CliError>
+where
+    F: FnOnce(ChannelSink) -> Result<(), sghtmltopdf_core::cli::CliError> + Send + 'static,
+{
+    use sghtmltopdf_core::cli::{CliError, STACK_SIZE};
+
+    // どちらも容量0のrendezvous。レンダリング側は1チャンクごとに
+    // ブロックの完了を待つ。
+    let (chunk_tx, chunk_rx) = std::sync::mpsc::sync_channel::<Vec<u8>>(0);
+    let (ack_tx, ack_rx) = std::sync::mpsc::sync_channel::<bool>(0);
+
+    let worker = std::thread::Builder::new()
+        .name("sghtmltopdf-render".to_string())
+        .stack_size(STACK_SIZE)
+        .spawn(move || render(ChannelSink::new(chunk_tx, ack_rx, chunk_size)))
+        .map_err(|e| CliError::Input(format!("レンダリングスレッドを作れません: {e}")))?;
+
+    while let Ok(chunk) = chunk_rx.recv() {
+        let ok = call_block(block, pending, chunk);
+        // 応答を返せない(レンダリング側が既に降りた)場合も抜ける。
+        if ack_tx.send(ok).is_err() || !ok {
+            break;
+        }
+    }
+    // 中断で抜けた場合、レンダリング側が次のsendでエラーになって巻き戻れる
+    // よう、受け口を先に落とす。
+    drop(chunk_rx);
+    drop(ack_tx);
+
+    worker
+        .join()
+        .unwrap_or_else(|panic| std::panic::resume_unwind(panic))
+}

data/ext/sghtmltopdf/src/errors.rs

@@ -0,0 +1,77 @@
+//! Rubyの例外クラスと、コアの[`CliError`]からの対応付け。
+
+use std::panic::AssertUnwindSafe;
+
+use magnus::{prelude::*, ExceptionClass, RModule, Ruby};
+use sghtmltopdf_core::cli::CliError;
+
+pub fn define(ruby: &Ruby, module: RModule) -> Result<(), magnus::Error> {
+    let base = module.define_error("Error", ruby.exception_standard_error())?;
+    module.define_error("UsageError", base)?;
+    module.define_error("InputError", base)?;
+    module.define_error("RenderError", base)?;
+    module.define_error("TimeoutError", base)?;
+    module.define_error("InternalError", base)?;
+    Ok(())
+}
+
+/// Rustのパニックを`Sghtmltopdf::InternalError`へ変換して`f`を実行する。
+///
+/// # なぜ自前で捕まえるか
+///
+/// magnusもメソッド呼び出しをパニックから守っており、プロセスがabortする
+/// ことはない。ただしmagnusが変換する先はRubyの`fatal`で、これは
+/// `rescue Exception`でも捕まえられずプロセスが終了する。Webアプリの中で
+/// 1リクエストぶんのバグのためにワーカーごと落ちるのは困るので、
+/// magnusへ渡る前にここで`StandardError`の子孫へ変換する。
+///
+/// パニックはコアの不具合を意味するので、握りつぶさずメッセージを残す。
+pub fn catch_panic<F, R>(ruby: &Ruby, f: F) -> Result<R, magnus::Error>
+where
+    F: FnOnce() -> Result<R, magnus::Error>,
+{
+    // AssertUnwindSafe: パニックで巻き戻った後に触るのはRuby側の例外生成だけで、
+    // Rust側の壊れかけた状態を読み直すことはない。
+    match std::panic::catch_unwind(AssertUnwindSafe(f)) {
+        Ok(result) => result,
+        Err(payload) => Err(magnus::Error::new(
+            class(ruby, "InternalError"),
+            format!("内部エラー(パニック): {}", panic_message(&payload)),
+        )),
+    }
+}
+
+/// パニックのペイロードから人が読めるメッセージを取り出す。
+fn panic_message(payload: &Box<dyn std::any::Any + Send>) -> String {
+    if let Some(message) = payload.downcast_ref::<&'static str>() {
+        (*message).to_string()
+    } else if let Some(message) = payload.downcast_ref::<String>() {
+        message.clone()
+    } else {
+        "詳細不明".to_string()
+    }
+}
+
+/// コアのエラーを、対応するRubyの例外へ変換する。
+///
+/// メッセージはコアが返す文言をそのまま使う（CLIと同じ文言になる）。
+pub fn to_ruby(ruby: &Ruby, error: CliError) -> magnus::Error {
+    let (class_name, message) = match error {
+        CliError::Usage(message) => ("UsageError", message),
+        CliError::Input(message) => ("InputError", message),
+        CliError::Render(message) => ("RenderError", message),
+        CliError::Timeout(message) => ("TimeoutError", message),
+    };
+    magnus::Error::new(class(ruby, class_name), message)
+}
+
+/// `Sghtmltopdf::<name>`の例外クラスを引く。
+///
+/// 定義は`.so`のロード時に済んでいる（[`define`]）。万一引けなかった場合は
+/// エラーを握りつぶさずに`RuntimeError`として上げる。
+pub fn class(ruby: &Ruby, name: &str) -> ExceptionClass {
+    ruby.class_object()
+        .const_get::<_, RModule>("Sghtmltopdf")
+        .and_then(|module| module.const_get::<_, ExceptionClass>(name))
+        .unwrap_or_else(|_| ruby.exception_runtime_error())
+}