vivlio-pdf 0.2.0

data/lib/vivlio/pdf/session.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Vivlio
+  module PDF
+    # One document open in the viewer, inside one browser tab.
+    #
+    # Wraps the CDP page so callers talk about rendering and printing rather
+    # than about JavaScript evaluation, and so Ferrum's exceptions stop here.
+    # A Session is single-use: open it, read from it, print it, close it.
+    class Session
+      READY_STATE = <<~JS
+        window.coreViewer ? window.coreViewer.readyState : 'loading'
+      JS
+
+      # Reading the TOC has a side effect we depend on: the entries must be in
+      # the DOM while printing for Chromium to emit named destinations for
+      # them. Same approach as vivliostyle-cli.
+      READ_TOC = <<~JS
+        const done = arguments[0];
+        function listener(payload) {
+          if (payload.a !== 'toc') return;
+          window.coreViewer.removeListener('done', listener);
+          window.coreViewer.showTOC(false);
+          done(window.coreViewer.getTOC());
+        }
+        window.coreViewer.addListener('done', listener);
+        window.coreViewer.showTOC(true);
+      JS
+
+      POLL_INTERVAL = 0.2
+
+      # Closes the tab if the document never renders, so a Printer reusing one
+      # browser does not accumulate tabs across failed conversions.
+      def self.open(page, url, timeout:)
+        session = new(page, timeout: timeout)
+        session.visit(url)
+        session
+      rescue StandardError
+        begin
+          session&.close
+        rescue StandardError
+          nil # whatever went wrong first is the failure worth reporting
+        end
+        raise
+      end
+
+      # Non-fatal problems met while rendering, in the order they happened.
+      # Printer hands these to the caller as Result#warnings; nothing here
+      # writes to stderr on the caller's behalf.
+      attr_reader :warnings
+
+      def initialize(page, timeout:)
+        @page = page
+        @timeout = timeout
+        @warnings = []
+      end
+
+      def visit(url)
+        PDF.translate_browser_errors { @page.go_to(url) }
+        wait_until_ready
+        self
+      end
+
+      # The publication's table of contents as a TocItem forest.
+      #
+      # A document that cannot report one still prints; the failure is recorded
+      # in +warnings+ rather than aborting the conversion over an outline.
+      def toc
+        @toc ||= TocItem.build(read_toc)
+      rescue Error => e
+        @warnings << "could not read the table of contents (#{e.message}); outline skipped"
+        @toc = []
+      end
+
+      # Renders the paginated document to PDF bytes.
+      def to_pdf(generate_outline: false)
+        parameters = {
+          preferCSSPageSize: true,
+          printBackground: true,
+          transferMode: 'ReturnAsBase64'
+        }
+        parameters[:generateDocumentOutline] = true if generate_outline
+        printed = PDF.translate_browser_errors { @page.command('Page.printToPDF', **parameters) }
+        printed['data'].unpack1('m')
+      end
+
+      def close
+        PDF.translate_browser_errors { @page.close }
+      end
+
+      private
+
+      def read_toc
+        PDF.translate_browser_errors { @page.evaluate_async(READ_TOC, @timeout) }
+      end
+
+      def wait_until_ready
+        deadline = now + @timeout
+        loop do
+          case state = PDF.translate_browser_errors { @page.evaluate(READY_STATE) }
+          when 'complete' then return
+          when 'error' then raise RenderError, 'Vivliostyle reported a rendering error'
+          end
+
+          if now > deadline
+            raise TimeoutError, "rendering did not finish within #{@timeout}s (readyState=#{state})"
+          end
+
+          sleep POLL_INTERVAL
+        end
+      end
+
+      def now
+        Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      end
+    end
+  end
+end

data/lib/vivlio/pdf/source.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Vivlio
+  module PDF
+    # A document to render: a single HTML file, the OPF of an unzipped EPUB, or
+    # a webpub manifest. Beyond being a local file, it knows only whether it
+    # brings a spine with it.
+    class Source < LocalFile
+      OPF_EXTENSIONS = ['.opf'].freeze
+      MANIFEST_NAMES = ['publication.json', 'manifest.json'].freeze
+
+      def initialize(path)
+        super(path, kind: 'source')
+      end
+
+      # A publication (EPUB/webpub) has a spine to follow; a lone HTML file
+      # does not. Only used as the default for Printer#print's book_mode:.
+      def publication?
+        OPF_EXTENSIONS.include?(File.extname(path).downcase) ||
+          MANIFEST_NAMES.include?(File.basename(path))
+      end
+    end
+  end
+end

data/lib/vivlio/pdf/staged_file.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Vivlio
+  module PDF
+    # Builds a file beside where it belongs and moves it into place only once
+    # it is finished, so a run that fails part way through never leaves a
+    # half-written file where the caller expects a complete one.
+    module StagedFile
+      module_function
+
+      # Yields the path to build, and returns whatever the block returned.
+      def write(destination)
+        staged = "#{destination}.part"
+        claim(staged)
+        result = yield staged
+        File.rename(staged, destination)
+        result
+      ensure
+        FileUtils.rm_f(staged)
+      end
+
+      # Creates the staged file before anyone writes to it. The staged name is
+      # predictable, so in a world-writable output directory someone could
+      # plant a symlink there and have the PDF bytes written through it into a
+      # file of their choosing. Deleting whatever is at the name (unlinking a
+      # symlink cannot touch its target) and then creating with EXCL closes
+      # that: if something reappears in between, the build fails instead of
+      # writing through it. The deletion also clears a stale .part left behind
+      # by a killed run.
+      def claim(staged)
+        FileUtils.rm_f(staged)
+        File.open(staged, File::WRONLY | File::CREAT | File::EXCL) {} # rubocop:disable Lint/EmptyBlock
+      rescue Errno::EEXIST
+        raise Error, "staged file reappeared while claiming it: #{staged}"
+      end
+    end
+  end
+end

data/lib/vivlio/pdf/toc_item.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Vivlio
+  module PDF
+    # One entry of a publication's table of contents, as reported by
+    # window.coreViewer.getTOC(). Immutable value object holding a subtree.
+    #
+    # +id+ is the anchor id of the heading the entry points at; Chromium turns
+    # it into a PDF named destination while printing, and Outline::Toc later
+    # references that name. No page numbers are involved.
+    class TocItem
+      include Enumerable
+
+      attr_reader :id, :title, :children
+
+      # Builds a forest from the viewer's raw TOC array.
+      def self.build(raw)
+        Array(raw).map do |entry|
+          new(id: entry['id'], title: entry['title'], children: build(entry['children']))
+        end
+      end
+
+      def initialize(id:, title: nil, children: [])
+        @id = id
+        @title = title
+        @children = children.freeze
+        freeze
+      end
+
+      # Depth-first traversal over self and all descendants.
+      def each(&block)
+        return enum_for(:each) unless block
+
+        yield self
+        children.each { |child| child.each(&block) }
+      end
+
+      def leaf?
+        children.empty?
+      end
+
+      # Falls back to the anchor id so an entry is never blank in a PDF reader.
+      def label
+        title || id.to_s
+      end
+
+      def inspect
+        "#<#{self.class} #{label.inspect} children=#{children.size}>"
+      end
+    end
+  end
+end

data/lib/vivlio/pdf/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Vivlio
+  module PDF
+    VERSION = '0.2.0'
+  end
+end

data/lib/vivlio/pdf/viewer.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Vivlio
+  module PDF
+    # The Vivliostyle Viewer installation used for rendering: a directory of
+    # static files containing index.html.
+    #
+    # Defaults to the copy vendored in this gem; pass another path to run a
+    # different release without rebuilding the gem.
+    class Viewer
+      VENDORED_PATH = File.expand_path('../../../vendor/viewer', __dir__)
+
+      attr_reader :path, :version
+
+      def self.default
+        @default ||= new(VENDORED_PATH)
+      end
+
+      # Accepts a Viewer, a path, or nil (meaning the vendored viewer).
+      def self.coerce(value)
+        case value
+        when Viewer then value
+        when nil then default
+        else new(value)
+        end
+      end
+
+      def initialize(path)
+        @path = File.expand_path(path.to_s)
+        @index = LocalFile.new(File.join(@path, 'index.html'), kind: 'Vivliostyle Viewer')
+        @version = read_version
+        freeze
+      end
+
+      def index_path
+        @index.path
+      end
+
+      # Viewer URL loading +source+.
+      #
+      # Fragment parameters:
+      #   src              document to load
+      #   bookMode         follow the spine/TOC to load the whole publication
+      #   renderAllPages   paginate everything up front (required before print)
+      #   style            additional stylesheet(s)
+      #
+      # A stylesheet the viewer cannot find is silently ignored, so the paths
+      # are resolved here and a missing one is reported instead.
+      def url_for(source, book_mode: true, style: nil)
+        parameters = ["src=#{Source.coerce(source).url}"]
+        parameters << 'bookMode=true' if book_mode
+        parameters << 'renderAllPages=true'
+        Array(style).each do |sheet|
+          parameters << "style=#{LocalFile.new(sheet, kind: 'stylesheet').url}"
+        end
+        "#{@index.url}##{parameters.join('&')}"
+      end
+
+      def to_s
+        path
+      end
+
+      private
+
+      # The bundled package.json records which viewer release this is; it is
+      # the only statement of that version, so nothing can drift from it.
+      def read_version
+        manifest = File.join(@path, 'package.json')
+        return nil unless File.exist?(manifest)
+
+        JSON.parse(File.read(manifest))['version']
+      rescue JSON::ParserError, SystemCallError
+        nil
+      end
+    end
+  end
+end

data/lib/vivlio/pdf.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require 'ferrum'
+
+require_relative 'pdf/version'
+
+module Vivlio
+  # HTML, unzipped EPUB, or webpub → PDF, rendered by the Vivliostyle Viewer
+  # in a local Chrome/Chromium driven over CDP. No Node.js required.
+  module PDF
+    class Error < StandardError; end
+
+    # The viewer reported that it could not lay the document out.
+    class RenderError < Error; end
+
+    # Rendering did not finish within the configured timeout.
+    class TimeoutError < Error; end
+
+    # The browser could not be started, or stopped answering.
+    class BrowserError < Error; end
+
+    # How we drive Chrome is an implementation detail, so Ferrum's exceptions
+    # are translated at every point they can escape: callers only ever have to
+    # rescue Vivlio::PDF::Error.
+    #
+    # SystemCallError too: spawning the browser raises Errno::ENOENT when
+    # browser_path points at nothing, and inside these blocks an OS-level
+    # failure is a browser failure.
+    def self.translate_browser_errors
+      yield
+    rescue Ferrum::TimeoutError => e
+      raise TimeoutError, e.message
+    rescue Ferrum::Error, SystemCallError => e
+      raise BrowserError, e.message
+    end
+
+    # Converts one document, starting and stopping a browser around it.
+    # Prefer a Printer when converting several documents in a row.
+    #
+    # Options are split between the browser session and the conversion by
+    # Printer::SETUP_OPTIONS and Printer::PRINT_OPTIONS; anything else is a
+    # typo, and saying so beats silently ignoring it.
+    #
+    #   Vivlio::PDF.print(source: 'book/OEBPS/package.opf', output: 'book.pdf')
+    def self.print(source:, output:, **options)
+      unknown = options.keys - Printer::SETUP_OPTIONS - Printer::PRINT_OPTIONS
+      unless unknown.empty?
+        raise ArgumentError, "unknown keyword#{'s' if unknown.size > 1}: " \
+                             "#{unknown.map(&:inspect).join(', ')}"
+      end
+
+      Printer.open(**options.slice(*Printer::SETUP_OPTIONS)) do |printer|
+        printer.print(source: source, output: output, **options.slice(*Printer::PRINT_OPTIONS))
+      end
+    end
+  end
+end
+
+require_relative 'pdf/local_file'
+require_relative 'pdf/source'
+require_relative 'pdf/viewer'
+require_relative 'pdf/toc_item'
+require_relative 'pdf/metadata'
+require_relative 'pdf/outline'
+require_relative 'pdf/session'
+require_relative 'pdf/staged_file'
+require_relative 'pdf/document'
+require_relative 'pdf/result'
+require_relative 'pdf/printer'