rubyzip 2.4.1 → 3.5.0

data/README.md

@@ -2,23 +2,26 @@
 
 [![Gem Version](https://badge.fury.io/rb/rubyzip.svg)](http://badge.fury.io/rb/rubyzip)
 [![Tests](https://github.com/rubyzip/rubyzip/actions/workflows/tests.yml/badge.svg)](https://github.com/rubyzip/rubyzip/actions/workflows/tests.yml)
-[![Code Climate](https://codeclimate.com/github/rubyzip/rubyzip.svg)](https://codeclimate.com/github/rubyzip/rubyzip)
+[![Linter](https://github.com/rubyzip/rubyzip/actions/workflows/lint.yml/badge.svg)](https://github.com/rubyzip/rubyzip/actions/workflows/lint.yml)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
+[![Maintainability](https://qlty.sh/gh/rubyzip/projects/rubyzip/maintainability.svg)](https://qlty.sh/gh/rubyzip/projects/rubyzip)
 [![Coverage Status](https://img.shields.io/coveralls/rubyzip/rubyzip.svg)](https://coveralls.io/r/rubyzip/rubyzip?branch=master)
 
 Rubyzip is a ruby library for reading and writing zip files.
 
-## Important note
+## Important notes
 
-Rubyzip 2.4 is intended to be the last release in the 2.x series. Please get ready for version 3.0.
+### Reporting security issues with this library
+
+If you think you have found a security issue with this library, please don't submit a public issue or PR. Email me directly at hainesr@gmail.com with as much information as you can provide - steps for replication are particularly helpful if you can - and we'll get it sorted ASAP. Thank you.
 
 ### Updating to version 3.0
 
-The public API of some classes has been modernized to use named parameters for optional arguments. Also some methods have been changed or removed. Please check your usage of the following Rubyzip classes:
+The public API of some classes has been modernized to use named parameters for optional arguments. Please check your usage of the following Rubyzip classes:
 * `File`
 * `Entry`
 * `InputStream`
 * `OutputStream`
-* `DOSTime`
 
 **Please see [Updating to version 3.x](https://github.com/rubyzip/rubyzip/wiki/Updating-to-version-3.x) in the wiki for details.**
 
@@ -41,9 +44,12 @@ gem install rubyzip
 Or in your Gemfile:
 
 ```ruby
-gem 'rubyzip'
+gem 'rubyzip', require: 'zip' # For versions before 3.4.
+gem 'rubyzip'                 # For version 3.4 and after.
 ```
 
+From version 3.4 onwards, you can `require` either 'zip' or 'rubyzip' to use this library. Before version 3.4 you need to `require 'zip'` explicitly.
+
 ## Usage
 
 ### Basic zip archive creation
@@ -57,7 +63,7 @@ input_filenames = ['image.jpg', 'description.txt', 'stats.csv']
 
 zipfile_name = "/Users/me/Desktop/archive.zip"
 
-Zip::File.open(zipfile_name, Zip::File::CREATE) do |zipfile|
+Zip::File.open(zipfile_name, create: true) do |zipfile|
   input_filenames.each do |filename|
     # Two arguments:
     # - The name of the file as it will appear in the archive
@@ -68,6 +74,48 @@ Zip::File.open(zipfile_name, Zip::File::CREATE) do |zipfile|
 end
 ```
 
+### Creating a Zip file with `Zip::OutputStream`
+
+```ruby
+require 'rubygems'
+require 'zip'
+
+Zip::OutputStream.open('archive.zip') do |zos|
+  # Quick.
+  zos.put_next_entry('greeting.txt')
+  zos << 'Hello, World!'
+
+  # More control.
+  # You MUST NOT make any calls on your `Entry` after calling `put_next_entry`.
+  entry = Zip::Entry.new(nil, 'parting.txt')
+  entry.atime = Time.now
+  zos.put_next_entry(entry)
+  zos.write('TTFN')
+end
+```
+
+You can generate a Zip archive in memory using `Zip::OutputStream.write_buffer`.
+
+### Suppressing extra fields
+
+If you wish to suppress extra fields from being added to your entries, you can do so by passing the `suppress_extra_fields` parameter to any of the archive opening calls within `Zip::File` or `Zip::OutputStream`, e.g.:
+
+```ruby
+# Suppress all extra fields.
+Zip::File.open('archive.zip', create: true, suppress_extra_fields: true)
+Zip::OutputStream.open('archive.zip', suppress_extra_fields: true)
+
+# Suppress an individual extra field.
+Zip::File.open('archive.zip', create: true, suppress_extra_fields: :zip64)
+Zip::OutputStream.open('archive.zip', suppress_extra_fields: :zip64)
+
+# Suppress multiple extra fields.
+Zip::File.open('archive.zip', create: true, suppress_extra_fields: [:ntfs, :zip64])
+Zip::OutputStream.open('archive.zip', suppress_extra_fields: [:ntfs, :zip64])
+```
+
+Note that there are some extra fields that cannot be suppressed at all (e.g. `:aes`), and some which will only be suppressed if it is safe to do so (e.g. `:zip64`).
+
 ### Zipping a directory recursively
 
 Copy from [here](https://github.com/rubyzip/rubyzip/blob/9d891f7353e66052283562d3e252fe380bb4b199/samples/example_recursive.rb)
@@ -96,7 +144,7 @@ class ZipFileGenerator
   def write
     entries = Dir.entries(@input_dir) - %w[. ..]
 
-    ::Zip::File.open(@output_file, ::Zip::File::CREATE) do |zipfile|
+    ::Zip::File.open(@output_file, create: true) do |zipfile|
       write_entries entries, '', zipfile
     end
   end
@@ -129,9 +177,9 @@ class ZipFileGenerator
 end
 ```
 
-### Save zip archive entries in sorted by name state
+### Save zip archive entries sorted by name
 
-To save zip archives in sorted order like below, you need to set `::Zip.sort_entries` to `true`
+To save zip archives with their entries sorted by name (see below), set `::Zip.sort_entries` to `true`
 
 ```
 Vegetable/
@@ -145,7 +193,7 @@ fruit/mango
 fruit/orange
 ```
 
-After this, entries in the zip archive will be saved in ordered state.
+Opening an existing zip file with this option set will not change the order of the entries automatically. Altering the zip file - adding an entry, renaming an entry, adding or changing the archive comment, etc - will cause the ordering to be applied when closing the file.
 
 ### Default permissions of zip archives
 
@@ -153,7 +201,7 @@ On Posix file systems the default file permissions applied to a new archive
 are (0666 - umask), which mimics the behavior of standard tools such as `touch`.
 
 On Windows the default file permissions are set to 0644 as suggested by the
-[Ruby File documentation](http://ruby-doc.org/core-2.2.2/File.html).
+[Ruby File documentation](https://docs.ruby-lang.org/en/master/File.html#class-file-file-permissions).
 
 When modifying a zip archive the file permissions of the archive are preserved.
 
@@ -181,28 +229,98 @@ Zip::File.open('foo.zip') do |zip_file|
 end
 ```
 
-#### Notice about ::Zip::InputStream
+### Reading a Zip file with `Zip::InputStream`
+
+`Zip::InputStream` can be used for faster reading of zip file content because it does not read the Central directory up front.
+
+There is one exception where it can not work however, and this is if the file does not contain enough information in the local entry headers to extract an entry. This is indicated in an entry by the General Purpose Flag bit 3 being set.
+
+> If bit 3 (0x08) of the general-purpose flags field is set, then the CRC-32 and file sizes are not known when the header is written. The fields in the local header are filled with zero, and the CRC-32 and size are appended in a 12-byte structure (optionally preceded by a 4-byte signature) immediately after the compressed data.
+
+If `Zip::InputStream` finds such an entry in the zip archive it will raise an exception (`Zip::StreamingError`).
+
+`Zip::InputStream` is not designed to be used for random access in a zip file. When performing any operations on an entry that you are accessing via `Zip::InputStream#get_next_entry` then you should complete any such operations before the next call to `get_next_entry`.
+
+```ruby
+Zip::InputStream.open('file.zip') do |zip_stream|
+  while entry = zip_stream.get_next_entry
+    # All required operations on `entry` go here.
+  end
+end # The `InputStream` is closed at the end of the block.
+```
+
+Any attempt to move about in a zip file opened with `Zip::InputStream` could result in the incorrect entry being accessed and/or Zlib buffer errors. If you need random access in a zip file, use `Zip::File`.
 
-`::Zip::InputStream` usable for fast reading zip file content because it not read Central directory.
+### Password Protection (experimental)
 
-But there is one exception when it is not working - General Purpose Flag Bit 3.
+Rubyzip supports reading zip files with AES encryption (version 3.1 and later), and reading and writing zip files with traditional zip encryption (a.k.a. "ZipCrypto"). Encryption is currently only available with the stream API, with either files or buffers, e.g.:
 
-> If bit 3 (0x08) of the general-purpose flags field is set, then the CRC-32 and file sizes are not known when the header is written. The fields in the local header are filled with zero, and the CRC-32 and size are appended in a 12-byte structure (optionally preceded by a 4-byte signature) immediately after the compressed data
+#### Version 2.x (ZipCrypto only)
 
-If `::Zip::InputStream` finds such entry in the zip archive it will raise an exception.
+```ruby
+# Writing.
+enc = Zip::TraditionalEncrypter.new('password')
+buffer = Zip::OutputStream.write_buffer(::StringIO.new(''), enc) do |output|
+  output.put_next_entry("my_file.txt")
+  output.write my_data
+end
 
-### Password Protection (Experimental)
+# Reading.
+dec = Zip::TraditionalDecrypter.new('password')
+Zip::InputStream.open(buffer, 0, dec) do |input|
+  entry = input.get_next_entry
+  puts "Contents of '#{entry.name}':"
+  puts input.read
+end
+```
 
-Rubyzip supports reading/writing zip files with traditional zip encryption (a.k.a. "ZipCrypto"). AES encryption is not yet supported. It can be used with buffer streams, e.g.:
+#### Version 3.x (AES reading and ZipCrypto read/write)
 
 ```ruby
-Zip::OutputStream.write_buffer(::StringIO.new, Zip::TraditionalEncrypter.new('password')) do |out|
-  out.put_next_entry("my_file.txt")
-  out.write my_data
-end.string
+# Reading AES, version 3.1 and later.
+dec = Zip::AESDecrypter.new('password', Zip::AESEncryption::STRENGTH_256_BIT)
+Zip::InputStream.open('aes-encrypted-file.zip', decrypter: dec) do |input|
+  entry = input.get_next_entry
+  puts "Contents of '#{entry.name}':"
+  puts input.read
+end
+
+# Writing.
+enc = Zip::TraditionalEncrypter.new('password')
+buffer = Zip::OutputStream.write_buffer(encrypter: enc) do |output|
+  output.put_next_entry("my_file.txt")
+  output.write my_data
+end
+
+# Reading.
+dec = Zip::TraditionalDecrypter.new('password')
+Zip::InputStream.open(buffer, decrypter: dec) do |input|
+  entry = input.get_next_entry
+  puts "Contents of '#{entry.name}':"
+  puts input.read
+end
 ```
 
-This is an experimental feature and the interface for encryption may change in future versions.
+#### Passing a decrypter to an individual `Entry`
+
+You can also decrypt an `Entry` by passing a decrypter into `Zip::Entry#get_input_stream`. This allows you to decrypt files from a Zip file with different passwords.
+
+```ruby
+Zip::File.open('aes-encrypted-file.zip') do |zip|
+  entries = [['file1.txt', 'password1'], ['file2.txt', 'password2']]
+
+  entries.each do |entry_name, password|
+    entry = zip.find_entry(entry_name)
+    dec = Zip::AESDecrypter.new(password, Zip::AESEncryption::STRENGTH_256_BIT)
+    zis = entry.get_input_stream(decrypter: dec)
+
+    puts "Contents of '#{entry.name}':"
+    puts zis.read
+  end
+end
+```
+
+_This is an evolving feature and the interface for encryption may change in future versions._
 
 ## Known issues
 
@@ -216,7 +334,7 @@ buffer = Zip::OutputStream.write_buffer do |out|
     unless [DOCUMENT_FILE_PATH, RELS_FILE_PATH].include?(e.name)
       out.put_next_entry(e.name)
       out.write e.get_input_stream.read
-     end
+    end
   end
 
   out.put_next_entry(DOCUMENT_FILE_PATH)
@@ -249,7 +367,7 @@ Zip.continue_on_exists_proc = true
 
 ### Non-ASCII Names
 
-If you want to store non-english names and want to open them on Windows(pre 7) you need to set this option:
+To store non-English filenames as UTF-8 (decoded correctly by Windows 7 or later and other modern tools), set this option:
 
 ```ruby
 Zip.unicode_names = true
@@ -271,7 +389,19 @@ Some zip files might have an invalid date format, which will raise a warning. Yo
 Zip.warn_invalid_date = false
 ```
 
-### Size Validation
+### Validating Declared Number of Entries
+
+When reading a zip file it is potentially dangerous to trust what it tells you about how many entries it contains. A malformed zip file could claim a high number of entries in an attempt to waste internal resources, or crash the processing application.
+
+By default rubyzip will warn if the number of declared entries is impossible based on the actual size of the Central Directory headers. You can set this check to raise an error:
+
+```ruby
+Zip.validate_declared_number_of_entries = true
+```
+
+It is likely that the default behaviour for this check will be changed to raise an error in version 4.
+
+### Entry Size Validation
 
 By default (in rubyzip >= 2.0), rubyzip's `extract` method checks that an entry's reported uncompressed size is not (significantly) smaller than its actual size. This is to help you protect your application against [zip bombs](https://en.wikipedia.org/wiki/Zip_bomb). Before `extract`ing an entry, you should check that its size is in the range you expect. For example, if your application supports processing up to 100 files at once, each up to 10MiB, your zip extraction code might look like:
 
@@ -296,25 +426,37 @@ Zip.validate_entry_sizes = false
 
 Note that if you use the lower level `Zip::InputStream` interface, `rubyzip` does *not* check the entry `size`s. In this case, the caller is responsible for making sure it does not read more data than expected from the input stream.
 
-### Default Compression
+### Compression level
 
-You can set the default compression level like so:
+When adding entries to a zip archive you can set the compression level to trade-off compressed size against compression speed. By default this is set to the same as the underlying Zlib library's default (`Zlib::DEFAULT_COMPRESSION`), which is somewhere in the middle.
+
+You can configure the default compression level with:
 
 ```ruby
-Zip.default_compression = Zlib::DEFAULT_COMPRESSION
+Zip.default_compression = X
 ```
 
-It defaults to `Zlib::DEFAULT_COMPRESSION`. Possible values are `Zlib::BEST_COMPRESSION`, `Zlib::DEFAULT_COMPRESSION` and `Zlib::NO_COMPRESSION`
+Where X is an integer between 0 and 9, inclusive. If this option is set to 0 (`Zlib::NO_COMPRESSION`) then entries will be stored in the zip archive uncompressed. A value of 1 (`Zlib::BEST_SPEED`) gives the fastest compression and 9 (`Zlib::BEST_COMPRESSION`) gives the smallest compressed file size.
+
+This can also be set for each archive as an option to `Zip::File`:
+
+```ruby
+Zip::File.open('foo.zip', create:true, compression_level: 9) do |zip|
+  zip.add ...
+end
+```
 
 ### Zip64 Support
 
-By default, Zip64 support is disabled for writing. To enable it do this:
+Since version 3.0, Zip64 support is enabled for writing by default. To disable it do this:
 
 ```ruby
-Zip.write_zip64_support = true
+Zip.write_zip64_support = false
 ```
 
-_NOTE_: If you will enable Zip64 writing then you will need zip extractor with Zip64 support to extract archive.
+Prior to version 3.0, Zip64 support is disabled for writing by default.
+
+_NOTE_: If Zip64 write support is enabled then any extractor subsequently used may also require Zip64 support to read from the resultant archive.
 
 ### Block Form
 
@@ -329,15 +471,51 @@ You can set multiple settings at the same time by using a block:
   end
 ```
 
+## Compatibility
+
+Rubyzip is known to run on a number of platforms and under a number of different Ruby versions.
+
+### Version 2.4.x
+
+Rubyzip 2.4 is known to work on MRI 2.4 to 3.4 on Linux and Mac, and JRuby and Truffleruby on Linux. There are known issues with Windows which have been fixed on the development branch. Please [let us know](https://github.com/rubyzip/rubyzip/pulls) if you know Rubyzip 2.4 works on a platform/Ruby combination not listed here, or [raise an issue](https://github.com/rubyzip/rubyzip/issues) if you see a failure where we think it should work.
+
+### Version 3.x
+
+Please see the table below for what we think the current situation is. Note: an empty cell means "unknown", not "does not work".
+
+| OS/Ruby | 3.0 | 3.1 | 3.2 | 3.3 | 3.4 | 4.0 | Head | JRuby 10.0.1.0 | JRuby Head | Truffleruby 34.0.1 | Truffleruby Head |
+|---------|-----|-----|-----|-----|-----|-----|------|----------------|------------|-------------------|------------------|
+|Ubuntu 24.04| CI | CI | CI | CI | CI | CI | ci | CI | ci | CI | ci |
+|Mac OS 15.7.7| CI | x | x | CI | CI | CI | ci | x |  | x |  |
+|Windows Server 2022| CI |  |  |  |  |  |  |  |  |  |  |
+|Windows Server 2025|  |  |  | CI |  | CI | CI&nbsp;mswin</br>CI&nbsp;ucrt |  |  |  |  |
+
+Key: `CI` - tested in CI, should work; `ci` - tested in CI, might fail; `x` - known working; `o` - known failing.
+
+Rubies 3.1+ are also tested separately with YJIT turned on (Ubuntu and Mac OS).
+
+See [the Actions tab](https://github.com/rubyzip/rubyzip/actions) in GitHub for full details.
+
+Please [raise a PR](https://github.com/rubyzip/rubyzip/pulls) if you know Rubyzip works on a platform/Ruby combination not listed here, or [raise an issue](https://github.com/rubyzip/rubyzip/issues) if you see a failure where we think it should work.
+
 ## Developing
 
-To run the test you need to do this:
+Install the dependencies:
 
-```
+```shell
 bundle install
+```
+
+Run the tests with `rake`:
+
+```shell
 rake
 ```
 
+Please also run `rubocop` over your changes.
+
+Our CI runs on [GitHub Actions](https://github.com/rubyzip/rubyzip/actions). Please note that `rubocop` is run as part of the CI configuration and will fail a build if errors are found.
+
 ## Website and Project Home
 
 http://github.com/rubyzip/rubyzip
@@ -346,17 +524,18 @@ http://rdoc.info/github/rubyzip/rubyzip/master/frames
 
 ## Authors
 
-Alexander Simonov ( alex at simonov.me)
+See https://github.com/rubyzip/rubyzip/graphs/contributors for a comprehensive list.
 
-Alan Harper ( alan at aussiegeek.net)
+### Current maintainers
 
-Thomas Sondergaard (thomas at sondergaard.cc)
+* Robert Haines (@hainesr)
+* John Lees-Miller (@jdleesmiller)
+* Oleksandr Simonov (@simonoff)
 
-Technorama Ltd. (oss-ruby-zip at technorama.net)
+### Original author
 
-extra-field support contributed by Tatsuki Sugiura (sugi at nemui.org)
+* Thomas Sondergaard
 
 ## License
 
-Rubyzip is distributed under the same license as ruby. See
-http://www.ruby-lang.org/en/LICENSE.txt
+Rubyzip is distributed under the same license as Ruby. In practice this means you can use it under the terms of the Ruby License or the 2-Clause BSD License. See https://www.ruby-lang.org/en/about/license.txt and LICENSE.md for details.

data/Rakefile

@@ -1,21 +1,23 @@
+# frozen_string_literal: true
+
 require 'bundler/gem_tasks'
-require 'rake/testtask'
+require 'minitest/test_task'
+require 'rdoc/task'
 require 'rubocop/rake_task'
 
 task default: :test
 
-Rake::TestTask.new(:test) do |test|
-  test.libs << 'lib'
-  test.libs << 'test'
-  test.pattern = 'test/**/*_test.rb'
-  test.verbose = true
+Minitest::TestTask.create do |test|
+  test.framework = 'require "simplecov"'
+  test.test_globs = 'test/**/*_test.rb'
 end
 
-RuboCop::RakeTask.new
+RDoc::Task.new do |rdoc|
+  rdoc.main = 'README.md'
+  rdoc.rdoc_files.include('README.md', 'lib/**/*.rb')
+  rdoc.options << '--markup=markdown'
+  rdoc.options << '--tab-width=2'
+  rdoc.options << "-t Rubyzip version #{Zip::VERSION}"
+end
 
-# Rake::TestTask.new(:zip64_full_test) do |test|
-#  test.libs << File.join(File.dirname(__FILE__), 'lib')
-#  test.libs << File.join(File.dirname(__FILE__), 'test')
-#  test.pattern = File.join(File.dirname(__FILE__), 'test/zip64_full_test.rb')
-#  test.verbose = true
-# end
+RuboCop::RakeTask.new

data/lib/rubyzip.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative 'zip'