zxing_ffi 0.1.0

data/lib/zxing_ffi/loaders/image_magick.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  module Loaders
+    # Raster loader running ImageMagick in a subprocess. Never used for PDF or vector/text formats.
+    #
+    # Load pipeline: aspect correction on the stored axes (best effort from +identify+ resolutions), then
+    # +-auto-orient -background white -alpha remove -alpha off -colorspace Gray -depth 8+ to PGM on stdout.
+    # The frame's size is checked against +max_pixels+ from +identify+ before anything is decoded.
+    class ImageMagickLoader < Base
+      # Resolutions differing by more than this ratio are corrected.
+      ASPECT_TOLERANCE = 0.05
+
+      class << self
+        # (see Base.loader_name)
+        def loader_name = :image_magick
+
+        # (see Base.kinds)
+        def kinds = ZXingFFI::ImageMagick::CODERS.keys
+
+        # (see Base.install_hint)
+        def install_hint
+          "install ImageMagick (brew install imagemagick / apt install imagemagick)"
+        end
+
+        # (see Base.diagnostics)
+        def diagnostics
+          tool = ZXingFFI::ImageMagick.tool
+          tool ? super.merge(version: tool.version, flavor: tool.flavor, command: tool.convert.first) : super
+        end
+
+        # (see Base.reset!)
+        def reset!
+          super
+          ZXingFFI::ImageMagick.reset!
+        end
+
+        private
+
+        def probe
+          return true if ZXingFFI::ImageMagick.tool
+
+          @unavailable_reason = ZXingFFI::ImageMagick.unavailable_reason
+          false
+        end
+      end
+
+      def open(source, password: nil)
+        tool = ZXingFFI::ImageMagick.tool(config) or raise LoaderUnavailable, ZXingFFI::ImageMagick.unavailable_reason(config)
+        raise UnsupportedInput, "ImageMagick is never used for #{source.kind} input" unless self.class.kinds.include?(source.kind)
+
+        MagickDocument.new(source, config, tool)
+      end
+
+      # A raster file; one page per frame.
+      class MagickDocument < Document
+        # Size and resolution (ppi, nil when unknown) of one frame, from +identify+.
+        Frame = Data.define(:width, :height, :x_res, :y_res)
+
+        def initialize(source, config, tool)
+          super(source)
+          @config = config
+          @tool = tool
+          @coder = ZXingFFI::ImageMagick::CODERS.fetch(source.kind)
+          @frames = identify
+          raise RenderError, "ImageMagick found no frames in #{source.name}" if @frames.empty?
+        end
+
+        # (see Document#page_count)
+        def page_count = @frames.size
+
+        # (see Document#page_info)
+        def page_info(number)
+          check_page!(number)
+          frame = @frames[number - 1]
+          width, height = corrected_size(frame)
+          PageInfo.new(number: number, width: width, height: height, unit: :px, rotation: 0,
+            native_ppi: [frame.x_res, frame.y_res].compact.max)
+        end
+
+        # (see Document#render)
+        def render(number, dpi: nil, timeout: nil)
+          check_page!(number)
+          frame = @frames[number - 1]
+          width, height = corrected_size(frame)
+          check_pixels!(width, height)
+          aspect = aspect_scale(frame)
+          resample = aspect ? ["-sample", "#{(aspect[0] * 100).round(4)}%x#{(aspect[1] * 100).round(4)}%!"] : []
+          stdout = ZXingFFI::ImageMagick.with_safe_path(source.path) do |path|
+            run([*@tool.convert, "#{@coder}:#{path}[#{number - 1}]", *resample, "-auto-orient", "-background", "white",
+              "-alpha", "remove", "-alpha", "off", "-colorspace", "Gray", "-depth", "8", "pgm:-"],
+              max_stdout: (width + 2) * (height + 2) * 2 + 1024, timeout: timeout)
+          end
+          decoded =
+            begin
+              ZXingFFI::Pnm.decode(stdout, max_pixels: @config.max_pixels)
+            rescue UnsupportedInput => e
+              raise RenderError, "ImageMagick produced invalid PGM for #{source.name}: #{e.message}"
+            end
+          image = Image.new(decoded.pixels, width: decoded.width, height: decoded.height)
+          Page.new(number: number, image: image, dpi: nil, scale_to_base: 1.0, metadata: {
+            loader: :image_magick, aspect_corrected: aspect && [frame.x_res, frame.y_res].map { |r| r.round(1) }
+          })
+        end
+
+        private
+
+        # One line per frame: width, height, x/y resolution and units. +-ping+ reads headers only, without decoding.
+        def identify
+          out = ZXingFFI::ImageMagick.with_safe_path(source.path) do |path|
+            run([*@tool.identify, "-ping", "-format", "%w %h %x %y %U\n", "#{@coder}:#{path}"], max_stdout: 1024 * 1024)
+          end
+          out.each_line.filter_map do |line|
+            width, height, x_res, y_res, units = line.split
+            next unless width&.match?(/\A\d+\z/) && height&.match?(/\A\d+\z/)
+
+            scale = (units == "PixelsPerCentimeter") ? 2.54 : 1.0
+            Frame.new(width: Integer(width), height: Integer(height), x_res: resolution(x_res, scale), y_res: resolution(y_res, scale))
+          end
+        end
+
+        def resolution(value, scale)
+          number = Float(value, exception: false)
+          number&.positive? ? number * scale : nil
+        end
+
+        def aspect_scale(frame)
+          x, y = frame.x_res, frame.y_res
+          return nil unless x && y
+          return nil if (x - y).abs / [x, y].max <= ASPECT_TOLERANCE
+
+          (x < y) ? [y / x, 1.0] : [1.0, x / y]
+        end
+
+        def corrected_size(frame)
+          hscale, vscale = aspect_scale(frame) || [1.0, 1.0]
+          [(frame.width * hscale).round, (frame.height * vscale).round]
+        end
+
+        def check_pixels!(width, height)
+          pixels = width * height
+          return unless @config.max_pixels && pixels > @config.max_pixels
+
+          raise LimitExceeded.new("#{width}x#{height} (#{pixels} pixels) exceeds max_pixels #{@config.max_pixels}",
+            limit: :max_pixels, value: pixels)
+        end
+
+        def run(argv, max_stdout:, timeout: nil)
+          status, stdout, stderr = Subprocess.run(argv, timeout: [timeout, @config.render_timeout].compact.min, max_stdout: max_stdout,
+            memory_limit: @config.subprocess_memory_limit)
+          return stdout if status.success?
+
+          raise RenderError.new("ImageMagick failed on #{source.name} (exit #{status.exitstatus}): #{stderr.lines.first&.strip}",
+            stderr: stderr, exit_status: status.exitstatus)
+        end
+      end
+    end
+  end
+end

data/lib/zxing_ffi/loaders/pnm.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  module Loaders
+    # Pure-Ruby loader for PNM files (P1–P6), always available.
+    #
+    # The file is streamed, never read whole: its header is read when the document is opened (at most
+    # {HEADER_LIMIT} bytes), and {PnmDocument#render} checks +max_pixels+ against it before {Pnm.decode} reads
+    # the raster in bounded chunks and nothing after it. So memory stays close to the decoded image's size
+    # whatever the file holds, a huge tail included.
+    class PnmLoader < Base
+      # Longest header accepted, comments included (it is read in chunks of 4 KiB and more).
+      HEADER_LIMIT = 1024 * 1024
+
+      class << self
+        # (see Base.loader_name)
+        def loader_name = :pnm
+
+        # (see Base.kinds)
+        def kinds = [:pnm]
+
+        # (see Base.install_hint)
+        def install_hint = "PNM input needs no external tools"
+
+        private
+
+        def probe = true
+      end
+
+      # @return [PnmDocument]
+      # @raise [UnsupportedInput] if the file does not start with a valid PNM header of at most {HEADER_LIMIT} bytes
+      def open(source, password: nil)
+        PnmDocument.new(source, max_pixels: config.max_pixels)
+      end
+
+      # A single-image PNM file.
+      class PnmDocument < Document
+        def initialize(source, max_pixels:)
+          super(source)
+          @max_pixels = max_pixels
+          @header = read_header
+        end
+
+        # (see Document#page_count)
+        def page_count = 1
+
+        # (see Document#page_info)
+        def page_info(number)
+          check_page!(number)
+          PageInfo.new(number: 1, width: @header.width, height: @header.height, unit: :px, rotation: 0, native_ppi: nil)
+        end
+
+        # (see Document#render)
+        # @raise [LimitExceeded] before reading the raster if the header declares more than +max_pixels+
+        # @raise [UnsupportedInput] if the raster is truncated or malformed
+        def render(number, dpi: nil, timeout: nil)
+          check_page!(number)
+          check_pixels!
+          decoded = File.open(source.path, "rb") { |file| ZXingFFI::Pnm.decode(file, max_pixels: @max_pixels) }
+          image = Image.new(decoded.pixels, width: decoded.width, height: decoded.height)
+          decoded.pixels.clear # copied into the image: free it now rather than at the next GC
+          Page.new(number: 1, image: image, dpi: nil, scale_to_base: 1.0, metadata: {loader: :pnm, pnm_kind: @header.kind})
+        end
+
+        private
+
+        def read_header
+          File.open(source.path, "rb") do |file|
+            reader = LimitedReader.new(file, HEADER_LIMIT)
+            ZXingFFI::Pnm.read_header(reader)
+          rescue UnsupportedInput
+            # Reaching the limit means the header was still incomplete there (a malformed one fails earlier).
+            raise unless reader.cut_short?
+
+            raise UnsupportedInput, "PNM header longer than #{HEADER_LIMIT} bytes (long comments?) is not supported"
+          end
+        end
+
+        # Checked from the header before reading the raster.
+        def check_pixels!
+          pixels = @header.width * @header.height
+          return unless @max_pixels && pixels > @max_pixels
+
+          raise LimitExceeded.new("#{@header.width}x#{@header.height} (#{pixels} pixels) exceeds max_pixels #{@max_pixels}",
+            limit: :max_pixels, value: pixels)
+        end
+      end
+
+      # Reads at most +limit+ bytes of an IO and then behaves as if at its end.
+      class LimitedReader
+        def initialize(io, limit)
+          @io = io
+          @remaining = limit
+        end
+
+        # @return [String, nil] like IO#read(length)
+        def read(length)
+          return nil if @remaining.zero?
+
+          data = @io.read([length, @remaining].min)
+          @remaining -= data.bytesize if data
+          data
+        end
+
+        # Whether the limit hid data that the IO still holds.
+        def cut_short?
+          @remaining.zero? && !@io.eof?
+        end
+      end
+      private_constant :LimitedReader
+    end
+  end
+end

data/lib/zxing_ffi/loaders/poppler.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  module Loaders
+    # PDF loader running Poppler's command-line tools in subprocesses: +pdfinfo+ for page count,
+    # sizes, rotation and encryption, +pdftoppm -gray+ to render one page to PGM on stdout, and (optionally)
+    # +pdfimages -list+ to find the native resolution of scanned pages for +dpi: :auto+.
+    #
+    # Every call uses an argument array (never a shell), an absolute input path, a timeout, an address-space limit
+    # (Linux) and a cap on stdout. Passwords are only ever passed as the argument after +-upw+.
+    # Renders of different pages may run concurrently.
+    class PopplerLoader < Base
+      # A page is treated as scanned when one embedded image covers at least this fraction of it.
+      SCAN_COVERAGE = 0.5
+
+      # Slack allowed on top of the expected PGM size (header + rounding of the page size).
+      OUTPUT_SLACK = 1024
+
+      # Poppler's command-line tools keep at most this many bytes of a password.
+      MAX_PASSWORD_BYTES = 32
+
+      class << self
+        # (see Base.loader_name)
+        def loader_name = :poppler
+
+        # (see Base.kinds)
+        def kinds = [:pdf]
+
+        # (see Base.install_hint)
+        def install_hint
+          "install Poppler's command-line tools (brew install poppler / apt install poppler-utils)"
+        end
+
+        # (see Base.diagnostics)
+        def diagnostics
+          info = super
+          return info unless available?
+
+          info.merge(
+            tools: %i[pdfinfo pdftoppm pdfimages].to_h { |tool| [tool, Subprocess.which(ZXingFFI.config.tool_path(tool).to_s)] },
+            version: version
+          )
+        end
+
+        # @return [String, nil] e.g. "26.07.0"
+        def version
+          _, out, err = Subprocess.run([ZXingFFI.config.tool_path(:pdftoppm).to_s, "-v"], timeout: 10)
+          (out + err)[/version\s+([\d.]+)/, 1]
+        rescue Error
+          nil
+        end
+
+        private
+
+        def probe
+          missing = %i[pdfinfo pdftoppm].reject { |tool| Subprocess.which(ZXingFFI.config.tool_path(tool).to_s) }
+          return true if missing.empty?
+
+          @unavailable_reason = "#{missing.join(" and ")} not found (config.tool_paths)"
+          false
+        end
+      end
+
+      # @return [PopplerDocument]
+      def open(source, password: nil)
+        PopplerDocument.new(source, config, password)
+      end
+
+      # Parsers for Poppler's text output (kept separate for unit tests against recorded samples).
+      module Parser
+        module_function
+
+        # "Pages:" and "Encrypted:" from +pdfinfo+.
+        # @return [Hash] +{pages: Integer, encrypted: Boolean}+
+        def info(text)
+          pages = text[/^Pages:\s+(\d+)/, 1] or raise RenderError, "pdfinfo output has no page count"
+          {pages: Integer(pages), encrypted: text.match?(/^Encrypted:\s+yes/)}
+        end
+
+        # Per-page sizes and rotations from +pdfinfo -f 1 -l N+.
+        # @return [Hash{Integer => Hash}] page => +{width:, height:, rotation:}+ (unrotated CropBox, points)
+        def page_boxes(text)
+          pages = Hash.new { |h, k| h[k] = {rotation: 0} }
+          text.each_line do |line|
+            if (m = line.match(/^Page\s+(\d+)\s+size:\s+(\S+)\s+x\s+(\S+)\s+pts/))
+              width, height = m[2, 2].map { |value| Float(value, exception: false) }
+              unless [width, height].all? { |value| value&.finite? && value.positive? }
+                raise RenderError, "pdfinfo reports an unusable size for page #{m[1]}: #{m[2]} x #{m[3]} pts"
+              end
+
+              pages[Integer(m[1])].merge!(width: width, height: height)
+            elsif (m = line.match(/^Page\s+(\d+)\s+rot:\s+(-?\d+)/))
+              pages[Integer(m[1])][:rotation] = Integer(m[2]) % 360
+            end
+          end
+          pages.select { |_, box| box.key?(:width) }
+        end
+
+        # Rows of +pdfimages -list+ (masks excluded). The resolution columns are read from the end of the row:
+        # the "object ID" column is two tokens ("23 0") for normal images but one ("[inline]") for inline images.
+        # Rows that do not parse are skipped.
+        # @return [Array<Hash>] +{page:, type:, width:, height:, x_ppi:, y_ppi:}+
+        def images(text)
+          text.each_line.filter_map do |line|
+            fields = line.split
+            next unless fields.size >= 13 && fields[0].match?(/\A\d+\z/) && fields[2] == "image"
+
+            page, width, height = fields.values_at(0, 3, 4).map { |f| Integer(f, exception: false) }
+            x_ppi, y_ppi = fields[-4, 2].map { |f| Float(f, exception: false) }
+            next unless page && width && height && x_ppi && y_ppi
+
+            {page: page, type: "image", width: width, height: height, x_ppi: x_ppi, y_ppi: y_ppi}
+          end
+        end
+
+        # Native resolution of a scanned page: the ppi of an image covering most of it, else nil.
+        # @return [Float, nil]
+        def native_ppi(images, width_pt, height_pt, coverage: SCAN_COVERAGE)
+          page_area = (width_pt / 72.0) * (height_pt / 72.0)
+          return nil unless page_area.positive?
+
+          scans = images.select do |image|
+            next false unless image[:x_ppi].positive? && image[:y_ppi].positive?
+
+            (image[:width] / image[:x_ppi]) * (image[:height] / image[:y_ppi]) >= coverage * page_area
+          end
+          scans.map { |image| [image[:x_ppi], image[:y_ppi]].max }.max
+        end
+      end
+
+      # An opened PDF. Page metadata comes from one +pdfinfo+ run; each render is one +pdftoppm+ run.
+      class PopplerDocument < Document
+        def initialize(source, config, password)
+          super(source)
+          if password && password.to_s.bytesize > MAX_PASSWORD_BYTES
+            raise NotSupported, "Poppler's command-line tools accept passwords of at most #{MAX_PASSWORD_BYTES} bytes; " \
+              "this one has #{password.to_s.bytesize}. Use loader: :vips with config.vips_block_untrusted = false."
+          end
+          @config = config
+          @password = password
+          @mutex = Mutex.new
+          info = Parser.info(pdfinfo)
+          @page_count = info[:pages]
+          @encrypted = info[:encrypted]
+        end
+
+        # @return [Integer]
+        attr_reader :page_count
+
+        # @return [Boolean] whether the file is encrypted (it opened, so no or the right password was needed)
+        def encrypted? = @encrypted
+
+        # Size in points of the page as displayed (after /Rotate).
+        def page_info(number)
+          check_page!(number)
+          box = boxes.fetch(number) { raise RenderError, "pdfinfo reported no size for page #{number}" }
+          width, height = displayed_size(box)
+          PageInfo.new(number: number, width: width, height: height, unit: :pt, rotation: box[:rotation],
+            native_ppi: native_ppi(number, width, height))
+        end
+
+        # Renders one page to 8-bit gray at +dpi+ (default: config.default_dpi).
+        def render(number, dpi: nil, timeout: nil)
+          check_page!(number)
+          dpi ||= @config.default_dpi
+          raise ArgumentError, "dpi must be a positive number" unless dpi.is_a?(Numeric) && dpi.positive?
+
+          info = page_info(number)
+          width, height = Dpi.dimensions(info.width, info.height, dpi)
+          check_pixels!(width, height)
+          argv = [tool(:pdftoppm), "-gray", "-cropbox", "-r", format_dpi(dpi), "-f", number.to_s, "-l", number.to_s, *password_args, source.path]
+          stdout = run(argv, max_stdout: (width + 2) * (height + 2) + OUTPUT_SLACK, timeout: timeout)
+          decoded =
+            begin
+              ZXingFFI::Pnm.decode(stdout, max_pixels: @config.max_pixels)
+            rescue UnsupportedInput => e
+              raise RenderError.new("pdftoppm produced invalid PGM for page #{number}: #{e.message}")
+            end
+          image = Image.new(decoded.pixels, width: decoded.width, height: decoded.height)
+          Page.new(number: number, image: image, dpi: dpi, scale_to_base: 1.0,
+            metadata: {loader: :poppler, rotation: info.rotation, native_ppi: info.native_ppi})
+        end
+
+        private
+
+        # Per-page output ("Page N size: …" and "Page N rot: …") is ~80 bytes per page, so the cap grows with the
+        # page count once it is known.
+        def pdfinfo(*range)
+          cap = 1024 * 1024 + (@page_count || 0) * 256
+          run([tool(:pdfinfo), *range, *password_args, source.path], max_stdout: cap)
+        end
+
+        def boxes
+          @mutex.synchronize do
+            @boxes ||= Parser.page_boxes(pdfinfo("-f", "1", "-l", @page_count.to_s))
+          end
+        end
+
+        def displayed_size(box)
+          [90, 270].include?(box[:rotation]) ? [box[:height], box[:width]] : [box[:width], box[:height]]
+        end
+
+        def native_ppi(number, width, height)
+          images = @mutex.synchronize { @images ||= list_images }
+          Parser.native_ppi(images.select { |image| image[:page] == number }, width, height)
+        end
+
+        # All pages' embedded images, or [] when pdfimages is missing or fails (auto DPI then uses default_dpi).
+        def list_images
+          command = tool(:pdfimages)
+          return [] unless Subprocess.which(command)
+
+          Parser.images(run([command, "-list", *password_args, source.path], max_stdout: 16 * 1024 * 1024))
+        rescue RenderError, TimeoutError, LimitExceeded
+          []
+        end
+
+        # Integer DPIs as-is; fractional ones (huge declared pages, see Dpi.max_dpi_for) with 3 decimals.
+        def format_dpi(dpi)
+          dpi.is_a?(Integer) ? dpi.to_s : format("%.3f", dpi)
+        end
+
+        def password_args
+          @password ? ["-upw", @password.to_s] : []
+        end
+
+        def tool(name)
+          @config.tool_path(name).to_s
+        end
+
+        def check_pixels!(width, height)
+          pixels = width * height
+          return unless @config.max_pixels && pixels > @config.max_pixels
+
+          raise LimitExceeded.new("rendering #{width}x#{height} (#{pixels} pixels) exceeds max_pixels #{@config.max_pixels}",
+            limit: :max_pixels, value: pixels)
+        end
+
+        def run(argv, max_stdout:, timeout: nil)
+          status, stdout, stderr = Subprocess.run(argv, timeout: [timeout, @config.render_timeout].compact.min, max_stdout: max_stdout,
+            memory_limit: @config.subprocess_memory_limit)
+          return stdout if status.success?
+
+          raise password_error if stderr.match?(/incorrect password/i)
+
+          raise RenderError.new("#{File.basename(argv.first)} failed on #{source.name} (exit #{status.exitstatus}): #{stderr.lines.first&.strip}",
+            stderr: stderr, exit_status: status.exitstatus)
+        end
+
+        def password_error
+          if @password
+            IncorrectPassword.new("the password for #{source.name} was rejected")
+          else
+            PasswordRequired.new("#{source.name} is encrypted; pass password:")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zxing_ffi/loaders/registry.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  module Loaders
+    # Chooses a loader for an input kind.
+    #
+    # Order comes from +config.pdf_loaders+ (PDF) or +config.image_loaders+ (everything else); an explicit
+    # +loader:+ overrides it. The first loader that supports the kind and is available wins.
+    module Registry
+      class << self
+        # @param kind [Symbol] sniffed input kind
+        # @param config [Config]
+        # @param loader [Symbol, Array<Symbol>, nil] explicit loader name(s)
+        # @return [Class<Base>]
+        # @raise [LoaderUnavailable] naming what to install
+        # @raise [ArgumentError] for unknown loader names
+        def loader_for(kind, config: ZXingFFI.config, loader: nil)
+          order = loader ? Array(loader) : default_order(kind, config)
+          tried = order.map do |name|
+            klass = Loaders.fetch(name)
+            return klass if klass.supports?(kind)
+
+            reason =
+              if klass.kinds.include?(kind)
+                klass.unavailable_reason || klass.unsupported_reason(kind) || "no #{kind} support in this build"
+              else
+                "does not read #{kind}"
+              end
+            [name, reason, klass]
+          end
+          raise LoaderUnavailable, unavailable_message(kind, tried)
+        end
+
+        # @return [Array<Symbol>] configured loader order for +kind+
+        def default_order(kind, config)
+          (kind == :pdf) ? config.pdf_loaders : config.image_loaders
+        end
+
+        private
+
+        def unavailable_message(kind, tried)
+          lines = tried.map { |name, reason, _| "  - #{name}: #{reason}" }
+          # install hints only for loaders that are missing; a present loader that refuses explains why in its reason
+          hints = tried.filter_map { |_, _, klass| klass.install_hint if klass.kinds.include?(kind) && !klass.available? }
+          hints = hints.reject(&:empty?).uniq
+          if hints.empty?
+            hints << ((tried.any? { |_, _, klass| klass.kinds.include?(kind) }) ? "see the reasons above" : "no configured loader reads #{kind} input")
+          end
+          "No loader available for #{kind} input.\nTried:\n#{lines.join("\n")}\nTo fix: #{hints.join("; or ")}"
+        end
+      end
+    end
+  end
+end