cabriolet 0.1.0

data/lib/cabriolet/streaming.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  # Streaming API for memory-efficient processing of large archives
+  module Streaming
+    # Stream-based archive parser
+    class StreamParser
+      DEFAULT_CHUNK_SIZE = 65_536 # 64KB chunks
+
+      def initialize(path, chunk_size: DEFAULT_CHUNK_SIZE)
+        @path = path
+        @chunk_size = chunk_size
+        @format = FormatDetector.detect(path)
+        raise UnsupportedFormatError, "Unable to detect format" unless @format
+      end
+
+      # Iterate over files without loading entire archive into memory
+      #
+      # @yield [file] Yields each file object
+      # @yieldparam file [Object] File object from the archive
+      # @return [Enumerator] if no block given
+      #
+      # @example
+      #   parser = Cabriolet::Streaming::StreamParser.new('huge.cab')
+      #   parser.each_file do |file|
+      #     # Process one file at a time
+      #     puts "#{file.name}: #{file.size} bytes"
+      #     # File data loaded on-demand via file.data
+      #   end
+      def each_file(&)
+        return enum_for(:each_file) unless block_given?
+
+        case @format
+        when :cab
+          stream_cab_files(&)
+        when :chm
+          stream_chm_files(&)
+        else
+          # Fallback to standard parsing for unsupported streaming formats
+          archive = Cabriolet::Auto.open(@path)
+          archive.files.each(&)
+        end
+      end
+
+      # Stream file data in chunks
+      #
+      # @param file [Object] File object from archive
+      # @yield [chunk] Yields data chunks
+      # @yieldparam chunk [String] Binary data chunk
+      # @return [Enumerator] if no block given
+      #
+      # @example
+      #   parser.stream_file_data(file) do |chunk|
+      #     output.write(chunk)
+      #   end
+      def stream_file_data(file, &)
+        return enum_for(:stream_file_data, file) unless block_given?
+
+        if file.respond_to?(:stream_data)
+          file.stream_data(chunk_size: @chunk_size, &)
+        else
+          # Fallback: load entire file and yield in chunks
+          data = file.data
+          offset = 0
+          while offset < data.bytesize
+            chunk = data.byteslice(offset, @chunk_size)
+            yield chunk
+            offset += @chunk_size
+          end
+        end
+      end
+
+      # Extract files using streaming to minimize memory usage
+      #
+      # @param output_dir [String] Directory to extract to
+      # @param options [Hash] Extraction options
+      # @return [Hash] Extraction statistics
+      def extract_streaming(output_dir, **_options)
+        FileUtils.mkdir_p(output_dir)
+        stats = { extracted: 0, bytes: 0, failed: 0 }
+
+        each_file do |file|
+          output_path = File.join(output_dir, file.name.gsub("\\", "/"))
+          FileUtils.mkdir_p(File.dirname(output_path))
+
+          File.open(output_path, "wb") do |out|
+            stream_file_data(file) do |chunk|
+              out.write(chunk)
+            end
+          end
+
+          stats[:extracted] += 1
+          stats[:bytes] += file.size if file.respond_to?(:size)
+        rescue StandardError => e
+          stats[:failed] += 1
+          warn "Failed to extract #{file.name}: #{e.message}"
+        end
+
+        stats
+      end
+
+      private
+
+      def stream_cab_files
+        # Use lazy enumeration for CAB files
+        parser = Cabriolet::CAB::Parser.new
+        cabinet = parser.parse(@path)
+
+        # Wrap files in lazy enumerator
+        cabinet.files.lazy.each do |file|
+          yield LazyFile.new(file, @chunk_size)
+        end
+      end
+
+      def stream_chm_files
+        parser = Cabriolet::CHM::Parser.new
+        chm = parser.parse(@path)
+
+        chm.files.lazy.each do |file|
+          yield LazyFile.new(file, @chunk_size)
+        end
+      end
+    end
+
+    # Wrapper for lazy file data loading
+    class LazyFile
+      def initialize(file, chunk_size)
+        @file = file
+        @chunk_size = chunk_size
+        @data_loaded = false
+      end
+
+      def name
+        @file.name
+      end
+
+      def size
+        @file.size
+      end
+
+      def attributes
+        @file.attributes if @file.respond_to?(:attributes)
+      end
+
+      def date
+        @file.date if @file.respond_to?(:date)
+      end
+
+      def time
+        @file.time if @file.respond_to?(:time)
+      end
+
+      # Load data only when accessed
+      def data
+        @data ||= @file.data
+      end
+
+      # Stream data in chunks
+      def stream_data(chunk_size: @chunk_size)
+        full_data = data
+        offset = 0
+
+        while offset < full_data.bytesize
+          chunk = full_data.byteslice(offset, chunk_size)
+          yield chunk
+          offset += chunk_size
+        end
+      end
+
+      def method_missing(method, ...)
+        @file.send(method, ...)
+      end
+
+      def respond_to_missing?(method, include_private = false)
+        @file.respond_to?(method, include_private)
+      end
+    end
+
+    # Stream processor for batch operations
+    class BatchProcessor
+      def initialize(chunk_size: StreamParser::DEFAULT_CHUNK_SIZE)
+        @chunk_size = chunk_size
+        @stats = { processed: 0, failed: 0, bytes: 0 }
+      end
+
+      # Process multiple archives in streaming mode
+      #
+      # @param paths [Array<String>] Array of archive paths
+      # @yield [file, archive_path] Yields each file with its archive path
+      # @return [Hash] Processing statistics
+      def process_archives(paths, &block)
+        paths.each do |path|
+          process_archive(path, &block)
+        end
+
+        @stats
+      end
+
+      # Process single archive in streaming mode
+      #
+      # @param path [String] Archive path
+      # @yield [file] Yields each file
+      def process_archive(path)
+        parser = StreamParser.new(path, chunk_size: @chunk_size)
+
+        parser.each_file do |file|
+          yield file, path
+          @stats[:processed] += 1
+          @stats[:bytes] += file.size if file.respond_to?(:size)
+        rescue StandardError => e
+          @stats[:failed] += 1
+          warn "Error processing #{file.name} from #{path}: #{e.message}"
+        end
+      rescue StandardError => e
+        warn "Error processing archive #{path}: #{e.message}"
+      end
+
+      attr_reader :stats
+    end
+  end
+end

data/lib/cabriolet/system/file_handle.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module System
+    # FileHandle provides file I/O operations using the Ruby File class
+    class FileHandle
+      attr_reader :filename, :mode
+
+      # Initialize a new file handle
+      #
+      # @param filename [String] Path to the file
+      # @param mode [Integer] One of MODE_READ, MODE_WRITE, MODE_UPDATE, MODE_APPEND
+      # @raise [IOError] if the file cannot be opened
+      def initialize(filename, mode)
+        @filename = filename
+        @mode = mode
+        @file = open_file(mode)
+      end
+
+      # Read bytes from the file
+      #
+      # @param bytes [Integer] Number of bytes to read
+      # @return [String] Bytes read (binary encoding)
+      def read(bytes)
+        @file.read(bytes) || ""
+      end
+
+      # Write bytes to the file
+      #
+      # @param data [String] Data to write
+      # @return [Integer] Number of bytes written
+      def write(data)
+        @file.write(data)
+      end
+
+      # Seek to a position in the file
+      #
+      # @param offset [Integer] Offset to seek to
+      # @param whence [Integer] One of SEEK_START, SEEK_CUR, SEEK_END
+      # @return [Integer] New position
+      def seek(offset, whence)
+        io_whence = case whence
+                    when Constants::SEEK_START then ::IO::SEEK_SET
+                    when Constants::SEEK_CUR then ::IO::SEEK_CUR
+                    when Constants::SEEK_END then ::IO::SEEK_END
+                    else
+                      raise ArgumentError, "Invalid whence value: #{whence}"
+                    end
+        @file.seek(offset, io_whence)
+        @file.pos
+      end
+
+      # Get current position in the file
+      #
+      # @return [Integer] Current position
+      def tell
+        @file.pos
+      end
+
+      # Get the size of the file
+      #
+      # @return [Integer] File size in bytes
+      def size
+        @file.size
+      end
+
+      # Flush the file buffer
+      #
+      # @return [void]
+      def flush
+        @file.flush unless @file.closed?
+      end
+
+      # Close the file
+      #
+      # @return [void]
+      def close
+        @file.flush unless @file.closed?
+        @file.close unless @file.closed?
+      end
+
+      # Check if the file is closed
+      #
+      # @return [Boolean]
+      def closed?
+        @file.closed?
+      end
+
+      private
+
+      def open_file(mode)
+        file_mode = case mode
+                    when Constants::MODE_READ then "rb"
+                    when Constants::MODE_WRITE then "wb"
+                    when Constants::MODE_UPDATE then "r+b"
+                    when Constants::MODE_APPEND then "ab"
+                    else
+                      raise ArgumentError, "Invalid mode: #{mode}"
+                    end
+
+        ::File.open(@filename, file_mode)
+      rescue Errno::ENOENT, Errno::EACCES => e
+        raise IOError, "Cannot open file #{@filename}: #{e.message}"
+      end
+    end
+  end
+end

data/lib/cabriolet/system/io_system.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module System
+    # IOSystem provides an abstraction layer for file I/O operations,
+    # enabling dependency injection and custom I/O implementations.
+    #
+    # This allows for:
+    # - Testing with mock I/O
+    # - In-memory operations
+    # - Custom I/O sources (network, etc.)
+    class IOSystem
+      # Open a file for reading, writing, or updating
+      #
+      # @param filename [String] Path to the file
+      # @param mode [Integer] One of MODE_READ, MODE_WRITE, MODE_UPDATE, MODE_APPEND
+      # @return [FileHandle] Handle for performing I/O operations
+      # @raise [IOError] if the file cannot be opened
+      def open(filename, mode)
+        FileHandle.new(filename, mode)
+      end
+
+      # Close a file handle
+      #
+      # @param handle [FileHandle, MemoryHandle] Handle to close
+      # @return [void]
+      def close(handle)
+        handle.close
+      end
+
+      # Read bytes from a handle
+      #
+      # @param handle [FileHandle, MemoryHandle] Handle to read from
+      # @param bytes [Integer] Number of bytes to read
+      # @return [String] Bytes read (may be fewer than requested at EOF)
+      def read(handle, bytes)
+        handle.read(bytes)
+      end
+
+      # Write bytes to a handle
+      #
+      # @param handle [FileHandle, MemoryHandle] Handle to write to
+      # @param data [String] Data to write
+      # @return [Integer] Number of bytes written
+      def write(handle, data)
+        handle.write(data)
+      end
+
+      # Seek to a position in a handle
+      #
+      # @param handle [FileHandle, MemoryHandle] Handle to seek in
+      # @param offset [Integer] Offset to seek to
+      # @param whence [Integer] One of SEEK_START, SEEK_CUR, SEEK_END
+      # @return [Integer] New position
+      def seek(handle, offset, whence)
+        handle.seek(offset, whence)
+      end
+
+      # Get current position in a handle
+      #
+      # @param handle [FileHandle, MemoryHandle] Handle to query
+      # @return [Integer] Current position
+      def tell(handle)
+        handle.tell
+      end
+
+      # Copy bytes from source to destination
+      #
+      # @param src [String] Source bytes
+      # @param dest [String] Destination buffer
+      # @param bytes [Integer] Number of bytes to copy
+      # @return [void]
+      def copy(src, dest, bytes)
+        dest.replace(src.byteslice(0, bytes))
+      end
+
+      # Output a message (for debugging/logging)
+      #
+      # @param handle [FileHandle, MemoryHandle, nil] Handle associated with message
+      # @param message [String] Message to output
+      # @return [void]
+      def message(_handle, message)
+        warn "[Cabriolet] #{message}" if Cabriolet.verbose
+      end
+    end
+  end
+end

data/lib/cabriolet/system/memory_handle.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Cabriolet
+  module System
+    # MemoryHandle provides in-memory I/O operations using a StringIO-like interface
+    class MemoryHandle
+      attr_reader :data, :mode
+
+      # Initialize a new memory handle
+      #
+      # @param data [String] Initial data (for reading) or empty string (for writing)
+      # @param mode [Integer] One of MODE_READ, MODE_WRITE, MODE_UPDATE, MODE_APPEND
+      def initialize(data = "", mode = Constants::MODE_READ)
+        @data = data.dup.force_encoding(Encoding::BINARY)
+        @mode = mode
+        @pos = mode == Constants::MODE_APPEND ? @data.bytesize : 0
+        @closed = false
+      end
+
+      # Read bytes from memory
+      #
+      # @param bytes [Integer] Number of bytes to read
+      # @return [String] Bytes read (binary encoding)
+      def read(bytes)
+        return "" if @pos >= @data.bytesize
+
+        result = @data.byteslice(@pos, bytes) || ""
+        @pos += result.bytesize
+        result
+      end
+
+      # Write bytes to memory
+      #
+      # @param content [String] Data to write
+      # @return [Integer] Number of bytes written
+      def write(content)
+        raise IOError, "Handle is closed" if @closed
+        raise IOError, "Handle not opened for writing" if @mode == Constants::MODE_READ
+
+        content = content.dup.force_encoding(Encoding::BINARY)
+
+        if @pos >= @data.bytesize
+          # Append to end
+          @data << content
+        else
+          # Overwrite existing data
+          before = @data.byteslice(0, @pos) || ""
+          after = @data.byteslice((@pos + content.bytesize)..-1) || ""
+          @data = before + content + after
+        end
+
+        @pos += content.bytesize
+        content.bytesize
+      end
+
+      # Seek to a position in memory
+      #
+      # @param offset [Integer] Offset to seek to
+      # @param whence [Integer] One of SEEK_START, SEEK_CUR, SEEK_END
+      # @return [Integer] New position
+      def seek(offset, whence)
+        new_pos = case whence
+                  when Constants::SEEK_START then offset
+                  when Constants::SEEK_CUR then @pos + offset
+                  when Constants::SEEK_END then @data.bytesize + offset
+                  else
+                    raise ArgumentError, "Invalid whence value: #{whence}"
+                  end
+
+        @pos = [[new_pos, 0].max, @data.bytesize].min
+      end
+
+      # Get current position in memory
+      #
+      # @return [Integer] Current position
+      def tell
+        @pos
+      end
+
+      # Close the handle
+      #
+      # @return [void]
+      def close
+        @closed = true
+      end
+
+      # Check if the handle is closed
+      #
+      # @return [Boolean]
+      def closed?
+        @closed
+      end
+
+      # Get the complete data buffer
+      #
+      # @return [String] All data in the buffer
+      def to_s
+        @data
+      end
+
+      # Alias for to_s
+      alias buffer to_s
+    end
+  end
+end