zip_kit 6.2.2 → 6.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e1136ebba851638486c9e47150a8d706c49a2bbc0074f457c794582d8ce19089
-  data.tar.gz: 80de3edcb5bc748aaf855a7bf0b1f19439522c8efa4b97754f813fe9413bac2c
+  metadata.gz: dcd59b7f9d367a40895c9bac2f909f3e22ebd0a96ee737073ef5153c4d486c70
+  data.tar.gz: 05665ca021d401cad02f80c38d8965c2e5fef1a477317f7ee92246d1c54a21ae
 SHA512:
-  metadata.gz: 20c5922a4178f2068a4f06388b201bd263f01c387d308c2c6297feba1c05385d601072cae0451d59a4a0b4e1ba1e354a6fa7f622ff1b58daf70947e6991b1e82
-  data.tar.gz: c373972ec6980000b40d1808247759b44f317a7aa3795b406e02005412cf0687e0f2311e5809f011eb1fbc19e6b2b7eb2a6a8f036cafe27a2645f6476cf0c441
+  metadata.gz: b13d15a467565ef66ce6a21ac3891e8a26b30246d538c232aca193c3fe24a24a8f3a2d844d48eaeaeeb5ccc2f92cfcaab20e4afa1a2717b89ba27f55bb4635e4
+  data.tar.gz: 29aacf905b670323861812a4aece1446917ac2f94ece22b948f5d2f77a6eb7574c39598177e7c4f33cc230fd863b4f1c02eb961c5b48e4823d40854a25368101

data/.yardopts

@@ -1 +1 @@
---markup markdown
+--markup markdown --no-private --protected lib/**/*.rb - LICENSE.txt IMPLEMENTATION_DETAILS.md RUBYZIP_DIFFERENCES.md CONTRIBUTING.md CODE_OF_CONDUCT.md CHANGELOG.md

data/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 6.3.0
+
+* Include `RailsStreaming` automatically via a Railtie. It is not really necessary to force people to manage it manually.
+
 ## 6.2.2
 
 * Make sure "zlib" gets required at the top, as it is used everywhere

data/CONTRIBUTING.md

@@ -16,7 +16,7 @@ If you are interested in contributing code and would like to learn more about th
 
  - [ruby](https://ruby-doc.org)
  - [rubyzip](https://github.com/rubyzip/rubyzip) as we like to test "our implementation against theirs"
- - [rspec](http://rspec.info/) and [appraisal]() https://github.com/thoughtbot/appraisal) for testing
+ - [rspec](http://rspec.info/) for testing
  - [zip files](https://en.wikipedia.org/wiki/Zip_(file_format))
 
 # How do I make a contribution?

data/IMPLEMENTATION_DETAILS.md

@@ -78,8 +78,8 @@ you can try this:
 
    [Encoding::CP437, Encoding::ISO_8859_1, Encoding::UTF_8]
 
-We don't want no such thing, and sorry Windows users, you are going to need a decent unarchiver
-that honors the standard. Alas, alas.
+While this could work, we found it to be broken in practice as the decoding of the filename
+also depends on the system locale.
 
 Additionally, the tests with the unarchivers we _do_ support have shown that including the InfoZIP
 extra field does not actually help any of them recognize the file name correctly. And the use of

data/README.md

@@ -14,8 +14,13 @@ point. Usable for creating very large ZIP archives for immediate sending out to
 large ZIP archives without memory inflation.
 
 The original gem (zip_tricks) handled all the zipping needs (millions of ZIP files generated per day),
-for a large file transfer service, so we are pretty confident it is widely compatible with a large number
-of unarchiving end-user applications and is well tested.
+for WeTransfer, it is widely compatible with a large number of unarchiving end-user applications.
+
+## How does it work? How is it different from Rubyzip?
+
+Check out [the implementation details](IMPLEMENTATION_DETAILS.md) on the design of the library, and
+we have a separate [reference](RUBYZIP_DIFFERENCES.md) on why you might want to use ZipKit over
+Rubyzip and vice versa.
 
 ## Requirements
 
@@ -23,13 +28,11 @@ Ruby 2.6+ syntax support is required, as well as a a working zlib (all available
 
 ## Diving in: send some large CSV reports from Rails
 
-The easiest is to include the `ZipKit::RailsStreaming` module into your
-controller. You will then have a `zip_kit_stream` method available which accepts a block:
+The included `Railtie` will automatically include `ZipKit::RailsStreaming` into the
+`ActionController::Base` class. You will then have a `zip_kit_stream` method available which accepts a block:
 
 ```ruby
 class ZipsController < ActionController::Base
-  include ZipKit::RailsStreaming
-
   def download
     zip_kit_stream do |zip|
       zip.write_file('report1.csv') do |sink|
@@ -48,6 +51,8 @@ class ZipsController < ActionController::Base
 end
 ```
 
+The block receives the `ZipKit::Streamer` object you can write your files through.
+
 The `write_file` method will use some heuristics to determine whether your output file would benefit
 from compression, and pick the appropriate storage mode for the file accordingly.
 

data/RUBYZIP_DIFFERENCES.md

@@ -0,0 +1,56 @@
+# Key differences between Rubyzip and ZipKit
+
+Please bear in mind that this is written down not to disparage [Rubyzip.](https://github.com/rubyzip/rubyzip)
+
+Rubyzip is, by all means, a very mature, fully featured library, and while ZipKit does have overlap with it in some functionality there are
+differences in supported features which may be important for you when choosing.
+
+## What ZipKit supports and Rubyzip does not
+
+* ZipKit outputs archives in a streaming fashion, using data descriptors.
+  This allows output of archives of very large size, without buffering.
+  Rubyzip will seek in the already written archive to overwrite the local entry after the write of every file into the output ZIP.
+  At the moment, it is difficult to build a streaming Rubyzip solution due to the output of extra field placeholders.
+* ZipKit supports block-deflate which allows for distributed compression of files
+* ZipKit reads files from the central directory, which allows for very rapid reading. Reading works well with data descriptors
+  and Zip64, and is economical enough to enable "remote uncapping" where pieces of a ZIP file get read over HTTP to reconstruct
+  the archive structure. Actual reading can then be done on a per-entry basis. Rubyzip reads entry data from local entries, which
+  is error prone and much less economical than using the central directory
+* ZipKit deliberately _does not_ allow you to crawl directories to add to an archive, as this has been used for security exploits
+  in Rubyzip.
+* ZipKit deliberately _does not_ allow you to extract a ZIP archive directly to the filesystem, as this has been used for security
+  exploits in Rubyzip.
+* When writing, ZipKit applies careful buffering to speed up CRC32 calculations. Rubyzip combines CRC32 values at every write, which
+  can be slow if there are many small writes.
+* ZipKit comes with a Rails helper and a Rack-compatible response body for facilitating streaming. Rubyzip has no Rails integration
+  and no Rack integration.
+* ZipKit allows you to estimate the exact size of an archive ahead of time
+* ZipKit has a heuristic module which picks the storage mode (stored or deflated) depending on how well your input compresses
+* ZipKit requires components using autoloading, which means that your application will likely boot faster as you will almost never
+  need all of the features in one codebase. Rubyzip requires its components eagerly.
+* ZipKit comes with exhaustive YARD documentation and `.rbi` typedefs for [Sorbet/Tapioca](https://sorbet.org/blog/2022/07/27/srb-tapioca)
+
+## What Rubyzip supports and ZipKit does not
+
+* Rubyzip allows limited manipulation of existing ZIP files by overwriting the archive entries
+* Rubyzip supports "classic" ZIP encryption - both for reading and writing. ZipKit has no encryption support.
+* Rubyzip allows extraction into a directory, ZipKit avoids implementing this for security reasons
+* Rubyzip allows archiving a directory, ZipKit avoids implementing this for security reasons
+* Rubyzip supports separate atime and ctime in the `UniversalTime` extra fields. ZipKit outputs just one timestamp
+* Rubyzip attempts to faithfully replicate UNIX permissions on the files being output. ZipKit does not attempt that
+  because it turned out that these permissions can break unarchiving of folders on macOS.
+
+## Where there is currently feature parity
+
+These used to be different, but Rubyzip has made great progress in addressing.
+
+* ZipKit automatically applies the EFS flag for Unicode filenames in the archive. This used to be optional in RubyZip
+* ZipKit automatically enables Zip64 and does so only when necessary. applies the EFS flag for Unicode filenames in the archive. This used to be optional in RubyZip.
+* ZipKit outputs the `UT` precise time extra field
+* ZipKit used to be distributed under the MIT-Hippocratic license which is much more restrictive than the Rubyzip BSD-2-Clause. ZipKit is now MIT-licensed. 
+
+## Code style differences
+
+Rubyzip is written in a somewhat Java-like style, with a lot of encapsulation and data hiding. ZipKit aims to be more approachable and have "less" of everything.
+Less modules, less classes, less OOP - just enough to be useful. But that is a matter of taste, and as such should not matter to you all that much
+when picking one over the other. Or it might, you never know ;-)

data/Rakefile

@@ -11,11 +11,7 @@ task :format do
   `bundle exec magic_frozen_string_literal ./lib`
 end
 
-YARD::Rake::YardocTask.new(:doc) do |t|
-  # The dash has to be between the two to "divide" the source files and
-  # miscellaneous documentation files that contain no code
-  t.files = ["lib/**/*.rb", "-", "LICENSE.txt", "IMPLEMENTATION_DETAILS.md"]
-end
+YARD::Rake::YardocTask.new(:doc)
 RSpec::Core::RakeTask.new(:spec)
 
 task :generate_typedefs do

data/lib/zip_kit/rails_streaming.rb

@@ -3,8 +3,7 @@
 # Should be included into a Rails controller for easy ZIP output from any action.
 module ZipKit::RailsStreaming
   # Opens a {ZipKit::Streamer} and yields it to the caller. The output of the streamer
-  # gets automatically forwarded to the Rails response stream. When the output completes,
-  # the Rails response stream is going to be closed automatically.
+  # will be sent through to the HTTP response body as it gets produced.
   #
   # Note that there is an important difference in how this method works, depending whether
   # you use it in a controller which includes `ActionController::Live` vs. one that does not.
@@ -25,7 +24,7 @@ module ZipKit::RailsStreaming
   # @param use_chunked_transfer_encoding[Boolean] whether to forcibly encode output as chunked. Normally you should not need this.
   # @param output_enumerator_options[Hash] options that will be passed to the OutputEnumerator - these include
   #     options for the Streamer. See {ZipKit::OutputEnumerator#initialize} for the full list of options.
-  # @yieldparam [ZipKit::Streamer] the streamer that can be written to
+  # @yieldparam [ZipKit::Streamer] zip the {ZipKit::Streamer} that can be written to
   # @return [Boolean] always returns true
   def zip_kit_stream(filename: "download.zip", type: "application/zip", use_chunked_transfer_encoding: false, **output_enumerator_options, &zip_streaming_blk)
     # We want some common headers for file sending. Rails will also set

data/lib/zip_kit/railtie.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+class ZipKit::Railtie < ::Rails::Railtie
+  initializer "zip_kit.install_extensions" do |app|
+    ActionController::Base.include(ZipKit::RailsStreaming)
+  end
+end

data/lib/zip_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ZipKit
-  VERSION = "6.2.2"
+  VERSION = "6.3.0"
 end

data/lib/zip_kit.rb

@@ -24,4 +24,6 @@ module ZipKit
   autoload :WriteShovel, File.dirname(__FILE__) + "/zip_kit/write_shovel.rb"
   autoload :RackChunkedBody, File.dirname(__FILE__) + "/zip_kit/rack_chunked_body.rb"
   autoload :RackTempfileBody, File.dirname(__FILE__) + "/zip_kit/rack_tempfile_body.rb"
+
+  require_relative "zip_kit/railtie" if defined?(::Rails)
 end

data/rbi/zip_kit.rbi

@@ -1,6 +1,9 @@
 # typed: strong
 module ZipKit
-  VERSION = T.let("6.2.2", T.untyped)
+  VERSION = T.let("6.3.0", T.untyped)
+
+  class Railtie < Rails::Railtie
+  end
 
   # A ZIP archive contains a flat list of entries. These entries can implicitly
   # create directories when the archive is expanded. For example, an entry with
@@ -1976,8 +1979,7 @@ end, T.untyped)
   # Should be included into a Rails controller for easy ZIP output from any action.
   module RailsStreaming
     # Opens a {ZipKit::Streamer} and yields it to the caller. The output of the streamer
-    # gets automatically forwarded to the Rails response stream. When the output completes,
-    # the Rails response stream is going to be closed automatically.
+    # will be sent through to the HTTP response body as it gets produced.
     # 
     # Note that there is an important difference in how this method works, depending whether
     # you use it in a controller which includes `ActionController::Live` vs. one that does not.
@@ -2008,7 +2010,7 @@ end, T.untyped)
         type: String,
         use_chunked_transfer_encoding: T::Boolean,
         output_enumerator_options: T::Hash[T.untyped, T.untyped],
-        zip_streaming_blk: T.proc.params(the: ZipKit::Streamer).void
+        zip_streaming_blk: T.proc.params(zip: ZipKit::Streamer).void
       ).returns(T::Boolean)
     end
     def zip_kit_stream(filename: "download.zip", type: "application/zip", use_chunked_transfer_encoding: false, **output_enumerator_options, &zip_streaming_blk); end

data/zip_kit.gemspec

@@ -27,7 +27,7 @@ Gem::Specification.new do |spec|
   # zip_kit does not use any runtime dependencies (besides zlib). However, for testing
   # things quite a few things are used - and for a good reason.
 
-  spec.add_development_dependency "rubyzip", "~> 1" # We test our output with _another_ ZIP library, which is the way to go here
+  spec.add_development_dependency "rubyzip", "~> 2" # We test our output with _another_ ZIP library, which is the way to go here
   spec.add_development_dependency "rack" # For tests where we spin up a server. Both for streaming out and for testing reads over HTTP
   spec.add_development_dependency "rake", "~> 12.2"
   spec.add_development_dependency "rspec", "~> 3"
@@ -40,6 +40,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "standard", "1.28.5" # Very specific version of standard for 2.6 with _known_ settings
   spec.add_development_dependency "magic_frozen_string_literal"
   spec.add_development_dependency "puma"
+  spec.add_development_dependency "rails", "~> 5" # For testing RailsStreaming against an actual Rails controller
   spec.add_development_dependency "actionpack", "~> 5" # For testing RailsStreaming against an actual Rails controller
   spec.add_development_dependency "nokogiri", "~> 1", ">= 1.13" # Rails 5 does by mistake use an older Nokogiri otherwise
   spec.add_development_dependency "sinatra"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zip_kit
 version: !ruby/object:Gem::Version
-  version: 6.2.2
+  version: 6.3.0
 platform: ruby
 authors:
 - Julik Tarkhanov
@@ -12,7 +12,7 @@ authors:
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-27 00:00:00.000000000 Z
+date: 2024-04-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -34,14 +34,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1'
+        version: '2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1'
+        version: '2'
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
@@ -216,6 +216,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
 - !ruby/object:Gem::Dependency
   name: actionpack
   requirement: !ruby/object:Gem::Requirement
@@ -298,6 +312,7 @@ files:
 - IMPLEMENTATION_DETAILS.md
 - LICENSE.txt
 - README.md
+- RUBYZIP_DIFFERENCES.md
 - Rakefile
 - bench/buffered_crc32_bench.rb
 - examples/archive_size_estimate.rb
@@ -319,6 +334,7 @@ files:
 - lib/zip_kit/rack_chunked_body.rb
 - lib/zip_kit/rack_tempfile_body.rb
 - lib/zip_kit/rails_streaming.rb
+- lib/zip_kit/railtie.rb
 - lib/zip_kit/remote_io.rb
 - lib/zip_kit/remote_uncap.rb
 - lib/zip_kit/size_estimator.rb
@@ -358,7 +374,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.6
+rubygems_version: 3.0.3
 signing_key:
 specification_version: 4
 summary: Stream out ZIP files from Ruby. Successor to zip_tricks.