omnizip 0.3.41 → 0.3.42

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 919a322870094f270bd574530af4c463b6446586fdf869026b79ad017834bc1e
-  data.tar.gz: 55507eb0b2da4109cb094e711cda2d39df10773c9774c4a01614edc0d8548d9a
+  metadata.gz: 060755f6c69bca46bcb999d0d36471045ae3d13e260cfa3c73601a8d440b1634
+  data.tar.gz: b524b77c579c824009821ca5d1bdb47327cfc55f3ebd1dab4ea8574d1ec3c631
 SHA512:
-  metadata.gz: 73b03468e2bb51d227059f316ab4fce911ce19ee6e0c175559de7b1df58a69536d9284d2b5ee2a0a19366ef0c53d448d02e4b95f397042c69c569630aacea86f
-  data.tar.gz: dad012852021f331f77a36bf86842274f612d215e32829965bf4bbaf5ad8b9b17539eb7e531a55e73c93d206c73a66760ccde6dfcf234b49e371f17f79451df8
+  metadata.gz: 237f14e0c479844a473d1830e956882a0d250f6c733522bcd9f3d36b7ba10b474b4564902791aecd52948ad330b82bb0bb7e61dd97db607bf3dcd85ab3dc847b
+  data.tar.gz: cfe4637c8ad1223ccb8b9735fc1494d61937b636f3d79dd7fbd2c1f59f6f35eb38686152ee56732f0cb29cfbf3c12f7ddfb6dae5bd6c146b8d833fca5315a00a

data/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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,63 @@
+# 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 decoding
+
+- **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.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/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.42"
 end

metadata

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