zip_kit 6.0.0

data/lib/zip_kit/null_writer.rb

@@ -0,0 +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 ZipKit::NullWriter
+  # @param _[String] the data to write
+  # @return [self]
+  def self.<<(_)
+    self
+  end
+end

data/lib/zip_kit/output_enumerator.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "time" # for .httpdate
+
+# The output enumerator makes it possible to "pull" from a ZipKit streamer
+# object instead of having it "push" writes to you. It will "stash" the block which
+# writes the ZIP archive through the streamer, and when you call `each` on the Enumerator
+# it will yield you the bytes the block writes. Since it is an enumerator you can
+# use `next` to take chunks written by the ZipKit streamer one by one. It can be very
+# convenient when you need to segment your ZIP output into bigger chunks for, say,
+# uploading them to a cloud storage provider such as S3.
+#
+# Another use of the `OutputEnumerator` is as a Rack response body - since a Rack
+# response body object must support `#each` yielding successive binary strings.
+# Which is exactly what `OutputEnumerator` does.
+#
+# The enumerator can provide you some more conveinences for HTTP output - correct streaming
+# headers and a body with chunked transfer encoding.
+#
+#     iterable_zip_body = ZipKit::OutputEnumerator.new do | streamer |
+#       streamer.write_file('big.csv') do |sink|
+#         CSV(sink) do |csv_writer|
+#           csv_writer << Person.column_names
+#           Person.all.find_each do |person|
+#             csv_writer << person.attributes.values
+#           end
+#         end
+#       end
+#     end
+#
+# Either as a `Transfer-Encoding: chunked` response (if your webserver supports it),
+# which will give you true streaming capability:
+#
+#     headers, chunked_or_presized_rack_body = iterable_zip_body.to_headers_and_rack_response_body(env)
+#     [200, headers, chunked_or_presized_rack_body]
+#
+# or it will wrap your output in a `TempfileBody` object which buffers the ZIP before output. Buffering has
+# benefits if your webserver does not support anything beyound HTTP/1.0, and also engages automatically
+# in unit tests (since rack-test and Rails tests do not do streaming HTTP/1.1).
+class ZipKit::OutputEnumerator
+  DEFAULT_WRITE_BUFFER_SIZE = 64 * 1024
+
+  # Creates a new OutputEnumerator enumerator. The enumerator can be read from using `each`,
+  # and the creation of the ZIP is in lockstep with the caller calling `each` on the returned
+  # output enumerator object. This can be used when the calling program wants to stream the
+  # output of the ZIP archive and throttle that output, or split it into chunks, or use it
+  # as a generator.
+  #
+  # For example:
+  #
+  #     # The block given to {output_enum} won't be executed immediately - rather it
+  #     # will only start to execute when the caller starts to read from the output
+  #     # by calling `each`
+  #     body = ::ZipKit::OutputEnumerator.new(writer: CustomWriter) do |streamer|
+  #       streamer.add_stored_entry(filename: 'large.tif', size: 1289894, crc32: 198210)
+  #       streamer << large_file.read(1024*1024) until large_file.eof?
+  #       ...
+  #     end
+  #
+  #     body.each do |bin_string|
+  #       # Send the output somewhere, buffer it in a file etc.
+  #       # The block passed into `initialize` will only start executing once `#each`
+  #       # is called
+  #       ...
+  #     end
+  #
+  # @param kwargs_for_new [Hash] keyword arguments for {Streamer.new}
+  # @return [ZipKit::OutputEnumerator] the enumerator you can read bytestrings of the ZIP from by calling `each`
+  #
+  # @param streamer_options[Hash] options for Streamer, see {ZipKit::Streamer.new}
+  # @param write_buffer_size[Integer] By default all ZipKit writes are unbuffered. For output to sockets
+  #     it is beneficial to bulkify those writes so that they are roughly sized to a socket buffer chunk. This
+  #     object will bulkify writes for you in this way (so `each` will yield not on every call to `<<` from the Streamer
+  #     but at block size boundaries or greater). Set it to 0 for unbuffered writes.
+  # @param blk a block that will receive the Streamer object when executing. The block will not be executed
+  #     immediately but only once `each` is called on the OutputEnumerator
+  def initialize(write_buffer_size: DEFAULT_WRITE_BUFFER_SIZE, **streamer_options, &blk)
+    @streamer_options = streamer_options.to_h
+    @bufsize = write_buffer_size.to_i
+    @archiving_block = blk
+  end
+
+  # Executes the block given to the constructor with a {ZipKit::Streamer}
+  # and passes each written chunk to the block given to the method. This allows one
+  # to "take" output of the ZIP piecewise. If called without a block will return an Enumerator
+  # that you can pull data from using `next`.
+  #
+  # **NOTE** Because the `WriteBuffer` inside this object can reuse the buffer, it is important
+  #    that the `String` that is yielded **either** gets consumed eagerly (written byte-by-byte somewhere, or `#dup`-ed)
+  #    since the write buffer will clear it after your block returns. If you expand this Enumerator
+  #    eagerly into an Array you might notice that a lot of the segments of your ZIP output are
+  #    empty - this means that you need to duplicate them.
+  #
+  # @yield [String] a chunk of the ZIP output in binary encoding
+  def each
+    if block_given?
+      block_write = ZipKit::BlockWrite.new { |chunk| yield(chunk) }
+      buffer = ZipKit::WriteBuffer.new(block_write, @bufsize)
+      ZipKit::Streamer.open(buffer, **@streamer_options, &@archiving_block)
+      buffer.flush
+    else
+      enum_for(:each)
+    end
+  end
+
+  # Returns a tuple of `headers, body` - headers are a `Hash` and the body is
+  # an object that can be used as a Rack response body. The method will automatically
+  # switch the wrapping of the output depending on whether the response can be pre-sized,
+  # and whether your downstream webserver (like nginx) is configured to support
+  # the HTTP/1.1 protocol version.
+  #
+  # @param rack_env[Hash] the Rack env, which the method may need to mutate (adding a Tempfile for cleanup)
+  # @param content_length[Integer] the amount of bytes that the archive will contain. If given, no Chunked encoding gets applied.
+  # @return [Array]
+  def to_headers_and_rack_response_body(rack_env, content_length: nil)
+    headers = {
+      # We need to ensure Rack::ETag does not suddenly start buffering us, see
+      # https://github.com/rack/rack/issues/1619#issuecomment-606315714
+      # Set this even when not streaming for consistency. The fact that there would be
+      # a weak ETag generated would mean that the middleware buffers, so we have tests for that.
+      "Last-Modified" => Time.now.httpdate,
+      # Make sure Rack::Deflater does not touch our response body either, see
+      # https://github.com/felixbuenemann/xlsxtream/issues/14#issuecomment-529569548
+      "Content-Encoding" => "identity",
+      # Disable buffering for both nginx and Google Load Balancer, see
+      # https://cloud.google.com/appengine/docs/flexible/how-requests-are-handled?tab=python#x-accel-buffering
+      "X-Accel-Buffering" => "no"
+    }
+
+    if content_length
+      # If we know the size of the body, transfer encoding is not required at all - so the enumerator itself
+      # can function as the Rack body. This also would apply in HTTP/2 contexts where chunked encoding would
+      # no longer be required - then the enumerator could get returned "bare".
+      body = self
+      headers["Content-Length"] = content_length.to_i.to_s
+    elsif rack_env["HTTP_VERSION"] == "HTTP/1.0"
+      # Check for the proxy configuration first. This is the first common misconfiguration which destroys streaming -
+      # since HTTP 1.0 does not support chunked responses we need to revert to buffering. The issue though is that
+      # this reversion happens silently and it is usually not clear at all why streaming does not work. So let's at
+      # the very least print it to the Rails log.
+      body = ZipKit::RackTempfileBody.new(rack_env, self)
+      headers["Content-Length"] = body.size.to_s
+    else
+      body = ZipKit::RackChunkedBody.new(self)
+      headers["Transfer-Encoding"] = "chunked"
+    end
+
+    [headers, body]
+  end
+end

data/lib/zip_kit/path_set.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+# 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
+# the filename of "some folder/file.docx" will make the unarchiving application
+# create a directory called "some folder" automatically, and then deposit the
+# file "file.docx" in that directory. These "implicit" directories can be
+# arbitrarily nested, and create a tree structure of directories. That structure
+# however is implicit as the archive contains a flat list.
+#
+# This creates opportunities for conflicts. For example, imagine the following
+# structure:
+#
+# * `something/` - specifies an empty directory with the name "something"
+# * `something` - specifies a file, creates a conflict
+#
+# This can be prevented with filename uniqueness checks. It does get funkier however
+# as the rabbit hole goes down:
+#
+# * `dir/subdir/another_subdir/yet_another_subdir/file.bin` - declares a file and directories
+# * `dir/subdir/another_subdir/yet_another_subdir` - declares a file at one of the levels, creates a conflict
+#
+# The results of this ZIP structure aren't very easy to predict as they depend on the
+# application that opens the archive. For example, BOMArchiveHelper on macOS will expand files
+# as they are declared in the ZIP, but once a conflict occurs it will fail with "error -21". It
+# is not very transparent to the user why unarchiving fails, and it has to - and can reliably - only
+# be prevented when the archive gets created.
+#
+# Unfortunately that conflicts with another "magical" feature of ZipKit which automatically
+# "fixes" duplicate filenames - filenames (paths) which have already been added to the archive.
+# This fix is performed by appending (1), then (2) and so forth to the filename so that the
+# conflict is avoided. This is not possible to apply to directories, because when one of the
+# path components is reused in multiple filenames it means those entities should end up in
+# the same directory (subdirectory) once the archive is opened.
+#
+# The `PathSet` keeps track of entries as they get added using 2 Sets (cheap presence checks),
+# one for directories and one for files. It will raise a `Conflict` exception if there are
+# files clobbering one another, or in case files collide with directories.
+class ZipKit::PathSet
+  class Conflict < StandardError
+  end
+
+  class FileClobbersDirectory < Conflict
+  end
+
+  class DirectoryClobbersFile < Conflict
+  end
+
+  def initialize
+    @known_directories = Set.new
+    @known_files = Set.new
+  end
+
+  # Adds a directory path to the set of known paths, including
+  # all the directories that contain it. So, calling
+  #    add_directory_path("dir/dir2/dir3")
+  # will add "dir", "dir/dir2", "dir/dir2/dir3".
+  #
+  # @param path[String] the path to the directory to add
+  # @return [void]
+  def add_directory_path(path)
+    path_and_ancestors(path).each do |parent_directory_path|
+      if @known_files.include?(parent_directory_path)
+        # Have to use the old-fashioned heredocs because ZipKit
+        # aims to be compatible with MRI 2.1+ syntax, and squiggly
+        # heredoc is only available starting 2.3+
+        error_message = <<~ERR
+          The path #{parent_directory_path.inspect} which has to be added
+          as a directory is already used for a file.
+
+          The directory at this path would get created implicitly
+          to produce #{path.inspect} during decompresison.
+
+          This would make some archive utilities refuse to open
+          the ZIP.
+        ERR
+        raise DirectoryClobbersFile, error_message
+      end
+      @known_directories << parent_directory_path
+    end
+  end
+
+  # Adds a file path to the set of known paths, including
+  # all the directories that contain it. Once a file has been added,
+  # it is no longer possible to add a directory having the same path
+  # as this would cause conflict.
+  #
+  # The operation also adds all the containing directories for the file, so
+  #    add_file_path("dir/dir2/file.doc")
+  # will add "dir" and "dir/dir2" as directories, "dir/dir2/dir3".
+  #
+  # @param file_path[String] the path to the directory to add
+  # @return [void]
+  def add_file_path(file_path)
+    if @known_files.include?(file_path)
+      error_message = <<~ERR
+        The file at #{file_path.inspect} has already been included
+        in the archive. Adding it the second time would cause
+        the first file to be overwritten during unarchiving, and
+        could also get the archive flagged as invalid.
+      ERR
+      raise Conflict, error_message
+    end
+
+    if @known_directories.include?(file_path)
+      error_message = <<~ERR
+        The path #{file_path.inspect} is already used for
+        a directory, but you are trying to add it as a file.
+
+        This would make some archive utilities refuse
+        to open the ZIP.
+      ERR
+      raise FileClobbersDirectory, error_message
+    end
+
+    # Add all the directories which this file is contained in
+    *dir_components, _file_name = non_empty_path_components(file_path)
+    add_directory_path(dir_components.join("/"))
+
+    # ...and then the file itself
+    @known_files << file_path
+  end
+
+  # Tells whether a specific full path is already known to the PathSet.
+  # Can be a path for a directory or for a file.
+  #
+  # @param path_in_archive[String] the path to check for inclusion
+  # @return [Boolean]
+  def include?(path_in_archive)
+    @known_files.include?(path_in_archive) || @known_directories.include?(path_in_archive)
+  end
+
+  # Clears the contained sets
+  # @return [void]
+  def clear
+    @known_files.clear
+    @known_directories.clear
+  end
+
+  # Adds the directory or file path to the path set
+  #
+  # @return [void]
+  def add_directory_or_file_path(path_in_archive)
+    if path_in_archive.end_with?("/")
+      add_directory_path(path_in_archive)
+    else
+      add_file_path(path_in_archive)
+    end
+  end
+
+  private
+
+  def non_empty_path_components(path)
+    path.split("/").reject(&:empty?)
+  end
+
+  def path_and_ancestors(path)
+    path_components = non_empty_path_components(path)
+    path_components.each_with_object([]) do |component, seen|
+      seen << [seen.last, component].compact.join("/")
+    end
+  end
+end

data/lib/zip_kit/rack_chunked_body.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+# A body wrapper that emits chunked responses, creating valid
+# Transfer-Encoding::Chunked HTTP response body. This is copied from Rack::Chunked::Body,
+# because Rack is not going to include that class after version 3.x
+# Rails has a substitute class for this inside ActionController::Streaming,
+# but that module is a private constant in the Rails codebase, and is thus
+# considered "private" from the Rails standpoint. It is not that much code to
+# carry, so we copy it into our code.
+class ZipKit::RackChunkedBody
+  TERM = "\r\n"
+  TAIL = "0#{TERM}"
+
+  # @param body[#each] the enumerable that yields bytes, usually a `OutputEnumerator`
+  def initialize(body)
+    @body = body
+  end
+
+  # For each string yielded by the response body, yield
+  # the element in chunked encoding - and finish off with a terminator
+  def each
+    term = TERM
+    @body.each do |chunk|
+      size = chunk.bytesize
+      next if size == 0
+
+      yield [size.to_s(16), term, chunk.b, term].join
+    end
+    yield TAIL
+    yield term
+  end
+end

data/lib/zip_kit/rack_tempfile_body.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Contains a file handle which can be closed once the response finishes sending.
+# It supports `to_path` so that `Rack::Sendfile` can intercept it
+class ZipKit::RackTempfileBody
+  TEMPFILE_NAME_PREFIX = "zip-tricks-tf-body-"
+  attr_reader :tempfile
+
+  # @param body[#each] the enumerable that yields bytes, usually a `OutputEnumerator`.
+  #   The `body` will be read in full immediately and closed.
+  def initialize(env, body)
+    @tempfile = Tempfile.new(TEMPFILE_NAME_PREFIX)
+    # Rack::TempfileReaper calls close! on tempfiles which get buffered
+    # We wil assume that it works fine with Rack::Sendfile (i.e. the path
+    # to the file getting served gets used before we unlink the tempfile)
+    env["rack.tempfiles"] ||= []
+    env["rack.tempfiles"] << @tempfile
+
+    @tempfile.binmode
+    @body = body
+    @did_flush = false
+  end
+
+  # Returns the size of the contained `Tempfile` so that a correct
+  # Content-Length header can be set
+  #
+  # @return [Integer]
+  def size
+    flush
+    @tempfile.size
+  end
+
+  # Returns the path to the `Tempfile`, so that Rack::Sendfile can send this response
+  # using the downstream webserver
+  #
+  # @return [String]
+  def to_path
+    flush
+    @tempfile.to_path
+  end
+
+  # Stream the file's contents if `Rack::Sendfile` isn't present.
+  #
+  # @return [void]
+  def each
+    flush
+    while (chunk = @tempfile.read(16384))
+      yield chunk
+    end
+  end
+
+  private
+
+  def flush
+    if !@did_flush
+      @body.each { |bytes| @tempfile << bytes }
+      @did_flush = true
+    end
+    @tempfile.rewind
+  end
+end

data/lib/zip_kit/rails_streaming.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# 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.
+  # @param filename[String] name of the file for the Content-Disposition header
+  # @param type[String] the content type (MIME type) of the archive being output
+  # @param zip_streamer_options[Hash] options that will be passed to the Streamer.
+  #     See {ZipKit::Streamer#initialize} for the full list of options.
+  # @yield [Streamer] the streamer that can be written to
+  # @return [ZipKit::OutputEnumerator] The output enumerator assigned to the response body
+  def zip_kit_stream(filename: "download.zip", type: "application/zip", **zip_streamer_options, &zip_streaming_blk)
+    # The output enumerator yields chunks of bytes generated from ZipKit. Instantiating it
+    # first will also validate the Streamer options.
+    chunk_yielder = ZipKit::OutputEnumerator.new(**zip_streamer_options, &zip_streaming_blk)
+
+    # We want some common headers for file sending. Rails will also set
+    # self.sending_file = true for us when we call send_file_headers!
+    send_file_headers!(type: type, filename: filename)
+
+    # Check for the proxy configuration first. This is the first common misconfiguration which destroys streaming -
+    # since HTTP 1.0 does not support chunked responses we need to revert to buffering. The issue though is that
+    # this reversion happens silently and it is usually not clear at all why streaming does not work. So let's at
+    # the very least print it to the Rails log.
+    if request.get_header("HTTP_VERSION") == "HTTP/1.0"
+      logger&.warn { "The downstream HTTP proxy/LB insists on HTTP/1.0 protocol, ZIP response will be buffered." }
+    end
+
+    headers, rack_body = chunk_yielder.to_headers_and_rack_response_body(request.env)
+
+    # Set the "particular" streaming headers
+    response.headers.merge!(headers)
+    self.response_body = rack_body
+  end
+end

data/lib/zip_kit/remote_io.rb

@@ -0,0 +1,114 @@
+# 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
+# for an object that fetches parts of the remote file over HTTP using `Range:`
+# headers. The `RemoteIO` acts as an adapter between an object that performs the
+# actual fetches over HTTP and an object that expects a handful of IO methods to be
+# available.
+class ZipKit::RemoteIO
+  # @param url[String, URI] the HTTP/HTTPS URL of the object to be retrieved
+  def initialize(url)
+    @pos = 0
+    @uri = URI(url)
+    @remote_size = nil
+  end
+
+  # Emulates IO#seek
+  # @param offset[Integer] absolute offset in the remote resource to seek to
+  # @param mode[Integer] The seek mode (only SEEK_SET is supported)
+  def seek(offset, mode = IO::SEEK_SET)
+    raise "Unsupported read mode #{mode}" unless mode == IO::SEEK_SET
+    @remote_size ||= request_object_size
+    @pos = clamp(0, offset, @remote_size)
+    0 # always return 0!
+  end
+
+  # Emulates IO#size.
+  #
+  # @return [Integer] 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.
+  #
+  # @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)
+    # If the resource is empty there is nothing to read
+    return if size.zero?
+
+    maximum_avaialable = size - @pos
+    n_bytes ||= maximum_avaialable # nil == read to the end of file
+    return "" if n_bytes.zero?
+    raise ArgumentError, "No negative reads(#{n_bytes})" if n_bytes < 0
+
+    n_bytes = clamp(0, n_bytes, maximum_avaialable)
+
+    http_range = (@pos..(@pos + n_bytes - 1))
+    request_range(http_range).tap do |data|
+      raise "Remote read returned #{data.bytesize} bytes instead of #{n_bytes} as requested" if data.bytesize != n_bytes
+      @pos = clamp(0, @pos + data.bytesize, size)
+    end
+  end
+
+  # Returns the current pointer position within the IO
+  #
+  # @return [Fixnum]
+  def tell
+    @pos
+  end
+
+  protected
+
+  # Only used internally when reading the remote ZIP.
+  #
+  # @param range[Range] the HTTP range of data to fetch from remote
+  # @return [String] the response body of the ranged request
+  def request_range(range)
+    http = Net::HTTP.start(@uri.hostname, @uri.port)
+    request = Net::HTTP::Get.new(@uri)
+    request.range = range
+    response = http.request(request)
+    case response.code
+    when "206", "200"
+      response.body
+    else
+      raise "Remote at #{@uri} replied with code #{response.code}"
+    end
+  end
+
+  # For working with S3 it is a better idea to perform a GET request for one byte, since doing a HEAD
+  # request needs a different permission - and standard GET presigned URLs are not allowed to perform it
+  #
+  # @return [Integer] the size of the remote resource, parsed either from Content-Length or Content-Range header
+  def request_object_size
+    http = Net::HTTP.start(@uri.hostname, @uri.port)
+    request = Net::HTTP::Get.new(@uri)
+    request.range = 0..0
+    response = http.request(request)
+    case response.code
+    when "206"
+      content_range_header_value = response["Content-Range"]
+      content_range_header_value.split("/").last.to_i
+    when "200"
+      response["Content-Length"].to_i
+    else
+      raise "Remote at #{@uri} replied with code #{response.code}"
+    end
+  end
+
+  private
+
+  def clamp(a, b, c)
+    return a if b < a
+    return c if b > c
+    b
+  end
+end

data/lib/zip_kit/remote_uncap.rb

@@ -0,0 +1,22 @@
+# 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
+# use the `Range:` HTTP headers to download those entries separately.
+#
+# Please read the security warning in `FileReader` _VERY CAREFULLY_
+# before you use this module.
+module ZipKit::RemoteUncap
+  # @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
+  # {ZipKit::FileReader} when reading
+  # @return [Array<ZipKit::FileReader::ZipEntry>] metadata about the
+  # files within the remote archive
+  def self.files_within_zip_at(uri, reader_class: ZipKit::FileReader, **options_for_zip_reader)
+    fake_io = ZipKit::RemoteIO.new(uri)
+    reader = reader_class.new
+    reader.read_zip_structure(io: fake_io, **options_for_zip_reader)
+  end
+end

data/lib/zip_kit/size_estimator.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# Helps to estimate archive sizes
+class ZipKit::SizeEstimator
+  require_relative "streamer"
+
+  # 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_deflated_entry(filename: "family.tif",
+  #               uncompressed_size: 89281911, compressed_size: 121908)
+  #     end
+  #
+  # @param kwargs_for_streamer_new Any options to pass to Streamer, see {Streamer#initialize}
+  # @return [Integer] the size of the resulting archive, in bytes
+  # @yield [SizeEstimator] the estimator
+  def self.estimate(**kwargs_for_streamer_new)
+    streamer = ZipKit::Streamer.new(ZipKit::NullWriter, **kwargs_for_streamer_new)
+    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
+  # @return self
+  def add_stored_entry(filename:, size:, use_data_descriptor: false)
+    @streamer.add_stored_entry(filename: filename,
+      crc32: 0,
+      size: size,
+      use_data_descriptor: use_data_descriptor)
+    @streamer.simulate_write(size)
+    if use_data_descriptor
+      @streamer.update_last_entry_and_write_data_descriptor(crc32: 0, compressed_size: size, uncompressed_size: size)
+    end
+    self
+  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 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
+  # @return self
+  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)
+    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
+
+  # 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_empty_directory(dirname: dirname)
+    self
+  end
+end