zip_kit 6.0.0

data/lib/zip_kit/write_and_tell.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# A tiny wrapper over any object that supports :<<.
+# Adds :tell and :advance_position_by. This is needed for write destinations
+# which do not respond to `#pos` or `#tell`. A lot of ZIP archive format parts
+# include "offsets in archive" - a byte offset from the start of file. Keeping
+# track of this value is what this object will do. It also allows "advancing"
+# this value if data gets written using a bypass (such as `IO#sendfile`)
+class ZipKit::WriteAndTell
+  include ZipKit::WriteShovel
+
+  def initialize(io)
+    @io = io
+    @pos = 0
+    # Some objects (such as ActionController::Live `stream` object) cannot be "pushed" into
+    # using the :<< operator, but only support `write`. For ease we add a small shim in that case instead of having
+    # the user abstract it themselves.
+    @use_write = !io.respond_to?(:<<)
+  end
+
+  def <<(bytes)
+    return self if bytes.nil?
+    if @use_write
+      @io.write(bytes.b)
+    else
+      @io << bytes.b
+    end
+
+    @pos += bytes.bytesize
+    self
+  end
+
+  def advance_position_by(num_bytes)
+    @pos += num_bytes
+  end
+
+  def tell
+    @pos
+  end
+end

data/lib/zip_kit/write_buffer.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+# Some operations (such as CRC32) benefit when they are performed
+# on larger chunks of data. In certain use cases, it is possible that
+# the consumer of ZipKit is going to be writing small chunks
+# in rapid succession, so CRC32 is going to have to perform a lot of
+# CRC32 combine operations - and this adds up. Since the CRC32 value
+# is usually not needed until the complete output has completed
+# we can buffer at least some amount of data before computing CRC32 over it.
+# We also use this buffer for output via Rack, where some amount of buffering
+# helps reduce the number of syscalls made by the webserver. ZipKit performs
+# lots of very small writes, and some degree of speedup (about 20%) can be achieved
+# with a buffer of a few KB.
+#
+# Note that there is no guarantee that the write buffer is going to flush at or above
+# the given `buffer_size`, because for writes which exceed the buffer size it will
+# first `flush` and then write through the oversized chunk, without buffering it. This
+# helps conserve memory. Also note that the buffer will *not* duplicate strings for you
+# and *will* yield the same buffer String over and over, so if you are storing it in an
+# Array you might need to duplicate it.
+#
+# Note also that the WriteBuffer assumes that the object it `<<`-writes into is going
+# to **consume** in some way the string that it passes in. After the `<<` method returns,
+# the WriteBuffer will be cleared, and it passes the same String reference on every call
+# to `<<`. Therefore, if you need to retain the output of the WriteBuffer in, say, an Array,
+# you might need to `.dup` the `String` it gives you.
+class ZipKit::WriteBuffer
+  # Creates a new WriteBuffer bypassing into a given writable object
+  #
+  # @param writable[#<<] An object that responds to `#<<` with a String as argument
+  # @param buffer_size[Integer] How many bytes to buffer
+  def initialize(writable, buffer_size)
+    # Allocating the buffer using a zero-padded String as a variation
+    # on using capacity:, which JRuby apparently does not like very much. The
+    # desire here is that the buffer doesn't have to be resized during the lifetime
+    # of the object.
+    @buf = ("\0".b * (buffer_size * 2)).clear
+    @buffer_size = buffer_size
+    @writable = writable
+  end
+
+  # Appends the given data to the write buffer, and flushes the buffer into the
+  # writable if the buffer size exceeds the `buffer_size` given at initialization
+  #
+  # @param data[String] data to be written
+  # @return self
+  def <<(data)
+    if data.bytesize >= @buffer_size
+      flush unless @buf.empty? # <- this is were we can output less than @buffer_size
+      @writable << data
+    else
+      @buf << data
+      flush if @buf.bytesize >= @buffer_size
+    end
+    self
+  end
+
+  # Explicitly flushes the buffer if it contains anything
+  #
+  # @return self
+  def flush
+    unless @buf.empty?
+      @writable << @buf
+      @buf.clear
+    end
+    self
+  end
+
+  # `flush!` was renamed to `flush` but we preserve this method for backwards compatibility
+  alias_method :flush!, :flush
+end

data/lib/zip_kit/write_shovel.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# A lot of objects in ZipKit accept bytes that may be sent
+# to the `<<` operator (the "shovel" operator). This is in the tradition
+# of late Jim Weirich and his Builder gem. In [this presentation](https://youtu.be/1BVFlvRPZVM?t=2403)
+# he justifies this design very eloquently. In ZipKit we follow this example.
+# However, there is a number of methods in Ruby - including the standard library -
+# which expect your object to implement the `write` method instead. Since the `write`
+# method can be expressed in terms of the `<<` method, why not allow all ZipKit
+# "IO-ish" things to also respond to `write`? This is what this module does.
+# Jim would be proud. We miss you, Jim.
+module ZipKit::WriteShovel
+  # Writes the given data to the output stream. Allows the object to be used as
+  # a target for `IO.copy_stream(from, to)`
+  #
+  # @param d[String] the binary string to write (part of the uncompressed file)
+  # @return [Fixnum] the number of bytes written
+  def write(bytes)
+    self << bytes
+    bytes.bytesize
+  end
+end

data/lib/zip_kit/zip_writer.rb

@@ -0,0 +1,436 @@
+# frozen_string_literal: true
+
+# A low-level ZIP file data writer. You can use it to write out various headers and central directory elements
+# separately. The class handles the actual encoding of the data according to the ZIP format APPNOTE document.
+#
+# The primary reason the writer is a separate object is because it is kept stateless. That is, all the data that
+# is needed for writing a piece of the ZIP (say, the EOCD record, or a data descriptor) can be written
+# without depending on data available elsewhere. This makes the writer very easy to test, since each of
+# it's methods outputs something that only depends on the method's arguments. For example, we use this
+# to test writing Zip64 files which, when tested in a streaming fashion, would need tricky IO stubs
+# to wind IO objects back and forth by large offsets. Instead, we can just write out the EOCD record
+# with given offsets as arguments.
+#
+# Since some methods need a lot of data about the entity being written, everything is passed via
+# keyword arguments - this way it is much less likely that you can make a mistake writing something.
+#
+# Another reason for having a separate Writer is that most ZIP libraries attach the methods for
+# writing out the file headers to some sort of Entry object, which represents a file within the ZIP.
+# However, when you are diagnosing issues with the ZIP files you produce, you actually want to have
+# absolute _most_ of the code responsible for writing the actual encoded bytes available to you on
+# one screen. Altering or checking that code then becomes much, much easier. The methods doing the
+# writing are also intentionally left very verbose - so that you can follow what is happening at
+# all times.
+#
+# All methods of the writer accept anything that responds to `<<` as `io` argument - you can use
+# that to output to String objects, or to output to Arrays that you can later join together.
+class ZipKit::ZipWriter
+  FOUR_BYTE_MAX_UINT = 0xFFFFFFFF
+  TWO_BYTE_MAX_UINT = 0xFFFF
+  ZIP_TRICKS_COMMENT = "Written using ZipKit %<version>s" % {version: ZipKit::VERSION}
+  VERSION_MADE_BY = 52
+  VERSION_NEEDED_TO_EXTRACT = 20
+  VERSION_NEEDED_TO_EXTRACT_ZIP64 = 45
+  DEFAULT_FILE_UNIX_PERMISSIONS = 0o644
+  DEFAULT_DIRECTORY_UNIX_PERMISSIONS = 0o755
+  FILE_TYPE_FILE = 0o10
+  FILE_TYPE_DIRECTORY = 0o04
+  MADE_BY_SIGNATURE = begin
+    # A combination of the VERSION_MADE_BY low byte and the OS type high byte
+    os_type = 3 # UNIX
+    [VERSION_MADE_BY, os_type].pack("CC")
+  end
+
+  C_UINT4 = "V" # Encode a 4-byte unsigned little-endian uint
+  C_UINT2 = "v" # Encode a 2-byte unsigned little-endian uint
+  C_UINT8 = "Q<" # Encode an 8-byte unsigned little-endian uint
+  C_CHAR = "C" # For bit-encoded strings
+  C_INT4 = "l<" # Encode a 4-byte signed little-endian int
+
+  private_constant :FOUR_BYTE_MAX_UINT,
+    :TWO_BYTE_MAX_UINT,
+    :VERSION_MADE_BY,
+    :VERSION_NEEDED_TO_EXTRACT,
+    :VERSION_NEEDED_TO_EXTRACT_ZIP64,
+    :FILE_TYPE_FILE,
+    :FILE_TYPE_DIRECTORY,
+    :MADE_BY_SIGNATURE,
+    :C_UINT4,
+    :C_UINT2,
+    :C_UINT8,
+    :ZIP_TRICKS_COMMENT
+
+  # Writes the local file header, that precedes the actual file _data_.
+  #
+  # @param io[#<<] the buffer to write the local file header to
+  # @param filename[String]  the name of the file in the archive
+  # @param compressed_size[Fixnum]    The size of the compressed (or stored) data - how much space it uses in the ZIP
+  # @param uncompressed_size[Fixnum]  The size of the file once extracted
+  # @param crc32[Fixnum] The CRC32 checksum of the file
+  # @param mtime[Time]  the modification time to be recorded in the ZIP
+  # @param gp_flags[Fixnum] bit-packed general purpose flags
+  # @param storage_mode[Fixnum] 8 for deflated, 0 for stored...
+  # @return [void]
+  def write_local_file_header(io:, filename:, compressed_size:, uncompressed_size:, crc32:, gp_flags:, mtime:, storage_mode:)
+    requires_zip64 = compressed_size > FOUR_BYTE_MAX_UINT || uncompressed_size > FOUR_BYTE_MAX_UINT
+
+    io << [0x04034b50].pack(C_UINT4) # local file header signature     4 bytes  (0x04034b50)
+    io << if requires_zip64 # version needed to extract       2 bytes
+      [VERSION_NEEDED_TO_EXTRACT_ZIP64].pack(C_UINT2)
+    else
+      [VERSION_NEEDED_TO_EXTRACT].pack(C_UINT2)
+    end
+
+    io << [gp_flags].pack(C_UINT2) # general purpose bit flag        2 bytes
+    io << [storage_mode].pack(C_UINT2) # compression method              2 bytes
+    io << [to_binary_dos_time(mtime)].pack(C_UINT2) # last mod file time              2 bytes
+    io << [to_binary_dos_date(mtime)].pack(C_UINT2) # last mod file date              2 bytes
+    io << [crc32].pack(C_UINT4) # crc-32                          4 bytes
+
+    if requires_zip64
+      io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4) # compressed size              4 bytes
+      io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4) # uncompressed size            4 bytes
+    else
+      io << [compressed_size].pack(C_UINT4) # compressed size              4 bytes
+      io << [uncompressed_size].pack(C_UINT4) # uncompressed size            4 bytes
+    end
+
+    # Filename should not be longer than 0xFFFF otherwise this wont fit here
+    io << [filename.bytesize].pack(C_UINT2) # file name length             2 bytes
+
+    extra_fields = StringIO.new
+
+    # Interesting tidbit:
+    # https://social.technet.microsoft.com/Forums/windows/en-US/6a60399f-2879-4859-b7ab-6ddd08a70948
+    # TL;DR of it is: Windows 7 Explorer _will_ open Zip64 entries. However, it desires to have the
+    # Zip64 extra field as _the first_ extra field.
+    if requires_zip64
+      extra_fields << zip_64_extra_for_local_file_header(compressed_size: compressed_size, uncompressed_size: uncompressed_size)
+    end
+    extra_fields << timestamp_extra_for_local_file_header(mtime)
+
+    io << [extra_fields.size].pack(C_UINT2) # extra field length              2 bytes
+
+    io << filename # file name (variable size)
+    io << extra_fields.string
+  end
+
+  # Writes the file header for the central directory, for a particular file in the archive. When writing out this data,
+  # ensure that the CRC32 and both sizes (compressed/uncompressed) are correct for the entry in question.
+  #
+  # @param io[#<<] the buffer to write the local file header to
+  # @param filename[String]  the name of the file in the archive
+  # @param compressed_size[Fixnum]    The size of the compressed (or stored) data - how much space it uses in the ZIP
+  # @param uncompressed_size[Fixnum]  The size of the file once extracted
+  # @param crc32[Fixnum] The CRC32 checksum of the file
+  # @param mtime[Time]  the modification time to be recorded in the ZIP
+  # @param gp_flags[Fixnum] bit-packed general purpose flags
+  # @param unix_permissions[Fixnum?] the permissions for the file, or nil for the default to be used
+  # @return [void]
+  def write_central_directory_file_header(io:,
+    local_file_header_location:,
+    gp_flags:,
+    storage_mode:,
+    compressed_size:,
+    uncompressed_size:,
+    mtime:,
+    crc32:,
+    filename:,
+    unix_permissions: nil)
+    # At this point if the header begins somewhere beyound 0xFFFFFFFF we _have_ to record the offset
+    # of the local file header as a zip64 extra field, so we give up, give in, you loose, love will always win...
+    add_zip64 = (local_file_header_location > FOUR_BYTE_MAX_UINT) ||
+      (compressed_size > FOUR_BYTE_MAX_UINT) || (uncompressed_size > FOUR_BYTE_MAX_UINT)
+
+    io << [0x02014b50].pack(C_UINT4) # central file header signature   4 bytes  (0x02014b50)
+    io << MADE_BY_SIGNATURE # version made by                 2 bytes
+    io << if add_zip64
+      [VERSION_NEEDED_TO_EXTRACT_ZIP64].pack(C_UINT2) # version needed to extract       2 bytes
+    else
+      [VERSION_NEEDED_TO_EXTRACT].pack(C_UINT2) # version needed to extract       2 bytes
+    end
+
+    io << [gp_flags].pack(C_UINT2) # general purpose bit flag        2 bytes
+    io << [storage_mode].pack(C_UINT2) # compression method              2 bytes
+    io << [to_binary_dos_time(mtime)].pack(C_UINT2) # last mod file time              2 bytes
+    io << [to_binary_dos_date(mtime)].pack(C_UINT2) # last mod file date              2 bytes
+    io << [crc32].pack(C_UINT4) # crc-32                          4 bytes
+
+    if add_zip64
+      io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4) # compressed size              4 bytes
+      io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4) # uncompressed size            4 bytes
+    else
+      io << [compressed_size].pack(C_UINT4) # compressed size              4 bytes
+      io << [uncompressed_size].pack(C_UINT4) # uncompressed size            4 bytes
+    end
+
+    # Filename should not be longer than 0xFFFF otherwise this wont fit here
+    io << [filename.bytesize].pack(C_UINT2) # file name length                2 bytes
+
+    extra_fields = StringIO.new
+    if add_zip64
+      extra_fields << zip_64_extra_for_central_directory_file_header(local_file_header_location: local_file_header_location,
+        compressed_size: compressed_size,
+        uncompressed_size: uncompressed_size)
+    end
+    extra_fields << timestamp_extra_for_central_directory_entry(mtime)
+
+    io << [extra_fields.size].pack(C_UINT2) # extra field length              2 bytes
+
+    io << [0].pack(C_UINT2) # file comment length             2 bytes
+
+    # For The Unarchiver < 3.11.1 this field has to be set to the overflow value if zip64 is used
+    # because otherwise it does not properly advance the pointer when reading the Zip64 extra field
+    # https://bitbucket.org/WAHa_06x36/theunarchiver/pull-requests/2/bug-fix-for-zip64-extra-field-parser/diff
+    io << if add_zip64 # disk number start               2 bytes
+      [TWO_BYTE_MAX_UINT].pack(C_UINT2)
+    else
+      [0].pack(C_UINT2)
+    end
+    io << [0].pack(C_UINT2) # internal file attributes        2 bytes
+
+    # Because the add_empty_directory method will create a directory with a trailing "/",
+    # this check can be used to assign proper permissions to the created directory.
+    # external file attributes        4 bytes
+    external_attrs = if filename.end_with?("/")
+      unix_permissions ||= DEFAULT_DIRECTORY_UNIX_PERMISSIONS
+      generate_external_attrs(unix_permissions, FILE_TYPE_DIRECTORY)
+    else
+      unix_permissions ||= DEFAULT_FILE_UNIX_PERMISSIONS
+      generate_external_attrs(unix_permissions, FILE_TYPE_FILE)
+    end
+    io << [external_attrs].pack(C_UINT4)
+
+    io << if add_zip64 # relative offset of local header 4 bytes
+      [FOUR_BYTE_MAX_UINT].pack(C_UINT4)
+    else
+      [local_file_header_location].pack(C_UINT4)
+    end
+
+    io << filename # file name (variable size)
+    io << extra_fields.string # extra field (variable size)
+    # (empty)                                          # file comment (variable size)
+  end
+
+  # Writes the data descriptor following the file data for a file whose local file header
+  # was written with general-purpose flag bit 3 set. If the one of the sizes exceeds the Zip64 threshold,
+  # the data descriptor will have the sizes written out as 8-byte values instead of 4-byte values.
+  #
+  # @param io[#<<] the buffer to write the local file header to
+  # @param crc32[Fixnum]    The CRC32 checksum of the file
+  # @param compressed_size[Fixnum]    The size of the compressed (or stored) data - how much space it uses in the ZIP
+  # @param uncompressed_size[Fixnum]  The size of the file once extracted
+  # @return [void]
+  def write_data_descriptor(io:, compressed_size:, uncompressed_size:, crc32:)
+    io << [0x08074b50].pack(C_UINT4) # Although not originally assigned a signature, the value
+    # 0x08074b50 has commonly been adopted as a signature value
+    # for the data descriptor record.
+    io << [crc32].pack(C_UINT4) # crc-32                          4 bytes
+
+    # If one of the sizes is above 0xFFFFFFF use ZIP64 lengths (8 bytes) instead. A good unarchiver
+    # will decide to unpack it as such if it finds the Zip64 extra for the file in the central directory.
+    # So also use the opportune moment to switch the entry to Zip64 if needed
+    requires_zip64 = compressed_size > FOUR_BYTE_MAX_UINT || uncompressed_size > FOUR_BYTE_MAX_UINT
+    pack_spec = requires_zip64 ? C_UINT8 : C_UINT4
+
+    io << [compressed_size].pack(pack_spec) # compressed size                 4 bytes, or 8 bytes for ZIP64
+    io << [uncompressed_size].pack(pack_spec) # uncompressed size               4 bytes, or 8 bytes for ZIP64
+  end
+
+  # Writes the "end of central directory record" (including the Zip6 salient bits if necessary)
+  #
+  # @param io[#<<] the buffer to write the central directory to.
+  # @param start_of_central_directory_location[Fixnum] byte offset of the start of central directory form the beginning of ZIP file
+  # @param central_directory_size[Fixnum] the size of the central directory (only file headers) in bytes
+  # @param num_files_in_archive[Fixnum] How many files the archive contains
+  # @param comment[String] the comment for the archive (defaults to ZIP_TRICKS_COMMENT)
+  # @return [void]
+  def write_end_of_central_directory(io:, start_of_central_directory_location:, central_directory_size:, num_files_in_archive:, comment: ZIP_TRICKS_COMMENT)
+    zip64_eocdr_offset = start_of_central_directory_location + central_directory_size
+
+    zip64_required = central_directory_size > FOUR_BYTE_MAX_UINT ||
+      start_of_central_directory_location > FOUR_BYTE_MAX_UINT ||
+      zip64_eocdr_offset > FOUR_BYTE_MAX_UINT ||
+      num_files_in_archive > TWO_BYTE_MAX_UINT
+
+    # Then, if zip64 is used
+    if zip64_required
+      # [zip64 end of central directory record]
+      # zip64 end of central dir
+      io << [0x06064b50].pack(C_UINT4) # signature                       4 bytes  (0x06064b50)
+      io << [44].pack(C_UINT8) # size of zip64 end of central
+      # directory record                8 bytes
+      # (this is ex. the 12 bytes of the signature and the size value itself).
+      # Without the extensible data sector (which we are not using)
+      # it is always 44 bytes.
+      io << MADE_BY_SIGNATURE # version made by                 2 bytes
+      io << [VERSION_NEEDED_TO_EXTRACT_ZIP64].pack(C_UINT2) # version needed to extract       2 bytes
+      io << [0].pack(C_UINT4) # number of this disk             4 bytes
+      io << [0].pack(C_UINT4) # number of the disk with the
+      # start of the central directory  4 bytes
+      io << [num_files_in_archive].pack(C_UINT8) # total number of entries in the
+      # central directory on this disk  8 bytes
+      io << [num_files_in_archive].pack(C_UINT8) # total number of entries in the
+      # central directory               8 bytes
+      io << [central_directory_size].pack(C_UINT8) # size of the central directory   8 bytes
+      # offset of start of central
+      # directory with respect to
+      io << [start_of_central_directory_location].pack(C_UINT8) # the starting disk number        8 bytes
+      # zip64 extensible data sector    (variable size), blank for us
+
+      # [zip64 end of central directory locator]
+      io << [0x07064b50].pack(C_UINT4) # zip64 end of central dir locator
+      # signature                       4 bytes  (0x07064b50)
+      io << [0].pack(C_UINT4) # number of the disk with the
+      # start of the zip64 end of
+      # central directory               4 bytes
+      io << [zip64_eocdr_offset].pack(C_UINT8) # relative offset of the zip64
+      # end of central directory record 8 bytes
+      # (note: "relative" is actually "from the start of the file")
+      io << [1].pack(C_UINT4) # total number of disks           4 bytes
+    end
+
+    # Then the end of central directory record:
+    io << [0x06054b50].pack(C_UINT4) # end of central dir signature     4 bytes  (0x06054b50)
+    io << [0].pack(C_UINT2) # number of this disk              2 bytes
+    io << [0].pack(C_UINT2) # number of the disk with the
+    # start of the central directory 2 bytes
+
+    if zip64_required # the number of entries will be read from the zip64 part of the central directory
+      io << [TWO_BYTE_MAX_UINT].pack(C_UINT2) # total number of entries in the
+      # central directory on this disk   2 bytes
+      io << [TWO_BYTE_MAX_UINT].pack(C_UINT2) # total number of entries in
+    # the central directory            2 bytes
+    else
+      io << [num_files_in_archive].pack(C_UINT2) # total number of entries in the
+      # central directory on this disk   2 bytes
+      io << [num_files_in_archive].pack(C_UINT2) # total number of entries in
+      # the central directory            2 bytes
+    end
+
+    if zip64_required
+      io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4) # size of the central directory    4 bytes
+      io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4) # offset of start of central
+    # directory with respect to
+    # the starting disk number        4 bytes
+    else
+      io << [central_directory_size].pack(C_UINT4) # size of the central directory    4 bytes
+      io << [start_of_central_directory_location].pack(C_UINT4) # offset of start of central
+      # directory with respect to
+      # the starting disk number        4 bytes
+    end
+    io << [comment.bytesize].pack(C_UINT2) # .ZIP file comment length        2 bytes
+    io << comment # .ZIP file comment       (variable size)
+  end
+
+  private
+
+  # Writes the Zip64 extra field for the local file header. Will be used by `write_local_file_header` when any sizes given to it warrant that.
+  #
+  # @param compressed_size[Fixnum]    The size of the compressed (or stored) data - how much space it uses in the ZIP
+  # @param uncompressed_size[Fixnum]  The size of the file once extracted
+  # @return [String]
+  def zip_64_extra_for_local_file_header(compressed_size:, uncompressed_size:)
+    data_and_packspecs = [
+      0x0001, C_UINT2, # 2 bytes    Tag for this "extra" block type
+      16, C_UINT2, # 2 bytes    Size of this "extra" block. For us it will always be 16 (2x8)
+      uncompressed_size, C_UINT8, # 8 bytes    Original uncompressed file size
+      compressed_size, C_UINT8 # 8 bytes    Size of compressed data
+    ]
+    pack_array(data_and_packspecs)
+  end
+
+  # Writes the extended timestamp information field for local headers.
+  #
+  # The spec defines 2
+  # different formats - the one for the local file header can also accomodate the
+  # atime and ctime, whereas the one for the central directory can only take
+  # the mtime - and refers the reader to the local header extra to obtain the
+  # remaining times
+  def timestamp_extra_for_local_file_header(mtime)
+    #         Local-header version:
+    #
+    #         Value         Size        Description
+    #         -----         ----        -----------
+    # (time)  0x5455        Short       tag for this extra block type ("UT")
+    #         TSize         Short       total data size for this block
+    #         Flags         Byte        info bits
+    #         (ModTime)     Long        time of last modification (UTC/GMT)
+    #         (AcTime)      Long        time of last access (UTC/GMT)
+    #         (CrTime)      Long        time of original creation (UTC/GMT)
+    #
+    #         Central-header version:
+    #
+    #         Value         Size        Description
+    #         -----         ----        -----------
+    # (time)  0x5455        Short       tag for this extra block type ("UT")
+    #         TSize         Short       total data size for this block
+    #         Flags         Byte        info bits (refers to local header!)
+    #         (ModTime)     Long        time of last modification (UTC/GMT)
+    #
+    # The lower three bits of Flags in both headers indicate which time-
+    #       stamps are present in the LOCAL extra field:
+    #
+    #       bit 0           if set, modification time is present
+    #       bit 1           if set, access time is present
+    #       bit 2           if set, creation time is present
+    #       bits 3-7        reserved for additional timestamps; not set
+    flags = 0b00000001 # Set the lowest bit only, to indicate that only mtime is present
+    data_and_packspecs = [
+      0x5455, C_UINT2, # tag for this extra block type ("UT")
+      (1 + 4), C_UINT2, # the size of this block (1 byte used for the Flag + 3 longs used for the timestamp)
+      flags, C_CHAR, # encode a single byte
+      mtime.utc.to_i, C_INT4 # Use a signed int, not the unsigned one used by the rest of the ZIP spec.
+    ]
+    # The atime and ctime can be omitted if not present
+    pack_array(data_and_packspecs)
+  end
+
+  # Since we do not supply atime or ctime, the contents of the two extra fields (central dir and local header)
+  # is exactly the same, so we can use a method alias.
+  alias_method :timestamp_extra_for_central_directory_entry, :timestamp_extra_for_local_file_header
+
+  # Writes the Zip64 extra field for the central directory header.It differs from the extra used in the local file header because it
+  # also contains the location of the local file header in the ZIP as an 8-byte int.
+  #
+  # @param compressed_size[Fixnum]    The size of the compressed (or stored) data - how much space it uses in the ZIP
+  # @param uncompressed_size[Fixnum]  The size of the file once extracted
+  # @param local_file_header_location[Fixnum] Byte offset of the start of the local file header from the beginning of the ZIP archive
+  # @return [String]
+  def zip_64_extra_for_central_directory_file_header(compressed_size:, uncompressed_size:, local_file_header_location:)
+    data_and_packspecs = [
+      0x0001, C_UINT2, # 2 bytes    Tag for this "extra" block type
+      28, C_UINT2, # 2 bytes    Size of this "extra" block. For us it will always be 28
+      uncompressed_size, C_UINT8, # 8 bytes    Original uncompressed file size
+      compressed_size, C_UINT8, # 8 bytes    Size of compressed data
+      local_file_header_location, C_UINT8, # 8 bytes    Offset of local header record
+      0, C_UINT4 # 4 bytes    Number of the disk on which this file starts
+    ]
+    pack_array(data_and_packspecs)
+  end
+
+  def to_binary_dos_time(t)
+    (t.sec / 2) + (t.min << 5) + (t.hour << 11)
+  end
+
+  def to_binary_dos_date(t)
+    t.day + (t.month << 5) + ((t.year - 1980) << 9)
+  end
+
+  # Unzips a given array of tuples of "numeric value, pack specifier" and then packs all the odd
+  # values using specifiers from all the even values. It is harder to explain than to show:
+  #
+  #   pack_array([1, 'V', 2, 'v', 148, 'v]) #=> "\x01\x00\x00\x00\x02\x00\x94\x00"
+  #
+  # will do the following two transforms:
+  #
+  #  [1, 'V', 2, 'v', 148, 'v] -> [1,2,148], ['V','v','v'] -> [1,2,148].pack('Vvv') -> "\x01\x00\x00\x00\x02\x00\x94\x00"
+  def pack_array(values_to_packspecs)
+    values, packspecs = values_to_packspecs.partition.each_with_index { |_, i| i.even? }
+    values.pack(packspecs.join)
+  end
+
+  def generate_external_attrs(unix_permissions_int, file_type_int)
+    (file_type_int << 12 | (unix_permissions_int & 0o7777)) << 16
+  end
+end

data/lib/zip_kit.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module ZipKit
+  autoload :OutputEnumerator, File.dirname(__FILE__) + "/zip_kit/rack_body.rb"
+  autoload :RailsStreaming, File.dirname(__FILE__) + "/zip_kit/rails_streaming.rb"
+  autoload :ZipWriter, File.dirname(__FILE__) + "/zip_kit/zip_writer.rb"
+  autoload :RemoteIO, File.dirname(__FILE__) + "/zip_kit/remote_io.rb"
+  autoload :NullWriter, File.dirname(__FILE__) + "/zip_kit/null_writer.rb"
+  autoload :OutputEnumerator, File.dirname(__FILE__) + "/zip_kit/output_enumerator.rb"
+  autoload :BlockDeflate, File.dirname(__FILE__) + "/zip_kit/block_deflate.rb"
+  autoload :WriteAndTell, File.dirname(__FILE__) + "/zip_kit/write_and_tell.rb"
+  autoload :RemoteUncap, File.dirname(__FILE__) + "/zip_kit/remote_uncap.rb"
+  autoload :FileReader, File.dirname(__FILE__) + "/zip_kit/file_reader.rb"
+  autoload :UniquifyFilename, File.dirname(__FILE__) + "/zip_kit/uniquify_filename.rb"
+  autoload :SizeEstimator, File.dirname(__FILE__) + "/zip_kit/size_estimator.rb"
+  autoload :Streamer, File.dirname(__FILE__) + "/zip_kit/streamer.rb"
+  autoload :PathSet, File.dirname(__FILE__) + "/zip_kit/path_set.rb"
+  autoload :StreamCRC32, File.dirname(__FILE__) + "/zip_kit/stream_crc32.rb"
+  autoload :BlockWrite, File.dirname(__FILE__) + "/zip_kit/block_write.rb"
+  autoload :WriteBuffer, File.dirname(__FILE__) + "/zip_kit/write_buffer.rb"
+  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"
+end

data/zip_kit.gemspec

@@ -0,0 +1,41 @@
+lib = File.expand_path("../lib", __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require "zip_kit/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "zip_kit"
+  spec.version = ZipKit::VERSION
+  spec.authors = ["Julik Tarkhanov", "Noah Berman", "Dmitry Tymchuk", "David Bosveld", "Felix Bünemann"]
+  spec.email = ["me@julik.nl"]
+  spec.required_ruby_version = ">= 2.6.0"
+
+  spec.summary = "Stream out ZIP files from Ruby"
+  spec.description = "Stream out ZIP files from Ruby"
+  spec.homepage = "https://github.com/julik/zip_kit"
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features|gemfiles)/})
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler"
+  spec.add_development_dependency "rubyzip", "~> 1"
+
+  spec.add_development_dependency "rack" # For tests where we spin up a server
+  spec.add_development_dependency "rake", "~> 12.2"
+  spec.add_development_dependency "rspec", "~> 3"
+  spec.add_development_dependency "rspec-mocks", "~> 3.10", ">= 3.10.2" # ruby 3 compatibility
+  spec.add_development_dependency "complexity_assert"
+  spec.add_development_dependency "coderay"
+  spec.add_development_dependency "benchmark-ips"
+  spec.add_development_dependency "allocation_stats", "~> 0.1.5"
+  spec.add_development_dependency "yard", "~> 0.9"
+  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 "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
+end