sghtmltopdf 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f317db9c1a48c59df592601e2246186da7539007f19859be3ebbf6c057283bb
-  data.tar.gz: 10d371ed48aa9b6772c840a75d4cc9e456468c783cae83ee95a0b73588b345a1
+  metadata.gz: c1679b41d8745afc3af14b9ea754429a5c9f895b770af172cbbdfba5af87658d
+  data.tar.gz: 3a176472e76010d1aa22a365f71b02c0c8ffe1461a1e05518f1a7f7bc8180d7c
 SHA512:
-  metadata.gz: ba289e596824c8cbc3a259bd1adfd9397e47c333cdbcefeff1d8e33ae512c64ec197a67d98f5f90a35f46cefc833b837b0348e6625dd69e03ff732a717844d3b
-  data.tar.gz: 9f6f870dee5e361e175d19d778d3129d416814cb7c7ae0092afe95e59f6469a1f43cbe24a5fa0e9a719c39ee406cb157cbf50285a64a67760f761705558dd9e1
+  metadata.gz: 401481476fb5d2dd13aadbac6b5d1e4fe2280826bfb38b6d20be486e825a78a938536821b1a8338273ccf9f5d51317e1cdc1eb557fb779b97a9a32400f9190e3
+  data.tar.gz: 4d9002823ff97d3b625be63065c5547269eb7ffde84e65b1eabfef57d92ad0f033539be96a66dd1b1e761dc3bfbfc1ae02f71c7549708dc87f1c77c72f62300a

data/Cargo.lock

@@ -927,9 +927,9 @@ dependencies = [
 
 [[package]]
 name = "rustls"
-version = "0.23.42"
+version = "0.23.45"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3c54fcab019b409d04215d3a17cb438fd7fbf192ee61461f20f4fe18704bc138"
+checksum = "0d41d731c7d2f962d1ccc364cec258de3c0e93b38c2fb3ba97ac74513048d634"
 dependencies = [
  "log",
  "once_cell",
@@ -951,9 +951,9 @@ dependencies = [
 
 [[package]]
 name = "rustls-webpki"
-version = "0.103.13"
+version = "0.103.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "61c429a8649f110dddef65e2a5ad240f747e85f7758a6bccc7e5777bd33f756e"
+checksum = "f3c3cf1d8b1e7d4927e2d154c3fcb02979afb9939629c62cd9048d4f07b60ac2"
 dependencies = [
  "ring",
  "rustls-pki-types",
@@ -1050,16 +1050,7 @@ dependencies = [
 
 [[package]]
 name = "sghtmltopdf"
-version = "0.4.0"
-dependencies = [
- "magnus",
- "rb-sys",
- "sghtmltopdf-core",
-]
-
-[[package]]
-name = "sghtmltopdf-core"
-version = "0.4.0"
+version = "0.5.1"
 dependencies = [
  "base64",
  "clap",
@@ -1084,6 +1075,15 @@ dependencies = [
  "ureq",
 ]
 
+[[package]]
+name = "sghtmltopdf-ruby"
+version = "0.5.1"
+dependencies = [
+ "magnus",
+ "rb-sys",
+ "sghtmltopdf",
+]
+
 [[package]]
 name = "shell-words"
 version = "1.1.1"

data/README.md

@@ -13,10 +13,10 @@ The engine runs inside your process through a native extension (magnus + rb-sys)
 gem "sghtmltopdf"
 ```
 
-Precompiled native gems are published for `x86_64-linux`, `aarch64-linux`, `x86_64-linux-musl`, `aarch64-linux-musl`, and `arm64-darwin`.
+Precompiled native gems are published for `x86_64-linux`, `aarch64-linux`, `x86_64-linux-musl`, `aarch64-linux-musl`, `arm64-darwin`, and `x86_64-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.
+Elsewhere (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.
@@ -38,6 +38,31 @@ 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.

data/ext/sghtmltopdf/Cargo.toml

@@ -1,22 +1,28 @@
 [package]
-name = "sghtmltopdf"
-version = "0.4.0"
+# The package name differs from the library name on purpose: the core crate is published as
+# `sghtmltopdf`, and two packages with the same name cannot be written to one lockfile.
+name = "sghtmltopdf-ruby"
+version = "0.5.1"
 edition = "2021"
 publish = false
 description = "Ruby binding for sghtmltopdf (see bindings/ruby)"
 
 [lib]
-# Rubyの拡張ライブラリ(.so/.bundle)として読み込まれる。
+# Loaded as a Ruby extension library (.so/.bundle). The name has to stay `sghtmltopdf`:
+# rb_sys looks for `libsghtmltopdf.so` (it derives that from the gem name) and
+# `Init_sghtmltopdf` is the entry point Ruby calls.
+name = "sghtmltopdf"
 crate-type = ["cdylib"]
 
 [dependencies]
-# `rb-sys` featureで`AsRawValue`/`FromRawValue`が使えるようになる
+# The `rb-sys` feature is what makes `AsRawValue`/`FromRawValue` available.
 magnus = { version = "0.8", features = ["rb-sys"] }
-# GVL解放(`rb_thread_call_without_gvl`)はmagnusに無いので直接呼ぶ。
+# magnus has no way to release the GVL (`rb_thread_call_without_gvl`), so we call it directly.
 rb-sys = "0.9"
-# HTTPサーバ(tiny_http)は要らないので`server` featureは外す。
-# `svg`はCLIと同じ既定に揃える(gemからもSVGを描画できるようにする)。
-sghtmltopdf-core = { path = "../../../../core", default-features = false, features = [
+# The HTTP server (tiny_http) is not needed here, so the `server` feature is left out.
+# `svg` matches the CLI default, so the gem can render SVG too.
+# Renamed on import so that the `sghtmltopdf_core::` paths in the source stay as they are.
+sghtmltopdf_core = { package = "sghtmltopdf", path = "../../../../core", default-features = false, features = [
     "cli",
     "svg",
 ] }

data/ext/sghtmltopdf/extconf.rb

@@ -6,16 +6,16 @@ require "rb_sys/mkmf"
 core = File.expand_path("../../../../core", __dir__)
 unless File.exist?(File.join(core, "Cargo.toml"))
   abort <<~MESSAGE
-    sghtmltopdf: Rustコア(#{core})が見つかりません。
+    sghtmltopdf: the Rust core (#{core}) was not found.
 
-    このgemは対応プラットフォーム向けのprecompiled gemとして配布しています。
-    お使いの環境(#{RUBY_PLATFORM} / ruby #{RUBY_VERSION})向けのビルド済みgemが
-    無いためソースからのビルドが試みられましたが、ソースgemにはRustコアが
-    含まれていないためビルドできません。
+    This gem is distributed as a precompiled gem for the supported platforms.
+    No prebuilt gem exists for your environment (#{RUBY_PLATFORM} / ruby #{RUBY_VERSION}),
+    so a build from source was attempted, but the source gem does not include the
+    Rust core and cannot be built.
 
-    対応プラットフォーム: x86_64-linux / aarch64-linux / x86_64-linux-musl / aarch64-linux-musl / arm64-darwin
+    Supported platforms: x86_64-linux / aarch64-linux / x86_64-linux-musl / aarch64-linux-musl / arm64-darwin / x86_64-darwin
   MESSAGE
 end
 
-# `lib/sghtmltopdf/sghtmltopdf.so`として作る。
+# Built as `lib/sghtmltopdf/sghtmltopdf.so`.
 create_rust_makefile("sghtmltopdf/sghtmltopdf")

data/ext/sghtmltopdf/src/callback_sink.rs

@@ -1,28 +1,28 @@
-//! 確定したPDFのバイト列を、Rubyのブロックへチャンクごとに渡す仕組み。
+//! Handing the settled PDF bytes to a Ruby block, chunk by chunk.
 //!
-//! # スレッドの分け方
+//! # How the threads are split
 //!
-//! レンダリングはDOMの深さぶん再帰する(スタイル計算・レイアウト・描画)。
-//! Rubyのスレッドのマシンスタックは既定1MiB(`RubyVM::DEFAULT_PARAMS`の
-//! `thread_machine_stack_size`)しかなく、Pumaのワーカースレッド上でそのまま
-//! 走らせると深さ200弱でスタックを溢れさせる。しかもGVLを解放した状態で
-//! ガードページに触れるため、プロセスが落ちるのではなくスレッドが固まる。
+//! Rendering recurses as deep as the DOM (style computation, layout, drawing).
+//! A Ruby thread's machine stack is 1MiB by default (`thread_machine_stack_size` in
+//! `RubyVM::DEFAULT_PARAMS`), so running it directly on a Puma worker thread overflows the
+//! stack at a depth just under 200. Worse, it touches the guard page with the GVL released,
+//! so rather than the process dying the thread hangs.
 //!
-//! そこでレンダリングは[`sghtmltopdf_core::render_stack::STACK_SIZE`]のスタックを
-//! 明示的に確保した専用スレッドで走らせ、確定したチャンクはチャネル越しに
-//! 元のスレッドへ渡す。Rubyへ触れるのは元のスレッドだけに限る。
+//! So rendering runs on a dedicated thread with a
+//! [`sghtmltopdf_core::STACK_SIZE`] stack allocated explicitly, and the settled
+//! chunks are passed back to the original thread over a channel. Only the original thread ever touches Ruby.
 //!
 //! ```text
-//! 元のスレッド(Rubyが作った / GVL解放中)     レンダリングスレッド(16MiB)
+//! original thread (Ruby's, GVL released)      rendering thread (16MiB)
 //!   recv(chunk)  <---------- chunk ----------  Sink::write
 //!   with_gvl { block.call(chunk) }
-//!   send(ack)    ------------ ack ---------->  (次のチャンクへ)
+//!   send(ack)    ------------ ack ---------->  (on to the next chunk)
 //! ```
 //!
-//! この向きでないと成立しない: [`crate::gvl::with_gvl`]の
-//! `rb_thread_call_with_gvl`は「そのスレッドが`rb_thread_call_without_gvl`で
-//! GVLを手放している」ことが前提で、Rubyの知らないスレッドから呼ぶことは
-//! できない。だからレンダリングスレッドはRubyに一切触れない。
+//! It only works this way round: [`crate::gvl::with_gvl`]'s `rb_thread_call_with_gvl`
+//! assumes "this thread released the GVL through `rb_thread_call_without_gvl`" and cannot
+//! be called from a thread Ruby does not know about. So the rendering thread never touches
+//! Ruby at all.
 
 use std::io;
 use std::sync::mpsc::{Receiver, SyncSender};
@@ -30,29 +30,28 @@ 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 sghtmltopdf_core::Sink;
 
 use crate::gvl;
 
-/// ブロックが中断したときに`Sink::write`が返すエラー。
+/// The error `Sink::write` returns when the block was interrupted.
 ///
-/// `convert::render`が`Sink<Output = (), Error = io::Error>`を要求するため、
-/// Ruby由来の情報をエラーの型に載せられない。本当の理由は
-/// [`PendingUnwind`]へ置き、こちらは「巻き戻すための合図」として使う。
+/// `convert::render` requires `Sink<Output = (), Error = io::Error>`, so no Ruby-derived
+/// information can ride on the error type. The real reason is put in [`PendingUnwind`] and
+/// this is used purely as "the signal to unwind".
 fn interrupted() -> io::Error {
-    io::Error::other("Rubyのブロックが中断しました")
+    io::Error::other("the Ruby block was interrupted")
 }
 
-/// `rb_gc_register_address`でGCから守った`VALUE`の置き場。
+/// Somewhere to keep a `VALUE` protected from the GC with `rb_gc_register_address`.
 ///
-/// Rubyの保守的GCはマシンスタックを走査してVALUEを見つけるが、
-/// GVLを解放した時点のスタック位置までしか走査しない
-/// (解放時にマシンコンテキストが保存されるため)。`without_gvl`の内側で
-/// スタックに積んだ値はその先にあるので走査されない。解放区間をまたいで
-/// 生かしたいVALUEは、必ずここへ登録する。
+/// Ruby's conservative GC scans the machine stack to find VALUEs, but only as far as the
+/// stack position at the moment the GVL was released (the machine context being saved then).
+/// A value pushed onto the stack inside `without_gvl` lies beyond that and is not scanned.
+/// Any VALUE that must survive across the released region has to be registered here.
 ///
-/// 登録アドレスは`Box`で固定する。GCのコンパクションでオブジェクトが移動
-/// しても、登録したアドレスの中身は更新されるため、古い参照を掴まない。
+/// The registered address is pinned with a `Box`. Even when GC compaction moves the object,
+/// the contents at the registered address are updated, so no stale reference is held.
 pub struct ValueSlot {
     slot: Box<VALUE>,
 }
@@ -64,12 +63,12 @@ impl ValueSlot {
         Self { slot }
     }
 
-    /// GC登録済みスロットのアドレス。
+    /// The address of the GC-registered slot.
     pub fn addr(&self) -> *mut VALUE {
         &*self.slot as *const VALUE as *mut VALUE
     }
 
-    /// 現在の`VALUE`。GVLを保持している間だけ呼ぶこと。
+    /// The current `VALUE`. Call only while holding the GVL.
     pub fn get(&self) -> VALUE {
         *self.slot
     }
@@ -81,13 +80,13 @@ impl Drop for ValueSlot {
     }
 }
 
-/// GVL解放区間へ運ぶための、[`ValueSlot`]のアドレス。
+/// The address of a [`ValueSlot`], for carrying into a GVL-released region.
 #[derive(Clone, Copy)]
 pub struct BlockSlot(*mut VALUE);
 
-// SAFETY: 解放区間ではアドレスを数値として持ち回るだけで、`VALUE`として
-// 読むのは`with_gvl`の内側(＝GVLを保持している間)に限る。指す先は
-// `ValueSlot`がGCに登録済みで、`without_gvl`が返るまで生きている。
+// SAFETY: in the released region the address is only carried around as a number; it is read
+// as a `VALUE` only inside `with_gvl` (that is, while holding the GVL). What it points at is
+// a `ValueSlot` registered with the GC and alive until `without_gvl` returns.
 unsafe impl Send for BlockSlot {}
 
 impl BlockSlot {
@@ -95,36 +94,36 @@ impl BlockSlot {
         Self(slot.addr())
     }
 
-    /// GVLを保持している前提で`Proc`へ戻す。
+    /// Convert back to a `Proc`, assuming the GVL is held.
     fn proc(self) -> Option<Proc> {
         let value = unsafe { Value::from_raw(*self.0) };
         Proc::from_value(value)
     }
 }
 
-/// ブロックが投げた例外・脱出を、GVL解放区間の外へ運ぶための受け皿。
+/// The receptacle for carrying an exception or non-local exit thrown by the block out of the GVL-released region.
 #[derive(Default)]
 pub struct PendingUnwind {
     unwind: Option<Unwind>,
 }
 
 enum Unwind {
-    /// Rubyの例外オブジェクト。
+    /// A Ruby exception object.
     Exception(ValueSlot),
-    /// Rust側(magnus)が組み立てたエラー。クラスとメッセージを別々に運ぶ。
+    /// An error the Rust side (magnus) built. The class and the message are carried separately.
     Raise { class: ValueSlot, message: String },
-    /// `break`・`return`・`throw`など。値は`rb_jump_tag`へ渡すタグ。
+    /// A `break`, `return`, `throw` and so on. The value is the tag passed to `rb_jump_tag`.
     Jump(i32),
 }
 
 impl PendingUnwind {
-    /// ブロックが中断していれば`true`。
+    /// Whether the block was interrupted.
     pub fn is_pending(&self) -> bool {
         self.unwind.is_some()
     }
 
-    /// magnusの`Error`を、解放区間をまたげる形に変換して保存する。
-    /// GVLを保持している間に呼ぶこと(GCへの登録を行うため)。
+    /// Convert a magnus `Error` into a form that can cross the released region and store it.
+    /// Call it while holding the GVL (it registers with the GC).
     fn store(&mut self, error: Error) {
         use magnus::error::ErrorType;
 
@@ -141,26 +140,26 @@ impl PendingUnwind {
         self.unwind = Some(unwind);
     }
 
-    /// 保存した中断をRubyへ返す。GVLを保持している間に呼ぶこと。
+    /// Return the stored interruption to Ruby. Call it while holding the GVL.
     ///
-    /// `break`などの脱出は`rb_jump_tag`で忠実に伝播させる。この関数は
-    /// そこから戻らないため、Rust側の後始末が済んでから呼ぶこと
-    /// (`ValueSlot`のGC登録解除もこの関数の中で済ませてある)。
+    /// A non-local exit such as `break` is propagated faithfully with `rb_jump_tag`. This
+    /// function does not return, so call it once the Rust-side cleanup is done
+    /// (deregistering the `ValueSlot` from the GC is already handled inside it).
     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の走査範囲に入る。
+                // Deregistration happens after the `Error` is built. From here on the caller
+                // returns to Ruby still holding the GVL, so it is within the conservative
+                // GC's scanning range.
                 let error = magnus::Exception::from_value(value).map(Error::from);
                 drop(slot);
                 Some(error.unwrap_or_else(|| {
                     Error::new(
                         Ruby::get()
-                            .expect("GVLを保持したまま呼ばれるはず")
+                            .expect("it should be called while holding the GVL")
                             .exception_runtime_error(),
-                        "ブロックが投げた例外を復元できませんでした",
+                        "could not restore the exception the block threw",
                     )
                 }))
             }
@@ -171,24 +170,24 @@ impl PendingUnwind {
                 Some(error.unwrap_or_else(|| {
                     Error::new(
                         Ruby::get()
-                            .expect("GVLを保持したまま呼ばれるはず")
+                            .expect("it should be called while holding the GVL")
                             .exception_runtime_error(),
-                        "ブロックの中断を復元できませんでした",
+                        "could not restore the block's interruption",
                     )
                 }))
             }
-            // `rb_jump_tag`は戻らない(`-> !`)。`self`の他のフィールドは
-            // ここまでで全部落ちている。
+            // `rb_jump_tag` does not return (`-> !`). Every other field of `self` has already
+            // been dropped by this point.
             Unwind::Jump(tag) => unsafe { rb_sys::rb_jump_tag(tag) },
         }
     }
 }
 
-/// 確定したバイト列を`chunk_size`ごとにチャネルへ流すSink。
+/// A Sink streaming the settled bytes to a channel in `chunk_size` pieces.
 ///
-/// レンダリングスレッド側で使う。Rubyには一切触れないので、`Send`であり
-/// GVLの制約とも無縁。1チャンク送るごとに受け取り側の応答を待つ
-/// (rendezvous)ことで、ブロックの処理より先に走ってメモリを溜め込まない。
+/// Used on the rendering thread. It never touches Ruby, so it is `Send` and free of the
+/// GVL's constraints. It waits for the receiving side's acknowledgement after every chunk
+/// (a rendezvous), so it cannot run ahead of the block's processing and pile up memory.
 pub struct ChannelSink {
     chunks: SyncSender<Vec<u8>>,
     ack: Receiver<bool>,
@@ -202,16 +201,16 @@ impl ChannelSink {
             chunks,
             ack,
             buf: Vec::new(),
-            // 0だと1バイトごとにGVLを取り直すことになるため下限を設ける。
+            // At 0 the GVL would be reacquired for every byte, hence the lower bound.
             chunk_size: chunk_size.max(1),
         }
     }
 
-    /// 1チャンク渡して、ブロックが受け取り終えるまで待つ。
+    /// Hand over one chunk and wait until the block has finished receiving it.
     ///
-    /// 送れない(受け取り側が降りた)場合と、ブロックが中断を返した場合は
-    /// どちらも[`interrupted`]で巻き戻す。中断の本当の理由は受け取り側の
-    /// [`PendingUnwind`]に入っている。
+    /// Both being unable to send (the receiver went away) and the block returning an
+    /// interruption unwind through [`interrupted`]. The real reason for the interruption is
+    /// in the receiver's [`PendingUnwind`].
     fn hand_off(&mut self, chunk: Vec<u8>) -> Result<(), io::Error> {
         if self.chunks.send(chunk).is_err() {
             return Err(interrupted());
@@ -245,18 +244,18 @@ impl Sink for ChannelSink {
     }
 }
 
-/// 1チャンクをRubyのブロックへ渡す。中断したら`false`を返す。
+/// Hand one chunk to the Ruby block. Returns `false` on an interruption.
 ///
-/// GVLを取り戻すのはこの中だけ。ブロックの呼び出しはmagnusの`Proc::call`が
-/// 内部で`rb_protect`しているので、例外が出てもlongjmpがRustのフレームを
-/// 飛び越えない。
+/// This is the only place the GVL is reacquired. The block call goes through magnus's
+/// `Proc::call`, which wraps it in `rb_protect` internally, so an exception's longjmp cannot
+/// jump over a Rust frame.
 ///
-/// エラーの保存もこの区間の中で済ませる。`with_gvl`からRubyのオブジェクト
-/// (例外)を持ち出すと、GVLを手放した瞬間にGCのスコープから外れてしまう
-/// ため(`gvl::with_gvl`のドキュメント)。持ち出すのは真偽値だけ。
+/// Storing the error also happens inside this region. Carrying a Ruby object (an exception)
+/// out of `with_gvl` would put it outside the GC's scope the moment the GVL is released
+/// (see the documentation of `gvl::with_gvl`). Only a boolean is carried out.
 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 ruby = Ruby::get().expect("inside with_gvl, so the GVL is held");
         let result = match block.proc() {
             Some(proc) => {
                 let chunk: RString = ruby.str_from_slice(&bytes);
@@ -264,13 +263,13 @@ fn call_block(block: BlockSlot, pending: &mut PendingUnwind, bytes: Vec<u8>) ->
             }
             None => Err(Error::new(
                 ruby.exception_runtime_error(),
-                "ブロックが失われました",
+                "the block was lost",
             )),
         };
         match result {
             Ok(()) => true,
             Err(error) => {
-                // GCへの登録もGVLを持っているこの場で行う。
+                // Registering with the GC also happens here, while the GVL is held.
                 pending.store(error);
                 false
             }
@@ -278,25 +277,25 @@ fn call_block(block: BlockSlot, pending: &mut PendingUnwind, bytes: Vec<u8>) ->
     })
 }
 
-/// `render`をレンダリング専用スレッドで走らせ、出てきたチャンクをこのスレッド
-/// からRubyのブロックへ渡し続ける。
+/// Run `render` on a dedicated rendering thread and keep handing the chunks it produces to
+/// the Ruby block from this thread.
 ///
-/// GVLを解放している区間(`without_gvl`の内側)から、その解放したスレッド上で
-/// 呼ぶこと。モジュールdocの図のうち左側がこの関数にあたる。
+/// Call it from inside a GVL-released region (inside `without_gvl`), on the thread that
+/// released it. It is the left-hand side of the diagram in the module docs.
 pub fn pump_to_block<F>(
     block: BlockSlot,
     pending: &mut PendingUnwind,
     chunk_size: usize,
     render: F,
-) -> Result<(), sghtmltopdf_core::cli::CliError>
+) -> Result<(), sghtmltopdf_core::ConvertError>
 where
-    F: FnOnce(ChannelSink) -> Result<(), sghtmltopdf_core::cli::CliError> + Send + 'static,
+    F: FnOnce(ChannelSink) -> Result<(), sghtmltopdf_core::ConvertError> + Send + 'static,
 {
-    use sghtmltopdf_core::cli::CliError;
-    use sghtmltopdf_core::render_stack::STACK_SIZE;
+    use sghtmltopdf_core::ConvertError;
+    use sghtmltopdf_core::STACK_SIZE;
 
-    // どちらも容量0のrendezvous。レンダリング側は1チャンクごとに
-    // ブロックの完了を待つ。
+    // Both are zero-capacity rendezvous channels. The rendering side waits for the block to
+    // finish after every chunk.
     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);
 
@@ -304,17 +303,17 @@ where
         .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}")))?;
+        .map_err(|e| ConvertError::Input(format!("cannot create the rendering thread: {e}")))?;
 
     while let Ok(chunk) = chunk_rx.recv() {
         let ok = call_block(block, pending, chunk);
-        // 応答を返せない(レンダリング側が既に降りた)場合も抜ける。
+        // Also break out when the acknowledgement cannot be sent (the rendering side already went away).
         if ack_tx.send(ok).is_err() || !ok {
             break;
         }
     }
-    // 中断で抜けた場合、レンダリング側が次のsendでエラーになって巻き戻れる
-    // よう、受け口を先に落とす。
+    // On an interruption, drop the receiving end first so the rendering side errors on its
+    // next send and can unwind.
     drop(chunk_rx);
     drop(ack_tx);
 

data/ext/sghtmltopdf/src/errors.rs

@@ -1,9 +1,9 @@
-//! Rubyの例外クラスと、コアの[`CliError`]からの対応付け。
+//! The Ruby exception classes, and the mapping from the core's [`ConvertError`].
 
 use std::panic::AssertUnwindSafe;
 
 use magnus::{prelude::*, ExceptionClass, RModule, Ruby};
-use sghtmltopdf_core::cli::CliError;
+use sghtmltopdf_core::ConvertError;
 
 pub fn define(ruby: &Ruby, module: RModule) -> Result<(), magnus::Error> {
     let base = module.define_error("Error", ruby.exception_standard_error())?;
@@ -15,60 +15,62 @@ pub fn define(ruby: &Ruby, module: RModule) -> Result<(), magnus::Error> {
     Ok(())
 }
 
-/// Rustのパニックを`Sghtmltopdf::InternalError`へ変換して`f`を実行する。
+/// Run `f`, converting a Rust panic into `Sghtmltopdf::InternalError`.
 ///
-/// # なぜ自前で捕まえるか
+/// # Why we catch it ourselves
 ///
-/// magnusもメソッド呼び出しをパニックから守っており、プロセスがabortする
-/// ことはない。ただしmagnusが変換する先はRubyの`fatal`で、これは
-/// `rescue Exception`でも捕まえられずプロセスが終了する。Webアプリの中で
-/// 1リクエストぶんのバグのためにワーカーごと落ちるのは困るので、
-/// magnusへ渡る前にここで`StandardError`の子孫へ変換する。
+/// magnus also guards method calls against panics, so the process does not abort. But what
+/// magnus converts to is Ruby's `fatal`, which not even `rescue Exception` catches and which
+/// terminates the process. Losing a whole worker inside a web application over a bug in one
+/// request is unacceptable, so it is converted to a descendant of `StandardError` here,
+/// before it reaches magnus.
 ///
-/// パニックはコアの不具合を意味するので、握りつぶさずメッセージを残す。
+/// A panic means a bug in the core, so the message is kept rather than swallowed.
 pub fn catch_panic<F, R>(ruby: &Ruby, f: F) -> Result<R, magnus::Error>
 where
     F: FnOnce() -> Result<R, magnus::Error>,
 {
-    // AssertUnwindSafe: パニックで巻き戻った後に触るのはRuby側の例外生成だけで、
-    // Rust側の壊れかけた状態を読み直すことはない。
+    // AssertUnwindSafe: after unwinding from a panic, all that is touched is building the
+    // Ruby-side exception; no half-broken Rust state is read back.
     match std::panic::catch_unwind(AssertUnwindSafe(f)) {
         Ok(result) => result,
         Err(payload) => Err(magnus::Error::new(
             class(ruby, "InternalError"),
-            format!("内部エラー(パニック): {}", panic_message(&payload)),
+            format!("internal error (panic): {}", panic_message(&payload)),
         )),
     }
 }
 
-/// パニックのペイロードから人が読めるメッセージを取り出す。
+/// Extract a human-readable message from a panic 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()
+        "no details".to_string()
     }
 }
 
-/// コアのエラーを、対応するRubyの例外へ変換する。
+/// Convert a core error into the corresponding Ruby exception.
 ///
-/// メッセージはコアが返す文言をそのまま使う（CLIと同じ文言になる）。
-pub fn to_ruby(ruby: &Ruby, error: CliError) -> magnus::Error {
+/// The message is the wording the core returns, verbatim (the same wording as the CLI).
+pub fn to_ruby(ruby: &Ruby, error: ConvertError) -> 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),
+        ConvertError::Usage(message) => ("UsageError", message),
+        ConvertError::Input(message) => ("InputError", message),
+        ConvertError::Render(message) => ("RenderError", message),
+        ConvertError::Timeout(message) => ("TimeoutError", message),
+        // A classification added in a later core release. Surface it rather than hide it.
+        other => ("Error", other.to_string()),
     };
     magnus::Error::new(class(ruby, class_name), message)
 }
 
-/// `Sghtmltopdf::<name>`の例外クラスを引く。
+/// Look up the `Sghtmltopdf::<name>` exception class.
 ///
-/// 定義は`.so`のロード時に済んでいる（[`define`]）。万一引けなかった場合は
-/// エラーを握りつぶさずに`RuntimeError`として上げる。
+/// It is defined when the `.so` is loaded ([`define`]). On the off chance the lookup fails,
+/// the error is raised as a `RuntimeError` rather than swallowed.
 pub fn class(ruby: &Ruby, name: &str) -> ExceptionClass {
     ruby.class_object()
         .const_get::<_, RModule>("Sghtmltopdf")