omnizip 0.3.35 → 0.3.37

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e76fab599398d72d3eb4999e7d516dabb26e1ca625dbc75afb35d48b7d037dcf
-  data.tar.gz: 6afeb78f1f806ba12a7577bfe8c6fd2f6ba127047ec8546b0513be5516a7420a
+  metadata.gz: dbb80e9d06123c538d5823fd0263b38c8a1a386ce0ba107f1aefd6320b2f3618
+  data.tar.gz: 53a147f76a0290e7b8dc211c2040cb090799f196fbc57c24cd4ff44290ef53f1
 SHA512:
-  metadata.gz: 7a46395d5faa8ed51438bb680839490c99dd15c01f2409b60a8cf9241af8269150b0fb98694fc176c330af90ded71bea99e64f0c11770f0c9d8259abf1719b8f
-  data.tar.gz: bec34c361902bc7954b98d4d9d1f50e53cdac36bb9b800b3d6d0109a1ffc9e36e5211fba84cb38f829ef54c27a3eba79f03b0df8be39af0026c378f5feeee773
+  metadata.gz: 8f1fae0da5256104bc0ce6871ebf6f85ec4e60865d513004a55c30389eca1dd3ba47bc3d94c6c0f419717930933920428eb3755e2a3f237014094012638953b7
+  data.tar.gz: 27eb53ffd94c880bfa429202cd8b9bdc9094e83ccc382a96479a6dd0c8f090997081f41d5b3463c6f63bb7e9d06fff0dc7b44c45425c0bdd85cc503998559763

data/CHANGELOG.md

@@ -7,6 +7,73 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- `Omnizip::Archive` — the block-style facade the guides have
+  documented since the docs were written (it never existed; ~50
+  examples across 17 files were dead). `Archive.create(path,
+  format:, **options)` yields a Builder with `add_file(path,
+  archive_path:)`, `add_directory(dir)` (tree stored under its own
+  name), and `add_data(name, content)`; `Archive.open(path,
+  password:)` yields (or returns) a session with `entries`
+  (name/size/directory?/mtime), `each_entry`, `read`, `extract`,
+  `extract_all`, `extract_matching`. 7z options (`level:`,
+  `password:`, `encrypt_headers:`, `algorithm:`, `filters:`,
+  `solid:`, `dict_size:`) pass through to the writer;
+  `ENV['OMNIZIP_PASSWORD']` backs `open`. Passwords are refused
+  loudly for zip/tar (no encryption support) instead of silently
+  producing unprotected archives.
+- `.zst` routing in the convenience API: `compress_file` to `.zst`
+  previously wrote a mislabeled ZIP; it now writes a real Zstandard
+  frame (validated against the system zstd CLI in both directions),
+  and `decompress_file` reads them.
+- Read-only RAR routing: `extract_archive`/`list_archive`/
+  `read_from_archive`/`Archive.open` operate on `.rar` files through
+  a new read-only `ArchiveHandlers::RarHandler`; creation keeps
+  raising truthfully. `resolve_archive_format` is now
+  operation-aware (`writing:`), so read operations no longer fail
+  with "cannot be written" errors.
+- `compress_file`/`compress_directory` forward compression options
+  (`algorithm:`, `level:`, ...) to the format writer instead of
+  silently dropping them (7z honors them; zip absorbs them —
+  per-entry ZIP compression is set through `Zip::OutputStream`).
+
+### Fixed
+- RAR5 metadata parsing: the file-header parser ignored the
+  optional ExtraAreaSize/DataSize vints, misaligning every field —
+  all RAR5 entries listed with size 0 (and one fixture failed to
+  parse at all). Field order now matches the RAR 5.0 specification
+  (verified against RARLAB fixtures); `compressed_size` is populated
+  from DataSize and the directory flag is the correct FileFlags bit
+  (0x0001). The main-header parser also reads the ArchiveFlags vint
+  it was skipping, so volume/solid detection works. Listing now
+  prefers the native parser (full metadata) over the external
+  `unrar vb` listing (names only, sizes hardcoded to 0).
+- `compress_directory` to a single-file stream extension (`.gz`,
+  `.lzma`, ...) silently wrote a ZIP under the foreign name; it now
+  raises `UnsupportedFormatError` explaining the mismatch.
+
+### Changed
+- Docs: every example across the guides now runs verbatim against
+  the real API. Fictional APIs removed or replaced
+  (`Omnizip::OutputStream`/`InputStream`, `compress_files`,
+  `train_dictionary`, `Archive#compression=` setters, `tar_bzip2`,
+  ZIP password attributes, `CorruptArchiveError`,
+  `UnsupportedEncryptionError`); fabricated parallel-processing and
+  benchmark sections rewritten as truthful process-level
+  parallelism; the zstandard guide now centers on the real
+  `.zst`/ZIP-entry/dictionary APIs (and no longer claims a native
+  zstd binding).
+
+## [0.3.36] - 2026-08-28
+
+### Fixed
+- `add_to_archive`/`remove_from_archive` errors name the resolved
+  format (`Format :seven_zip does not support adding entries`)
+  instead of always blaming `:zip`, the default parameter the caller
+  never passed.
+
+## [0.3.35] - 2026-08-28
+
 ### Fixed
 - `Omnizip.list_archive` on `.7z` returned raw Reader objects (the
   SevenZip.open facade discards block return values) and

data/docs/getting-started/basic-usage.adoc

@@ -53,12 +53,8 @@ Omnizip.compress_directory('my_folder/', 'backup.zip')
 # Create 7z archive
 Omnizip.compress_directory('my_folder/', 'backup.7z', format: :seven_zip)
 
-# Add individual files
-Omnizip::Archive.create('custom.zip') do |archive|
-  archive.add_file('file1.txt')
-  archive.add_file('file2.txt')
-  archive.add_directory('folder/')
-end
+# Add individual files: compress one file per call
+Omnizip.compress_file('file1.txt', 'custom.zip')
 ----
 
 === Extracting Archives
@@ -70,10 +66,9 @@ require 'omnizip'
 # Extract entire archive
 Omnizip.extract_archive('backup.zip', 'output/')
 
-# Extract with pattern matching
-Omnizip::Archive.open('backup.zip') do |archive|
-  archive.extract_matching('*.txt', 'output/')
-end
+# Extract a single entry without a full extraction
+content = Omnizip.read_from_archive('backup.zip', 'notes.txt')
+File.write('output/notes.txt', content)
 ----
 
 === Reading Archive Contents
@@ -82,10 +77,10 @@ end
 ----
 require 'omnizip'
 
-# List all entries
-entries = Omnizip.list_archive('backup.zip')
-entries.each do |entry|
-  puts "#{entry.name}: #{entry.size} bytes"
+# List all entries (names); pass details: true for sizes
+Omnizip.list_archive('backup.zip').each { |name| puts name }
+Omnizip.list_archive('backup.zip', details: true).each do |entry|
+  puts "#{entry[:name]}: #{entry[:size]} bytes"
 end
 
 # Read specific file without extraction
@@ -187,13 +182,12 @@ end
 ----
 require 'omnizip'
 
-# Verify archive integrity
+# Verify archive integrity: reading the archive's central
+# directory raises FormatError when the archive is damaged.
 begin
-  Omnizip::Archive.open('archive.zip') do |archive|
-    archive.verify
-  end
+  Omnizip.list_archive('archive.zip')
   puts "Archive is valid"
-rescue Omnizip::CorruptArchiveError => e
+rescue Omnizip::FormatError => e
   puts "Archive is corrupted: #{e.message}"
 end
 ----
@@ -253,9 +247,7 @@ require 'tempfile'
 
 # Create temporary archive
 Tempfile.create(['backup', '.zip']) do |tmpfile|
-  Omnizip::Archive.create(tmpfile.path) do |archive|
-    archive.add_directory('data/')
-  end
+  Omnizip.compress_directory('data', tmpfile.path)
 
   # Use archive...
   puts "Temporary archive: #{tmpfile.path}"

data/docs/guides/advanced-features/encryption.adoc

@@ -12,7 +12,7 @@ Protect sensitive data in your archives with industry-standard AES-256 encryptio
 == Benefits
 
 * **Strong Security**: AES-256 encryption with secure key derivation
-* **Format Flexibility**: Encryption available in both ZIP and 7z formats
+* **Format**: Encryption available for 7z archives (ZIP encryption is unsupported)
 * **Header Protection**: Encrypt filenames and metadata (7z format)
 * **Password Validation**: Built-in password strength checking
 * **Compatibility**: Works with archives from other tools
@@ -44,40 +44,20 @@ end
 * Optional header encryption (hides filenames)
 * HMAC-SHA-256 authentication
 
-=== WinZip AES (ZIP Format)
+=== ZIP Encryption: not supported
 
-Industry-standard AES encryption for ZIP archives:
+Omnizip can neither create nor decrypt encrypted ZIP archives —
+neither WinZip AES nor traditional ZipCrypto. Encrypted 7z is the
+supported path; extract encrypted ZIPs with 7-Zip/unzip.
 
-[source,ruby]
-----
-# Create AES-encrypted ZIP
-Omnizip::Zip::File.open('secure.zip', create: true) do |zip|
-  zip.password = 'SecurePassword123'
-  zip.encryption = :winzip_aes  # AES-256
-  zip.add('private.doc', 'files/private.doc')
-end
-----
-
-**Features**:
-
-* AES-256, AES-192, or AES-128
-* Compatible with WinZip, 7-Zip, PeaZip
-* HMAC-SHA-1 authentication
-* Standard ZIP format
-
-=== Traditional ZIP Encryption
-
-[WARNING]
-Traditional ZIP encryption (ZipCrypto) is weak and should only be used for compatibility with legacy systems.
+The convenience API raises rather than silently ignoring a
+password for zip:
 
 [source,ruby]
 ----
-# Only for compatibility - NOT RECOMMENDED
-Omnizip::Zip::File.open('legacy.zip', create: true) do |zip|
-  zip.password = 'password'
-  zip.encryption = :traditional  # Weak encryption
-  zip.add('file.txt', 'data.txt')
-end
+Omnizip::Archive.create('secure.zip', password: 'x')
+# => Omnizip::UnsupportedFormatError:
+#    password is only supported for seven_zip; :zip has no encryption support
 ----
 
 == Decrypting Archives
@@ -91,10 +71,8 @@ Omnizip::Archive.open('secure.7z', password: 'MyStr0ngP@ssw0rd') do |archive|
   archive.extract_all('decrypted/')
 end
 
-# Decrypt ZIP archive
-Omnizip::Zip::File.open('secure.zip', password: 'SecurePassword123') do |zip|
-  zip.extract_all('output/')
-end
+# ZIP encryption: Omnizip can neither create nor decrypt
+# password-protected ZIP archives; extract them with 7-Zip/unzip
 ----
 
 === Password via Environment Variable
@@ -286,12 +264,11 @@ Some older archives may use unsupported encryption:
 [source,ruby]
 ----
 begin
-  Omnizip::Archive.open('old-archive.zip') do |archive|
-    # ...
+  Omnizip::Archive.open('old-archive.7z', password: 'wrong') do |archive|
+    archive.read('secret.txt')
   end
-rescue Omnizip::UnsupportedEncryptionError => e
-  puts "Encryption method not supported: #{e.message}"
-  puts "Try opening with 7-Zip or WinZip first"
+rescue Omnizip::FormatError => e
+  puts "Archive damaged or password wrong: #{e.message}"
 end
 ----
 

data/docs/guides/advanced-features/index.adoc

@@ -34,12 +34,22 @@ These features can be combined for maximum efficiency:
 
 [source,ruby]
 ----
-# Combine streaming + parallel + progress
-Omnizip.compress_directory('large_data/', 'backup.7z',
-  parallel: true,
-  threads: 8
-) do |progress|
-  puts "#{progress.percentage}% - #{progress.throughput_mb_s} MB/s"
+# Streaming writes + a progress tracker
+require 'omnizip/zip/output_stream'
+
+files = Dir.glob('large_data/**/*').select { |f| File.file?(f) }
+tracker = Omnizip::Progress.track(
+  total_files: files.size,
+  total_bytes: files.sum { |f| File.size(f) },
+  reporter: :console
+)
+
+Omnizip::Zip::OutputStream.open('backup.zip') do |stream|
+  files.each do |file|
+    stream.put_next_entry(file.delete_prefix('large_data/'))
+    stream.write(File.binread(file))
+    tracker.update(files: 1, bytes: File.size(file))
+  end
 end
 ----
 

data/docs/guides/advanced-features/parallel-processing.adoc

@@ -7,176 +7,94 @@ grand_parent: Guides
 
 == Purpose
 
-Parallel processing leverages multiple CPU cores to significantly speed up compression and extraction operations. This feature allows you to process large archives or multiple files simultaneously, reducing overall processing time.
+Omnizip's codecs are pure Ruby and single-threaded: a single archive
+is always compressed or extracted by one CPU core. To use multiple
+cores, run independent archive operations in parallel — across
+processes for CPU-bound compression, or across threads for
+I/O-bound extraction of separate archives.
 
-== Benefits
-
-* **2-3x Faster**: Achieve 2-3x speedup on multi-core systems
-* **Better Resource Utilization**: Use all available CPU cores effectively
-* **Reduced Wait Time**: Process large batches of files quickly
-* **Scalable**: Performance improves with more CPU cores
-
-== When to Use Parallel Processing
+== When It Helps
 
 [cols="1,3"]
 |===
-|Scenario |Parallel Benefit
-
-|Large Archives (>100 files)
-|Distribute file processing across cores
+|Scenario |Approach
 
-|Batch Operations
-|Process multiple archives simultaneously
+|Many archives to compress
+|One process per archive
 
-|Multi-core Servers
-|Maximize server resource utilization
+|Many archives to extract
+|One thread per archive (I/O releases the GVL)
 
-|Time-Critical Tasks
-|Reduce processing time for urgent operations
+|One large archive
+|No parallelism available; pick an appropriate +level:+
 |===
 
-== Parallel Compression
+== Parallel Compression (Processes)
 
-=== Compress Directory in Parallel
-
-Automatically distribute files across available cores:
+Compression is CPU-bound, so use processes — MRI's GVL prevents
+in-thread parallelism:
 
 [source,ruby]
 ----
-# Compress using all available cores
-Omnizip.compress_directory(
-  'large_project/',
-  'backup.zip',
-  parallel: true,
-  threads: 4  # Or omit to use all cores
-)
-----
-
-=== Custom Thread Count
+# Compress each directory in its own process
+dirs = %w[project_a project_b project_c]
 
-Control the number of parallel workers:
-
-[source,ruby]
-----
-# Use specific number of threads
-Omnizip::Archive.create('archive.7z', format: :seven_zip) do |archive|
-  archive.add_directory(
-    'data/',
-    parallel: true,
-    threads: 8,  # Use 8 worker threads
-    chunk_size: 1.megabyte  # Process 1MB chunks
-  )
+pids = dirs.map do |dir|
+  Process.fork do
+    Omnizip.compress_directory(dir, "#{dir}.7z", format: :seven_zip)
+  end
 end
+pids.each { |pid| Process.wait(pid) }
 ----
 
-== Parallel Extraction
-
-=== Extract Multiple Files Simultaneously
-
-Extract files in parallel for faster extraction:
-
-[source,ruby]
-----
-# Extract with parallel processing
-Omnizip.extract_archive(
-  'large-archive.zip',
-  'output/',
-  parallel: true,
-  threads: 4
-)
-----
-
-=== With Progress Tracking
-
-Combine parallel processing with progress monitoring:
+Or drive the CLI from your shell or job scheduler:
 
-[source,ruby]
+[source,bash]
 ----
-Omnizip.extract_archive('backup.zip', 'restored/') do |progress|
-  puts "Extracted #{progress.files_processed}/#{progress.total_files} files"
-  puts "Using #{progress.active_threads} parallel threads"
-  puts "Speed: #{progress.throughput_mb_s} MB/s"
-end
+ls -d project_*/ | xargs -P 8 -I{} omnizip archive create {}.7z {}
 ----
 
-== Performance Characteristics
-
-[cols="2,1,1,1,1"]
-|===
-|Workload |1 Thread |2 Threads |4 Threads |8 Threads
-
-|100 small files
-|10s
-|6s
-|4s
-|3s
-
-|10 large files
-|60s
-|35s
-|20s
-|15s
-
-|Mixed workload
-|30s
-|18s
-|12s
-|10s
-|===
-
-*Note: Performance varies based on CPU, disk speed, and file characteristics.*
+== Parallel Extraction (Threads)
 
-== Configuration Options
-
-=== Thread Count
-
-Control parallelism level:
+Extracting separate archives is I/O-bound, so threads work:
 
 [source,ruby]
 ----
-# Auto-detect (recommended)
-parallel: true
-
-# Specific thread count
-parallel: true, threads: 4
-
-# Match CPU cores
-parallel: true, threads: Etc.nprocessors
-----
-
-=== Chunk Size
+archives = Dir.glob('downloads/*.zip')
 
-Configure work distribution:
+threads = archives.map do |archive|
+  Thread.new do
+    Omnizip.extract_archive(
+      archive,
+      "extracted/#{File.basename(archive, '.zip')}/"
+    )
+  end
+end
 
-[source,ruby]
+threads.each(&:join)
 ----
-# Smaller chunks = better distribution, more overhead
-chunk_size: 512.kilobytes
-
-# Larger chunks = less overhead, less parallel benefit
-chunk_size: 10.megabytes
 
-# Default: 1MB (good balance)
-chunk_size: 1.megabyte
-----
+Note: a single archive's extraction still uses one thread.
 
 == Use Cases
 
 === Server Deployments
 
-Maximize server hardware utilization:
-
 [source,ruby]
 ----
-# Backup server with 16 cores
-Omnizip.compress_directory(
-  '/var/www/',
-  '/backups/www-backup.7z',
-  format: :seven_zip,
-  compression: :lzma2,
-  parallel: true,
-  threads: 16
-)
+# One process per site on a multi-core backup server
+sites = Dir.children('/var/www')
+
+pids = sites.map do |site|
+  Process.fork do
+    Omnizip.compress_directory(
+      File.join('/var/www', site),
+      "/backups/#{site}.7z",
+      format: :seven_zip, algorithm: :lzma2, level: 9
+    )
+  end
+end
+pids.each { |pid| Process.wait(pid) }
 ----
 
 === Batch Processing
@@ -204,43 +122,23 @@ end
 
 == Best Practices
 
-. **Match Thread Count to Cores**: Use `Etc.nprocessors` for optimal performance
-. **Consider Disk I/O**: More threads may not help with slow disks
-. **Monitor Memory**: Each thread uses additional memory
-. **Test Your Workload**: Measure actual speedup for your use case
-. **Combine with Streaming**: Use both for maximum efficiency
+. **One process per archive** for compression; threads only help I/O
+. **Consider disk I/O**: more parallelism may not help on slow disks
+. **Monitor memory**: each process/thread adds overhead
+. **Test your workload**: measure the real speedup
 
 == Limitations
 
-* Ruby GIL limits true parallelism (use JRuby for better results)
-* Memory usage increases with thread count
-* I/O-bound operations see less benefit
-* Very small files have overhead from thread management
+* No intra-archive parallelism: a single archive uses one core
+* MRI's GVL blocks in-thread CPU parallelism — use processes
+* Memory usage grows with process/thread count
 
 == Platform Considerations
 
-[cols="1,3"]
-|===
-|Platform |Notes
-
-|MRI Ruby
-|Limited by GIL, 2-3x speedup typical
-
-|JRuby
-|No GIL, better parallel scalability
-
-|TruffleRuby
-|Excellent parallel performance
-
-|Windows
-|Similar performance to Unix systems
-
-|Linux/macOS
-|Full parallel processing support
-|===
+`Process.fork` is unavailable on Windows — use `Process.spawn` with
+the +omnizip+ CLI there, or a job scheduler.
 
 == See Also
 
-* link:streaming.html[Streaming] - Combine for memory efficiency
-* link:progress-tracking.html[Progress Tracking] - Monitor parallel operations
-* link:../../compatibility.html[Compatibility] - Format support for parallel processing
+* link:streaming.html[Streaming] - Memory efficiency
+* link:../compression-algorithms/lzma2.html[LZMA2] - Default 7z algorithm