omnizip 0.3.1

data/lib/omnizip/formats/rar/rar5/models/encryption_options.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+begin
+  require "lutaml/model"
+rescue LoadError, ArgumentError
+  # lutaml-model not available, using simple classes
+end
+
+module Omnizip
+  module Formats
+    module Rar
+      module Rar5
+        module Models
+          # Encryption options for RAR5 archives
+          #
+          # This model configures password-based encryption using
+          # AES-256-CBC with PBKDF2-HMAC-SHA256 key derivation.
+          #
+          # @example Enable encryption with default settings
+          #   options = EncryptionOptions.new(
+          #     enabled: true,
+          #     password: "SecurePassword123"
+          #   )
+          #
+          # @example Custom KDF iterations
+          #   options = EncryptionOptions.new(
+          #     enabled: true,
+          #     password: "SecurePassword123",
+          #     kdf_iterations: 524_288  # 2^19, higher security
+          #   )
+          class EncryptionOptions < Lutaml::Model::Serializable
+            # Enable encryption (default: false)
+            attribute :enabled, :boolean, default: false
+
+            # Encryption password
+            attribute :password, :string, default: nil
+
+            # PBKDF2 iteration count (default: 262,144 = 2^18)
+            attribute :kdf_iterations, :integer, default: 262_144
+
+            # Validate options
+            #
+            # @raise [ArgumentError] If validation fails
+            def validate!
+              if enabled? && (password.nil? || password.empty?)
+                raise ArgumentError,
+                      "Password required when encryption is enabled"
+              end
+
+              if kdf_iterations < 65_536 || kdf_iterations > 1_048_576
+                raise ArgumentError,
+                      "KDF iterations must be between 65,536 and 1,048,576"
+              end
+            end
+
+            # Check if encryption is enabled
+            #
+            # @return [Boolean] true if enabled
+            def enabled?
+              enabled == true
+            end
+
+            # Check if password is set
+            #
+            # @return [Boolean] true if password provided
+            def has_password?
+              !password.nil? && !password.empty?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/formats/rar/rar5/models/recovery_options.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+begin
+  require "lutaml/model"
+rescue LoadError, ArgumentError
+  # lutaml-model not available, using simple classes
+end
+
+module Omnizip
+  module Formats
+    module Rar
+      module Rar5
+        module Models
+          # Recovery (PAR2) options for RAR5 archives
+          #
+          # This model configures PAR2 parity file generation for error
+          # correction and recovery of corrupted or missing archive data.
+          #
+          # @example Enable recovery with default settings
+          #   options = RecoveryOptions.new(enabled: true)
+          #
+          # @example Custom redundancy percentage
+          #   options = RecoveryOptions.new(
+          #     enabled: true,
+          #     redundancy: 10  # 10% redundancy
+          #   )
+          class RecoveryOptions < Lutaml::Model::Serializable
+            # Enable PAR2 recovery (default: false)
+            attribute :enabled, :boolean, default: false
+
+            # Redundancy percentage (0-100, default: 5)
+            attribute :redundancy, :integer, default: 5
+
+            # Block size for PAR2 (default: 16384)
+            attribute :block_size, :integer, default: 16_384
+
+            # Validate options
+            #
+            # @raise [ArgumentError] If validation fails
+            def validate!
+              if redundancy.negative? || redundancy > 100
+                raise ArgumentError,
+                      "Redundancy must be 0-100, got #{redundancy}"
+              end
+
+              if block_size <= 0 || (block_size % 4) != 0
+                raise ArgumentError,
+                      "Block size must be positive and divisible by 4"
+              end
+            end
+
+            # Check if recovery is enabled
+            #
+            # @return [Boolean] true if enabled
+            def enabled?
+              enabled == true
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/formats/rar/rar5/models/solid_options.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+begin
+  require "lutaml/model"
+rescue LoadError, ArgumentError
+  # lutaml-model not available, using simple classes
+end
+
+module Omnizip
+  module Formats
+    module Rar
+      module Rar5
+        module Models
+          # Solid compression options
+          #
+          # This model configures solid compression behavior, including
+          # whether to enable solid mode and block size limits.
+          #
+          # @example Enable solid compression
+          #   options = SolidOptions.new(enabled: true)
+          #
+          # @example Configure solid block size
+          #   options = SolidOptions.new(enabled: true, max_block_size: 100 * 1024 * 1024)
+          class SolidOptions < Lutaml::Model::Serializable
+            # Enable solid compression (default: false)
+            attribute :enabled, :boolean, default: false
+
+            # Maximum solid block size in bytes (default: unlimited)
+            # When set, files are grouped into blocks not exceeding this size
+            attribute :max_block_size, :integer, default: nil
+
+            # Whether to split by file extension (default: false)
+            # When true, files with different extensions use separate solid blocks
+            attribute :split_by_extension, :boolean, default: false
+
+            # Validate options
+            #
+            # @raise [ArgumentError] if max_block_size is too small
+            def validate!
+              if max_block_size && max_block_size < 1_048_576 # 1 MB minimum
+                raise ArgumentError, "Solid block size must be at least 1 MB"
+              end
+            end
+
+            # Check if solid compression is enabled
+            #
+            # @return [Boolean] true if enabled
+            def enabled?
+              enabled == true
+            end
+
+            # Check if block size is limited
+            #
+            # @return [Boolean] true if max_block_size set
+            def block_size_limited?
+              !max_block_size.nil?
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/formats/rar/rar5/models/volume_options.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+begin
+  require "lutaml/model"
+rescue LoadError, ArgumentError
+  # lutaml-model not available, using simple classes
+end
+
+module Omnizip
+  module Formats
+    module Rar
+      module Rar5
+        module Models
+          # Volume options for multi-volume archives
+          #
+          # This model configures split archive behavior, including
+          # maximum volume size and naming convention.
+          #
+          # @example Create with default options
+          #   options = VolumeOptions.new
+          #   options.max_volume_size # => 104857600 (100 MB)
+          #
+          # @example Create with custom size
+          #   options = VolumeOptions.new(max_volume_size: 10 * 1024 * 1024)
+          #   options.max_volume_size # => 10485760 (10 MB)
+          class VolumeOptions < Lutaml::Model::Serializable
+            # Maximum size per volume in bytes (default: 100 MB)
+            attribute :max_volume_size, :integer, default: 104_857_600
+
+            # Volume naming pattern (default: 'part')
+            # Results in: archive.part1.rar, archive.part2.rar, etc.
+            attribute :volume_naming, :string, default: "part"
+
+            # Validate options
+            #
+            # @raise [ArgumentError] if max_volume_size is too small
+            def validate!
+              if max_volume_size < 65_536 # 64 KB minimum
+                raise ArgumentError, "Volume size must be at least 64 KB"
+              end
+            end
+
+            # Parse human-readable size string
+            #
+            # @param size_str [String] Size with suffix (e.g., "10M", "1G")
+            # @return [Integer] Size in bytes
+            def self.parse_size(size_str)
+              return size_str if size_str.is_a?(Integer)
+
+              match = size_str.match(/^(\d+(?:\.\d+)?)\s*([KMGT])?$/i)
+              unless match
+                raise ArgumentError,
+                      "Invalid size format: #{size_str}"
+              end
+
+              value = match[1].to_f
+              suffix = match[2]&.upcase
+
+              multiplier = case suffix
+                           when "K" then 1024
+                           when "M" then 1024**2
+                           when "G" then 1024**3
+                           when "T" then 1024**4
+                           else 1
+                           end
+
+              (value * multiplier).to_i
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnizip/formats/rar/rar5/multi_volume/ARCHITECTURE.md

@@ -0,0 +1,290 @@
+# Multi-Volume Archive Architecture
+
+## Overview
+
+The multi-volume archive feature enables splitting large RAR5 archives into multiple smaller volume files. This is essential for distributing large datasets across size-constrained media or network uploads.
+
+## Key Components
+
+### 1. VolumeOptions Model
+**File**: [`models/volume_options.rb`](../models/volume_options.rb)
+
+**Purpose**: Configuration for multi-volume archives using Lutaml::Model
+
+**Attributes**:
+- `max_volume_size` (Integer): Maximum size per volume in bytes (default: 100 MB)
+- `volume_naming` (String): Naming pattern - "part", "volume", or "numeric"
+
+**Key Methods**:
+- `validate!`: Ensures volume size >= 64 KB minimum
+- `parse_size(str)`: Converts "10M", "1G" to bytes
+
+### 2. VolumeSplitter
+**File**: [`volume_splitter.rb`](volume_splitter.rb)
+
+**Purpose**: Handles data splitting logic and file distribution calculation
+
+**Responsibilities**:
+- Calculate optimal file distribution across volumes
+- Track volume boundaries and remaining space
+- Ensure atomic file placement (no mid-file splits in v0.5.0)
+- Reserve header overhead (1 KB per volume)
+
+**Key Methods**:
+- `can_fit_in_current_volume?(size)`: Check space availability
+- `calculate_file_distribution(files)`: Optimize file placement
+- `needs_splitting?(total, max)`: Determine if splitting required
+
+**Algorithm**:
+```
+For each file:
+  If file fits in current volume with headers:
+    Add to current volume
+  Else:
+    Finalize current volume
+    Start new volume with this file
+Return: Array of volume assignments
+```
+
+### 3. VolumeWriter
+**File**: [`volume_writer.rb`](volume_writer.rb)
+
+**Purpose**: Write individual .rar volume files with proper headers
+
+**Responsibilities**:
+- Write RAR5 signature to each volume
+- Add volume-specific Main header flags
+- Write file entries
+- Add End header with continuation flags
+
+**RAR5 Volume Flags**:
+```ruby
+# Main header
+VOLUME_ARCHIVE_FLAG = 0x0001  # Indicates multi-volume archive
+VOLUME_NUMBER_FLAG  = 0x0002  # Volume number in extra area
+
+# End header
+VOLUME_END_FLAG = 0x0001  # More volumes follow (not last)
+```
+
+**Volume Naming**:
+- **part**: `archive.part1.rar`, `archive.part2.rar`, ... (default)
+- **volume**: `archive.vol1.rar`, `archive.vol2.rar`, ...
+- **numeric**: `archive.rar`, `archive.r00`, `archive.r01`, ...
+
+### 4. VolumeManager
+**File**: [`volume_manager.rb`](volume_manager.rb)
+
+**Purpose**: Coordinate entire multi-volume archive creation
+
+**Responsibilities**:
+- Accept file additions
+- Compress all files upfront
+- Calculate optimal volume distribution
+- Delegate to VolumeWriter for each volume
+- Return array of created volume paths
+
+**Workflow**:
+```
+1. User adds files via add_file() or add_directory()
+2. User calls create_volumes()
+3. Manager compresses all files
+4. Calculate file distribution across volumes
+5. For each volume:
+   a. Create VolumeWriter
+   b. Write signature + main header
+   c. Write assigned file entries
+   d. Write end header
+6. Return volume paths
+```
+
+## Integration with Existing Writer
+
+The [`Writer`](../writer.rb) class is enhanced with multi-volume support:
+
+**New Options**:
+- `multi_volume: true` - Enable multi-volume mode
+- `volume_size: Integer` - Maximum volume size (accepts human-readable)
+
+**API**:
+```ruby
+# Single archive (existing)
+writer = Writer.new('archive.rar', compression: :lzma)
+writer.add_file('file.txt')
+writer.write
+
+# Multi-volume (new)
+writer = Writer.new('archive.rar',
+  multi_volume: true,
+  volume_size: '10M',  # or 10_485_760
+  compression: :lzma
+)
+writer.add_file('largefile.dat')
+writer.write  # Returns: ['archive.part1.rar', 'archive.part2.rar', ...]
+```
+
+**Implementation Strategy**:
+- Check `multi_volume` option in `write()`
+- If enabled, delegate to VolumeManager
+- If disabled, use existing single-file logic
+- Clean separation - no complex conditionals
+
+## Data Flow
+
+### Single Archive (Existing)
+```
+Files → Writer → Compress → Single .rar file
+```
+
+### Multi-Volume Archive (New)
+```
+Files → Writer (multi_volume=true)
+         ↓
+      VolumeManager
+         ↓
+      Compress all files
+         ↓
+      VolumeSplitter (calculate distribution)
+         ↓
+      For each volume:
+        VolumeWriter → part1.rar, part2.rar, ...
+```
+
+## Volume Format Specification
+
+### Volume File Structure
+```
+Volume 1 (archive.part1.rar):
+  [RAR5 Signature: 8 bytes]
+  [Main Header: VOLUME_ARCHIVE_FLAG set]
+  [File1 Header + Data]
+  [File2 Header + Data]
+  ...
+  [End Header: VOLUME_END_FLAG set]
+
+Volume 2 (archive.part2.rar):
+  [RAR5 Signature: 8 bytes]
+  [Main Header: VOLUME_ARCHIVE_FLAG + VOLUME_NUMBER_FLAG]
+  [File5 Header + Data]
+  ...
+  [End Header: VOLUME_END_FLAG set]
+
+Last Volume (archive.partN.rar):
+  [RAR5 Signature: 8 bytes]
+  [Main Header: VOLUME_ARCHIVE_FLAG + VOLUME_NUMBER_FLAG]
+  [FileX Header + Data]
+  ...
+  [End Header: VOLUME_END_FLAG NOT set]
+```
+
+## Limitations (v0.5.0)
+
+1. **No File Spanning**: Individual files cannot span multiple volumes
+   - Large files must fit in a single volume
+   - Trade-off: Simplicity vs flexibility
+   - Future: Implement file spanning in v0.6.0+
+
+2. **Sequential Creation**: Volumes created sequentially, not in parallel
+   - Simpler implementation
+   - Future: Parallel volume writing with Ractors
+
+3. **Fixed Boundaries**: Volume splits at file boundaries only
+   - Predictable behavior
+   - May result in inefficient space usage
+
+## Testing Strategy
+
+### Unit Tests
+- VolumeOptions: Validation, size parsing
+- VolumeSplitter: Distribution algorithm, space calculation
+- VolumeWriter: Header generation, filename creation
+- VolumeManager: File preparation, volume coordination
+
+### Integration Tests
+- Small archive (< volume size): Single volume
+- Large archive (> volume size): Multiple volumes
+- Many small files: Optimal distribution
+- Few large files: One per volume
+- Round-trip: Extract with unrar, verify integrity
+
+### Compatibility Tests
+- Extract with official unrar
+- Extract with 7-Zip
+- Verify all volume flags correct
+- Verify volume sequence correct
+
+## Performance Considerations
+
+### Memory Usage
+- All files compressed before splitting → Memory = sum of compressed sizes
+- For 100 MB archives, reasonable memory footprint
+- Future: Streaming compression for > 1 GB archives
+
+### Disk I/O
+- Sequential writes to multiple files
+- No random access required
+- Single pass through data
+
+### Optimization Opportunities
+1. Parallel compression of files (Ractors)
+2. Streaming compression to reduce memory
+3. Intelligent file ordering (similar files together for solid compression)
+
+## Error Handling
+
+### Volume Size Too Small
+```ruby
+VolumeOptions#validate!
+# Raises ArgumentError if < 64 KB
+```
+
+### File Too Large
+```ruby
+VolumeSplitter#calculate_file_distribution
+# Places large file in dedicated volume
+# Logs warning if file > max_volume_size
+```
+
+### Disk Space Exhausted
+```ruby
+VolumeWriter#write
+# Standard Ruby File I/O exceptions propagate
+# Partial volumes cleaned up on failure (future)
+```
+
+## Future Enhancements (Post-v0.5.0)
+
+1. **File Spanning**: Split large files across volumes
+2. **Parallel Processing**: Compress files in parallel
+3. **Streaming Mode**: Compress directly to volumes
+4. **Resume Support**: Continue interrupted volume creation
+5. **Volume Verification**: CRC checks for each volume
+6. **Automatic Recovery**: Generate PAR2 for each volume
+
+## References
+
+- RAR5 Format Specification: https://www.rarlab.com/technote.htm
+- RAR Volume Format Details: Section 4.3
+- Volume Header Flags: Section 3.1
+
+## Design Decisions
+
+### Why Upfront Compression?
+**Decision**: Compress all files before splitting
+**Rationale**: Need exact compressed size to calculate distribution
+**Trade-off**: Higher memory usage vs accurate splitting
+
+### Why Atomic Files?
+**Decision**: No file spanning in v0.5.0
+**Rationale**: Simpler implementation, faster delivery
+**Trade-off**: Potential wasted space vs implementation complexity
+
+### Why Sequential Writing?
+**Decision**: Write volumes one at a time
+**Rationale**: Simpler error handling, predictable behavior
+**Trade-off**: Slower for very large archives vs complexity
+
+### Why Lutaml::Model?
+**Decision**: Use Lutaml::Model for VolumeOptions
+**Rationale**: Consistent with project architecture, serialization support
+**Benefit**: YAML/JSON configuration files for volume settings