sghtmltopdf 0.4.0 → 0.5.1

data/lib/sghtmltopdf/renderer.rb

@@ -1,25 +1,25 @@
 # frozen_string_literal: true
 
 module Sghtmltopdf
-  # `render pdf: "invoice"`のオプションを、
+  # Sorts the options of `render pdf: "invoice"` into three groups:
   #
-  # * Railsのビュー描画(`render_to_string`)へ渡すもの
-  # * レスポンスの組み立て(`send_data`)へ渡すもの
-  # * PDF変換(`Sghtmltopdf.render`)へ渡すもの
+  # * those passed to Rails view rendering (`render_to_string`)
+  # * those passed to building the response (`send_data`)
+  # * those passed to PDF conversion (`Sghtmltopdf.render`)
   #
-  # の3つに振り分ける。
-  # Railsに依存しないpure Rubyのクラスなので、Rails無しでも単体テストできる。
+  #
+  # It is a pure Ruby class with no dependency on Rails, so it can be unit tested without Rails.
   class Renderer
-    # `render_to_string`へそのまま渡すキー。
+    # 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
 
-    # レスポンスの組み立てに使うキー(`send_data`へ渡す)。
+    # The keys used to build the response (passed to `send_data`).
     RESPONSE_KEYS = %i[disposition filename status].freeze
 
-    # レンダラ自身が解釈するキー(PDFにせずHTMLのまま返すデバッグ用)。
+    # 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"
@@ -27,17 +27,17 @@ module Sghtmltopdf
 
     attr_reader :name, :options
 
-    # @param name [String, Symbol, nil] `pdf:`に渡された値(ファイル名の素)
-    # @param options [Hash] `render`に渡されたその他のオプション
-    # @param default_name [String, nil] `name`が空のときのファイル名
-    #   (コントローラの`action_name`を想定)
+    # @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
 
-    # `ActionController::Renderers.add(:pdf)`でレンダラを登録する。
-    # RailtieのAction Controller読み込みフック(`on_load`)から呼ぶ。
+    # Register the renderer with `ActionController::Renderers.add(:pdf)`.
+    # Called from the Railtie's Action Controller load hook (`on_load`).
     def self.register!
       ::ActionController::Renderers.add(:pdf) do |name, options|
         renderer = ::Sghtmltopdf::Renderer.new(name, options, default_name: action_name)
@@ -46,18 +46,18 @@ module Sghtmltopdf
       end
     end
 
-    # ビューの描画に使うオプション。
+    # The options used to render the view.
     def render_options
       options.select { |key, _| RAILS_RENDER_KEYS.include?(key) }
     end
 
-    # PDF変換に使うオプション。
+    # 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
 
-    # 描画したHTMLをレスポンスの本文へ変換する。
+    # Turn the rendered HTML into the response body.
     def body_for(html)
       show_as_html? ? html : Sghtmltopdf.render(html, **convert_options)
     end
@@ -73,19 +73,19 @@ module Sghtmltopdf
       show_as_html? ? HTML_CONTENT_TYPE : PDF_CONTENT_TYPE
     end
 
-    # `filename: "x.pdf"` > `pdf: "x"` の順。拡張子は二重に付けない。
+    # `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
 
-    # wicked_pdfと同じく既定は`inline`(ブラウザ内で開く)。
+    # The default is `inline` (opened in the browser), as in wicked_pdf.
     def disposition
       blank?(options[:disposition]) ? "inline" : options[:disposition].to_s
     end
 
-    # wicked_pdfの`show_as_html`相当。PDFにせずHTMLをそのまま返すので、
-    # ブラウザの開発者ツールでレイアウトを確認できる。
+    # 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")

data/lib/sghtmltopdf/server_client.rb

@@ -6,7 +6,7 @@ require "uri"
 module Sghtmltopdf
   class ServerError < Error; end
 
-  # HTTPサーバモード(`sghtmltopdf server`)へ変換を委譲するクライアント。
+  # 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")
@@ -14,29 +14,28 @@ module Sghtmltopdf
     DEFAULT_OPEN_TIMEOUT = 5
     DEFAULT_READ_TIMEOUT = 120
 
-    # 一度に読むチャンクの目安。`?stream=1`のときはこの単位でブロックへ渡る。
+    # 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] サーバのベースURL(`http://host:port`)
+    # @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
 
-    # HTMLをPDFへ変換する。
+    # Convert HTML to PDF.
     #
-    # ブロックを渡すと`?stream=1`(chunked transfer encoding)を使い、
-    # サーバがページを確定したそばからチャンクを渡す。ブロックが無ければ
-    # PDF全体をStringで返す。
+    # 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|
-        # `request`はブロック付きだとレスポンスオブジェクトを返すので、
-        # 結果は外の変数で受ける。
+        # 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
@@ -49,9 +48,9 @@ module Sghtmltopdf
       pdf
     end
 
-    # 変換結果を`path`へ書き出す。途中で失敗しても壊れたPDFを残さないよう、
-    # 一時ファイルへ書いてからrenameする(ネイティブ拡張の`FileSink`と同じ
-    # 挙動に揃えている)。
+    # 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
@@ -60,7 +59,7 @@ module Sghtmltopdf
         end
       rescue SystemCallError => e
         File.unlink(tmp) if File.exist?(tmp)
-        raise InputError, "#{path}への書き出しに失敗しました: #{e.message}"
+        raise InputError, "failed to write to #{path}: #{e.message}"
       rescue StandardError
         File.unlink(tmp) if File.exist?(tmp)
         raise
@@ -74,7 +73,7 @@ module Sghtmltopdf
     def parse(url)
       uri = URI.parse(url.to_s)
       unless uri.is_a?(URI::HTTP) && uri.host
-        raise ArgumentError, "server_urlにはhttp(s)のURLを指定してください: #{url.inspect}"
+        raise ArgumentError, "server_url must be an http(s) URL: #{url.inspect}"
       end
 
       uri
@@ -102,12 +101,12 @@ module Sghtmltopdf
         &block
       )
     rescue Net::OpenTimeout, Net::ReadTimeout => e
-      raise ServerError, "#{base}への接続がタイムアウトしました: #{e.class}"
+      raise ServerError, "the connection to #{base} timed out: #{e.class}"
     rescue SocketError, SystemCallError, IOError, OpenSSL::SSL::SSLError => e
-      raise ServerError, "#{base}への接続に失敗しました: #{e.message}"
+      raise ServerError, "the connection to #{base} failed: #{e.message}"
     end
 
-    # エラー応答の本文は`text/plain`の日本語メッセージ(CLIと同じ文言)。
+    # 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)
 
@@ -120,8 +119,8 @@ module Sghtmltopdf
       when 400 then UsageError
       when 413 then InputError
       when 500 then RenderError
-      # 404/405はパスやメソッドの間違い＝相手がsghtmltopdfのサーバでない
-      # 可能性が高い。503/504はキュー溢れ・キュー待ちのタイムアウト。
+      # 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

data/lib/sghtmltopdf/version.rb

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

data/lib/sghtmltopdf.rb

@@ -5,9 +5,9 @@ require_relative "sghtmltopdf/options"
 require_relative "sghtmltopdf/configuration"
 require_relative "sghtmltopdf/renderer"
 
-# precompiled gemはRubyのマイナーバージョンごとのディレクトリへ`.so`を置く
-# (rake-compilerのクロスビルドの慣習)。開発中の`rake compile`は
-# `lib/sghtmltopdf/sghtmltopdf.so`に置くので、両方を試す。
+# 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"
@@ -15,37 +15,36 @@ rescue LoadError
   require "sghtmltopdf/sghtmltopdf"
 end
 
-# `Error`(ネイティブ拡張が定義)を継承するため、拡張の読み込みより後に書く。
+# It inherits `Error` (defined by the native extension), so it comes after the extension is loaded.
 require_relative "sghtmltopdf/server_client"
 
 module Sghtmltopdf
-  # ブロック付き`render`で1回に渡すバイト数の目安(ローカル変換のみ)。
-  # ページ確定ごとにブロックを呼ぶとGVLの取り直しが増えるため、ここまで
-  # 溜めてから渡す。
+  # 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
-    # HTMLを変換してPDFのバイト列(ASCII-8BITのString)を返す。
+    # Convert HTML and return the PDF bytes (an ASCII-8BIT String).
     #
-    # ブロックを渡すと、PDF全体を組み立ててから返す代わりにチャンクごとに
-    # ブロックを呼ぶ(返り値はnil)。Rackの`response.stream`へ流したり、S3の
-    # マルチパートアップロードへ繋いだりするための口(エンジン側は出力先(sink)
-    # を意識しない設計に対応する)。
+    # 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) }
     #
-    # ローカル・サーバ委譲のどちらでも、PDF全体が組み上がるのを待たずに
-    # 書き出せる(ローカルは確定したページから順に、サーバは`?stream=1`の
-    # chunked transfer encodingをそのまま渡す)。
+    # 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).
     #
-    # ただし逐次になるのはPDFの書き出しだけで、HTMLのパースとレイアウトは
-    # 文書全体に対して先に行う。最初のチャンクが届くのは変換の終盤で、
-    # ピークメモリもブロック無しの場合と変わらない。HTMLを読みながら
-    # ページを確定させたい場合は`streaming: true`と併せて使う
-    # (制約と引き換えにメモリが大きく減る)。
+    # 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).
     #
-    # 1回に渡すバイト数の目安は`chunk_size:`で変えられる(既定64KiB。
-    # ローカル変換のみ。小さくするとGVLの取り直しが増える)。
+    # 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)
@@ -56,10 +55,10 @@ module Sghtmltopdf
       nil
     end
 
-    # HTMLを変換して`path`へ書き出す。
+    # Convert HTML and write it to `path`.
     #
-    # 一時ファイルへ書いて成功時だけrenameするため、途中で失敗しても
-    # 壊れたPDFが出力先に残らない(サーバへ委譲する場合も同じ)。
+    # 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)
@@ -69,7 +68,7 @@ module Sghtmltopdf
       nil
     end
 
-    # グローバルな既定オプション。
+    # The global default options.
     def configure
       yield config
       config
@@ -79,19 +78,19 @@ module Sghtmltopdf
       @config ||= Configuration.new
     end
 
-    # 主にテスト用。設定を空に戻す。
+    # Mainly for tests. Resets the configuration to empty.
     def reset_config!
       @config = Configuration.new
     end
 
     private
 
-    # グローバル設定 → 呼び出し時オプションの順にマージしてargvにする。
+    # 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
 
-    # `server_url`があればサーバへ委譲する。タイムアウトも同じ順でマージする。
+    # 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]
@@ -104,16 +103,16 @@ module Sghtmltopdf
       )
     end
 
-    # ブロックへ1回に渡すバイト数の目安(ローカル変換のみ)。
+    # 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
 
-    # サーバへ渡すオプション。流し込まれた既定値は外す
-    # (Rails向けの`base_url`・`allow`はローカルのファイル解決のための
-    # 既定値で、サーバモードではリクエストから指定できず400になる。
-    # 明示的に設定した値はそのまま送り、可否はサーバに判断させる)。
+    # 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sghtmltopdf
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - yo_waka