zxing_ffi 0.1.0-x86_64-linux-gnu

data/lib/zxing_ffi/image.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module ZXingFFI
+  # A normalized pixel buffer that owns its memory.
+  #
+  # The bytes are copied into an +FFI::MemoryPointer+ (malloc'd, never moved by the GC), which is what the
+  # decoder reads while the GVL is released. Call {#release!} to free large buffers early.
+  #
+  # @example
+  #   image = ZXingFFI::Image.new(gray_bytes, width: 640, height: 480)
+  #   ZXingFFI.read(image)
+  class Image
+    # Bytes per pixel of each supported pixel format.
+    BYTES_PER_PIXEL = {lum: 1, lum_a: 2, rgb: 3, bgr: 3, rgba: 4, argb: 4, bgra: 4, abgr: 4}.freeze
+
+    # Largest buffer the C API can describe (its sizes are C ints).
+    MAX_BYTES = 2**31 - 1
+
+    # @return [Integer]
+    attr_reader :width, :height, :row_stride, :bytesize
+    # @return [Symbol] one of {BYTES_PER_PIXEL}'s keys
+    attr_reader :format
+
+    # Decodes PGM/PNM data (a String or an IO) into an 8-bit luminance image.
+    # @return [Image]
+    def self.from_pgm(io_or_string, max_pixels: nil)
+      decoded = Pnm.decode(io_or_string, max_pixels: max_pixels)
+      new(decoded.pixels, width: decoded.width, height: decoded.height)
+    end
+
+    # @param bytes [String] pixel data, at least +row_stride * height+ bytes
+    # @param width [Integer]
+    # @param height [Integer]
+    # @param format [Symbol] +:lum+ (default), +:lum_a+, +:rgb+, +:bgr+, +:rgba+, +:argb+, +:bgra+, +:abgr+
+    # @param row_stride [Integer, nil] bytes per row (default: width × bytes per pixel)
+    def initialize(bytes, width:, height:, format: :lum, row_stride: nil)
+      raise ArgumentError, "unsupported pixel format #{format.inspect}" unless BYTES_PER_PIXEL.key?(format)
+      raise ArgumentError, "width must be a positive Integer" unless width.is_a?(Integer) && width.positive?
+      raise ArgumentError, "height must be a positive Integer" unless height.is_a?(Integer) && height.positive?
+
+      min_stride = width * BYTES_PER_PIXEL.fetch(format)
+      row_stride ||= min_stride
+      raise ArgumentError, "row_stride must be an Integer >= #{min_stride}" unless row_stride.is_a?(Integer) && row_stride >= min_stride
+
+      bytes = String.try_convert(bytes) or raise(TypeError, "bytes must be a String, got #{bytes.class}")
+      size = row_stride * height
+      raise ArgumentError, "image too large: #{size} bytes (max #{MAX_BYTES})" if size > MAX_BYTES
+      raise ArgumentError, "expected at least #{size} bytes (row_stride #{row_stride} × height #{height}), got #{bytes.bytesize}" if bytes.bytesize < size
+
+      @width = width
+      @height = height
+      @format = format
+      @row_stride = row_stride
+      @bytesize = size
+      @pointer = FFI::MemoryPointer.new(:uint8, size, false)
+      @pointer.put_bytes(0, bytes, 0, size)
+    end
+
+    # The pixel buffer. Raises once the image has been released.
+    # @return [FFI::MemoryPointer]
+    def pointer
+      @pointer or raise Error, "#{inspect} has been released"
+    end
+
+    # Frees the pixel buffer now instead of waiting for GC. Later use of the image raises.
+    # Never release an image while another thread is decoding it.
+    # @return [self]
+    def release!
+      pointer = @pointer
+      @pointer = nil
+      pointer&.free
+      self
+    end
+
+    # @return [Boolean]
+    def released?
+      @pointer.nil?
+    end
+
+    # @return [Integer] bytes per pixel
+    def bytes_per_pixel
+      BYTES_PER_PIXEL.fetch(format)
+    end
+
+    # A BINARY copy of the pixel buffer.
+    # @return [String]
+    def to_bytes
+      pointer.get_bytes(0, bytesize)
+    end
+
+    # A photographic negative of a +:lum+ image (every byte v becomes 255 - v), made at C speed with String#tr.
+    # Used by the inverted pass: zxing-cpp's try_invert only applies to 2D readers, so white-on-black linear codes
+    # need inverted pixels.
+    # @return [Image]
+    def inverted
+      raise ArgumentError, "inverted needs a :lum image, this one is #{format.inspect}" unless format == :lum
+
+      Image.new(to_bytes.tr(INVERT_FROM, INVERT_TO), width: width, height: height, row_stride: row_stride)
+    end
+
+    escape = ->(byte) { ["-", "^", "\\"].include?(byte) ? "\\#{byte}".b : byte.b }
+    # String#tr maps for byte inversion; tr's special characters (-, ^, \) are escaped.
+    INVERT_FROM = (0..255).map { |v| escape.call(v.chr) }.join.b.freeze
+    INVERT_TO = (0..255).map { |v| escape.call((255 - v).chr) }.join.b.freeze
+    private_constant :INVERT_FROM, :INVERT_TO
+
+    # PGM (P5) encoding of a +:lum+ image, e.g. for piping into an external transformer.
+    # @return [String]
+    def to_pgm
+      raise ArgumentError, "to_pgm needs a :lum image, this one is #{format.inspect}" unless format == :lum
+
+      rows = (row_stride == width) ? to_bytes : Array.new(height) { |y| pointer.get_bytes(y * row_stride, width) }.join
+      Pnm.encode_pgm(rows, width, height)
+    end
+
+    # @return [String] e.g. "#<ZXingFFI::Image 640x480 lum>"
+    def inspect
+      "#<#{self.class.name} #{width}x#{height} #{format}#{" (released)" if released?}>"
+    end
+  end
+end

data/lib/zxing_ffi/image_magick.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "tmpdir"
+
+module ZXingFFI
+  # Locating and invoking ImageMagick safely, shared by the loader and the transformer.
+  #
+  # ImageMagick 7 is used through +magick+; ImageMagick 6 through +convert+ and +identify+. Inputs are always read
+  # with an explicit coder prefix matching our sniffed kind (e.g. +png:/abs/path+) so ImageMagick cannot re-detect a
+  # dangerous format (PDF, PS, EPS, SVG, MVG, MSL, text) from the content. Paths containing characters ImageMagick
+  # interprets (+[ ] * ? { } @ %+ …) are symlinked to a safe temporary name first.
+  module ImageMagick
+    # Sniffed kind => ImageMagick coder. PDF and vector/text formats are deliberately absent.
+    CODERS = {
+      png: "png", jpeg: "jpeg", tiff: "tiff", gif: "gif", bmp: "bmp", webp: "webp",
+      heif: "heic", avif: "avif", pnm: "pnm"
+    }.freeze
+
+    # Paths made only of these characters are passed to ImageMagick as they are.
+    SAFE_PATH = %r{\A[A-Za-z0-9_./\- ]+\z}
+
+    # A resolved ImageMagick installation.
+    # @!attribute flavor [Symbol] +:im7+ or +:im6+
+    # @!attribute convert [Array<String>] argv prefix that converts images
+    # @!attribute identify [Array<String>] argv prefix that identifies images
+    # @!attribute version [String, nil]
+    Tool = Data.define(:flavor, :convert, :identify, :version)
+
+    @mutex = Mutex.new
+
+    class << self
+      # The ImageMagick installation to use, or nil (memoized per configured path).
+      # @return [Tool, nil]
+      def tool(config = ZXingFFI.config)
+        configured = config.tool_path(:magick)
+        @mutex.synchronize do
+          @tools ||= {}
+          return @tools[configured] if @tools.key?(configured)
+
+          @tools[configured] = detect(configured)
+        end
+      end
+
+      # Forgets detected installations (tests, or after changing config.tool_paths[:magick]).
+      def reset!
+        @mutex.synchronize { @tools = nil }
+      end
+
+      # @return [String] why no ImageMagick is usable
+      def unavailable_reason(config = ZXingFFI.config)
+        configured = config.tool_path(:magick)
+        configured ? "#{configured} is not a working ImageMagick 7 `magick`" : "neither `magick` (IM7) nor `convert`/`identify` (IM6) found"
+      end
+
+      # Yields a path safe to hand to ImageMagick (the original, or a symlink with a plain name).
+      def with_safe_path(path)
+        return yield(path) if path.match?(SAFE_PATH)
+
+        Dir.mktmpdir("zxing_ffi_im") do |dir|
+          link = File.join(dir, "input")
+          File.symlink(path, link)
+          yield link
+        end
+      end
+
+      private
+
+      def detect(configured)
+        if configured
+          version = version_of([configured, "-version"])
+          return version && Tool.new(flavor: :im7, convert: [configured], identify: [configured, "identify"], version: version)
+        end
+
+        if (magick = Subprocess.which("magick")) && (version = version_of([magick, "-version"]))
+          return Tool.new(flavor: :im7, convert: [magick], identify: [magick, "identify"], version: version)
+        end
+
+        convert = Subprocess.which("convert")
+        identify = Subprocess.which("identify")
+        if convert && identify && (version = version_of([convert, "-version"]))
+          return Tool.new(flavor: :im6, convert: [convert], identify: [identify], version: version)
+        end
+
+        nil
+      end
+
+      def version_of(argv)
+        status, out, = Subprocess.run(argv, timeout: 10, max_stdout: 64 * 1024)
+        status.success? && out[/ImageMagick\s+(\d+\.\d+\.\d+(?:-\d+)?)/, 1]
+      rescue Error
+        nil
+      end
+    end
+  end
+end

data/lib/zxing_ffi/library_defaults.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  # The loaded library's ReaderOptions defaults, read through the get* functions when first referenced.
+  # Never assume them: e.g. zxing-cpp 3.1.1 enables try_invert and uses the HRI text mode by default.
+  LIBRARY_DEFAULTS = Reader.library_defaults.freeze
+end

data/lib/zxing_ffi/library_loader.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "ffi"
+
+module ZXingFFI
+  # Finds a compatible libZXing and checks its version and required symbols.
+  #
+  # Candidates, in order (the first one that loads and passes the checks wins):
+  # 1. +ZXingFFI.config.library_path+ / +ENV["ZXING_LIB"]+ — authoritative: when set, nothing else is tried.
+  # 2. The library bundled in a platform gem (+vendor/lib/+; the plain ruby-platform gem has none).
+  # 3. System library names resolved by the dynamic loader.
+  # 4. Common prefixes (+/opt/homebrew/lib+, +/usr/local/lib+).
+  # {Found#source} records which of these the library came from.
+  module LibraryLoader
+    # zxing-cpp versions whose C API this gem binds.
+    SUPPORTED_VERSIONS = Gem::Requirement.new(">= 3.1.0", "< 4.0")
+
+    # Symbols that must resolve for the library to be usable.
+    REQUIRED_SYMBOLS = %w[ZXing_Version ZXing_ReadBarcodes ZXing_BarcodeFormatsFromString].freeze
+
+    # Names handed to the dynamic loader. zxing-cpp 3.1's SONAME is 4.
+    SYSTEM_NAMES = [
+      FFI.map_library_name("ZXing"),
+      "libZXing.so.4", "libZXing.so.3", "libZXing.so",
+      "libZXing.4.dylib", "libZXing.dylib"
+    ].uniq.freeze
+
+    # Directories searched after the loader's own search path.
+    PREFIXES = %w[/opt/homebrew/lib /usr/local/lib].freeze
+
+    # Directory holding a library bundled with a platform gem.
+    BUNDLED_DIR = File.expand_path("../../vendor/lib", __dir__)
+
+    # A library that passed every check.
+    # @!attribute name [String] what was handed to dlopen
+    # @!attribute path [String] resolved file path (best effort, falls back to +name+)
+    # @!attribute version [String] value of ZXing_Version()
+    # @!attribute source [Symbol, nil] which candidate group it came from: +:explicit+ (library_path / ZXING_LIB),
+    #   +:bundled+ (a platform gem's vendor/lib), +:system+ (the dynamic loader's search path) or +:prefix+
+    #   ({PREFIXES}); nil when {LibraryLoader.probe} was called directly
+    Found = Data.define(:name, :path, :version, :source) do
+      def initialize(name:, path:, version:, source: nil) = super
+    end
+
+    # Outcome of probing one candidate.
+    Attempt = Data.define(:name, :status, :detail)
+
+    # Flags for probing candidates: resolve lazily, keep symbols local.
+    DLOPEN_FLAGS = FFI::DynamicLibrary::RTLD_LAZY | FFI::DynamicLibrary::RTLD_LOCAL
+
+    # Resolves the absolute path of a loaded library via dladdr(3).
+    module Dl
+      extend FFI::Library
+
+      ffi_lib FFI::Library::LIBC
+
+      # Dl_info from <dlfcn.h>.
+      class Info < FFI::Struct
+        layout :dli_fname, :pointer, :dli_fbase, :pointer, :dli_sname, :pointer, :dli_saddr, :pointer
+      end
+
+      begin
+        attach_function :dladdr, [:pointer, Info.by_ref], :int
+      rescue FFI::NotFoundError
+        # not available on this platform; paths are reported as given
+      end
+    end
+
+    class << self
+      # Finds the first compatible library.
+      #
+      # @param explicit [String, nil] explicit path (defaults to the configured library_path)
+      # @param bundled_dir [String] directory searched for a bundled library (defaults to {BUNDLED_DIR})
+      # @return [Found]
+      # @raise [LibraryNotFound] when no candidate loads
+      # @raise [IncompatibleLibrary] when libraries load but none is compatible
+      def find(explicit: ZXingFFI.config.library_path, bundled_dir: BUNDLED_DIR)
+        attempts = []
+        sourced_candidates(explicit, bundled_dir).each do |name, source|
+          result = probe(name, source: source)
+          return result if result.is_a?(Found)
+
+          attempts << result
+        end
+        raise failure(attempts, explicit)
+      end
+
+      # Candidate names/paths in search order.
+      # @param (see .find)
+      # @return [Array<String>]
+      def candidates(explicit: ZXingFFI.config.library_path, bundled_dir: BUNDLED_DIR)
+        sourced_candidates(explicit, bundled_dir).map(&:first)
+      end
+
+      # Loads one candidate and checks its version and required symbols.
+      # @param source [Symbol, nil] recorded in the {Found} result
+      # @return [Found, Attempt]
+      def probe(name, source: nil)
+        library = FFI::DynamicLibrary.open(name.to_s, DLOPEN_FLAGS)
+        version_symbol = library.find_function("ZXing_Version")
+        return Attempt.new(name, :incompatible, "ZXing_Version not exported (zxing-cpp < 2.2 or built without the C API)") unless version_symbol
+
+        version = FFI::Function.new(:string, [], version_symbol).call.to_s
+        return Attempt.new(name, :incompatible, "version #{version} is not #{SUPPORTED_VERSIONS}") unless supported_version?(version)
+
+        missing = REQUIRED_SYMBOLS.reject { |sym| library.find_function(sym) }
+        return Attempt.new(name, :incompatible, "version #{version} lacks #{missing.join(", ")}") if missing.any?
+
+        Found.new(name: name.to_s, path: resolve_path(version_symbol) || name.to_s, version: version, source: source)
+      rescue LoadError => e
+        Attempt.new(name, :not_found, e.message.lines.first.to_s.strip)
+      end
+
+      # @param version [String] e.g. "3.1.1"
+      def supported_version?(version)
+        numeric = version.to_s[/\A\d+(?:\.\d+)*/]
+        return false unless numeric
+
+        SUPPORTED_VERSIONS.satisfied_by?(Gem::Version.new(numeric))
+      end
+
+      private
+
+      # [name, source] pairs in search order (see {Found#source}).
+      def sourced_candidates(explicit, bundled_dir)
+        return [[explicit, :explicit]] if explicit && !explicit.to_s.empty?
+
+        bundled = Dir[File.join(bundled_dir, "libZXing*.{dylib,so}*")].sort.map { |path| [path, :bundled] }
+        system = SYSTEM_NAMES.map { |name| [name, :system] }
+        prefixed = PREFIXES.flat_map { |dir| SYSTEM_NAMES.map { |name| File.join(dir, name) } }
+          .select { |path| File.exist?(path) }.map { |path| [path, :prefix] }
+        (bundled + system + prefixed).uniq(&:first)
+      end
+
+      def resolve_path(symbol_pointer)
+        return nil unless Dl.respond_to?(:dladdr)
+
+        info = Dl::Info.new
+        return nil if Dl.dladdr(symbol_pointer, info).zero? || info[:dli_fname].null?
+
+        path = info[:dli_fname].read_string
+        File.exist?(path) ? File.realpath(path) : path
+      rescue
+        nil
+      end
+
+      def failure(attempts, explicit)
+        incompatible = attempts.select { |a| a.status == :incompatible }
+        tried = attempts.map { |a| "  - #{a.name}: #{a.detail}" }.join("\n")
+        if incompatible.any?
+          version = incompatible.first.detail[/version (\S+)/, 1]
+          IncompatibleLibrary.new(<<~MSG.chomp, version: version)
+            Found libZXing, but no compatible version (need zxing-cpp #{SUPPORTED_VERSIONS} built with the C API).
+            Tried:
+            #{tried}
+            #{HELP}
+          MSG
+        else
+          LibraryNotFound.new(<<~MSG.chomp)
+            Could not load libZXing#{" from #{explicit.inspect}" if explicit && !explicit.to_s.empty?}.
+            Tried:
+            #{tried}
+            #{HELP}
+          MSG
+        end
+      end
+    end
+
+    # Advice appended to LibraryNotFound / IncompatibleLibrary messages.
+    HELP = <<~HELP.chomp
+      To fix: install zxing-cpp 3.x with its C API (e.g. `brew install zxing-cpp`), or build it from source
+      (`rake zxing:build` in this gem's repository, or cmake with -DZXING_C_API=ON), then point ZXING_LIB
+      (or ZXingFFI.config.library_path) at the resulting libZXing shared library.
+    HELP
+  end
+end

data/lib/zxing_ffi/loaders/base.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  module Loaders
+    # Size and orientation of one page or frame, known before rendering.
+    #
+    # @!attribute number [Integer] 1-based
+    # @!attribute width [Numeric] as displayed (after /Rotate or EXIF orientation), in +unit+
+    # @!attribute height [Numeric] as displayed, in +unit+
+    # @!attribute unit [Symbol] +:pt+ for PDF pages, +:px+ for raster frames
+    # @!attribute rotation [Integer] PDF /Rotate or applied EXIF rotation in degrees (0 when unknown)
+    # @!attribute native_ppi [Float, nil] resolution of the scan image covering the page (PDF), or the
+    #   raster's resolution when recorded; nil when unknown or born-digital
+    PageInfo = Data.define(:number, :width, :height, :unit, :rotation, :native_ppi)
+
+    # A rendered page.
+    #
+    # @!attribute number [Integer] 1-based page/frame number
+    # @!attribute image [Image] normalized 8-bit luminance image
+    # @!attribute dpi [Integer, nil] render DPI (PDF) or nil for rasters
+    # @!attribute scale_to_base [Float] factor mapping this image's pixels to the page's base image (1.0 for the base)
+    # @!attribute metadata [Hash] what was applied, e.g. +orientation_applied:+, +aspect_corrected:+, +dpi_capped:+
+    Page = Data.define(:number, :image, :dpi, :scale_to_base, :metadata)
+
+    # Base class for loaders. Subclasses implement the class-level capability checks and {#open}.
+    class Base
+      class << self
+        # @return [Symbol] registry name, e.g. +:poppler+
+        def loader_name
+          raise NotImplementedError, "#{name}.loader_name"
+        end
+
+        # Input kinds this loader can handle in principle (see {Sniffer::KINDS}).
+        # @return [Array<Symbol>]
+        def kinds
+          raise NotImplementedError, "#{name}.kinds"
+        end
+
+        # Whether the tool/gem is present at all (memoized; see {.reset!}).
+        # @return [Boolean]
+        def available?
+          return @available if defined?(@available)
+
+          @available = probe
+        end
+
+        # Why {.available?} is false (or nil when available).
+        # @return [String, nil]
+        def unavailable_reason
+          available? ? nil : (@unavailable_reason || "not available")
+        end
+
+        # Whether this loader can handle +kind+ on this machine (e.g. vips without HEIF support → false for :heif).
+        # @return [Boolean]
+        def supports?(kind)
+          kinds.include?(kind.to_sym) && available?
+        end
+
+        # Why +kind+ is not supported although it is in {.kinds} and the loader is available (e.g. an operation
+        # refused by configuration), or nil.
+        # @return [String, nil]
+        def unsupported_reason(kind)
+          nil
+        end
+
+        # What to install to get this loader.
+        # @return [String]
+        def install_hint
+          ""
+        end
+
+        # Tool versions and capabilities, for {ZXingFFI.diagnostics}.
+        # @return [Hash]
+        def diagnostics
+          {available: available?, reason: unavailable_reason, kinds: available? ? kinds.select { |k| supports?(k) } : []}
+        end
+
+        # Forgets memoized availability (tests, or after installing tools at runtime).
+        def reset!
+          remove_instance_variable(:@available) if defined?(@available)
+          @unavailable_reason = nil
+        end
+
+        private
+
+        # Subclasses return true/false and may set @unavailable_reason.
+        def probe
+          raise NotImplementedError, "#{name}.probe"
+        end
+      end
+
+      # @return [Config] effective configuration (global config merged with per-call overrides)
+      attr_reader :config
+
+      # @param config [Config]
+      def initialize(config = ZXingFFI.config)
+        @config = config
+      end
+
+      # Opens a document. Encrypted PDFs without a (correct) password raise before any rendering.
+      #
+      # @param source [Source] absolute path + sniffed kind
+      # @param password [String, nil]
+      # @return [Document]
+      # @raise [PasswordRequired, IncorrectPassword, RenderError, LimitExceeded, UnsupportedInput]
+      def open(source, password: nil)
+        raise NotImplementedError, "#{self.class}#open"
+      end
+    end
+
+    # An opened input: a sequence of pages (PDF) or frames (raster). Always {#close} it.
+    class Document
+      # @return [Source]
+      attr_reader :source
+
+      def initialize(source)
+        @source = source
+      end
+
+      # @return [Integer]
+      def page_count
+        raise NotImplementedError, "#{self.class}#page_count"
+      end
+
+      # @param number [Integer] 1-based
+      # @return [PageInfo]
+      def page_info(number)
+        raise NotImplementedError, "#{self.class}#page_info"
+      end
+
+      # Renders or decodes one page. +dpi+ is honored for PDFs and ignored for rasters.
+      #
+      # @param number [Integer] 1-based
+      # @param dpi [Integer, Float, nil]
+      # @param timeout [Numeric, nil] seconds for this render, capped by config.render_timeout (subprocess loaders;
+      #   in-process loaders cannot be interrupted and ignore it)
+      # @return [Page]
+      def render(number, dpi: nil, timeout: nil)
+        raise NotImplementedError, "#{self.class}#render"
+      end
+
+      # Releases resources (temp files, handles). Idempotent.
+      def close
+      end
+
+      private
+
+      def check_page!(number)
+        return if number.is_a?(Integer) && number.between?(1, page_count)
+
+        raise ArgumentError, "page #{number.inspect} out of range 1..#{page_count}"
+      end
+    end
+  end
+end