omnizip 0.3.1

data/lib/omnizip/buffer/memory_archive.rb

@@ -0,0 +1,251 @@
+# frozen_string_literal: true
+
+module Omnizip
+  module Buffer
+    # Wrapper for in-memory archive operations
+    #
+    # Provides unified interface for adding entries to and reading entries
+    # from archives stored in memory (StringIO). Works with both OutputStream
+    # (for creating) and InputStream (for reading).
+    #
+    # @example Creating an archive
+    #   buffer = StringIO.new
+    #   Omnizip::Zip::OutputStream.open(buffer) do |zos|
+    #     archive = MemoryArchive.new(zos, :zip)
+    #     archive.add('file.txt', 'content')
+    #   end
+    #
+    # @example Reading an archive
+    #   Omnizip::Zip::InputStream.open(buffer) do |zis|
+    #     archive = MemoryArchive.new(zis, :zip)
+    #     archive.each_entry do |entry|
+    #       puts entry.name
+    #     end
+    #   end
+    class MemoryArchive
+      attr_reader :format, :stream
+
+      # Initialize memory archive wrapper
+      #
+      # @param stream [Omnizip::Zip::OutputStream, Omnizip::Zip::InputStream]
+      #   Underlying stream
+      # @param format [Symbol] Archive format (:zip, :seven_zip)
+      def initialize(stream, format)
+        @stream = stream
+        @format = format
+        @entries_cache = nil
+      end
+
+      # Add file from memory (write mode only)
+      #
+      # @param name [String] Entry name (path within archive)
+      # @param data [String] Entry content
+      # @param options [Hash] Entry options
+      # @option options [Time] :time Modification time (default: now)
+      # @option options [String] :comment Entry comment
+      # @option options [Symbol] :compression Compression method
+      #   (:store, :deflate)
+      # @option options [Integer] :level Compression level (1-9)
+      # @return [self] For method chaining
+      #
+      # @example Add multiple files
+      #   archive.add('file1.txt', 'content1')
+      #          .add('file2.txt', 'content2')
+      #          .add('dir/', '')  # Directory entry
+      #
+      # @raise [RuntimeError] If stream is not an OutputStream
+      def add(name, data, **options)
+        ensure_write_mode!
+
+        case stream
+        when Omnizip::Zip::OutputStream
+          stream.put_next_entry(name, **options)
+          stream.write(data) unless name.end_with?("/")
+        else
+          raise NotImplementedError,
+                "Unsupported stream type: #{stream.class}"
+        end
+
+        self
+      end
+
+      # Add data with block (write mode only)
+      #
+      # @param name [String] Entry name
+      # @param options [Hash] Entry options
+      # @yield Block that returns content
+      # @yieldreturn [String] Entry content
+      # @return [self] For method chaining
+      #
+      # @example Add with block
+      #   archive.add_data('file.txt') { File.read('source.txt') }
+      def add_data(name, **options)
+        ensure_write_mode!
+        data = yield
+        add(name, data, **options)
+      end
+
+      # Iterate entries (read mode only)
+      #
+      # @yield [entry] Block called for each entry
+      # @yieldparam entry [Entry] Archive entry
+      # @return [void]
+      #
+      # @example Process all entries
+      #   archive.each_entry do |entry|
+      #     puts "#{entry.name}: #{entry.size} bytes"
+      #     content = entry.read unless entry.directory?
+      #   end
+      #
+      # @raise [RuntimeError] If stream is not an InputStream
+      def each_entry
+        ensure_read_mode!
+
+        case stream
+        when Omnizip::Zip::InputStream
+          while (zip_entry = stream.get_next_entry)
+            entry = Entry.new(zip_entry, stream)
+            yield(entry)
+          end
+        else
+          raise NotImplementedError,
+                "Unsupported stream type: #{stream.class}"
+        end
+      end
+
+      # Extract all entries to memory (read mode only)
+      #
+      # @return [Hash<String, String>] Filename => content mapping
+      #
+      # @example Extract all
+      #   files = archive.extract_all_to_memory
+      #   files.each { |name, content| puts "#{name}: #{content.size}" }
+      def extract_all_to_memory
+        ensure_read_mode!
+
+        result = {}
+        each_entry do |entry|
+          result[entry.name] = entry.read unless entry.directory?
+        end
+        result
+      end
+
+      # Get underlying buffer as string (write mode only)
+      #
+      # @return [String] Complete archive as binary string
+      #
+      # @example Get archive data
+      #   archive_data = archive.to_s
+      #   File.binwrite('output.zip', archive_data)
+      #
+      # @raise [RuntimeError] If stream is not an OutputStream
+      def to_s
+        ensure_write_mode!
+
+        case stream
+        when Omnizip::Zip::OutputStream
+          # OutputStream wraps the IO, we need to get the underlying buffer
+          # This is only safe after close
+          unless stream.closed?
+            raise "Archive must be closed before accessing data"
+          end
+
+          # The buffer was passed in during creation, but we don't have
+          # direct access. This method should be called on the StringIO
+          # returned by Buffer.create instead.
+          raise NotImplementedError,
+                "Use Buffer.create return value instead"
+        else
+          raise "Cannot get string from read mode archive"
+        end
+      end
+
+      # Entry wrapper with read capability
+      #
+      # Wraps underlying ZIP entry to provide consistent interface
+      # for reading entry data from the stream.
+      class Entry
+        attr_reader :name, :size, :compressed_size, :time, :comment
+
+        # Initialize entry wrapper
+        #
+        # @param entry [Omnizip::Zip::Entry] Underlying entry
+        # @param stream [Omnizip::Zip::InputStream] Stream to read from
+        def initialize(entry, stream)
+          @entry = entry
+          @stream = stream
+          @name = entry.name
+          @size = entry.size
+          @compressed_size = entry.compressed_size
+          @time = entry.time
+          @comment = entry.comment
+          @directory = entry.directory?
+        end
+
+        # Read entry content
+        #
+        # @param size [Integer, nil] Number of bytes to read (nil for all)
+        # @return [String, nil] Entry data or nil if EOF
+        #
+        # @example Read entire entry
+        #   content = entry.read
+        #
+        # @example Read in chunks
+        #   while (chunk = entry.read(8192))
+        #     process_chunk(chunk)
+        #   end
+        def read(size = nil)
+          @stream.read(size)
+        end
+
+        # Check if entry is a directory
+        #
+        # @return [Boolean] True if directory entry
+        def directory?
+          @directory
+        end
+
+        # Check if entry is a file
+        #
+        # @return [Boolean] True if file entry
+        def file?
+          !@directory
+        end
+
+        # Get compression method
+        #
+        # @return [Symbol] Compression method (:store, :deflate, etc.)
+        def compression_method
+          @entry.compression_method
+        end
+
+        # Get CRC32 checksum
+        #
+        # @return [Integer] CRC32 value
+        def crc32
+          @entry.crc32
+        end
+      end
+
+      private
+
+      # Ensure stream is in write mode (OutputStream)
+      #
+      # @raise [RuntimeError] If not in write mode
+      def ensure_write_mode!
+        return if stream.is_a?(Omnizip::Zip::OutputStream)
+
+        raise "Operation requires write mode (OutputStream)"
+      end
+
+      # Ensure stream is in read mode (InputStream)
+      #
+      # @raise [RuntimeError] If not in read mode
+      def ensure_read_mode!
+        return if stream.is_a?(Omnizip::Zip::InputStream)
+
+        raise "Operation requires read mode (InputStream)"
+      end
+    end
+  end
+end

data/lib/omnizip/buffer/memory_extractor.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "stringio"
+
+module Omnizip
+  module Buffer
+    # Extract archive contents to memory
+    #
+    # Provides efficient extraction of archive entries to Hash without
+    # loading all files at once. Uses lazy evaluation where possible.
+    #
+    # @example Extract all files
+    #   extractor = MemoryExtractor.new(zip_data)
+    #   files = extractor.extract_all
+    #   # => {"file1.txt" => "content1", "file2.txt" => "content2"}
+    #
+    # @example Extract single file
+    #   extractor = MemoryExtractor.new(zip_data)
+    #   content = extractor.extract_entry('file1.txt')
+    #   # => "content1"
+    class MemoryExtractor
+      attr_reader :format
+
+      # Initialize extractor
+      #
+      # @param data [String, StringIO] Archive data
+      # @param format [Symbol, nil] Archive format (auto-detected if nil)
+      #
+      # @example Create extractor
+      #   extractor = MemoryExtractor.new(zip_data)
+      #   extractor = MemoryExtractor.new(zip_buffer, format: :zip)
+      def initialize(data, format: nil)
+        @buffer = data.is_a?(StringIO) ? data : StringIO.new(data.b)
+        @format = format || detect_format
+        @extracted_cache = {}
+      end
+
+      # Extract all entries to Hash
+      #
+      # @return [Hash<String, String>] Filename => content mapping
+      #
+      # @example Extract everything
+      #   files = extractor.extract_all
+      #   files.keys  # => ["file1.txt", "file2.txt", "dir/file3.txt"]
+      def extract_all
+        result = {}
+
+        case @format
+        when :zip
+          extract_all_zip(result)
+        when :seven_zip, :'7z'
+          raise NotImplementedError, "7z format support coming in Phase 2"
+        else
+          raise ArgumentError, "Unsupported format: #{@format}"
+        end
+
+        result
+      end
+
+      # Extract single entry by name
+      #
+      # @param name [String] Entry name to extract
+      # @return [String, nil] Entry content or nil if not found
+      #
+      # @example Extract specific file
+      #   content = extractor.extract_entry('readme.txt')
+      #   # => "Hello World"
+      def extract_entry(name)
+        # Check cache first
+        return @extracted_cache[name] if @extracted_cache.key?(name)
+
+        # Extract from archive
+        content = nil
+
+        case @format
+        when :zip
+          content = extract_entry_zip(name)
+        when :seven_zip, :'7z'
+          raise NotImplementedError, "7z format support coming in Phase 2"
+        else
+          raise ArgumentError, "Unsupported format: #{@format}"
+        end
+
+        # Cache the result
+        @extracted_cache[name] = content if content
+        content
+      end
+
+      # List all entry names without extracting
+      #
+      # @return [Array<String>] Entry names
+      #
+      # @example List files
+      #   extractor.list_entries
+      #   # => ["file1.txt", "dir/", "dir/file2.txt"]
+      def list_entries
+        names = []
+
+        case @format
+        when :zip
+          list_entries_zip(names)
+        when :seven_zip, :'7z'
+          raise NotImplementedError, "7z format support coming in Phase 2"
+        else
+          raise ArgumentError, "Unsupported format: #{@format}"
+        end
+
+        names
+      end
+
+      # Check if entry exists in archive
+      #
+      # @param name [String] Entry name
+      # @return [Boolean] True if entry exists
+      #
+      # @example Check existence
+      #   extractor.entry_exists?('file.txt')  # => true
+      def entry_exists?(name)
+        list_entries.include?(name)
+      end
+
+      # Get total number of entries
+      #
+      # @return [Integer] Number of entries
+      def entry_count
+        list_entries.size
+      end
+
+      # Extract entries matching pattern
+      #
+      # @param pattern [Regexp, String] Pattern to match
+      # @return [Hash<String, String>] Matching entries
+      #
+      # @example Extract by pattern
+      #   extractor.extract_matching(/\.txt$/)
+      #   # => {"file1.txt" => "content1", "file2.txt" => "content2"}
+      def extract_matching(pattern)
+        pattern = Regexp.new(pattern) if pattern.is_a?(String)
+        result = {}
+
+        list_entries.each do |name|
+          next unless name&.match?(pattern)
+          next if name.end_with?("/") # Skip directories
+
+          content = extract_entry(name)
+          result[name] = content if content
+        end
+
+        result
+      end
+
+      private
+
+      # Detect archive format from magic bytes
+      #
+      # @return [Symbol] Detected format
+      # @raise [Omnizip::FormatError] If format cannot be detected
+      def detect_format
+        magic = @buffer.read(4)
+        @buffer.rewind
+
+        case magic
+        when "PK\x03\x04", "PK\x05\x06", "PK\x07\x08"
+          # ZIP signatures: local file header, EOCD, data descriptor
+          :zip
+        when "7z\xBC\xAF"
+          :seven_zip
+        else
+          raise Omnizip::FormatError,
+                "Unknown archive format (magic: #{magic.inspect})"
+        end
+      end
+
+      # Extract all entries from ZIP
+      #
+      # @param result [Hash] Hash to populate with entries
+      def extract_all_zip(result)
+        @buffer.rewind
+        Omnizip::Zip::InputStream.open(@buffer) do |zis|
+          while (entry = zis.get_next_entry)
+            next if entry.directory?
+
+            content = zis.read
+            result[entry.name] = content
+            @extracted_cache[entry.name] = content
+          end
+        end
+      end
+
+      # Extract single entry from ZIP
+      #
+      # @param name [String] Entry name
+      # @return [String, nil] Entry content or nil if not found
+      def extract_entry_zip(name)
+        @buffer.rewind
+        content = nil
+
+        Omnizip::Zip::InputStream.open(@buffer) do |zis|
+          while (entry = zis.get_next_entry)
+            if entry.name == name
+              content = zis.read unless entry.directory?
+              break
+            end
+          end
+        end
+
+        content
+      end
+
+      # List all entry names from ZIP
+      #
+      # @param names [Array] Array to populate with names
+      def list_entries_zip(names)
+        @buffer.rewind
+
+        Omnizip::Zip::InputStream.open(@buffer) do |zis|
+          while (entry = zis.get_next_entry)
+            names << entry.name
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/buffer.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "stringio"
+require_relative "buffer/memory_archive"
+require_relative "buffer/memory_extractor"
+
+module Omnizip
+  # In-memory archive operations without filesystem I/O
+  #
+  # This module provides methods for creating and reading archives
+  # entirely in memory using StringIO, enabling web applications,
+  # testing, and API responses without temporary files.
+  #
+  # @example Create archive in memory
+  #   zip_data = Omnizip::Buffer.create(:zip) do |archive|
+  #     archive.add('readme.txt', 'Hello World')
+  #     archive.add('data.json', '{"key": "value"}')
+  #   end
+  #   # => Returns StringIO with complete ZIP archive
+  #
+  # @example Extract from memory
+  #   contents = Omnizip::Buffer.extract_to_memory(zip_data)
+  #   # => {"readme.txt" => "Hello World", "data.json" => '{"key": "value"}'}
+  #
+  # @example From Hash
+  #   archive_data = {
+  #     'file1.txt' => 'content1',
+  #     'file2.txt' => 'content2'
+  #   }
+  #   zip_buffer = Omnizip::Buffer.create_from_hash(archive_data, :zip)
+  module Buffer
+    class << self
+      # Create archive in memory
+      #
+      # @param format [Symbol] Archive format (:zip, :seven_zip)
+      # @param options [Hash] Format-specific options
+      # @yield [archive] Block to populate archive
+      # @yieldparam archive [MemoryArchive] Archive object to add entries to
+      # @return [StringIO] Complete archive in memory, rewound to start
+      #
+      # @example Create ZIP in memory
+      #   buffer = Omnizip::Buffer.create(:zip) do |archive|
+      #     archive.add('file.txt', 'content')
+      #     archive.add('dir/file2.txt', 'more content')
+      #   end
+      #   File.binwrite('output.zip', buffer.string)
+      # rubocop:disable Naming/BlockForwarding, Style/ArgumentsForwarding -- Ruby 3.0 compatibility
+      def create(format = :zip, **options, &block)
+        buffer = StringIO.new(String.new(encoding: Encoding::BINARY))
+
+        case format
+        when :zip
+          create_zip(buffer, options, &block)
+        when :seven_zip, :'7z'
+          raise NotImplementedError, "7z format support coming in Phase 2"
+        else
+          raise ArgumentError, "Unsupported format: #{format}"
+        end
+
+        buffer.tap(&:rewind)
+      end
+      # rubocop:enable Naming/BlockForwarding, Style/ArgumentsForwarding
+
+      # Open archive from memory
+      #
+      # @param data [String, StringIO] Archive data
+      # @param format [Symbol, nil] Archive format (auto-detected if nil)
+      # @yield [archive] Block to read from archive
+      # @yieldparam archive [MemoryArchive] Archive object to read entries from
+      # @return [MemoryArchive, Object] Archive object or block return value
+      #
+      # @example Read entries
+      #   Omnizip::Buffer.open(zip_data) do |archive|
+      #     archive.each_entry do |entry|
+      #       puts "#{entry.name}: #{entry.size} bytes"
+      #     end
+      #   end
+      def open(data, format: nil, &block)
+        buffer = data.is_a?(StringIO) ? data : StringIO.new(data.b)
+        format ||= detect_format(buffer)
+
+        case format
+        when :zip
+          open_zip(buffer, &block)
+        when :seven_zip, :'7z'
+          raise NotImplementedError, "7z format support coming in Phase 2"
+        else
+          raise ArgumentError, "Unsupported format: #{format}"
+        end
+      end
+
+      # Extract all entries to memory
+      #
+      # @param data [String, StringIO] Archive data
+      # @param format [Symbol, nil] Archive format (auto-detected if nil)
+      # @return [Hash<String, String>] Filename => content mapping
+      #
+      # @example Extract to Hash
+      #   files = Omnizip::Buffer.extract_to_memory(zip_data)
+      #   files.each do |name, content|
+      #     puts "#{name}: #{content.bytesize} bytes"
+      #   end
+      def extract_to_memory(data, format: nil)
+        extractor = Buffer::MemoryExtractor.new(data, format: format)
+        extractor.extract_all
+      end
+
+      # Create archive from Hash of filename => content
+      #
+      # @param hash [Hash<String, String>] Filename => content mapping
+      # @param format [Symbol] Archive format
+      # @param options [Hash] Format-specific options
+      # @return [StringIO] Complete archive in memory
+      #
+      # @example Create from Hash
+      #   data = {'file1.txt' => 'content1', 'file2.txt' => 'content2'}
+      #   zip = Omnizip::Buffer.create_from_hash(data, :zip)
+      def create_from_hash(hash, format = :zip, **options)
+        create(format, **options) do |archive|
+          hash.each do |name, content|
+            archive.add(name, content)
+          end
+        end
+      end
+
+      private
+
+      # Detect archive format from magic bytes
+      #
+      # @param buffer [StringIO] Buffer containing archive data
+      # @return [Symbol] Detected format
+      # @raise [Omnizip::FormatError] If format cannot be detected
+      def detect_format(buffer)
+        magic = buffer.read(4)
+        buffer.rewind
+
+        case magic
+        when "PK\x03\x04", "PK\x05\x06", "PK\x07\x08"
+          # ZIP signatures: local file header, EOCD, data descriptor
+          :zip
+        when "7z\xBC\xAF"
+          :seven_zip
+        else
+          raise Omnizip::FormatError,
+                "Unknown archive format (magic: #{magic.inspect})"
+        end
+      end
+
+      # Create ZIP archive in buffer
+      #
+      # @param buffer [StringIO] Buffer to write to
+      # @param options [Hash] ZIP-specific options
+      # @yield [archive] Block to populate archive
+      def create_zip(buffer, _options, &block)
+        Omnizip::Zip::OutputStream.open(buffer) do |zos|
+          archive = Buffer::MemoryArchive.new(zos, :zip)
+          block&.call(archive)
+        end
+      end
+
+      # Open ZIP archive from buffer
+      #
+      # @param buffer [StringIO] Buffer containing ZIP data
+      # @yield [archive] Block to read from archive
+      # @return [MemoryArchive, Object] Archive or block return value
+      def open_zip(buffer, &block)
+        result = nil
+        Omnizip::Zip::InputStream.open(buffer) do |zis|
+          archive = Buffer::MemoryArchive.new(zis, :zip)
+          result = block ? yield(archive) : archive
+        end
+        result
+      end
+    end
+  end
+end