omnizip 0.3.41 → 0.3.43

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 919a322870094f270bd574530af4c463b6446586fdf869026b79ad017834bc1e
-  data.tar.gz: 55507eb0b2da4109cb094e711cda2d39df10773c9774c4a01614edc0d8548d9a
+  metadata.gz: 436437db6697f7363305eda4e6a3e2b78b922aa12b3c43e29756efe187310b60
+  data.tar.gz: 6e0b17e143c50beae378cdb5b7902e773d888bca14183fcf83e61dfeabe56a5e
 SHA512:
-  metadata.gz: 73b03468e2bb51d227059f316ab4fce911ce19ee6e0c175559de7b1df58a69536d9284d2b5ee2a0a19366ef0c53d448d02e4b95f397042c69c569630aacea86f
-  data.tar.gz: dad012852021f331f77a36bf86842274f612d215e32829965bf4bbaf5ad8b9b17539eb7e531a55e73c93d206c73a66760ccde6dfcf234b49e371f17f79451df8
+  metadata.gz: f1e20ae301093cacb8c582e1b554a678c72cefa6bf21095d129bebc14b8c4095a68a87da653ef5ea16cb65c00de9edd6ae7b0d92191e49c25e05438ceba264ab
+  data.tar.gz: a6ad938ab6bdfd75586bcef013ba056cc523681ef34449d03bc44daf18a591e6485b292b7c62bd17c72c13c20c7ff8c45caf4faf6735d5cff79a0c2f4a5a010b

data/CHANGELOG.md

@@ -7,6 +7,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.42] - 2026-08-29
+
+### Changed
+- `Formats::Zip::Reader` is usable immediately: entries parse on
+  first use, so `extract_all`/listing no longer silently do nothing
+  when `#read` was not called first. `#read` remains for eager
+  loading.
+- `Temp::ArchiveHelper` writes zips through the native
+  `Formats::Zip::Writer` instead of the rubyzip-compat
+  `Omnizip::Zip::File` seam (the Metadata subsystem remains on
+  compat deliberately as an in-place central-directory editor).
+- The RAR extraction spill cache installs an `at_exit` sweeper on
+  first use, reclaiming spill directories at normal process exit.
+- Module docs tell the truth: `Formats::Rar` claimed read-only with
+  external tools required; `Formats::Iso` claimed read-only while
+  carrying the verified writer. New `CONTEXT.md` records the domain
+  glossary (primary parser vs adapters, native vs external decode,
+  interop-verified vs Omnizip-internal codecs, handler routes, the
+  compat seam, bridges).
+
+## [0.3.41] - 2026-08-29
+
+### Changed
+- One RAR parser. `Formats::Rar3::Reader` and `Formats::Rar5::Reader`
+  are adapters over the primary `Formats::Rar::Reader` — the only
+  parser verified against real WinRAR archives — replacing ~600
+  lines of duplicate parsing. Both legacy interfaces gain real-
+  archive fidelity for free (exact mtimes, backslash normalization,
+  directory detection, CRC fields). The legacy RAR5 writer — whose
+  output not even unrar could list (garbage names, 2038 dates) —
+  now bridges onto the spec-conformant primary writer; its archives
+  pass `unrar t`. The primary Header learned minimal archives (file
+  block first, no main header) for RAR4 and RAR5, restoring a legacy
+  capability in one place.
+- Direct-seek extraction: the parser records each entry's
+  data_offset, so native extraction is one seek + read instead of
+  re-parsing the archive per entry. unrar-backed extraction spills
+  the archive once per archive path instead of extracting the whole
+  archive per entry (O(n^2) -> O(n)). Fixed a latent off-by-two in
+  the fallback block walk.
+- Converter symmetry: zip -> 7z uses the native reader with the
+  same extract-to-temp/write-from-tree shape as 7z -> zip; internal
+  code no longer calls the rubyzip-compat `Omnizip::Zip::File` seam.
+- `omnizip archive create` passes one flat options hash;
+  `Formats::Rar.create` applies the RAR4/RAR5-specific semantics
+  (the RAR4 writer's recovery guard no longer trips on explicit
+  false).
+
+### Fixed
+- Native-decode CRC guard referenced `Compression::DecompressionError`
+  which does not exist (the classes live under
+  `Compression::Dispatcher`); the NameError was silently masked by
+  the fallback rescue.
+- Unicode-flagged RAR4 names can carry non-UTF-8 bytes;
+  String#tr raised and aborted the block walk under non-UTF-8
+  locales (CI runners). Names are scrubbed before normalization.
+- Corrupt size fields drove unbounded reads: a garbage pack_size
+  attempted a multi-gigabyte read (NoMemoryError on CI) or an
+  overflowing seek (EINVAL on Linux, silently clamped on macOS).
+  Packed data is now seeked past — never allocated to skip — with
+  sizes bounds-checked against the archive length and corrupt skips
+  clamped to EOF so entries still list.
+
 ## [0.3.40] - 2026-08-29
 
 ### Fixed

data/CONTEXT.md

@@ -0,0 +1,67 @@
+# Domain Glossary
+
+Names for the concepts that keep coming up in omnizip. Use these
+words in code, docs, and reviews; when a term sharpens, update it
+here.
+
+## Archive access
+
+- **Archive facade** — `Omnizip::Archive`: the format-neutral entry
+  point. `create` yields a Builder (add_file/add_directory/add_data),
+  `open` yields a ReaderSession (entries/read/extract/extract_all).
+- **ArchiveHandler** — per-format adapter registered in the handler
+  registry (create/extract_to/list/read_entry) plus its extension
+  route. The facade and the convenience layer dispatch through
+  handlers, never through format classes directly.
+- **Extension route** — mapping from a file extension to a format
+  symbol. Writable routes (`ARCHIVE_FORMAT_EXTENSIONS`) may create
+  archives; read routes (`READ_ARCHIVE_FORMAT_EXTENSIONS`) only
+  extract/list/read. `.rar`, `.cpio`, `.iso` are read-only routes;
+  creating them raises truthfully.
+
+## Reading and decode
+
+- **Reader invariant — always usable** — every Reader
+  (`Formats::Zip`, `Formats::SevenZip`, `Formats::Rar`) parses on
+  first use; calling `#open` first is never required, only eager.
+
+- **Native decode** — decompression implemented in Ruby inside
+  omnizip. RAR native decode is **CRC-gated**: the stored header CRC
+  must match the decoded bytes or the result is discarded.
+- **External fallback** — delegating to an external tool (the unrar
+  command) when native decode cannot be trusted. RAR extraction
+  spills the archive once per archive path (the **extraction spill
+  cache**) and copies entries out of it.
+
+## Writing and interop
+
+- **Interop-verified** — output accepted by the official tool for
+  the format (unrar for RAR, 7zz for 7z/ISO, unzip for ZIP), checked
+  with `test` plus a byte-identical extraction round-trip.
+- **Omnizip-internal codec** — a compression stream only omnizip can
+  decode (RAR methods above :store). Archives carrying them must be
+  labeled honestly; official tools fail loudly, never silently.
+- **STORE** — the uncompressed method; the interoperability floor
+  for every archive writer in this library.
+
+## Seams
+
+- **Compat seam** — `Omnizip::Zip` (aliased into the global `Zip`
+  namespace by `omnizip/rubyzip_compat`): a rubyzip-compatible
+  layer for library consumers migrating off rubyzip. Internal code
+  must use the native `Formats::Zip` tree instead; the Metadata
+  subsystem is its one deliberate in-house consumer (in-place
+  central-directory editing).
+- **Bridge** — an adapter that carries a file-based implementation
+  across to a non-file interface, spilling through a temporary file
+  (the RAR3/RAR5 legacy readers, `Buffer::SevenZipBridge`).
+- **Primary parser** — the one parser per format family verified
+  against real archives (e.g. `Formats::Rar::Reader`). Legacy
+  interfaces are adapters over primary parsers, never parallel
+  implementations.
+
+## In memory
+
+- **Buffer** — `Omnizip::Buffer`: in-memory archive create/read for
+  ZIP (stream-based) and 7z (through the bridge). Format detection
+  compares binary magic literals.

data/lib/omnizip/formats/iso.rb

@@ -3,14 +3,13 @@
 module Omnizip
   module Formats
     # ISO 9660 CD-ROM filesystem format support
-    # Provides read-only access to ISO images
     #
-    # ISO 9660 is the standard filesystem for CD-ROMs and DVD-ROMs.
-    # This implementation supports:
-    # - Primary Volume Descriptor parsing
-    # - Directory structure traversal
-    # - File extraction
-    # - Rock Ridge extensions (basic)
+    # Reads and writes ISO 9660 images: Primary Volume Descriptor
+    # parsing, directory traversal, file extraction, and image
+    # creation whose directory records point at allocated extents
+    # (verified against 7-Zip). Rock Ridge and Joliet are NOT
+    # implemented — the writer's options stay false rather than
+    # advertising extensions readers would misparse.
     module Iso
       # Nested classes - autoloaded
       autoload :Reader, "omnizip/formats/iso/reader"

data/lib/omnizip/formats/rar/decompressor.rb

@@ -258,6 +258,7 @@ module Omnizip
                 raise "Command entry extraction failed: #{entry_name}"
               end
               extract_cache[cache_key] = cached_dir
+              install_exit_sweeper
             end
 
             source = File.join(cached_dir, entry_name)
@@ -265,8 +266,8 @@ module Omnizip
           end
 
           # Extracted-archive cache: archive path => spill directory.
-          # Cleared by .clear_extract_cache! (tests); directories live
-          # in the system temp dir until process exit.
+          # Cleared by .clear_extract_cache!; an at_exit sweeper
+          # reclaims everything at normal process termination.
           def extract_cache
             @extract_cache ||= {}
           end
@@ -277,6 +278,14 @@ module Omnizip
             extract_cache.clear
           end
 
+          # Reclaim spill directories when the process exits normally
+          def install_exit_sweeper
+            return if @exit_sweeper_installed
+
+            at_exit { clear_extract_cache! }
+            @exit_sweeper_installed = true
+          end
+
           # Build extract command
           def build_extract_command(archive_path, output_dir, password)
             # Array form: no shell involved, so paths and passwords

data/lib/omnizip/formats/rar/reader.rb

@@ -12,7 +12,7 @@ module Omnizip
       class Reader
         include Omnizip::Formats::Rar::Constants
 
-        attr_reader :file_path, :header, :entries, :archive_info,
+        attr_reader :file_path, :header, :archive_info,
                     :volume_manager
 
         # Initialize reader with file path
@@ -25,6 +25,7 @@ module Omnizip
           @archive_info = Models::RarArchive.new(file_path)
           @volume_manager = VolumeManager.new(file_path)
           @use_native = true # Prefer native decompression
+          @opened = false
         end
 
         # Open and parse RAR archive
@@ -34,14 +35,24 @@ module Omnizip
           File.open(@file_path, "rb") do |io|
             parse_archive(io)
           end
+          @opened = true
           self
         end
 
+        # All entries, parsing on first use — a Reader is always
+        # usable; #open remains for eager loading
+        #
+        # @return [Array<Models::RarEntry>] File entries
+        def entries
+          ensure_open
+          @entries
+        end
+
         # List all files in archive
         #
         # @return [Array<Models::RarEntry>] File entries
         def list_files
-          @entries
+          entries
         end
 
         # Extract file to output path
@@ -51,6 +62,7 @@ module Omnizip
         # @param password [String, nil] Optional password
         # @raise [RuntimeError] if entry not found or extraction fails
         def extract_entry(entry_name, output_path, password: nil)
+          ensure_open
           entry = @entries.find { |e| e.name == entry_name }
           raise "Entry not found: #{entry_name}" unless entry
 
@@ -79,6 +91,7 @@ module Omnizip
         # @param password [String, nil] Optional password
         # @raise [RuntimeError] on extraction error
         def extract_all(output_dir, password: nil)
+          ensure_open
           FileUtils.mkdir_p(output_dir)
 
           # Use decompressor to extract all
@@ -126,6 +139,11 @@ module Omnizip
 
         private
 
+        # Parse the archive once, on demand
+        def ensure_open
+          open unless @opened
+        end
+
         # Parse RAR archive structure
         #
         # @param io [IO] Input stream

data/lib/omnizip/formats/rar.rb

@@ -3,17 +3,18 @@
 module Omnizip
   module Formats
     # RAR archive format support
-    # Provides read-only access to RAR archives (single and multi-volume)
     #
-    # This module implements RAR archive format support:
-    # - Format signature validation (RAR4 and RAR5)
-    # - Archive structure parsing
-    # - File listing
-    # - File extraction (requires unrar gem or system command)
-    # - Multi-volume archive support
-    #
-    # Note: RAR compression is proprietary, so this implementation
-    # is read-only and requires external decompression tools.
+    # - Formats::Rar::Reader — the primary parser, verified against
+    #   real WinRAR archives: listing, directories, mtimes, and
+    #   extraction (native STORE decode with stored-CRC verification;
+    #   foreign compressed streams fall back to the unrar command
+    #   after the CRC check rejects them)
+    # - Formats::Rar::Writer (RAR4) and Formats::Rar::Rar5::Writer —
+    #   STORE output is unrar-verified; compressed methods produce
+    #   Omnizip-internal streams (see the README interop table)
+    # - Formats::Rar3 / Formats::Rar5 — legacy interfaces, thin
+    #   adapters over the primary reader and the RAR5 writer
+    # - Multi-volume archives, encryption (RAR5), recovery records
     module Rar
       # Nested classes - autoloaded
       autoload :Constants, "omnizip/formats/rar/constants"

data/lib/omnizip/formats/seven_zip/reader.rb

@@ -28,6 +28,7 @@ module Omnizip
           @offset = options[:offset] || 0
           @solid_cache = {}
           @solid_cache_extracted = {}
+          @opened = false
         end
 
         # Open and parse .7z archive
@@ -79,10 +80,12 @@ module Omnizip
           @split_reader&.volumes || [@file_path]
         end
 
-        # List all files in archive
+        # List all files in archive, parsing on first use — a Reader
+        # is always usable; #open remains for eager loading
         #
         # @return [Array<Models::FileEntry>] File entries
         def list_files
+          ensure_open
           @entries.reject { |e| e.name.nil? || e.name.empty? }
         end
 
@@ -92,6 +95,7 @@ module Omnizip
         # @param output_path [String] Destination path
         # @raise [RuntimeError] if entry not found or extraction fails
         def extract_entry(entry_name, output_path)
+          ensure_open
           # Delegate to split reader if available
           if @split_reader
             @split_reader.extract_entry(entry_name, output_path)
@@ -132,6 +136,7 @@ module Omnizip
         # @param output_dir [String] Destination directory
         # @raise [RuntimeError] on extraction error
         def extract_all(output_dir)
+          ensure_open
           FileUtils.mkdir_p(output_dir)
 
           real_out = File.realpath(output_dir)
@@ -187,6 +192,11 @@ module Omnizip
 
         private
 
+        # Parse the archive once, on demand
+        def ensure_open
+          open unless @opened
+        end
+
         # Parse .7z archive structure
         #
         # @param io [io] Input stream
@@ -236,7 +246,16 @@ module Omnizip
 
           # Parse metadata
           parser = Parser.new(next_header_data)
-          @stream_info, @entries = parse_metadata(parser)
+          begin
+            @stream_info, @entries = parse_metadata(parser)
+          rescue StandardError => e
+            if @headers_decrypted
+              raise "Failed to decrypt headers: incorrect password " \
+                    "or corrupted data (#{e.message})"
+            end
+
+            raise
+          end
 
           # Map entries to their folders/streams
           map_entries_to_streams
@@ -257,11 +276,16 @@ module Omnizip
 
           # Decrypt using password
           encryptor = HeaderEncryptor.new(@password)
-          encryptor.decrypt(
+          decrypted = encryptor.decrypt(
             @encrypted_header.encrypted_data,
             @encrypted_header.salt,
             @encrypted_header.iv,
           )
+          # AES-CBC 'succeeds' with any key and yields garbage; wrong
+          # passwords surface as later header-parse failures, so mark
+          # the archive and translate those into the password error
+          @headers_decrypted = true
+          decrypted
         rescue OpenSSL::Cipher::CipherError => e
           raise "Failed to decrypt headers: incorrect password (#{e.message})"
         end
@@ -393,6 +417,20 @@ module Omnizip
             entry.folder_index = folder_idx
             entry.file_index = i
             entry.size = @stream_info.unpack_sizes[stream_idx] if @stream_info.unpack_sizes[stream_idx]
+
+            # Single-stream folders own their packed bytes outright,
+            # so the entry's compressed size is exact. Solid folders
+            # share packed bytes across streams — leave nil rather
+            # than fabricate a split.
+            num_in_folder = @stream_info.num_unpack_streams_in_folders[folder_idx]
+            if num_in_folder == 1
+              folder = @stream_info.folders[folder_idx]
+              packed = folder.pack_stream_indices.sum do |pi|
+                @stream_info.pack_sizes[pi] || 0
+              end
+              entry.compressed_size = packed
+            end
+
             stream_idx += 1
           end
         end

data/lib/omnizip/formats/zip/reader.rb

@@ -9,7 +9,7 @@ module Omnizip
       class Reader
         include Omnizip::Formats::Zip::Constants
 
-        attr_reader :file_path, :entries
+        attr_reader :file_path
 
         def initialize(file_path)
           @file_path = file_path
@@ -36,6 +36,13 @@ module Omnizip
           self
         end
 
+        # All entries, parsing on first use — a Reader is usable
+        # immediately; #read remains for explicit eager loading
+        def entries
+          ensure_read
+          @entries
+        end
+
         # Extract all files to a directory
         def extract_all(output_dir, preserve_links: true,
 dereference_links: false)
@@ -163,6 +170,11 @@ dereference_links: false)
 
         private
 
+        # Parse the central directory once, on demand
+        def ensure_read
+          read if @entries.empty? && @central_directory.empty?
+        end
+
         # Read central directory entries
         def read_central_directory(io, eocd)
           io.seek(eocd.central_directory_offset, ::IO::SEEK_SET)

data/lib/omnizip/temp.rb

@@ -129,9 +129,12 @@ module Omnizip
 
         case format
         when :zip
-          Omnizip::Zip::File.create(path) do |zip|
-            zip.add(name) { data }
-          end
+          # Native writer — the rubyzip-compat Omnizip::Zip seam is
+          # for library consumers migrating from rubyzip, not for
+          # internal use
+          writer = Omnizip::Formats::Zip::Writer.new(path)
+          writer.add_data(name, data.to_s)
+          writer.write
         end
       end
     end

data/lib/omnizip/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Omnizip
-  VERSION = "0.3.41"
+  VERSION = "0.3.43"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omnizip
 version: !ruby/object:Gem::Version
-  version: 0.3.41
+  version: 0.3.43
 platform: ruby
 authors:
 - Ribose Inc.
@@ -115,6 +115,7 @@ files:
 - ".rubocop.yml"
 - ".rubocop_todo.yml"
 - CHANGELOG.md
+- CONTEXT.md
 - COPYING
 - Gemfile
 - LICENSE