bidi2pdf 0.1.8 → 0.1.10

data/lib/bidi2pdf/test_helpers/images/tiff_helper.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module TestHelpers
+    module Images
+      # rubocop: disable  Metrics/ModuleLength, Metrics/AbcSize
+      module TIFFHelper
+        # TIFF Tag IDs
+        IMAGE_WIDTH = 256
+        IMAGE_LENGTH = 257
+        BITS_PER_SAMPLE = 258
+        COMPRESSION = 259
+        PHOTOMETRIC_INTERPRETATION = 262
+        STRIP_OFFSETS = 273
+        SAMPLES_PER_PIXEL = 277
+        ROWS_PER_STRIP = 278
+        STRIP_BYTE_COUNTS = 279
+        PLANAR_CONFIGURATION = 284
+        INK_SET = 332
+
+        # TIFF Data Types
+        TYPE_SHORT = 3
+        TYPE_LONG = 4
+
+        # TIFF Compression Types
+        COMPRESSION_NONE = 1
+        COMPRESSION_CCITT_G3 = 3
+        COMPRESSION_CCITT_G4 = 4
+
+        # TIFF Photometric Interpretations
+        PHOTO_WHITE_IS_ZERO = 0
+        PHOTO_BLACK_IS_ZERO = 1
+        PHOTO_RGB = 2
+        PHOTO_SEPARATION = 5
+
+        # Planar Configuration
+        PLANAR_CHUNKY = 1
+
+        def tiff_header(hash, data)
+          cs_entry = hash[:ColorSpace]
+
+          cs = if cs_entry.is_a?(Array) && cs_entry.first == :ICCBased
+                 icc_stream = cs_entry[1]
+                 icc_stream.hash[:Alternate]
+               else
+                 cs_entry
+               end
+
+          case cs
+          when :DeviceCMYK then tiff_header_for_CMYK(hash, data)
+          when :DeviceGray then tiff_header_for_gray(hash, data)
+          when :DeviceRGB then tiff_header_for_rgb(hash, data)
+          else
+            logger.warn("Unsupported color space '#{cs}' for compressed image with filter '#{hash[:Filter]}'. Skipping image.")
+            nil # Skip processing this image
+          end
+        end
+
+        # See:
+        #    * https://gist.github.com/gstorer/f6a9f1dfe41e8e64dcf58d07afa9ab2a
+        #    * https://github.com/yob/pdf-reader/blob/main/examples/extract_images.rb
+        def pack_tiff(entries)
+          fields = entries.size
+          fmt = [
+            "a2", # Byte order ("II")
+            "S<", # TIFF magic (42)
+            "L<", # Offset to first IFD (8)
+            "S<", # Number of directory entries
+            ("S< S< L< L<" * fields), # each tag: id, type, count, value
+            "L<" # Next IFD offset (0 = end)
+          ].join(" ")
+
+          # Build the flat array: ['II', 42, 8, fields, tag1, type1, count1, value1, …, 0]
+          values = ["II", 42, 8, fields] + entries.flatten + [0]
+          values.pack(fmt)
+        end
+
+        def tiff_header_for_gray(hash, data)
+          width = hash[:Width]
+          height = hash[:Height]
+          bpc = hash[:BitsPerComponent] || 8
+          img_size = data.bytesize
+
+          # 9 tags, no extra arrays needed
+          fields = 9
+          # size of header+IFD before the image data starts
+          header_ifd_size = 2 + 2 + 4 + 2 + (fields * 12) + 4
+          data_offset = header_ifd_size
+
+          entries = [
+            [IMAGE_WIDTH, TYPE_LONG, 1, width], # ImageWidth
+            [IMAGE_LENGTH, TYPE_LONG, 1, height], # ImageLength
+            [BITS_PER_SAMPLE, TYPE_SHORT, 1, bpc], # BitsPerSample
+            [COMPRESSION, TYPE_SHORT, 1, COMPRESSION_NONE], # Compression (1 = none)
+            [PHOTOMETRIC_INTERPRETATION, TYPE_SHORT, 1, PHOTO_BLACK_IS_ZERO], # PhotometricInterpretation (1 = BlackIsZero)
+            [STRIP_OFFSETS, TYPE_LONG, 1, data_offset], # StripOffsets
+            [SAMPLES_PER_PIXEL, TYPE_SHORT, 1, 1], # SamplesPerPixel
+            [STRIP_BYTE_COUNTS, TYPE_LONG, 1, img_size], # StripByteCounts
+            [PLANAR_CONFIGURATION, TYPE_SHORT, 1, PLANAR_CHUNKY] # PlanarConfiguration (1 = chunky)
+          ]
+
+          pack_tiff(entries)
+        end
+
+        def tiff_header_for_ccitt(hash, data)
+          dp = hash[:DecodeParms] || {}
+          width = dp[:Columns] || hash[:Width]
+          height = hash[:Height]
+          k = dp[:K] || 0
+          group = (k.positive? ? COMPRESSION_CCITT_G3 : COMPRESSION_CCITT_G4)
+          img_size = data.bytesize
+
+          # We’ll emit exactly 8 tags:
+          fields = 8
+          # Calculate where the image data will start:
+          header_size = 2 + 2 + 4 + 2 + (fields * 12) + 4
+
+          entries = [
+            [IMAGE_WIDTH, TYPE_LONG, 1, width], # ImageWidth
+            [IMAGE_LENGTH, TYPE_LONG, 1, height], # ImageLength
+            [BITS_PER_SAMPLE, TYPE_SHORT, 1, 1], # BitsPerSample
+            [COMPRESSION, TYPE_SHORT, 1, group], # Compression (3=G3, 4=G4)
+            [PHOTOMETRIC_INTERPRETATION, TYPE_SHORT, 1, PHOTO_WHITE_IS_ZERO], # PhotometricInterpretation (0 = WhiteIsZero)
+            [STRIP_OFFSETS, TYPE_LONG, 1, header_size], # StripOffsets
+            [ROWS_PER_STRIP, TYPE_LONG, 1, height], # RowsPerStrip
+            [STRIP_BYTE_COUNTS, TYPE_LONG, 1, img_size] # StripByteCounts
+          ]
+
+          pack_tiff(entries)
+        end
+
+        def tiff_header_for_cmyk(hash, data)
+          width = hash[:Width]
+          height = hash[:Height]
+          bpc = hash[:BitsPerComponent] || 8
+          img_size = data.bytesize
+
+          # CMYK needs 10 tags + a 4×SHORT BitsPerSample array
+          fields = 10
+          bits_array_size = 4 * 2 # 4 channels × 2 bytes each
+
+          # Size of header + IFD (before the bits array)
+          header_ifd_size = 2 + 2 + 4 + 2 + (fields * 12) + 4
+          # Where the pixel data will really start:
+          data_offset = header_ifd_size + bits_array_size
+
+          entries = [
+            [IMAGE_WIDTH, TYPE_LONG, 1, width], # ImageWidth
+            [IMAGE_LENGTH, TYPE_LONG, 1, height], # ImageLength
+            [BITS_PER_SAMPLE, TYPE_SHORT, 4, header_ifd_size], # BitsPerSample (pointer to array)
+            [COMPRESSION, TYPE_SHORT, 1, COMPRESSION_NONE], # Compression (1 = none)
+            [PHOTOMETRIC_INTERPRETATION, TYPE_SHORT, 1, PHOTO_SEPARATION], # PhotometricInterpretation (5 = Separation)
+            [STRIP_OFFSETS, TYPE_LONG, 1, data_offset], # StripOffsets
+            [SAMPLES_PER_PIXEL, TYPE_SHORT, 1, 4], # SamplesPerPixel
+            [STRIP_BYTE_COUNTS, TYPE_LONG, 1, img_size], # StripByteCounts
+            [PLANAR_CONFIGURATION, TYPE_SHORT, 1, PLANAR_CHUNKY], # PlanarConfiguration (1 = chunky)
+            [INK_SET, TYPE_SHORT, 1, 1] # InkSet (1 = CMYK)
+          ]
+
+          header = pack_tiff(entries)
+          # Append the 4-channel BitsPerSample array as little‐endian SHORTs:
+          header << [bpc, bpc, bpc, bpc].pack("S<S<S<S<")
+          header
+        end
+
+        def tiff_header_for_rgb(hash, data)
+          width = hash[:Width]
+          height = hash[:Height]
+          bpc = hash[:BitsPerComponent] || 8
+          img_size = data.bytesize
+
+          # 8 tags + a 3×SHORT BitsPerSample array
+          fields = 8
+          bits_array_size = 3 * 2 # 3 channels × 2 bytes each
+
+          # size of header + IFD before the bits array
+          header_ifd_size = 2 + 2 + 4 + 2 + (fields * 12) + 4
+          # where the pixel data really starts:
+          data_offset = header_ifd_size + bits_array_size
+
+          entries = [
+            [IMAGE_WIDTH, TYPE_LONG, 1, width], # ImageWidth
+            [IMAGE_LENGTH, TYPE_LONG, 1, height], # ImageLength
+            [BITS_PER_SAMPLE, TYPE_SHORT, 3, header_ifd_size], # BitsPerSample → pointer to our array
+            [COMPRESSION, TYPE_SHORT, 1, COMPRESSION_NONE], # Compression (1 = none)
+            [PHOTOMETRIC_INTERPRETATION, TYPE_SHORT, 1, PHOTO_RGB], # PhotometricInterpretation (2 = RGB)
+            [STRIP_OFFSETS, TYPE_LONG, 1, data_offset], # StripOffsets
+            [SAMPLES_PER_PIXEL, TYPE_SHORT, 1, 3], # SamplesPerPixel
+            [STRIP_BYTE_COUNTS, TYPE_LONG, 1, img_size] # StripByteCounts
+          ]
+
+          # pack the IFD
+          header = pack_tiff(entries)
+
+          # append the 3-channel BitsPerSample as little-endian SHORTs
+          header << [bpc, bpc, bpc].pack("S<S<S<")
+
+          header
+        end
+      end
+    end
+    # rubocop: enable Metrics/ModuleLength, Metrics/AbcSize
+  end
+end

data/lib/bidi2pdf/test_helpers/images.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+%w[vips dhash-vips].each do |dep|
+  require dep
+rescue LoadError
+  warn "Missing #{dep}. Add it to your Gemfile if you're using Bidi2pdf image test helpers."
+end
+
+require_relative "images/tiff_helper"
+require_relative "images/extractor"
+require_relative "images/image_similarity_checker"
+require_relative "matchers/contains_pdf_image"

data/lib/bidi2pdf/test_helpers/matchers/contains_pdf_image.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+RSpec::Matchers.define :contains_pdf_image do |expected, tolerance: 10|
+  chain :at_page do |page_number|
+    @page_number = page_number
+  end
+
+  chain :at_position do |i|
+    @image_number = i
+  end
+
+  match do |actual_pdf|
+    extractor = Bidi2pdf::TestHelpers::Images::Extractor.new(actual_pdf)
+    @images = if @page_number
+                @image_number ? [extractor.image_on_page(@page_number, @image_number)].compact : extractor.images_on_page(@page_number)
+              else
+                extractor.all_images
+              end
+
+    @checkers = @images.map { |image| Bidi2pdf::TestHelpers::Images::ImageSimilarityChecker.new(expected, image) }
+
+    @checkers.any? { |checker| checker.similar?(tolerance:) }
+  end
+
+  failure_message do |_actual_pdf|
+    "expected to find one image #{"on page #{@page_number}" if @page_number}#{" at position #{@image_number}" if @image_number} to be perceptually similar (distance ≤ #{tolerance}), " \
+      "but Hamming distances have been #{@checkers.map(&:distance).join(", ")}"
+  end
+end

data/lib/bidi2pdf/test_helpers/pdf_file_helper.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module TestHelpers
+    # This module provides helper methods for handling PDF files in tests.
+    # It includes methods for debugging, storing, and managing PDF files.
+    module PdfFileHelper
+      # Executes a block with the given PDF data and handles debugging in case of test failures.
+      # If an expectation fails, the PDF data is saved to a file for debugging purposes.
+      # @param [String] pdf_data the PDF data to debug
+      # @yield [String] yields the PDF data to the given block
+      # @raise [RSpec::Expectations::ExpectationNotMetError] re-raises the exception after saving the PDF
+      def with_pdf_debug(pdf_data)
+        yield pdf_data
+      rescue RSpec::Expectations::ExpectationNotMetError => e
+        failure_output = store_pdf_file pdf_data, "test-failure"
+        puts "Test failed! PDF saved to: #{failure_output}"
+        raise e
+      end
+
+      # Stores the given PDF data to a file with a specified filename prefix.
+      # The file is saved in a temporary directory.
+      # @param [String] pdf_data the PDF data to store
+      # @param [String] filename_prefix the prefix for the generated filename (default: "test")
+      # @return [String] the full path to the saved PDF file
+      def store_pdf_file(pdf_data, filename_prefix = "test")
+        pdf_file = tmp_file("pdf-files", "#{filename_prefix}-#{Time.now.to_i}.pdf")
+        FileUtils.mkdir_p(File.dirname(pdf_file))
+        File.binwrite(pdf_file, pdf_data)
+
+        pdf_file
+      end
+    end
+
+    RSpec.configure do |config|
+      config.include PdfFileHelper, pdf: true
+    end
+  end
+end

data/lib/bidi2pdf/test_helpers/spec_paths_helper.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+# This module provides helper methods for managing paths in test environments.
+# It includes methods to retrieve directories and generate temporary file paths.
+module Bidi2pdf
+  module TestHelpers
+    # This submodule contains path-related helper methods and configuration for tests.
+    module SpecPathsHelper
+      # Retrieves the directory path for Docker files.
+      # @return [String] the Docker directory path
+      def fixture_dir
+        TestHelpers.configuration.fixture_dir
+      end
+
+      # Retrieves the directory path for fixtures.
+      # @return [String] the fixture directory path
+      def fixture_file(*)
+        File.join(fixture_dir, *)
+      end
+
+      # Retrieves the directory path for specs.
+      # @return [String] the spec directory path
+      def spec_dir
+        TestHelpers.configuration.spec_dir
+      end
+
+      # Retrieves the directory path for temporary files.
+      # @return [String] the temporary directory path
+      def tmp_dir
+        TestHelpers.configuration.tmp_dir
+      end
+
+      # Generates a path for a temporary file by joining the temporary directory with the given parts.
+      # @param [Array<String>] parts the parts of the file path to join
+      # @return [String] the full path to the temporary file
+      def tmp_file(*parts)
+        File.join(tmp_dir, *parts)
+      end
+
+      # Generates a random temporary directory path.
+      # @param [Array<String>] dirs additional directory components to include in the path
+      # @param [String, nil] prefix an optional prefix for the directory name
+      # @return [String] the full path to the random temporary directory
+      def random_tmp_dir(*dirs, prefix: nil)
+        base_dirs = [tmp_dir] + dirs.compact
+        pfx = prefix || TestHelpers.configuration.prefix
+        File.join(*base_dirs, "#{pfx}#{SecureRandom.hex(8)}")
+      end
+    end
+
+    # Configures RSpec to include and extend SpecPathsHelper for examples with the `:pdf` metadata.
+    RSpec.configure do |config|
+      # Includes SpecPathsHelper methods in examples with `:pdf` metadata.
+      config.include SpecPathsHelper, pdf: true
+
+      # Extends SpecPathsHelper methods to example groups with `:pdf` metadata.
+      config.extend SpecPathsHelper, pdf: true
+    end
+  end
+end

data/lib/bidi2pdf/test_helpers/testcontainers/chromedriver_container.rb

@@ -1,11 +1,5 @@
 # frozen_string_literal: true
 
-begin
-  require "testcontainers"
-rescue LoadError
-  warn "Missing #{dep}. Add it to your Gemfile if you're using Bidi2pdf test helpers."
-end
-
 module Bidi2pdf
   module TestHelpers
     module Testcontainers

data/lib/bidi2pdf/test_helpers/testcontainers/chromedriver_test_helper.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require_relative "shared_docker_network"
+
+module Bidi2pdf
+  module TestHelpers
+    module Testcontainers
+      module ChromedriverTestHelper
+        def session_url
+          chromedriver_container.session_url
+        end
+
+        def chromedriver_container
+          RSpec.configuration.chromedriver_container
+        end
+      end
+
+      module SessionTestHelper
+        def chrome_args
+          chrome_args = Bidi2pdf::Bidi::Session::DEFAULT_CHROME_ARGS.dup
+
+          # within github actions, the sandbox is not supported, when we start our own container
+          # some privileges are not available ???
+          if ENV["DISABLE_CHROME_SANDBOX"]
+            chrome_args << "--no-sandbox"
+
+            puts "🚨 Chrome sandbox disabled"
+          end
+          chrome_args
+        end
+
+        def create_session(session_url)
+          Bidi2pdf::Bidi::Session.new(session_url: session_url, headless: true, chrome_args: chrome_args)
+        end
+      end
+    end
+  end
+end
+
+RSpec.configure do |config|
+  config.add_setting :chromedriver_container, default: nil
+
+  config.include Bidi2pdf::TestHelpers::Testcontainers::ChromedriverTestHelper, chromedriver: true
+  config.include Bidi2pdf::TestHelpers::Testcontainers::SessionTestHelper, session: true
+
+  config.before(:suite) do
+    if chromedriver_tests_present?
+      config.chromedriver_container = start_chromedriver_container(
+        build_dir: File.join(Bidi2pdf::TestHelpers.configuration.docker_dir, ".."),
+        mounts: config.respond_to?(:chromedriver_mounts) ? config.chromedriver_mounts : {},
+        shared_network: config.shared_network
+      )
+
+      puts "🚀 chromedriver container started for tests"
+    end
+  end
+
+  config.after(:suite) do
+    stop_container config.chromedriver_container
+  end
+end
+
+def stop_container(container)
+  if container&.running?
+
+    if ENV["SHOW_CONTAINER_LOGS"]
+      puts "Container logs:"
+      logs_std, logs_error = container.logs
+
+      puts logs_error
+      puts logs_std
+    end
+
+    puts "🧹 #{container.image} stopping container..."
+    container.stop
+  end
+  container&.remove
+end
+
+def chromedriver_tests_present?
+  test_of_kind_present? :chromedriver
+end
+
+def test_of_kind_present?(type)
+  RSpec.world.filtered_examples.values.flatten.any? { |example| example.metadata[type] }
+end
+
+# alias the long class name
+ChromedriverTestcontainer = Bidi2pdf::TestHelpers::Testcontainers::ChromedriverContainer
+
+def start_chromedriver_container(build_dir:, mounts:, shared_network:)
+  container = ChromedriverTestcontainer.new(ChromedriverTestcontainer::DEFAULT_IMAGE,
+                                            build_dir: build_dir,
+                                            docker_file: "docker/Dockerfile.chromedriver")
+                                       .with_network(shared_network)
+                                       .with_network_aliases("remote-chrome")
+
+  container.with_filesystem_binds(mounts) if mounts&.any?
+
+  container.start
+
+  container
+end

data/lib/bidi2pdf/test_helpers/testcontainers/shared_docker_network.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+RSpec.configure do |config|
+  config.add_setting :shared_network, default: nil
+
+  config.before(:suite) do
+    examples = RSpec.world.filtered_examples.values.flatten
+    uses_containers = examples.any? do |ex|
+      ex.metadata[:nginx] || ex.metadata[:chrome] || ex.metadata[:chromedriver] || ex.metadata[:container]
+    end
+
+    if uses_containers
+      config.shared_network = Docker::Network.create("bidi2pdf-test-net-#{SecureRandom.hex(4)}")
+      puts "🕸️  started shared network #{config.shared_network}"
+    end
+  end
+
+  config.after(:suite) do
+    config.shared_network&.remove
+  end
+end

data/lib/bidi2pdf/test_helpers/testcontainers/testcontainers_refinement.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Bidi2pdf
+  module TestHelpers
+    module TestcontainersRefinement
+      def id
+        @_id
+      end
+
+      def aliases
+        @aliases ||= []
+      end
+
+      def aliases=(aliases)
+        @aliases = aliases
+      end
+
+      def network
+        @_network
+      end
+
+      def with_network(network)
+        @_network = network
+        self
+      end
+
+      def with_network_aliases(*aliases)
+        self.aliases += aliases
+        self
+      end
+
+      def _container_create_options
+        opts = super
+        network_name = network&.info&.[]("Name")
+        opts["HostConfig"]["NetworkMode"] = network_name
+
+        if network && aliases.any?
+          opts["NetworkingConfig"] = {
+            "EndpointsConfig" => {
+              network_name => {
+                "Aliases" => aliases
+              }
+            }
+          }
+        end
+
+        opts.compact
+      end
+    end
+  end
+end
+
+Testcontainers::DockerContainer.prepend(Bidi2pdf::TestHelpers::TestcontainersRefinement)

data/lib/bidi2pdf/test_helpers/testcontainers.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+%w[docker testcontainers].each do |dep|
+  require dep
+rescue LoadError
+  warn "Missing #{dep}. Add it to your Gemfile if you're using Bidi2pdf test helpers."
+end
+
+module Bidi2pdf
+  module TestHelpers
+    module Testcontainers
+      require_relative "testcontainers/testcontainers_refinement"
+      require_relative "testcontainers/chromedriver_container"
+      require_relative "testcontainers/chromedriver_test_helper"
+    end
+  end
+end

data/lib/bidi2pdf/test_helpers.rb

@@ -6,8 +6,15 @@ rescue LoadError
   warn "Missing #{dep}. Add it to your Gemfile if you're using Bidi2pdf test helpers."
 end
 
+require "bidi2pdf/test_helpers/configuration"
+require "bidi2pdf/test_helpers/pdf_file_helper"
+require "bidi2pdf/test_helpers/spec_paths_helper"
 require "bidi2pdf/test_helpers/pdf_text_sanitizer"
 require "bidi2pdf/test_helpers/pdf_reader_utils"
 require "bidi2pdf/test_helpers/matchers/match_pdf_text"
 require "bidi2pdf/test_helpers/matchers/contains_pdf_text"
 require "bidi2pdf/test_helpers/matchers/have_pdf_page_count"
+
+# don't require "bidi2pdf/test_helpers/matchers/contains_pdf_image.rb" directly, use
+# require "bidi2pdf/test_helpers/images" instead, because it requires
+# ruby-vips and dhash-vips, and not every one wants to use them

data/lib/bidi2pdf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bidi2pdf
-  VERSION = "0.1.8"
+  VERSION = "0.1.10"
 end

data/sig/bidi2pdf/bidi/event_manager.rbs

@@ -1,29 +1,35 @@
 module Bidi2pdf
   module Bidi
     class EventManager
-      @browser: Bidi2pdf::Bidi::Browser
-      @listeners: Hash[String, Array[Proc]]
-      @active: bool
+      class Listener
+        attr_reader block: untyped
+        attr_reader id: String
 
-      def initialize: (browser: Bidi2pdf::Bidi::Browser) -> void
+        def initialize: (untyped block, ?String id) -> void
 
-      def on: (String event_name) { (Hash[String, untyped]) -> void } -> void
+        def call: (*untyped args) -> untyped
 
-      def off: (String event_name) -> void
+        def ==: (untyped other) -> bool
 
-      def emit: (String event_name, Hash[String, untyped] params) -> void
+        def eql?: (untyped other) -> bool
 
-      def start_listening: () -> void
+        def hash: () -> Integer
+      end
 
-      def stop_listening: () -> void
+      @listeners: untyped
+      @type: untyped
 
-      private
+      attr_reader type: untyped
 
-      def register_browser_events: () -> void
+      def initialize: (untyped type) -> void
 
-      def handle_event: (String event_name, Hash[String, untyped] params) -> void
+      def on: (*untyped event_names, &untyped block) -> Listener
 
-      def process_event: (String event_name, Hash[String, untyped] params) -> void
+      def off: (untyped event_name, Listener listener) -> void
+
+      def dispatch: (untyped event_name, *untyped args) -> void
+
+      def clear: (?untyped event_name) -> void
     end
   end
 end