png_conform 0.1.2 → 0.1.3

data/lib/png_conform/services/chunk_processor.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require_relative "../validators/chunk_registry"
+require_relative "validator_pool"
+
+module PngConform
+  module Services
+    # Processes chunks through validation pipeline
+    #
+    # The ChunkProcessor handles:
+    # - Iterating through chunks from the reader
+    # - Creating validators via ChunkRegistry
+    # - Collecting validation results
+    # - Handling unknown chunk types
+    #
+    # This class extracts chunk processing logic from ValidationService
+    # following Single Responsibility Principle.
+    #
+    class ChunkProcessor
+      # Initialize chunk processor
+      #
+      # @param reader [Object] File reader (StreamingReader or FullLoadReader)
+      # @param context [ValidationContext] Validation context for state
+      # @param options [Hash] CLI options for controlling behavior
+      def initialize(reader, context, options = {})
+        @reader = reader
+        @context = context
+        @options = options
+        @validator_pool = ValidatorPool.new(options.slice(:max_per_type))
+      end
+
+      # Process all chunks from the reader
+      #
+      # Uses batch validation by default for performance (groups chunks by type).
+      # Falls back to individual processing if batch_disabled option is set.
+      # Supports early termination if fail_fast option is enabled.
+      #
+      # @yield [chunk] Optional block to receive chunks as they're processed
+      # @return [void]
+      def process(&block)
+        # Use batch validation by default (faster for files with many chunks)
+        if @options[:batch_enabled] == false
+          process_individual(&block)
+        else
+          process_batch_inline(&block)
+        end
+      end
+
+      private
+
+      # Process chunks in batch inline (collecting from reader)
+      #
+      # Performance optimization: groups chunks by type and validates
+      # in batches to reduce validator instantiation overhead.
+      #
+      # @return [void]
+      def process_batch_inline
+        # Collect all chunks first
+        chunk_groups = Hash.new { |h, k| h[k] = [] }
+
+        @reader.each_chunk do |chunk|
+          chunk_groups[chunk.chunk_type.to_s] << chunk
+          yield chunk if block_given?
+        end
+
+        # Validate each group together
+        chunk_groups.each do |chunk_type, chunks|
+          validate_chunk_batch(chunk_type, chunks)
+
+          # Early termination check after each batch
+          break if @options[:fail_fast] && @context.has_errors?
+        end
+      end
+
+      # Process chunks individually (original behavior)
+      #
+      # @return [void]
+      def process_individual
+        @reader.each_chunk do |chunk|
+          validate_chunk(chunk)
+          yield chunk if block_given?
+
+          break if @options[:fail_fast] && @context.has_errors?
+        end
+      end
+
+      # Process chunks in batch (performance optimization)
+      #
+      # Groups chunks by type and validates in batches to reduce
+      # validator instantiation overhead.
+      #
+      # @param chunks [Array] Array of chunks to validate
+      # @return [void]
+      def process_batch(chunks)
+        grouped = chunks.group_by { |c| c.chunk_type.to_s }
+
+        grouped.each do |chunk_type, chunk_group|
+          validate_chunk_batch(chunk_type, chunk_group)
+        end
+      end
+
+      # Validate a single chunk
+      #
+      # Gets validator from pool for this chunk type from ChunkRegistry,
+      # executes validation, and handles unknown chunks.
+      #
+      # @param chunk [Object] Chunk to validate
+      # @return [void]
+      def validate_chunk(chunk)
+        chunk_type = chunk.chunk_type.to_s
+        validator_class = Validators::ChunkRegistry.validator_for(chunk_type)
+
+        if validator_class
+          validator = @validator_pool.acquire(chunk_type, validator_class,
+                                              chunk, @context)
+          begin
+            validator.validate
+          ensure
+            @validator_pool.release(chunk_type, validator)
+          end
+        else
+          handle_unknown_chunk(chunk)
+        end
+
+        # Mark chunk as seen AFTER validation
+        # This allows validators to check for duplicates before marking
+        @context.mark_chunk_seen(chunk_type, chunk)
+      end
+
+      # Validate a batch of chunks of the same type
+      #
+      # Performance optimization: reduces validator instantiation
+      # overhead by pooling validators for multiple chunks of same type.
+      #
+      # @param chunk_type [String] Type of chunks in batch
+      # @param chunks [Array] Array of chunks of same type
+      # @return [void]
+      def validate_chunk_batch(chunk_type, chunks)
+        validator_class = Validators::ChunkRegistry.validator_for(chunk_type)
+
+        unless validator_class
+          # No validator for this chunk type - handle as unknown
+          chunks.each do |chunk|
+            handle_unknown_chunk(chunk)
+            @context.mark_chunk_seen(chunk.chunk_type.to_s, chunk)
+          end
+          return
+        end
+
+        chunks.each do |chunk|
+          validator = @validator_pool.acquire(chunk_type, validator_class,
+                                              chunk, @context)
+          begin
+            validator.validate
+          ensure
+            @validator_pool.release(chunk_type, validator)
+          end
+          @context.mark_chunk_seen(chunk_type, chunk)
+        end
+      end
+
+      # Handle unknown chunk types
+      #
+      # Unknown chunks are checked for safety:
+      # - If ancillary (bit 5 of first byte = 1), it's safe to ignore
+      # - If critical (bit 5 = 0), it's an error
+      #
+      # @param chunk [Object] Unknown chunk
+      # @return [void]
+      def handle_unknown_chunk(chunk)
+        chunk_type = chunk.chunk_type.to_s
+        first_byte = chunk_type.bytes[0]
+
+        # Bit 5 (0x20) of first byte indicates ancillary vs critical
+        if (first_byte & 0x20).zero?
+          # Critical chunk - must be recognized
+          @context.add_error(
+            chunk_type: chunk_type,
+            message: "Unknown critical chunk type: #{chunk_type}",
+            severity: :error,
+            offset: chunk.abs_offset,
+          )
+        else
+          # Ancillary chunk - safe to ignore
+          @context.add_error(
+            chunk_type: chunk_type,
+            message: "Unknown ancillary chunk type: #{chunk_type} (ignored)",
+            severity: :info,
+            offset: chunk.abs_offset,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/services/file_signature.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module PngConform
+  module Services
+    # File signature service for fast comparison
+    #
+    # Creates cryptographic signatures of PNG files to enable fast
+    # equality checking without full validation. This is particularly
+    # useful for comparison operations and caching.
+    #
+    # The signature is based on key file characteristics that are
+    # quick to compute but provide strong uniqueness guarantees.
+    #
+    class FileSignature
+      attr_reader :result, :signature, :metadata
+
+      class << self
+        # Create signature from ValidationResult
+        #
+        # @param result [ValidationResult] Validation result to signature
+        # @return [FileSignature] FileSignature instance
+        def from_result(result)
+          new(result).compute_signature
+        end
+
+        # Create signature directly from file metadata
+        #
+        # @param file_path [String] Path to PNG file
+        # @param options [Hash] Options for signature creation
+        # @return [FileSignature] FileSignature instance
+        def from_file(file_path, _options = {})
+          unless File.exist?(file_path)
+            raise ArgumentError, "File not found: #{file_path}"
+          end
+
+          # Quick signature from file metadata without full validation
+          metadata = extract_quick_metadata(file_path)
+          new(nil, metadata).compute_signature
+        end
+      end
+
+      # Initialize with validation result or metadata hash
+      #
+      # @param result [ValidationResult, nil] Validation result
+      # @param metadata [Hash, nil] File metadata hash
+      def initialize(result, metadata = nil)
+        @result = result
+        @metadata = metadata || extract_metadata_from_result
+        @signature = nil
+      end
+
+      # Compute the signature
+      #
+      # @return [FileSignature] Self for chaining
+      def compute_signature
+        @signature = generate_signature
+        self
+      end
+
+      # Check if two signatures are equal
+      #
+      # @param other [FileSignature, String] Another signature or signature string
+      # @return [Boolean] True if signatures match
+      def ==(other)
+        return false unless other.is_a?(self.class)
+
+        @signature == other.signature
+      end
+
+      # Get signature as hex string
+      #
+      # @return [String] Hex signature
+      def to_hex
+        @signature
+      end
+
+      # Get signature as bytes
+      #
+      # @return [String] Signature bytes
+      def to_bytes
+        [@signature].pack("H*")
+      end
+
+      # Get short signature (first 8 bytes of hex)
+      #
+      # @return [String] Short signature for quick comparison
+      def short_signature
+        @signature[0..15]
+      end
+
+      private
+
+      # Extract metadata from validation result
+      #
+      # @return [Hash] Metadata hash
+      def extract_metadata_from_result
+        return {} unless @result
+
+        {
+          file_size: @result.file_size,
+          chunk_count: @result.chunks.count,
+          chunk_types: @result.chunks.map(&:type).sort,
+          chunk_sizes: @result.chunks.map(&:length).sort,
+          crcs: @result.chunks.map do |c|
+            c.crc_actual || c.crc_expected
+          end.compact,
+        }
+      end
+
+      # Generate signature from metadata
+      #
+      # Uses SHA-256 on concatenated metadata for cryptographic strength.
+      #
+      # @return [String] Hex signature
+      def generate_signature
+        signature_data = signature_string
+        Digest::SHA256.hexdigest(signature_data)
+      end
+
+      # Build signature string from metadata
+      #
+      # Creates a deterministic string representation of key file attributes.
+      #
+      # @return [String] Signature string
+      def signature_string
+        StringIO.new.tap do |io|
+          # File size (8 bytes)
+          io << [@metadata[:file_size]].pack("N")
+
+          # Chunk count (4 bytes)
+          io << [@metadata[:chunk_count]].pack("N")
+
+          # Chunk types (sorted for consistency)
+          @metadata[:chunk_types].each do |type|
+            io << type.ljust(4, "\0")[0..3] # Fixed 4-char chunk types
+          end
+
+          # Chunk sizes (sorted for consistency)
+          @metadata[:chunk_sizes].each do |size|
+            io << [size].pack("N")
+          end
+
+          # CRC checksums (for integrity verification)
+          @metadata[:crcs].each do |crc|
+            io << [crc].pack("N")
+          end
+        end.string
+      end
+
+      # Extract quick metadata from file without full validation
+      #
+      # Reads just the PNG signature and chunk headers to create
+      # a signature without loading entire file into memory.
+      #
+      # @param file_path [String] Path to PNG file
+      # @return [Hash] Quick metadata hash
+      def extract_quick_metadata(file_path)
+        File.open(file_path, "rb") do |file|
+          # Verify PNG signature first
+          sig = file.read(8)
+          expected_sig = [137, 80, 78, 71, 13, 10, 26, 10].pack("C*")
+          unless sig == expected_sig
+            raise ArgumentError, "Not a valid PNG file: #{file_path}"
+          end
+
+          # Quick scan to count chunks and collect metadata
+          chunk_count = 0
+          chunk_types = []
+          chunk_sizes = []
+          total_data_size = 0
+
+          # Read entire file - no arbitrary limits for complete signatures
+          while file.pos < File.size(file_path)
+            # Read chunk length (4 bytes)
+            length_bytes = file.read(4)
+            break if length_bytes.nil? || length_bytes.length < 4
+
+            chunk_length = length_bytes.unpack1("N")
+            break if chunk_length > 10 * 1024 * 1024 # Sanity check
+
+            # Read chunk type (4 bytes)
+            type_bytes = file.read(4)
+            break if type_bytes.nil? || type_bytes.length < 4
+
+            chunk_type = type_bytes
+
+            # Skip data
+            file.seek(chunk_length, IO::SEEK_CUR)
+
+            # Read CRC (4 bytes)
+            crc_bytes = file.read(4)
+            break if crc_bytes.nil? || crc_bytes.length < 4
+
+            # Record metadata
+            chunk_count += 1
+            chunk_types << chunk_type
+            chunk_sizes << chunk_length
+            total_data_size += chunk_length
+
+            # Stop if we found IEND
+            break if chunk_type == "IEND"
+          end
+
+          {
+            file_size: File.size(file_path),
+            chunk_count: chunk_count,
+            chunk_types: chunk_types.sort,
+            chunk_sizes: chunk_sizes.sort,
+            crcs: [], # Not easily available without validation
+          }
+        end
+      rescue StandardError
+        # Fallback to basic metadata
+        {
+          file_size: File.size(file_path),
+          chunk_count: 0,
+          chunk_types: [],
+          chunk_sizes: [],
+          crcs: [],
+        }
+      end
+    end
+  end
+end

data/lib/png_conform/services/file_strategy.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module PngConform
+  module Services
+    # File strategy service for reader selection
+    #
+    # Determines the optimal reader type based on file characteristics
+    # and validation options. This enables automatic reader selection for
+    # better performance and memory efficiency.
+    #
+    class FileStrategy
+      # Large file threshold (10MB) - files larger than this use streaming
+      LARGE_FILE_THRESHOLD = 10 * 1024 * 1024
+
+      class << self
+        # Determine the appropriate reader type for a file
+        #
+        # @param file_path [String] Path to the PNG file
+        # @param options [Hash] Validation options
+        # @return [Symbol] Reader type (:streaming or :full_load)
+        def reader_type_for(file_path, options = {})
+          file_size = File.size(file_path)
+
+          # Use streaming for large files unless explicitly forced
+          if file_size > LARGE_FILE_THRESHOLD && !options[:force_full]
+            :streaming
+          else
+            :full_load
+          end
+        end
+
+        # Check if a file is considered large
+        #
+        # @param file_path [String] Path to the PNG file
+        # @return [Boolean] True if file is large
+        def large_file?(file_path)
+          File.size(file_path) > LARGE_FILE_THRESHOLD
+        end
+
+        # Get the threshold for large file detection
+        #
+        # @return [Integer] Threshold in bytes
+        def large_file_threshold
+          LARGE_FILE_THRESHOLD
+        end
+
+        # Calculate recommended chunk size for processing
+        #
+        # For large files, smaller chunks are better for memory management
+        #
+        # @param file_path [String] Path to the PNG file
+        # @return [Integer] Recommended chunk size in bytes
+        def recommended_chunk_size(file_path)
+          file_size = File.size(file_path)
+
+          if file_size > 100 * 1024 * 1024 # > 100MB
+            8192 # 8KB chunks for very large files
+          elsif file_size > 10 * 1024 * 1024 # > 10MB
+            16384 # 16KB chunks for large files
+          else
+            65536 # 64KB chunks for normal files
+          end
+        end
+
+        # Estimate memory usage for full-load reader
+        #
+        # @param file_path [String] Path to the PNG file
+        # @return [Integer] Estimated memory in bytes
+        def estimate_memory_usage(file_path)
+          file_size = File.size(file_path)
+          # Estimate: file_size + overhead for chunks (rough estimate)
+          # Each chunk adds overhead for BinData structures
+          file_size * 1.2
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/services/lru_cache.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module PngConform
+  module Services
+    # LRU (Least Recently Used) Cache implementation
+    #
+    # Provides efficient caching with automatic eviction of least recently
+    # used items when capacity is reached. Thread-safe for basic operations.
+    #
+    class LRUCache
+      attr_reader :max_size, :current_size
+
+      # Initialize LRU cache
+      #
+      # @param max_size [Integer] Maximum number of items to store
+      # @param options [Hash] Additional options
+      def initialize(max_size, options = {})
+        @max_size = max_size
+        @cache = {}
+        @order = [] # Tracks access order (most recent at end)
+        @current_size = 0
+        @thread_safe = options[:thread_safe] || false
+        @mutex = @thread_safe ? Mutex.new : nil
+      end
+
+      # Get value for key
+      #
+      # @param key [Object] Cache key
+      # @return [Object, nil] Cached value or nil if not found
+      def [](key)
+        return @cache[key] if @thread_safe && !@mutex.synchronize do
+          @cache.key?(key)
+        end
+
+        with_synchronization do
+          return nil unless @cache.key?(key)
+
+          # Move to end (most recently used)
+          @order.delete(key)
+          @order.push(key)
+
+          @cache[key]
+        end
+      end
+
+      # Set value for key
+      #
+      # @param key [Object] Cache key
+      # @param value [Object] Value to cache
+      # @return [Object] The cached value
+      def []=(key, value)
+        with_synchronization do
+          # Remove existing key if updating (to re-insert at end)
+          @order.delete(key) if @cache.key?(key)
+
+          @cache[key] = value
+          @order.push(key)
+
+          # Evict oldest if over capacity
+          if @order.size > @max_size
+            oldest = @order.shift
+            @cache.delete(oldest)
+          end
+
+          @current_size = @cache.size
+        end
+
+        value
+      end
+
+      # Check if key exists
+      #
+      # @param key [Object] Cache key
+      # @return [Boolean] True if key exists in cache
+      def key?(key)
+        @cache.key?(key)
+      end
+
+      # Check if cache is empty
+      #
+      # @return [Boolean] True if cache has no items
+      def empty?
+        @cache.empty?
+      end
+
+      # Clear all cached items
+      #
+      # @return [void]
+      def clear
+        with_synchronization do
+          @cache.clear
+          @order.clear
+          @current_size = 0
+        end
+      end
+
+      # Get all keys
+      #
+      # @return [Array<Object>] All cached keys (in LRU order)
+      def keys
+        @order.dup # Return copy to avoid external modification
+      end
+
+      # Get cache statistics
+      #
+      # @return [Hash] Cache statistics
+      def stats
+        {
+          size: @cache.size,
+          max_size: @max_size,
+          usage_percent: ((@cache.size.to_f / @max_size) * 100).round(1),
+        }
+      end
+
+      # Delete a specific key
+      #
+      # @param key [Object] Cache key to delete
+      # @return [Object, nil] Deleted value or nil if not found
+      def delete(key)
+        with_synchronization do
+          @order.delete(key)
+          @cache.delete(key)
+          @current_size = @cache.size
+        end
+      end
+
+      # Peek at value without affecting LRU order
+      #
+      # @param key [Object] Cache key
+      # @return [Object, nil] Cached value or nil if not found
+      def peek(key)
+        @cache[key]
+      end
+
+      # Get most recently used item
+      #
+      # @return [Array] [key, value] or nil if empty
+      def mru
+        return nil if @order.empty?
+
+        key = @order.last
+        [key, @cache[key]]
+      end
+
+      # Get least recently used item
+      #
+      # @return [Array] [key, value] or nil if empty
+      def lru
+        return nil if @order.empty?
+
+        key = @order.first
+        [key, @cache[key]]
+      end
+
+      private
+
+      # Execute block with optional synchronization
+      #
+      # @yield Block to execute
+      # @return [Object] Block result
+      def with_synchronization(&block)
+        if @thread_safe && @mutex
+          @mutex.synchronize(&block)
+        else
+          yield
+        end
+      end
+    end
+  end
+end