omnizip 0.4.7-x86_64-linux

data/docs/getting-started/your-first-archive.adoc

@@ -0,0 +1,219 @@
+---
+title: Your First Archive
+nav_order: 4
+parent: Getting Started
+---
+
+== Your First Archive
+
+=== General
+
+This guide walks you through creating your first archive with Omnizip, covering both .7z and ZIP formats.
+
+=== Creating a Simple 7z Archive
+
+==== Command Line
+
+[source,bash]
+----
+# Create a 7z archive with default settings
+omnizip archive create backup.7z document.txt photo.jpg
+----
+
+This creates a new archive using LZMA2 compression at level 5 (default).
+
+==== Ruby API
+
+[source,ruby]
+----
+require 'omnizip'
+
+# Create archive with default settings
+writer = Omnizip::Formats::SevenZip::Writer.new('backup.7z')
+writer.add_file('document.txt')
+writer.add_file('photo.jpg')
+writer.close
+
+puts "Archive created successfully!"
+----
+
+=== Customizing Compression
+
+==== Higher Compression
+
+[source,bash]
+----
+omnizip archive create backup.7z documents/ \
+  --algorithm lzma2 --level 9
+----
+
+[source,ruby]
+----
+writer = Omnizip::Formats::SevenZip::Writer.new('backup.7z',
+  algorithm: :lzma2,
+  level: 9
+)
+writer.add_directory('documents/')
+writer.close
+----
+
+==== Faster Compression
+
+[source,bash]
+----
+omnizip archive create backup.7z data/ \
+  --algorithm lzma2 --level 1
+----
+
+[source,ruby]
+----
+writer = Omnizip::Formats::SevenZip::Writer.new('backup.7z',
+  algorithm: :lzma2,
+  level: 1
+)
+writer.add_directory('data/')
+writer.close
+----
+
+=== Creating a ZIP Archive
+
+==== Command Line
+
+[source,bash]
+----
+# Create a ZIP archive
+omnizip archive create backup.zip documents/ \
+  --format zip
+----
+
+==== Ruby API
+
+[source,ruby]
+----
+require 'omnizip'
+
+writer = Omnizip::Formats::Zip::Writer.new('backup.zip')
+writer.add_directory('documents/')
+writer.close
+----
+
+=== Using Filters for Executables
+
+BCJ filters improve compression of executable files:
+
+[source,bash]
+----
+omnizip archive create binaries.7z app.exe \
+  --filters bcj_x86
+----
+
+[source,ruby]
+----
+writer = Omnizip::Formats::SevenZip::Writer.new('binaries.7z',
+  filters: [:bcj_x86]
+)
+writer.add_file('app.exe')
+writer.close
+----
+
+=== Creating Multi-Volume Archives
+
+Split large archives into multiple volumes:
+
+[source,bash]
+----
+# Create volumes of 100MB each
+omnizip archive create backup.7z.001 large_data/ \
+  --volume-size 100M
+----
+
+[source,ruby]
+----
+writer = Omnizip::Formats::SevenZip::Writer.new('backup.7z.001',
+  volume_size: 100 * 1024 * 1024
+)
+writer.add_directory('large_data/')
+writer.close
+----
+
+=== Encrypting Archives
+
+Protect your archives with a password:
+
+[source,bash]
+----
+omnizip archive create secure.7z documents/ \
+  --password "MySecurePassword123!"
+----
+
+[source,ruby]
+----
+writer = Omnizip::Formats::SevenZip::Writer.new('secure.7z',
+  password: 'MySecurePassword123!'
+)
+writer.add_directory('documents/')
+writer.close
+----
+
+=== Complete Example
+
+Here's a complete example that creates a backup archive:
+
+[source,ruby]
+----
+require 'omnizip'
+
+# Create encrypted backup with high compression
+writer = Omnizip::Formats::SevenZip::Writer.new('backup.7z',
+  algorithm: :lzma2,
+  level: 7,
+  password: ENV['BACKUP_PASSWORD'],
+  solid: true
+)
+
+# Add directories
+writer.add_directory('/home/user/documents')
+writer.add_directory('/home/user/projects')
+writer.add_directory('/home/user/photos')
+
+# Write the archive
+writer.close
+
+# Get statistics
+entries = Omnizip.list_archive('backup.7z', details: true)
+files = entries.reject { |e| e[:directory] }
+uncompressed = files.sum { |e| e[:size] }
+compressed = File.size('backup.7z')
+puts "Archive created:"
+puts "  Files: #{files.size}"
+puts "  Size: #{uncompressed} bytes"
+puts "  Compressed: #{compressed} bytes"
+puts "  Ratio: #{(compressed.to_f / uncompressed * 100).round(1)}%"
+----
+
+=== Verifying Your Archive
+
+Always verify your archive after creation:
+
+[source,bash]
+----
+omnizip archive list backup.7z
+----
+
+[source,ruby]
+----
+require 'omnizip'
+
+reader = Omnizip::Formats::SevenZip::Reader.new('backup.7z')
+puts "Archive contents:"
+reader.entries.each do |entry|
+  puts "  #{entry.name} (#{entry.size} bytes)"
+end
+----
+
+=== Next Steps
+
+* link:../guides/basic-usage/creating-archives[Creating Archives Guide] - More archive options
+* link:../guides/advanced-usage/solid-compression[Solid Archives] - Better compression for similar files
+* link:../guides/advanced-usage/encryption[Encryption Guide] - Password protection details
+* link:../guides/basic-usage/extracting-archives[Extracting Archives] - How to extract your archives

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

@@ -0,0 +1,277 @@
+---
+title: Encryption
+nav_order: 4
+parent: Advanced Features
+grand_parent: Guides
+---
+
+== Purpose
+
+Protect sensitive data in your archives with industry-standard AES-256 encryption. Omnizip supports multiple encryption methods across different archive formats.
+
+== Benefits
+
+* **Strong Security**: AES-256 encryption with secure key derivation
+* **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
+
+== Encryption Methods
+
+=== AES-256 (7z Format)
+
+The strongest encryption option with header protection:
+
+[source,ruby]
+----
+# Create encrypted 7z archive
+Omnizip::Archive.create(
+  'secure.7z',
+  format: :seven_zip,
+  password: 'MyStr0ngP@ssw0rd',
+  encrypt_headers: true  # Hide filenames
+) do |archive|
+  archive.add_file('confidential.pdf', 'documents/confidential.pdf')
+  archive.add_directory('sensitive_data/')
+end
+----
+
+**Features**:
+
+* AES-256-CBC encryption
+* PBKDF2-HMAC-SHA256 key derivation (524,288 iterations)
+* Optional header encryption (hides filenames)
+* HMAC-SHA-256 authentication
+
+=== ZIP Encryption: not supported
+
+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.
+
+The convenience API raises rather than silently ignoring a
+password for zip:
+
+[source,ruby]
+----
+Omnizip::Archive.create('secure.zip', password: 'x')
+# => Omnizip::UnsupportedFormatError:
+#    password is only supported for seven_zip; :zip has no encryption support
+----
+
+== Decrypting Archives
+
+=== Provide Password at Open
+
+[source,ruby]
+----
+# Decrypt 7z archive
+Omnizip::Archive.open('secure.7z', password: 'MyStr0ngP@ssw0rd') do |archive|
+  archive.extract_all('decrypted/')
+end
+
+# ZIP encryption: Omnizip can neither create nor decrypt
+# password-protected ZIP archives; extract them with 7-Zip/unzip
+----
+
+=== Password via Environment Variable
+
+[source,ruby]
+----
+# Set password in environment
+ENV['OMNIZIP_PASSWORD'] = 'MyStr0ngP@ssw0rd'
+
+# Opens without explicit password parameter
+Omnizip::Archive.open('secure.7z') do |archive|
+  archive.extract_all('output/')
+end
+----
+
+== Password Management
+
+=== Password Strength Validation
+
+Ensure strong passwords before encryption:
+
+[source,ruby]
+----
+validator = Omnizip::PasswordValidator.new(
+  min_length: 12,
+  require_uppercase: true,
+  require_lowercase: true,
+  require_numbers: true,
+  require_special: true
+)
+
+begin
+  validator.validate('weak')
+rescue Omnizip::WeakPasswordError => e
+  puts "Password too weak: #{e.message}"
+  # Password must be at least 12 characters with uppercase, lowercase, numbers, and special characters
+end
+
+# Use validated password
+validator.validate('MyStr0ng!P@ssw0rd2024')  # ✅ Passes
+----
+
+=== Secure Password Input
+
+Prompt for passwords without echo:
+
+[source,ruby]
+----
+require 'io/console'
+
+def get_password
+  print "Enter password: "
+  password = STDIN.noecho(&:gets).chomp
+  puts # New line after password entry
+  password
+end
+
+password = get_password
+Omnizip::Archive.create('secure.7z', password: password) do |archive|
+  # Create encrypted archive
+end
+----
+
+== Security Best Practices
+
+. **Use Strong Passwords**: Minimum 12 characters with mixed case, numbers, and symbols
+. **Prefer 7z Format**: Header encryption hides filenames and structure
+. **Avoid Traditional Encryption**: Use WinZip AES or 7z AES-256 instead
+. **Secure Password Storage**: Never hardcode passwords in source code
+. **Key Derivation**: Use default iterations (524,288) or higher
+. **Test Decryption**: Always verify encrypted archives can be decrypted
+
+== Encryption Comparison
+
+[cols="2,1,1,1,1"]
+|===
+|Feature |7z AES-256 |WinZip AES |Traditional |Recommendation
+
+|**Security Level**
+|Excellent
+|Very Good
+|Weak
+|Use 7z or WinZip AES
+
+|**Header Encryption**
+|✅
+|❌
+|❌
+|7z for privacy
+
+|**Key Derivation**
+|PBKDF2-SHA256
+|PBKDF2-SHA1
+|CRC check
+|Modern algorithms
+
+|**Authentication**
+|HMAC-SHA-256
+|HMAC-SHA-1
+|None
+|Detects tampering
+
+|**Compatibility**
+|7-Zip, PeaZip
+|Most tools
+|Universal
+|Consider audience
+|===
+
+== Command-Line Usage
+
+[source,bash]
+----
+# Create encrypted archive
+omnizip archive create secure.7z files/ \
+  --password 'MyStr0ngP@ssw0rd' \
+  --encrypt-headers
+
+# Extract with password
+omnizip archive extract secure.7z output/ \
+  --password 'MyStr0ngP@ssw0rd'
+
+# Or prompt for password
+omnizip archive create secure.7z files/ --password
+Enter password: ********
+----
+
+== Common Use Cases
+
+=== Protect Sensitive Documents
+
+[source,ruby]
+----
+# Encrypt sensitive files before cloud storage
+Omnizip::Archive.create(
+  'confidential-docs.7z',
+  format: :seven_zip,
+  password: secure_password,
+  encrypt_headers: true,
+  compression: :lzma2,
+  level: 9
+) do |archive|
+  archive.add_directory('contracts/')
+  archive.add_directory('financial-records/')
+end
+
+# Upload to cloud storage
+cloud_storage.upload('confidential-docs.7z')
+----
+
+=== Secure Backups
+
+[source,ruby]
+----
+# Create encrypted backup with timestamp
+timestamp = Time.now.strftime('%Y%m%d_%H%M%S')
+backup_file = "backup_#{timestamp}.7z"
+
+Omnizip::Archive.create(
+  backup_file,
+  format: :seven_zip,
+  password: ENV['BACKUP_PASSWORD'],
+  encrypt_headers: true
+) do |archive|
+  archive.add_directory('/var/www/app/')
+  archive.add_directory('/etc/app-config/')
+end
+----
+
+== Troubleshooting
+
+=== Wrong Password Error
+
+[source,ruby]
+----
+begin
+  Omnizip::Archive.open('secure.7z', password: 'wrong') do |archive|
+    archive.extract_all('output/')
+  end
+rescue Omnizip::DecryptionError => e
+  puts "Incorrect password: #{e.message}"
+end
+----
+
+=== Unsupported Encryption Method
+
+Some older archives may use unsupported encryption:
+
+[source,ruby]
+----
+begin
+  Omnizip::Archive.open('old-archive.7z', password: 'wrong') do |archive|
+    archive.read('secret.txt')
+  end
+rescue Omnizip::FormatError => e
+  puts "Archive damaged or password wrong: #{e.message}"
+end
+----
+
+== See Also
+
+* link:../../compatibility.html[Compatibility] - Encryption support across formats

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

@@ -0,0 +1,59 @@
+---
+title: Advanced Features
+nav_order: 30
+parent: Guides
+has_children: true
+---
+
+== Advanced Features Overview
+
+Omnizip provides several advanced features for power users and production deployments.
+
+== Available Features
+
+[cols="1,3"]
+|===
+|Feature |Description
+
+|link:streaming.html[Streaming Operations]
+|Process archives without loading entire files into memory
+
+|link:parallel-processing.html[Parallel Processing]
+|Leverage multiple CPU cores for faster compression
+
+|link:progress-tracking.html[Progress Tracking]
+|Real-time progress monitoring for long operations
+
+|link:encryption.html[Encryption]
+|AES-256 password protection for archives
+|===
+
+== Feature Combinations
+
+These features can be combined for maximum efficiency:
+
+[source,ruby]
+----
+# 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
+----
+
+== See Also
+
+* link:../compression-algorithms/[Compression Algorithms] - Algorithm-specific features
+* link:../performance-tuning.html[Performance Tuning] - Optimize for your workload

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

@@ -0,0 +1,144 @@
+---
+title: Parallel Processing
+nav_order: 2
+parent: Advanced Features
+grand_parent: Guides
+---
+
+== Purpose
+
+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.
+
+== When It Helps
+
+[cols="1,3"]
+|===
+|Scenario |Approach
+
+|Many archives to compress
+|One process per archive
+
+|Many archives to extract
+|One thread per archive (I/O releases the GVL)
+
+|One large archive
+|No parallelism available; pick an appropriate +level:+
+|===
+
+== Parallel Compression (Processes)
+
+Compression is CPU-bound, so use processes — MRI's GVL prevents
+in-thread parallelism:
+
+[source,ruby]
+----
+# Compress each directory in its own process
+dirs = %w[project_a project_b project_c]
+
+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) }
+----
+
+Or drive the CLI from your shell or job scheduler:
+
+[source,bash]
+----
+ls -d project_*/ | xargs -P 8 -I{} omnizip archive create {}.7z {}
+----
+
+== Parallel Extraction (Threads)
+
+Extracting separate archives is I/O-bound, so threads work:
+
+[source,ruby]
+----
+archives = Dir.glob('downloads/*.zip')
+
+threads = archives.map do |archive|
+  Thread.new do
+    Omnizip.extract_archive(
+      archive,
+      "extracted/#{File.basename(archive, '.zip')}/"
+    )
+  end
+end
+
+threads.each(&:join)
+----
+
+Note: a single archive's extraction still uses one thread.
+
+== Use Cases
+
+=== Server Deployments
+
+[source,ruby]
+----
+# 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
+
+Process multiple archives efficiently:
+
+[source,ruby]
+----
+# Extract multiple archives in parallel
+archives = Dir.glob('downloads/*.zip')
+
+archives.each_slice(4) do |batch|
+  threads = batch.map do |archive|
+    Thread.new do
+      Omnizip.extract_archive(
+        archive,
+        "extracted/#{File.basename(archive, '.zip')}/"
+      )
+    end
+  end
+
+  threads.each(&:join)
+end
+----
+
+== Best Practices
+
+. **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
+
+* 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
+
+`Process.fork` is unavailable on Windows — use `Process.spawn` with
+the +omnizip+ CLI there, or a job scheduler.
+
+== See Also
+
+* link:streaming.html[Streaming] - Memory efficiency
+* link:../compression-algorithms/lzma2.html[LZMA2] - Default 7z algorithm