zip_tricks 4.4.2 → 4.5.0

data/lib/zip_tricks/file_reader/inflating_reader.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# Rubocop: convention: Missing top-level class documentation comment.
 class ZipTricks::FileReader::InflatingReader
   def initialize(from_io, compressed_data_size)
     @io = from_io
@@ -6,7 +9,7 @@ class ZipTricks::FileReader::InflatingReader
     @zlib_inflater = ::Zlib::Inflate.new(-Zlib::MAX_WBITS)
   end
 
-  def extract(n_bytes=nil)
+  def extract(n_bytes = nil)
     n_bytes ||= (@compressed_data_size - @already_read)
 
     return if eof?

data/lib/zip_tricks/file_reader/stored_reader.rb

@@ -1,3 +1,6 @@
+# frozen_string_literal: true
+
+# Rubocop: convention: Missing top-level class documentation comment.
 class ZipTricks::FileReader::StoredReader
   def initialize(from_io, compressed_data_size)
     @io = from_io
@@ -5,7 +8,7 @@ class ZipTricks::FileReader::StoredReader
     @already_read = 0
   end
 
-  def extract(n_bytes=nil)
+  def extract(n_bytes = nil)
     n_bytes ||= (@compressed_data_size - @already_read)
 
     return if eof?

data/lib/zip_tricks/null_writer.rb

@@ -1,12 +1,12 @@
+# frozen_string_literal: true
+
 # Used when you need to supply a destination IO for some
 # write operations, but want to discard the data (like when
 # estimating the size of a ZIP)
 module ZipTricks::NullWriter
   # @param data[String] the data to write
   # @return [self]
-  def self.<<(data); self; end
-  
-  # @param data[String] the data to write
-  # @return [Fixnum] the amount of data that was supposed to be written
-  def self.write(data); data.bytesize; end
+  def self.<<(_)
+    self
+  end
 end

data/lib/zip_tricks/rack_body.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Can be used as a Rack response body directly. Will yield
 # a {ZipTricks::Streamer} for adding entries to the archive and writing
 # zip entry bodies.
@@ -13,14 +15,16 @@ class ZipTricks::RackBody
   #       estimator.add_stored_entry(filename: 'large.tif', size: 1289894)
   #     end
   #
-  #     # Prepare the response body. The block will only be called when the response starts to be written.
+  #     # Prepare the response body. The block will only be called when the
+  #       response starts to be written.
   #     body = ZipTricks::RackBody.new do | streamer |
   #       streamer.add_stored_entry(filename: 'large.tif', size: 1289894, crc32: 198210)
   #       streamer << large_file.read(1024*1024) until large_file.eof?
   #       ...
   #     end
   #
-  #     return [200, {'Content-Type' => 'binary/octet-stream', 'Content-Length' => content_length.to_s}, body]
+  #     return [200, {'Content-Type' => 'binary/octet-stream',
+  #     'Content-Length' => content_length.to_s}, body]
   def initialize(&blk)
     @archiving_block = blk
   end
@@ -36,6 +40,5 @@ class ZipTricks::RackBody
   # Does nothing because nothing has to be deallocated or canceled
   # even if the zip output is incomplete. The archive gets closed
   # automatically as part of {ZipTricks::Streamer.open}
-  def close
-  end
+  def close; end
 end

data/lib/zip_tricks/rails_streaming.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Should be included into a Rails controller (together with `ActionController::Live`)
 # for easy ZIP output from any action.
 module ZipTricks::RailsStreaming
@@ -10,7 +12,7 @@ module ZipTricks::RailsStreaming
     # Create a wrapper for the write call that quacks like something you
     # can << to, used by ZipTricks
     w = ZipTricks::BlockWrite.new { |chunk| response.stream.write(chunk) }
-    ZipTricks::Streamer.open(w){|z| yield(z) }
+    ZipTricks::Streamer.open(w) { |z| yield(z) }
   ensure
     response.stream.close
   end

data/lib/zip_tricks/remote_io.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # An object that fakes just-enough of an IO to be dangerous
 # - or, more precisely, to be useful as a source for the FileReader
 # central directory parser. Effectively we substitute an IO object
@@ -20,23 +22,25 @@ class ZipTricks::RemoteIO
     @pos = clamp(0, offset, @remote_size)
     0 # always return 0!
   end
-  
+
   # Emulates IO#size.
   #
   # @return [Fixnum] the size of the remote resource
   def size
     @remote_size ||= request_object_size
   end
-  
+
   # Emulates IO#read, but requires the number of bytes to read
   # The read will be limited to the
   # size of the remote resource relative to the current offset in the IO,
   # so if you are at offset 0 in the IO of size 10, doing a `read(20)`
-  # will only return you 10 bytes of result, and not raise any exceptions. 
+  # will only return you 10 bytes of result, and not raise any exceptions.
   #
   # @param n_bytes[Fixnum, nil] how many bytes to read, or `nil` to read all the way to the end
   # @return [String] the read bytes
-  def read(n_bytes=nil)
+  # Rubocop: convention: Assignment Branch Condition size for read is too high. [17.92/15]
+  # Rubocop: convention: Method has too many lines. [13/10]
+  def read(n_bytes = nil)
     @remote_size ||= request_object_size
 
     # If the resource is empty there is nothing to read
@@ -87,7 +91,7 @@ class ZipTricks::RemoteIO
 
   private
 
-  def clamp(a,b,c)
+  def clamp(a, b, c)
     return a if b < a
     return c if b > c
     b

data/lib/zip_tricks/remote_uncap.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Alows reading the central directory of a remote ZIP file without
 # downloading the entire file. The central directory provides the
 # offsets at which the actual file contents is located. You can then
@@ -6,12 +8,15 @@
 # Please read the security warning in `FileReader` _VERY CAREFULLY_
 # before you use this module.
 class ZipTricks::RemoteUncap
-
-  # @param uri[String] the HTTP(S) URL to read the ZIP footer from 
+  # @param uri[String] the HTTP(S) URL to read the ZIP footer from
   # @param reader_class[Class] which class to use for reading
-  # @param options_for_zip_reader[Hash] any additional options to give to {ZipTricks::FileReader} when reading
-  # @return [Array<ZipTricks::FileReader::ZipEntry>] metadata about the files within the remote archive
-  def self.files_within_zip_at(uri, reader_class: ZipTricks::FileReader, **options_for_zip_reader)
+  # @param options_for_zip_reader[Hash] any additional options to give to
+  # {ZipTricks::FileReader} when reading
+  # @return [Array<ZipTricks::FileReader::ZipEntry>] metadata about the
+  # files within the remote archive
+  def self.files_within_zip_at(uri,
+                               reader_class: ZipTricks::FileReader,
+                               **options_for_zip_reader)
     fetcher = new(uri)
     fake_io = ZipTricks::RemoteIO.new(fetcher)
     reader = reader_class.new

data/lib/zip_tricks/size_estimator.rb

@@ -1,48 +1,50 @@
+# frozen_string_literal: true
+
 # Helps to estimate archive sizes
 class ZipTricks::SizeEstimator
   require_relative 'streamer'
-  
-  # Used to mark a couple of methods public
-  class DetailStreamer < ::ZipTricks::Streamer
-    public :add_file_and_write_local_header, :write_data_descriptor_for_last_entry
-  end
-  private_constant :DetailStreamer
-  
+
   # Creates a new estimator with a Streamer object. Normally you should use
   # `estimate` instead an not use this method directly.
   def initialize(streamer)
     @streamer = streamer
   end
   private :initialize
-  
+
   # Performs the estimate using fake archiving. It needs to know the sizes of the
   # entries upfront. Usage:
   #
   #     expected_zip_size = SizeEstimator.estimate do | estimator |
   #       estimator.add_stored_entry(filename: "file.doc", size: 898291)
-  #       estimator.add_compressed_entry(filename: "family.tif", uncompressed_size: 89281911, compressed_size: 121908)
+  #       estimator.add_deflated_entry(filename: "family.tif",
+  #               uncompressed_size: 89281911, compressed_size: 121908)
   #     end
   #
-  # @return [Fixnum] the size of the resulting archive, in bytes
+  # @return [Integer] the size of the resulting archive, in bytes
   # @yield [SizeEstimator] the estimator
   def self.estimate
-    output_io = ZipTricks::WriteAndTell.new(ZipTricks::NullWriter)
-    DetailStreamer.open(output_io) { |zip| yield(new(zip)) }
-    output_io.tell
+    streamer = ZipTricks::Streamer.new(ZipTricks::NullWriter)
+    estimator = new(streamer)
+    yield(estimator)
+    streamer.close # Returns the .tell of the contained IO
   end
 
   # Add a fake entry to the archive, to see how big it is going to be in the end.
   #
   # @param filename [String] the name of the file (filenames are variable-width in the ZIP)
   # @param size [Fixnum] size of the uncompressed entry
-  # @param use_data_descriptor[Boolean] whether the entry uses a postfix data descriptor to specify size
+  # @param use_data_descriptor[Boolean] whether the entry uses a postfix
+  # data descriptor to specify size
   # @return self
   def add_stored_entry(filename:, size:, use_data_descriptor: false)
-    udd = !!use_data_descriptor
-    @streamer.add_file_and_write_local_header(filename: filename, crc32: 0, storage_mode: 0,
-      compressed_size: size, uncompressed_size: size, use_data_descriptor: udd)
+    @streamer.add_stored_entry(filename: filename,
+                               crc32: 0,
+                               size: size,
+                               use_data_descriptor: use_data_descriptor)
     @streamer.simulate_write(size)
-    @streamer.write_data_descriptor_for_last_entry if udd
+    if use_data_descriptor
+      @streamer.update_last_entry_and_write_data_descriptor(crc32: 0, compressed_size: size, uncompressed_size: size)
+    end
     self
   end
 
@@ -51,24 +53,34 @@ class ZipTricks::SizeEstimator
   # @param filename [String] the name of the file (filenames are variable-width in the ZIP)
   # @param uncompressed_size [Fixnum] size of the uncompressed entry
   # @param compressed_size [Fixnum] size of the compressed entry
-  # @param use_data_descriptor[Boolean] whether the entry uses a postfix data descriptor to specify size
+  # @param use_data_descriptor[Boolean] whether the entry uses a postfix data
+  #                                     descriptor to specify size
   # @return self
-  def add_compressed_entry(filename:, uncompressed_size:, compressed_size:, use_data_descriptor: false)
-    udd = !!use_data_descriptor
-    @streamer.add_file_and_write_local_header(filename: filename, crc32: 0, storage_mode: 8,
-      compressed_size: compressed_size, uncompressed_size: uncompressed_size, use_data_descriptor: udd)
+  def add_deflated_entry(filename:, uncompressed_size:, compressed_size:, use_data_descriptor: false)
+    @streamer.add_deflated_entry(filename: filename,
+                                 crc32: 0,
+                                 compressed_size: compressed_size,
+                                 uncompressed_size: uncompressed_size,
+                                 use_data_descriptor: use_data_descriptor)
+
     @streamer.simulate_write(compressed_size)
-    @streamer.write_data_descriptor_for_last_entry if udd
+    if use_data_descriptor
+      @streamer.update_last_entry_and_write_data_descriptor(crc32: 0,
+                                                            compressed_size: compressed_size,
+                                                            uncompressed_size: uncompressed_size)
+    end
     self
   end
-  
+
+  # Will be phased out in ZipTricks 5.x
+  alias_method :add_compressed_entry, :add_deflated_entry
+
   # Add an empty directory to the archive.
   #
   # @param dirname [String] the name of the directory
   # @return self
   def add_empty_directory_entry(dirname:)
-    @streamer.add_file_and_write_local_header(filename: "#{dirname}" + "/", crc32: 0, storage_mode: 8,
-      compressed_size: 0, uncompressed_size: 0)
+    @streamer.add_empty_directory(dirname: dirname)
     self
   end
 end

data/lib/zip_tricks/stream_crc32.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # A simple stateful class for keeping track of a CRC32 value through multiple writes
 class ZipTricks::StreamCRC32
   # Compute a CRC32 value from an IO object. The object should respond to `read` and `eof?`

data/lib/zip_tricks/streamer.rb

@@ -1,6 +1,11 @@
+# frozen_string_literal: true
+
+require 'set'
+
 # Is used to write streamed ZIP archives into the provided IO-ish object.
 # The output IO is never going to be rewound or seeked, so the output
-# of this object can be coupled directly to, say, a Rack output.
+# of this object can be coupled directly to, say, a Rack output. The
+# output can also be a String, Array or anything that responds to `<<`.
 #
 # Allows for splicing raw files (for "stored" entries without compression)
 # and splicing of deflated files (for "deflated" storage mode).
@@ -16,7 +21,7 @@
 # You can use the Streamer with data descriptors (the CRC32 and the sizes will be
 # written after the file data). This allows non-rewinding on-the-fly compression.
 # If you are compressing large files, the Deflater object that the Streamer controls
-# will be regularly flushed to prevent memory inflation. 
+# will be regularly flushed to prevent memory inflation.
 #
 #     ZipTricks::Streamer.open(file_socket_or_string) do |zip|
 #       zip.write_stored_file('mov.mp4') do |sink|
@@ -51,7 +56,28 @@
 # so far. When using `sendfile` the Ruby write methods get bypassed entirely, and the
 # offsets in the IO will not be updated - which will result in an invalid ZIP.
 #
-# The central directory will be written automatically at the end of the `open` block.
+#
+# ## On-the-fly deflate -using the Streamer with async/suspended writes and data descriptors
+#
+# If you are unable to use the block versions of `write_deflated_file` and `write_stored_file`
+# there is an option to use a separate writer object. It gets returned from `write_deflated_file`
+# and `write_stored_file` if you do not provide them with a block, and will accept data writes.
+#
+#     ZipTricks::Streamer.open(socket) do | zip |
+#       w = zip.write_stored_file('mov.mp4')
+#       w << data
+#       w.close
+#     end
+#
+# The central directory will be written automatically at the end of the `open` block. If you need
+# to manage the Streamer manually, or defer the central directory write until appropriate, use
+# the constructor instead and call `Streamer#close`:
+#
+#     zip = ZipTricks::Streamer.new(out_io)
+#     .....
+#     zip.close
+#
+# Calling {Streamer#close} **will not** call `#close` on the underlying IO object.
 class ZipTricks::Streamer
   require_relative 'streamer/deflated_writer'
   require_relative 'streamer/writable'
@@ -82,16 +108,13 @@ class ZipTricks::Streamer
 
   # Creates a new Streamer on top of the given IO-ish object.
   #
-  # @param stream[IO] the destination IO for the ZIP (should respond to `<<`)
+  # @param stream[IO] the destination IO for the ZIP. Anything that responds to `<<` can be used.
   # @param writer[ZipTricks::ZipWriter] the object to be used as the writer.
   #    Defaults to an instance of ZipTricks::ZipWriter, normally you won't need to override it
   def initialize(stream, writer: create_writer)
-    raise InvalidOutput, "The stream must respond to #<<" unless stream.respond_to?(:<<)
-    unless stream.respond_to?(:tell) && stream.respond_to?(:advance_position_by)
-      stream = ZipTricks::WriteAndTell.new(stream) 
-    end
+    raise InvalidOutput, 'The stream must respond to #<<' unless stream.respond_to?(:<<)
 
-    @out = stream
+    @out = ZipTricks::WriteAndTell.new(stream)
     @files = []
     @local_header_offsets = []
     @filenames_set = Set.new
@@ -112,114 +135,189 @@ class ZipTricks::Streamer
   # `IO.copy_stream(from, to)`.
   #
   # @param binary_data [String] a String in binary encoding
-  # @return [Fixnum] the number of bytes written
+  # @return [Integer] the number of bytes written
   def write(binary_data)
     @out << binary_data
     binary_data.bytesize
   end
 
-  # Advances the internal IO pointer to keep the offsets of the ZIP file in check. Use this if you are going
-  # to use accelerated writes to the socket (like the `sendfile()` call) after writing the headers, or if you
+  # Advances the internal IO pointer to keep the offsets of the ZIP file in
+  # check. Use this if you are going to use accelerated writes to the socket
+  # (like the `sendfile()` call) after writing the headers, or if you
   # just need to figure out the size of the archive.
   #
-  # @param num_bytes [Numeric] how many bytes are going to be written bypassing the Streamer
-  # @return [Numeric] position in the output stream / ZIP archive
+  # @param num_bytes [Integer] how many bytes are going to be written bypassing the Streamer
+  # @return [Integer] position in the output stream / ZIP archive
   def simulate_write(num_bytes)
     @out.advance_position_by(num_bytes)
     @out.tell
   end
 
-  # Writes out the local header for an entry (file in the ZIP) that is using the deflated storage model (is compressed).
-  # Once this method is called, the `<<` method has to be called to write the actual contents of the body.
+  # Writes out the local header for an entry (file in the ZIP) that is using
+  # the deflated storage model (is compressed). Once this method is called,
+  # the `<<` method has to be called to write the actual contents of the body.
   #
-  # Note that the deflated body that is going to be written into the output has to be _precompressed_ (pre-deflated)
-  # before writing it into the Streamer, because otherwise it is impossible to know it's size upfront.
+  # Note that the deflated body that is going to be written into the output
+  # has to be _precompressed_ (pre-deflated) before writing it into the
+  # Streamer, because otherwise it is impossible to know it's size upfront.
   #
   # @param filename [String] the name of the file in the entry
-  # @param compressed_size [Fixnum] the size of the compressed entry that is going to be written into the archive
-  # @param uncompressed_size [Fixnum] the size of the entry when uncompressed, in bytes
-  # @param crc32 [Fixnum] the CRC32 checksum of the entry when uncompressed
-  # @return [Fixnum] the offset the output IO is at after writing the entry header
-  def add_compressed_entry(filename:, compressed_size:, uncompressed_size:, crc32:)
-    add_file_and_write_local_header(filename: filename, crc32: crc32, storage_mode: DEFLATED, 
-      compressed_size: compressed_size, uncompressed_size: uncompressed_size)
+  # @param compressed_size [Integer] the size of the compressed entry that
+  #                                   is going to be written into the archive
+  # @param uncompressed_size [Integer] the size of the entry when uncompressed, in bytes
+  # @param crc32 [Integer] the CRC32 checksum of the entry when uncompressed
+  # @param use_data_descriptor [Boolean] whether the entry body will be followed by a data descriptor
+  # @return [Integer] the offset the output IO is at after writing the entry header
+  def add_deflated_entry(filename:, compressed_size: 0, uncompressed_size: 0, crc32: 0, use_data_descriptor: false)
+    add_file_and_write_local_header(filename: filename, crc32: crc32,
+                                    storage_mode: DEFLATED,
+                                    compressed_size: compressed_size,
+                                    uncompressed_size: uncompressed_size,
+                                    use_data_descriptor: use_data_descriptor)
     @out.tell
   end
 
-  # Writes out the local header for an entry (file in the ZIP) that is using the stored storage model (is stored as-is).
-  # Once this method is called, the `<<` method has to be called one or more times to write the actual contents of the body.
+  # Will be phased out in ZipTricks 5.x
+  alias_method :add_compressed_entry, :add_deflated_entry
+
+  # Writes out the local header for an entry (file in the ZIP) that is using
+  # the stored storage model (is stored as-is).
+  # Once this method is called, the `<<` method has to be called one or more
+  # times to write the actual contents of the body.
   #
   # @param filename [String] the name of the file in the entry
-  # @param size [Fixnum] the size of the file when uncompressed, in bytes
-  # @param crc32 [Fixnum] the CRC32 checksum of the entry when uncompressed
-  # @return [Fixnum] the offset the output IO is at after writing the entry header
-  def add_stored_entry(filename:, size:, crc32:)
-    add_file_and_write_local_header(filename: filename, crc32: crc32, storage_mode: STORED,
-      compressed_size: size, uncompressed_size: size)
+  # @param size [Integer] the size of the file when uncompressed, in bytes
+  # @param crc32 [Integer] the CRC32 checksum of the entry when uncompressed
+  # @param use_data_descriptor [Boolean] whether the entry body will be followed by a data descriptor. When in use
+  # @return [Integer] the offset the output IO is at after writing the entry header
+  def add_stored_entry(filename:, size: 0, crc32: 0, use_data_descriptor: false)
+    add_file_and_write_local_header(filename: filename,
+                                    crc32: crc32,
+                                    storage_mode: STORED,
+                                    compressed_size: size,
+                                    uncompressed_size: size,
+                                    use_data_descriptor: use_data_descriptor)
     @out.tell
   end
 
   # Adds an empty directory to the archive with a size of 0 and permissions of 755.
   #
   # @param dirname [String] the name of the directory in the archive
-  # @return [Fixnum] the offset the output IO is at after writing the entry header
+  # @return [Integer] the offset the output IO is at after writing the entry header
   def add_empty_directory(dirname:)
-    add_file_and_write_local_header(filename: "#{dirname}" + "/", crc32: 0, storage_mode: STORED,
-      compressed_size: 0, uncompressed_size: 0)
+    add_file_and_write_local_header(filename: dirname.to_s + '/',
+                                    crc32: 0,
+                                    storage_mode: STORED,
+                                    compressed_size: 0,
+                                    uncompressed_size: 0,
+                                    use_data_descriptor: false)
     @out.tell
   end
-  
-  # Opens the stream for a stored file in the archive, and yields a writer for that file to the block.
-  # Once the write completes, a data descriptor will be written with the actual compressed/uncompressed
-  # sizes and the CRC32 checksum.
+
+  # Opens the stream for a stored file in the archive, and yields a writer
+  # for that file to the block.
+  # Once the write completes, a data descriptor will be written with the
+  # actual compressed/uncompressed sizes and the CRC32 checksum.
+  #
+  # Using a block, the write will be terminated with a data descriptor outright.
+  #
+  #     zip.write_stored_file("foo.txt") do |sink|
+  #       IO.copy_stream(source_file, sink)
+  #     end
+  #
+  # If deferred writes are desired (for example - to integerate with an API that
+  # does not support blocks, or to work with non-blocking environments) the method
+  # has to be called without a block. In that case it returns the sink instead,
+  # permitting to write to it in a deferred fashion. When `close` is called on
+  # the sink, any remanining compression output will be flushed and the data
+  # descriptor is going to be written.
+  #
+  # Note that even though it does not have to happen within the same call stack,
+  # call sequencing still must be observed. It is therefore not possible to do
+  # this:
+  #
+  #     writer_for_file1 = zip.write_stored_file("somefile.jpg")
+  #     writer_for_file2 = zip.write_stored_file("another.tif")
+  #     writer_for_file1 << data
+  #     writer_for_file2 << data
+  #
+  # because it is likely to result in an invalid ZIP file structure later on.
+  # So using this facility in async scenarios is certainly possible, but care
+  # and attention is recommended.
   #
   # @param filename[String] the name of the file in the archive
-  # @yield [#<<, #write] an object that the file contents must be written to
+  # @yield [#<<, #write] an object that the file contents must be written to that will be automatically closed
+  # @return [#<<, #write, #close] an object that the file contents must be written to, has to be closed manually
   def write_stored_file(filename)
-    add_file_and_write_local_header(filename: filename, storage_mode: STORED,
-      use_data_descriptor: true, crc32: 0, compressed_size: 0, uncompressed_size: 0)
-
-    w = StoredWriter.new(@out)
-    yield(Writable.new(w))
-    crc, comp, uncomp = w.finish
-
-    # Save the information into the entry for when the time comes to write out the central directory
-    last_entry = @files.last
-    last_entry.crc32 = crc
-    last_entry.compressed_size = comp
-    last_entry.uncompressed_size = uncomp
+    add_stored_entry(filename: filename,
+                     use_data_descriptor: true,
+                     crc32: 0,
+                     size: 0)
 
-    @writer.write_data_descriptor(io: @out, crc32: crc, compressed_size: comp, uncompressed_size: uncomp)
+    writable = Writable.new(self, StoredWriter.new(@out))
+    if block_given?
+      yield(writable)
+      writable.close
+    end
+    writable
   end
 
-  # Opens the stream for a deflated file in the archive, and yields a writer for that file to the block.
-  # Once the write completes, a data descriptor will be written with the actual compressed/uncompressed
-  # sizes and the CRC32 checksum.
+  # Opens the stream for a deflated file in the archive, and yields a writer
+  # for that file to the block. Once the write completes, a data descriptor
+  # will be written with the actual compressed/uncompressed sizes and the
+  # CRC32 checksum.
+  #
+  # Using a block, the write will be terminated with a data descriptor outright.
+  #
+  #     zip.write_stored_file("foo.txt") do |sink|
+  #       IO.copy_stream(source_file, sink)
+  #     end
+  #
+  # If deferred writes are desired (for example - to integerate with an API that
+  # does not support blocks, or to work with non-blocking environments) the method
+  # has to be called without a block. In that case it returns the sink instead,
+  # permitting to write to it in a deferred fashion. When `close` is called on
+  # the sink, any remanining compression output will be flushed and the data
+  # descriptor is going to be written.
+  #
+  # Note that even though it does not have to happen within the same call stack,
+  # call sequencing still must be observed. It is therefore not possible to do
+  # this:
+  #
+  #     writer_for_file1 = zip.write_deflated_file("somefile.jpg")
+  #     writer_for_file2 = zip.write_deflated_file("another.tif")
+  #     writer_for_file1 << data
+  #     writer_for_file2 << data
+  #     writer_for_file1.close
+  #     writer_for_file2.close
+  #
+  # because it is likely to result in an invalid ZIP file structure later on.
+  # So using this facility in async scenarios is certainly possible, but care
+  # and attention is recommended.
   #
   # @param filename[String] the name of the file in the archive
   # @yield [#<<, #write] an object that the file contents must be written to
   def write_deflated_file(filename)
-    add_file_and_write_local_header(filename: filename, storage_mode: DEFLATED,
-      use_data_descriptor: true, crc32: 0, compressed_size: 0, uncompressed_size: 0)
-
-    w = DeflatedWriter.new(@out)
-    yield(Writable.new(w))
-    crc, comp, uncomp = w.finish
-
-    # Save the information into the entry for when the time comes to write out the central directory
-    last_entry = @files[-1]
-    last_entry.crc32 = crc
-    last_entry.compressed_size = comp
-    last_entry.uncompressed_size = uncomp
-    write_data_descriptor_for_last_entry
+    add_deflated_entry(filename: filename,
+                       use_data_descriptor: true,
+                       crc32: 0,
+                       compressed_size: 0,
+                       uncompressed_size: 0)
+
+    writable = Writable.new(self, DeflatedWriter.new(@out))
+    if block_given?
+      yield(writable)
+      writable.close
+    end
+    writable
   end
-    
+
   # Closes the archive. Writes the central directory, and switches the writer into
   # a state where it can no longer be written to.
   #
   # Once this method is called, the `Streamer` should be discarded (the ZIP archive is complete).
   #
-  # @return [Fixnum] the offset the output IO is at after closing the archive
+  # @return [Integer] the offset the output IO is at after closing the archive
   def close
     # Record the central directory offset, so that it can be written into the EOCD record
     cdir_starts_at = @out.tell
@@ -227,18 +325,31 @@ class ZipTricks::Streamer
     # Write out the central directory entries, one for each file
     @files.each_with_index do |entry, i|
       header_loc = @local_header_offsets.fetch(i)
-      @writer.write_central_directory_file_header(io: @out, local_file_header_location: header_loc,
-        gp_flags: entry.gp_flags, storage_mode: entry.storage_mode,
-        compressed_size: entry.compressed_size, uncompressed_size: entry.uncompressed_size,
-        mtime: entry.mtime, crc32: entry.crc32, filename: entry.filename) #, external_attrs: DEFAULT_EXTERNAL_ATTRS)
+      @writer.write_central_directory_file_header(io: @out,
+                                                  local_file_header_location: header_loc,
+                                                  gp_flags: entry.gp_flags,
+                                                  storage_mode: entry.storage_mode,
+                                                  compressed_size: entry.compressed_size,
+                                                  uncompressed_size: entry.uncompressed_size,
+                                                  mtime: entry.mtime,
+                                                  crc32: entry.crc32,
+                                                  filename: entry.filename)
     end
 
     # Record the central directory size, for the EOCDR
     cdir_size = @out.tell - cdir_starts_at
 
     # Write out the EOCDR
-    @writer. write_end_of_central_directory(io: @out, start_of_central_directory_location: cdir_starts_at,
-       central_directory_size: cdir_size, num_files_in_archive: @files.length)
+    @writer.write_end_of_central_directory(io: @out,
+                                           start_of_central_directory_location: cdir_starts_at,
+                                           central_directory_size: cdir_size,
+                                           num_files_in_archive: @files.length)
+
+    # Clear the files so that GC will not have to trace all the way to here to deallocate them
+    @files.clear
+    @filenames_set.clear
+
+    # and return the final offset
     @out.tell
   end
 
@@ -251,29 +362,73 @@ class ZipTricks::Streamer
     ZipTricks::ZipWriter.new
   end
 
+  # Updates the last entry written with the CRC32 checksum and compressed/uncompressed
+  # sizes. For stored entries, `compressed_size` and `uncompressed_size` are the same.
+  # After updating the entry will immediately write the data descriptor bytes
+  # to the output.
+  #
+  # @param crc32 [Integer] the CRC32 checksum of the entry when uncompressed
+  # @param compressed_size [Integer] the size of the compressed segment within the ZIP
+  # @param uncompressed_size [Integer] the size of the entry once uncompressed
+  # @return [Integer] the offset the output IO is at after writing the data descriptor
+  def update_last_entry_and_write_data_descriptor(crc32:, compressed_size:, uncompressed_size:)
+    # Save the information into the entry for when the time comes to write
+    # out the central directory
+    last_entry = @files.fetch(-1)
+    last_entry.crc32 = crc32
+    last_entry.compressed_size = compressed_size
+    last_entry.uncompressed_size = uncompressed_size
+
+    @writer.write_data_descriptor(io: @out,
+                                  crc32: last_entry.crc32,
+                                  compressed_size: last_entry.compressed_size,
+                                  uncompressed_size: last_entry.uncompressed_size)
+    @out.tell
+  end
+
   private
 
-  def add_file_and_write_local_header(filename:, crc32:, storage_mode:, compressed_size:,
-      uncompressed_size:, use_data_descriptor: false)
+  def add_file_and_write_local_header(filename:,
+                                      crc32:,
+                                      storage_mode:,
+                                      compressed_size:,
+                                      uncompressed_size:,
+                                      use_data_descriptor:)
 
     # Clean backslashes and uniqify filenames if there are duplicates
     filename = remove_backslash(filename)
     filename = uniquify_name(filename) if @filenames_set.include?(filename)
 
-    raise UnknownMode, "Unknown compression mode #{storage_mode}" unless [STORED, DEFLATED].include?(storage_mode)
-    raise Overflow, "Filename is too long" if filename.bytesize > 0xFFFF
+    unless [STORED, DEFLATED].include?(storage_mode)
+      raise UnknownMode, "Unknown compression mode #{storage_mode}"
+    end
+
+    raise Overflow, 'Filename is too long' if filename.bytesize > 0xFFFF
 
-    e = Entry.new(filename, crc32, compressed_size, uncompressed_size, storage_mode, mtime=Time.now.utc, use_data_descriptor)
+    if use_data_descriptor
+      crc32 = 0
+      compressed_size = 0
+      uncompressed_size = 0
+    end
+
+    e = Entry.new(filename,
+                  crc32,
+                  compressed_size,
+                  uncompressed_size,
+                  storage_mode,
+                  mtime = Time.now.utc,
+                  use_data_descriptor)
     @files << e
     @filenames_set << e.filename
     @local_header_offsets << @out.tell
-    @writer.write_local_file_header(io: @out, gp_flags: e.gp_flags, crc32: e.crc32, compressed_size: e.compressed_size,
-      uncompressed_size: e.uncompressed_size, mtime: e.mtime, filename: e.filename, storage_mode: e.storage_mode)
-  end
-      
-  def write_data_descriptor_for_last_entry
-    e = @files.fetch(-1)
-    @writer.write_data_descriptor(io: @out, crc32: 0, compressed_size: e.compressed_size, uncompressed_size: e.uncompressed_size)
+    @writer.write_local_file_header(io: @out,
+                                    gp_flags: e.gp_flags,
+                                    crc32: e.crc32,
+                                    compressed_size: e.compressed_size,
+                                    uncompressed_size: e.uncompressed_size,
+                                    mtime: e.mtime,
+                                    filename: e.filename,
+                                    storage_mode: e.storage_mode)
   end
 
   def remove_backslash(filename)
@@ -281,8 +436,9 @@ class ZipTricks::Streamer
   end
 
   def uniquify_name(filename)
-    copy_pattern = /\((\d+)\)$/ # we add (1), (2), (n) at the end of a filename if there is a duplicate
-    parts = filename.split(".")
+    # we add (1), (2), (n) at the end of a filename if there is a duplicate
+    copy_pattern = /\((\d+)\)$/
+    parts = filename.split('.')
     ext = if parts.last =~ /gz|zip/ && parts.size > 2
             parts.pop(2)
           elsif parts.size > 1
@@ -292,12 +448,12 @@ class ZipTricks::Streamer
 
     duplicate_counter = 1
     loop do
-      if fn_last_part =~ copy_pattern
-        fn_last_part.sub!(copy_pattern, "(#{duplicate_counter})")
-      else
-        fn_last_part = "#{fn_last_part} (#{duplicate_counter})"
-      end
-      new_filename = (parts + [fn_last_part, ext]).compact.join(".")
+      fn_last_part = if fn_last_part =~ copy_pattern
+                       fn_last_part.sub(copy_pattern, "(#{duplicate_counter})")
+                     else
+                       "#{fn_last_part} (#{duplicate_counter})"
+                     end
+      new_filename = (parts + [fn_last_part, ext]).compact.join('.')
       return new_filename unless @filenames_set.include?(new_filename)
       duplicate_counter += 1
     end