zxing_ffi 0.1.0

data/lib/zxing_ffi/reader.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  # Single-pass decoding of an {Image}: options → native ReaderOptions, native object lifetimes,
+  # and extraction of results into Ruby objects before the native collection is freed.
+  module Reader
+    # Option → [ReaderOptions setter, kind]. Kinds: :bool, :byte (1..255), or an Array of allowed symbols.
+    SETTERS = {
+      try_harder: [:ZXing_ReaderOptions_setTryHarder, :bool],
+      try_rotate: [:ZXing_ReaderOptions_setTryRotate, :bool],
+      try_invert: [:ZXing_ReaderOptions_setTryInvert, :bool],
+      try_downscale: [:ZXing_ReaderOptions_setTryDownscale, :bool],
+      try_denoise: [:ZXing_ReaderOptions_setTryDenoise, :bool],
+      pure: [:ZXing_ReaderOptions_setIsPure, :bool],
+      return_errors: [:ZXing_ReaderOptions_setReturnErrors, :bool],
+      validate_optional_checksum: [:ZXing_ReaderOptions_setValidateOptionalChecksum, :bool],
+      binarizer: [:ZXing_ReaderOptions_setBinarizer, %i[local_average global_histogram fixed_threshold bool_cast]],
+      text_mode: [:ZXing_ReaderOptions_setTextMode, %i[plain eci hri escaped hex hex_eci]],
+      ean_add_on: [:ZXing_ReaderOptions_setEanAddOnSymbol, %i[ignore read require]],
+      max_symbols: [:ZXing_ReaderOptions_setMaxNumberOfSymbols, :byte],
+      min_line_count: [:ZXing_ReaderOptions_setMinLineCount, :byte]
+    }.freeze
+
+    # Every option {ZXingFFI.read} accepts.
+    OPTION_KEYS = ([:formats] + SETTERS.keys).freeze
+
+    # Gem defaults applied unless overridden. Everything else keeps the
+    # library's default (see {ZXingFFI::LIBRARY_DEFAULTS}).
+    GEM_DEFAULTS = {
+      formats: :all,
+      validate_optional_checksum: true,
+      text_mode: :plain,
+      return_errors: false
+    }.freeze
+
+    # Validated reader options, reusable across many decodes (the scanner builds one per pass).
+    class Options
+      # @return [Hash{Symbol => Object}] effective settings (gem defaults merged with the given options)
+      attr_reader :settings
+      # @return [Array<Integer>, nil] resolved ZXing_BarcodeFormat values (nil = every format)
+      attr_reader :format_values
+
+      # @param options [Hash] see {ZXingFFI.read}; +nil+ values mean "library default"
+      # @param defaults [Hash] merged underneath +options+
+      # @raise [ArgumentError] for unknown keys or invalid values
+      # @raise [NotSupported] for +try_denoise: true+ when the library lacks it
+      def initialize(options = {}, defaults = GEM_DEFAULTS)
+        options = options.to_h
+        unknown = options.keys - OPTION_KEYS
+        raise ArgumentError, "unknown option(s) #{unknown.map(&:inspect).join(", ")}; valid: #{OPTION_KEYS.join(", ")}" if unknown.any?
+
+        @settings = defaults.merge(options).reject { |_, value| value.nil? }
+        @settings.each { |key, value| validate(key, value) unless key == :formats }
+        @format_values = Formats.resolve(@settings[:formats]).freeze
+        if @settings[:try_denoise] && !Native.supports?(:try_denoise)
+          raise NotSupported, "try_denoise needs libZXing built with ZXING_EXPERIMENTAL_API (#{Native.library.path})"
+        end
+        @settings.freeze
+        freeze
+      end
+
+      # @return [Options] a copy with +overrides+ applied on top
+      def merge(overrides)
+        return self if overrides.empty?
+
+        Options.new(settings.merge(overrides), {})
+      end
+
+      # @return [Object] the effective value of +key+ (nil = library default)
+      def [](key)
+        settings[key]
+      end
+
+      # @return [Hash]
+      def to_h
+        settings.dup
+      end
+
+      # Applies the settings to a native ZXing_ReaderOptions*.
+      # @api private
+      def apply(native_options)
+        settings.each do |key, value|
+          next if key == :formats
+          next if key == :try_denoise && !value # absent symbol + false is a no-op
+
+          Native.public_send(SETTERS.fetch(key).first, native_options, value)
+        end
+        return unless format_values
+
+        buffer = FFI::MemoryPointer.new(:int, format_values.size)
+        buffer.write_array_of_int(format_values)
+        Native.ZXing_ReaderOptions_setFormats(native_options, buffer, format_values.size)
+      end
+
+      private
+
+      def validate(key, value)
+        kind = SETTERS.fetch(key).last
+        valid =
+          case kind
+          when :bool then value == true || value == false
+          when :byte then value.is_a?(Integer) && value.between?(1, 255)
+          else kind.include?(value)
+          end
+        return if valid
+
+        expected =
+          case kind
+          when :bool then "true or false"
+          when :byte then "an Integer in 1..255"
+          else kind.map(&:inspect).join(", ")
+          end
+        raise ArgumentError, "invalid #{key}: #{value.inspect} (expected #{expected})"
+      end
+    end
+
+    class << self
+      # Decodes +image+ once with +options+ and returns every barcode the library reports.
+      #
+      # @param image [Image]
+      # @param options [Hash, Options]
+      # @param crop [Array(Integer, Integer, Integer, Integer), nil] +[left, top, width, height]+ view into the
+      #   image (no copy, via ZXing_ImageView_crop); positions are then relative to the crop.
+      # @return [Array<Barcode>]
+      # @raise [DecodeError] when ZXing_ReadBarcodes returns NULL
+      def read(image, options = {}, crop: nil)
+        raise TypeError, "expected a ZXingFFI::Image, got #{image.class}" unless image.is_a?(Image)
+
+        options = Options.new(options) unless options.is_a?(Options)
+        Native.load!
+        pixels = image.pointer # raises if released; keeps the buffer referenced for the whole call
+        validate_crop!(image, crop) if crop
+
+        text_mode = options[:text_mode] || LIBRARY_DEFAULTS[:text_mode]
+        view = options_ptr = barcodes = nil
+        # Interrupts (Thread#raise, Timeout, signals) are deferred until the native objects are freed: otherwise one
+        # arriving just after a native call returns, before its result is assigned, would leak that result. The
+        # decode itself cannot be interrupted anyway while it runs without the GVL.
+        Thread.handle_interrupt(Object => :never) do
+          view = new_view(image, pixels)
+          Native.ZXing_ImageView_crop(view, *crop) if crop
+          options_ptr = Native.ZXing_ReaderOptions_new
+          raise DecodeError, "ZXing_ReaderOptions_new failed: #{Native.last_error_message}" if options_ptr.null?
+
+          options.apply(options_ptr)
+          barcodes = Native.ZXing_ReadBarcodes(view, options_ptr)
+          if barcodes.null?
+            raise DecodeError, Native.last_error_message || "ZXing_ReadBarcodes failed (no error message available)"
+          end
+
+          Array.new(Native.ZXing_Barcodes_size(barcodes)) { |i| build(Native.ZXing_Barcodes_at(barcodes, i), text_mode) }
+        ensure
+          Native.ZXing_Barcodes_delete(barcodes) if barcodes && !barcodes.null?
+          Native.ZXing_ReaderOptions_delete(options_ptr) if options_ptr && !options_ptr.null?
+          Native.ZXing_ImageView_delete(view) if view && !view.null?
+        end
+      end
+
+      # The library's ReaderOptions defaults, read through the get* functions.
+      # @return [Hash{Symbol => Object}]
+      def library_defaults
+        Native.load!
+        ptr = Native.ZXing_ReaderOptions_new
+        raise DecodeError, "ZXing_ReaderOptions_new failed" if ptr.null?
+
+        begin
+          defaults = {
+            formats: Native.take_formats { |count| Native.ZXing_ReaderOptions_getFormats(ptr, count) }.to_a.map { |v| Formats.symbol_for(v) },
+            try_harder: Native.ZXing_ReaderOptions_getTryHarder(ptr),
+            try_rotate: Native.ZXing_ReaderOptions_getTryRotate(ptr),
+            try_invert: Native.ZXing_ReaderOptions_getTryInvert(ptr),
+            try_downscale: Native.ZXing_ReaderOptions_getTryDownscale(ptr)
+          }
+          defaults[:try_denoise] = Native.ZXing_ReaderOptions_getTryDenoise(ptr) if Native.supports?(:try_denoise)
+          defaults.merge(
+            pure: Native.ZXing_ReaderOptions_getIsPure(ptr),
+            return_errors: Native.ZXing_ReaderOptions_getReturnErrors(ptr),
+            validate_optional_checksum: Native.ZXing_ReaderOptions_getValidateOptionalChecksum(ptr),
+            binarizer: Native.ZXing_ReaderOptions_getBinarizer(ptr),
+            text_mode: Native.ZXing_ReaderOptions_getTextMode(ptr),
+            ean_add_on: Native.ZXing_ReaderOptions_getEanAddOnSymbol(ptr),
+            max_symbols: Native.ZXing_ReaderOptions_getMaxNumberOfSymbols(ptr),
+            min_line_count: Native.ZXing_ReaderOptions_getMinLineCount(ptr)
+          )
+        ensure
+          Native.ZXing_ReaderOptions_delete(ptr)
+        end
+      end
+
+      private
+
+      def new_view(image, pixels)
+        view =
+          if Native.supports?(:image_view_new_checked)
+            Native.ZXing_ImageView_new_checked(pixels, image.bytesize, image.width, image.height, image.format, image.row_stride, 0)
+          else
+            Native.ZXing_ImageView_new(pixels, image.width, image.height, image.format, image.row_stride, 0)
+          end
+        raise DecodeError, "could not create an ImageView for #{image.inspect}: #{Native.last_error_message}" if view.null?
+
+        view
+      end
+
+      def validate_crop!(image, crop)
+        left, top, width, height = crop
+        valid = crop.is_a?(Array) && crop.size == 4 && crop.all?(Integer) &&
+          left >= 0 && top >= 0 && width.positive? && height.positive? &&
+          left + width <= image.width && top + height <= image.height
+        raise ArgumentError, "crop #{crop.inspect} is outside #{image.width}x#{image.height}" unless valid
+      end
+
+      # Copies every field of a (parent-owned) ZXing_Barcode* into a Ruby Barcode.
+      def build(ptr, text_mode)
+        format = Native.ZXing_Barcode_format(ptr)
+        error_type = Native.ZXing_Barcode_errorType(ptr)
+        bytes = Native.take_bytes { |len| Native.ZXing_Barcode_bytes(ptr, len) }
+        Barcode.new(
+          text: text(Native.take_string(Native.ZXing_Barcode_text(ptr)) || "", bytes, text_mode),
+          bytes: bytes,
+          format: Formats.symbol_for(format),
+          symbology: Formats.symbol_for(Native.ZXing_Barcode_symbology(ptr)),
+          format_name: Formats.name_for(format),
+          content_type: Native.ZXing_Barcode_contentType(ptr),
+          symbology_identifier: Native.take_string(Native.ZXing_Barcode_symbologyIdentifier(ptr)) || "",
+          position: quad(Native.ZXing_Barcode_position(ptr)),
+          page_position: nil,
+          rotation: Native.barcode_rotation(ptr) % 360,
+          mirrored: Native.ZXing_Barcode_isMirrored(ptr),
+          inverted: Native.ZXing_Barcode_isInverted(ptr),
+          eci: Native.ZXing_Barcode_hasECI(ptr),
+          valid: Native.ZXing_Barcode_isValid(ptr),
+          error: (error_type == :none) ? nil : {type: error_type, message: Native.take_string(Native.ZXing_Barcode_errorMsg(ptr))},
+          line_count: Native.ZXing_Barcode_lineCount(ptr),
+          sequence: sequence(ptr),
+          extra_json: Native.take_string(Native.ZXing_Barcode_extra(ptr, nil)),
+          page: nil,
+          pass: nil,
+          dpi: nil
+        )
+      end
+
+      # ZXing_Barcode_text returns a NUL-terminated C string, so plain text of a payload containing NUL bytes is
+      # cut at the first NUL. Rebuild it from the bytes the way zxing-cpp renders undeclared binary data (UTF-8 if
+      # valid, else ISO-8859-1), provided the library's prefix agrees.
+      def text(text, bytes, text_mode)
+        return text unless text_mode == :plain && bytes.include?("\x00")
+
+        utf8 = bytes.dup.force_encoding(Encoding::UTF_8)
+        rebuilt = utf8.valid_encoding? ? utf8 : bytes.dup.force_encoding(Encoding::ISO_8859_1).encode(Encoding::UTF_8)
+        rebuilt.start_with?(text) ? rebuilt : text
+      end
+
+      def quad(position)
+        corners = %i[top_left top_right bottom_right bottom_left].map do |corner|
+          point = position[corner]
+          Geometry::Point.new(point[:x], point[:y])
+        end
+        Geometry::Quad.new(*corners)
+      end
+
+      # Structured append: the library reports -1/-1 outside a sequence; size 0 means "unknown count".
+      def sequence(ptr)
+        index = Native.ZXing_Barcode_sequenceIndex(ptr)
+        size = Native.ZXing_Barcode_sequenceSize(ptr)
+        return nil if index.negative? || size.negative? || size == 1
+
+        {index: index, size: size.zero? ? nil : size, id: Native.take_string(Native.ZXing_Barcode_sequenceId(ptr))}
+      end
+    end
+  end
+end

data/lib/zxing_ffi/scanner.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+module ZXingFFI
+  # Results for one page or frame.
+  #
+  # @!attribute page [Integer] 1-based
+  # @!attribute barcodes [Array<Barcode>] ordered top-to-bottom, left-to-right
+  # @!attribute dpi [Integer, nil] base render DPI (PDF) or nil
+  # @!attribute width [Integer, nil] base image width in pixels
+  # @!attribute height [Integer, nil] base image height in pixels
+  # @!attribute passes_run [Array<Symbol>]
+  # @!attribute skipped_passes [Hash{Symbol => String}] passes that could not run, with the reason
+  # @!attribute duration [Float] seconds spent on the page
+  # @!attribute error [Exception, nil] set only with +on_page_error: :skip+
+  # @!attribute metadata [Hash] what the loader applied (orientation, aspect correction, DPI capping, …)
+  PageResult = Data.define(:page, :barcodes, :dpi, :width, :height, :passes_run, :skipped_passes, :duration, :error, :metadata)
+
+  # Orchestrates a scan: input → loader → pages → pass ladder → ordered results, optionally on several
+  # threads.
+  class Scanner
+    # Options that only the scanner understands.
+    SCAN_OPTIONS = %i[
+      effort passes stop dpi max_dpi max_pixels max_pages pages password threads on_page_error loader
+      min_length timeout instrument
+    ].freeze
+
+    # Every option +scan+/+scan_pages+ accept: the scanner's plus every {ZXingFFI.read} option.
+    OPTIONS = (SCAN_OPTIONS + Reader::OPTION_KEYS).freeze
+
+    # Accepted values of +on_page_error:+.
+    ON_PAGE_ERROR = %i[raise skip].freeze
+
+    # @param options [Hash] see {ZXingFFI.scan}
+    # @raise [ArgumentError] for unknown or invalid options (before any input is opened)
+    def initialize(**options)
+      unknown = options.keys - OPTIONS
+      raise ArgumentError, "unknown option(s) #{unknown.map(&:inspect).join(", ")}; valid: #{OPTIONS.join(", ")}" if unknown.any?
+
+      @passes = Strategy.passes_for(effort: options.fetch(:effort, :normal), passes: options[:passes])
+      @stop = Strategy.validate_stop(options.fetch(:stop, :found))
+      @dpi = validate_dpi(options.fetch(:dpi, :auto))
+      @pages = validate_pages(options[:pages])
+      @password = options[:password]&.to_s
+      @threads = validate_positive_integer(:threads, options.fetch(:threads, 1))
+      @on_page_error = options.fetch(:on_page_error, :raise)
+      raise ArgumentError, "on_page_error must be :raise or :skip, got #{@on_page_error.inspect}" unless ON_PAGE_ERROR.include?(@on_page_error)
+
+      @loader = options[:loader]
+      @timeout = options[:timeout] && validate_positive_number(:timeout, options[:timeout])
+      @instrument = options[:instrument]
+      raise ArgumentError, "instrument must respond to #call" if @instrument && !@instrument.respond_to?(:call)
+
+      @config = effective_config(options)
+      @reader_options = Reader::Options.new(options.slice(*Reader::OPTION_KEYS))
+      @min_length = validate_min_length(options.fetch(:min_length, {}))
+      @notify_mutex = Mutex.new
+    end
+
+    # @return [Array<Barcode>] every page's barcodes, ordered by page then position
+    def scan(input)
+      results = []
+      scan_pages(input) { |page_result| results.concat(page_result.barcodes) }
+      results
+    end
+
+    # Yields a {PageResult} per selected page, in page order.
+    # @yieldparam page_result [PageResult]
+    # @return [nil]
+    def scan_pages(input, &block)
+      raise ArgumentError, "a block is required" unless block
+
+      if input.is_a?(Image)
+        yield process(nil, 1, pdf: false, image: input)
+      else
+        Source.open(input) { |source| scan_source(source, &block) }
+      end
+      nil
+    end
+
+    # Orders barcodes top-to-bottom, then left-to-right (by quad center). Centers within half the smaller
+    # code's height (at least 8 px) count as the same row.
+    # @return [Array<Barcode>]
+    def self.order(barcodes)
+      rows = []
+      barcodes.sort_by { |b| [b.center.y, b.center.x] }.each do |barcode|
+        row = rows.last
+        if row && (barcode.center.y - row.first.center.y).abs <= row_tolerance(row.first, barcode)
+          row << barcode
+        else
+          rows << [barcode]
+        end
+      end
+      rows.flat_map { |row| row.sort_by { |b| b.center.x } }
+    end
+
+    def self.row_tolerance(a, b)
+      heights = [a, b].map { |barcode| barcode.position.bounding_box.then { |_, y0, _, y1| y1 - y0 } }
+      [8, heights.min / 2.0].max
+    end
+    private_class_method :row_tolerance
+
+    private
+
+    def scan_source(source, &block)
+      HeaderProbe.check!(source.path, source.kind, @config.max_pixels) unless source.kind == :pdf
+      loader_class = Loaders::Registry.loader_for(source.kind, config: @config, loader: @loader)
+      document = loader_class.new(@config).open(source, password: @password)
+      begin
+        numbers = select_pages(document.page_count)
+        if @config.max_pages && numbers.size > @config.max_pages
+          raise LimitExceeded.new("#{numbers.size} pages selected, max_pages is #{@config.max_pages}",
+            limit: :max_pages, value: numbers.size)
+        end
+
+        pdf = source.kind == :pdf
+        each_result(numbers, ->(number) { process(document, number, pdf: pdf) }, &block)
+      ensure
+        document.close
+      end
+    end
+
+    # Runs +work+ for each page number, on @threads threads, yielding results in page order.
+    def each_result(numbers, work)
+      if @threads <= 1 || numbers.size <= 1
+        numbers.each { |number| yield work.call(number) }
+        return
+      end
+
+      queue = Queue.new
+      numbers.each { |number| queue << number }
+      queue.close
+      results = Queue.new
+      workers = Array.new([@threads, numbers.size].min) do
+        Thread.new do
+          while (number = queue.pop)
+            outcome =
+              begin
+                work.call(number)
+              rescue Exception => e # rubocop:disable Lint/RescueException -- re-raised on the caller's thread
+                e
+              end
+            results << [number, outcome]
+          end
+        end
+      end
+
+      buffered = {}
+      numbers.each do |number|
+        buffered.store(*results.pop) until buffered.key?(number)
+        outcome = buffered.delete(number)
+        raise outcome if outcome.is_a?(Exception)
+
+        yield outcome
+      end
+      completed = true
+    ensure
+      if workers
+        queue.clear # stop handing out pages
+        # Leaving early (error, break, Ctrl-C, Timeout): don't wait for pages in progress. Killing is safe: native
+        # decodes defer interrupts until their objects are freed, and Subprocess kills its child process group.
+        workers.each(&:kill) unless completed
+        workers.each(&:join)
+      end
+    end
+
+    def process(document, number, pdf:, image: nil)
+      started = monotonic
+      deadline = @timeout && started + @timeout
+      page = nil
+      info = document&.page_info(number)
+      choice = pdf ? choose_dpi(info) : nil
+      page = image ? Loaders::Page.new(number: 1, image: image, dpi: nil, scale_to_base: 1.0, metadata: {loader: :image}) : document.render(number, dpi: choice&.dpi)
+      notify(:page_loaded, page: number, width: page.image.width, height: page.image.height, dpi: page.dpi, duration: monotonic - started)
+
+      # re-renders (high_res pass) get only what is left of the page budget
+      rerender = pdf ? ->(dpi) { document.render(number, dpi: dpi, timeout: deadline && [deadline - monotonic, 0.05].max) } : nil
+      result = strategy.run(page, rerender: rerender, page_info: info, deadline: deadline,
+        notify: ->(event, payload) { notify(event, page: number, **payload) })
+      barcodes = Scanner.order(result.barcodes.map { |barcode| finalize(barcode, number, page.dpi) })
+      metadata = page.metadata.merge(choice ? {dpi_source: choice.source, dpi_capped: choice.capped} : {})
+      page_result = PageResult.new(
+        page: number, barcodes: barcodes, dpi: page.dpi, width: page.image.width, height: page.image.height,
+        passes_run: result.passes_run, skipped_passes: result.skipped_passes, duration: monotonic - started,
+        error: nil, metadata: metadata
+      )
+      notify(:page_completed, page: number, barcodes: barcodes.size, passes_run: result.passes_run, duration: page_result.duration)
+      page_result
+    rescue => e
+      raise if @on_page_error == :raise
+
+      PageResult.new(
+        page: number, barcodes: [], dpi: page&.dpi, width: nil, height: nil, passes_run: [], skipped_passes: {},
+        duration: monotonic - started, error: e, metadata: {}
+      )
+    ensure
+      page.image.release! if page && !image
+    end
+
+    def strategy
+      Strategy.new(passes: @passes, stop: @stop, options: @reader_options, config: @config, min_length: @min_length,
+        transformer: -> { Transformers.first_available(@config.transformers, config: @config) })
+    end
+
+    def choose_dpi(info)
+      Dpi.choose(requested: @dpi, width_pt: info.width, height_pt: info.height, native_ppi: info.native_ppi,
+        default_dpi: @config.default_dpi, max_dpi: @config.max_dpi, max_pixels: @config.max_pixels)
+    end
+
+    # Adds page metadata and PDF page coordinates (points from the top-left of the displayed page).
+    def finalize(barcode, number, dpi)
+      page_position = dpi && barcode.position.map { |p| Geometry::Point.new((p.x * 72.0 / dpi).round(2), (p.y * 72.0 / dpi).round(2)) }
+      barcode.with(page: number, dpi: dpi, page_position: page_position)
+    end
+
+    def select_pages(count)
+      numbers =
+        case @pages
+        when nil then (1..count).to_a
+        when Integer then [@pages]
+        when Range
+          last = if @pages.end.nil?
+            count
+          else
+            (@pages.exclude_end? ? @pages.end - 1 : @pages.end)
+          end
+          ((@pages.begin || 1)..[last, count].min).to_a
+        else @pages.uniq.sort
+        end
+      numbers.select! { |n| n.between?(1, count) }
+      raise ArgumentError, "no pages selected: #{@pages.inspect} is outside 1..#{count}" if numbers.empty?
+
+      numbers
+    end
+
+    def notify(event, **payload)
+      return unless @instrument
+
+      @notify_mutex.synchronize { @instrument.call(event, payload) }
+    end
+
+    def effective_config(options)
+      overrides = options.slice(:max_dpi, :max_pixels, :max_pages)
+      if @timeout
+        overrides[:render_timeout] = [ZXingFFI.config.render_timeout, @timeout].compact.min
+      end
+      ZXingFFI.config.with(**overrides)
+    end
+
+    def validate_dpi(dpi)
+      return dpi if dpi == :auto || (dpi.is_a?(Integer) && dpi.positive?)
+
+      raise ArgumentError, "dpi must be a positive Integer or :auto, got #{dpi.inspect}"
+    end
+
+    def validate_pages(pages)
+      valid =
+        case pages
+        when nil then true
+        when Integer then pages.positive?
+        when Range then [pages.begin, pages.end].all? { |n| n.nil? || (n.is_a?(Integer) && n.positive?) }
+        when Array then pages.any? && pages.all? { |n| n.is_a?(Integer) && n.positive? }
+        else false
+        end
+      return pages if valid
+
+      raise ArgumentError, "pages must be a positive Integer, a Range or an Array of 1-based page numbers, got #{pages.inspect}"
+    end
+
+    def validate_min_length(min_length)
+      raise ArgumentError, "min_length must be a Hash of format => Integer" unless min_length.is_a?(Hash)
+
+      min_length.each do |format, length|
+        raise ArgumentError, "min_length: unknown format #{format.inspect}" unless Formats.all.include?(format)
+        raise ArgumentError, "min_length for #{format.inspect} must be a non-negative Integer" unless length.is_a?(Integer) && length >= 0
+      end
+      min_length.dup.freeze
+    end
+
+    def validate_positive_integer(name, value)
+      return value if value.is_a?(Integer) && value.positive?
+
+      raise ArgumentError, "#{name} must be a positive Integer, got #{value.inspect}"
+    end
+
+    def validate_positive_number(name, value)
+      return value if value.is_a?(Numeric) && value.positive?
+
+      raise ArgumentError, "#{name} must be a positive number of seconds, got #{value.inspect}"
+    end
+
+    def monotonic
+      Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+  end
+end