zip_kit 6.0.1 → 6.2.0

data/lib/zip_kit/zip_writer.rb

@@ -27,7 +27,7 @@
 class ZipKit::ZipWriter
   FOUR_BYTE_MAX_UINT = 0xFFFFFFFF
   TWO_BYTE_MAX_UINT = 0xFFFF
-  ZIP_TRICKS_COMMENT = "Written using ZipKit %<version>s" % {version: ZipKit::VERSION}
+  ZIP_KIT_COMMENT = "Written using ZipKit %<version>s" % {version: ZipKit::VERSION}
   VERSION_MADE_BY = 52
   VERSION_NEEDED_TO_EXTRACT = 20
   VERSION_NEEDED_TO_EXTRACT_ZIP64 = 45
@@ -58,7 +58,7 @@ class ZipKit::ZipWriter
     :C_UINT4,
     :C_UINT2,
     :C_UINT8,
-    :ZIP_TRICKS_COMMENT
+    :ZIP_KIT_COMMENT
 
   # Writes the local file header, that precedes the actual file _data_.
   #
@@ -74,29 +74,41 @@ class ZipKit::ZipWriter
   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
+    # local file header signature     4 bytes  (0x04034b50)
+    io << [0x04034b50].pack(C_UINT4)
+    # version needed to extract       2 bytes
+    io << if requires_zip64
       [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
+    # general purpose bit flag        2 bytes
+    io << [gp_flags].pack(C_UINT2)
+    # compression method              2 bytes
+    io << [storage_mode].pack(C_UINT2)
+    # last mod file time              2 bytes
+    io << [to_binary_dos_time(mtime)].pack(C_UINT2)
+    # last mod file date              2 bytes
+    io << [to_binary_dos_date(mtime)].pack(C_UINT2)
+    # crc-32                          4 bytes
+    io << [crc32].pack(C_UINT4)
 
     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
+      # compressed size              4 bytes
+      io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4)
+      # uncompressed size            4 bytes
+      io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4)
     else
-      io << [compressed_size].pack(C_UINT4) # compressed size              4 bytes
-      io << [uncompressed_size].pack(C_UINT4) # uncompressed size            4 bytes
+      # compressed size              4 bytes
+      io << [compressed_size].pack(C_UINT4)
+      # uncompressed size            4 bytes
+      io << [uncompressed_size].pack(C_UINT4)
     end
 
     # Filename should not be longer than 0xFFFF otherwise this wont fit here
-    io << [filename.bytesize].pack(C_UINT2) # file name length             2 bytes
+    # file name length             2 bytes
+    io << [filename.bytesize].pack(C_UINT2)
 
     extra_fields = StringIO.new
 
@@ -109,9 +121,13 @@ class ZipKit::ZipWriter
     end
     extra_fields << timestamp_extra_for_local_file_header(mtime)
 
-    io << [extra_fields.size].pack(C_UINT2) # extra field length              2 bytes
+    # extra field length              2 bytes
+    io << [extra_fields.size].pack(C_UINT2)
 
-    io << filename # file name (variable size)
+    # file name (variable size)
+    io << filename
+
+    # Contents of the extra fields (variable size)
     io << extra_fields.string
   end
 
@@ -125,7 +141,7 @@ class ZipKit::ZipWriter
   # @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
+  # @param unix_permissions[Integer] 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:,
@@ -142,30 +158,42 @@ class ZipKit::ZipWriter
     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
+    # central file header signature   4 bytes  (0x02014b50)
+    io << [0x02014b50].pack(C_UINT4)
+    # version made by                 2 bytes
+    io << MADE_BY_SIGNATURE
+
+    # version needed to extract       2 bytes
     io << if add_zip64
-      [VERSION_NEEDED_TO_EXTRACT_ZIP64].pack(C_UINT2) # version needed to extract       2 bytes
+      [VERSION_NEEDED_TO_EXTRACT_ZIP64].pack(C_UINT2)
     else
-      [VERSION_NEEDED_TO_EXTRACT].pack(C_UINT2) # version needed to extract       2 bytes
+      [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
-
+    # general purpose bit flag        2 bytes
+    io << [gp_flags].pack(C_UINT2)
+    # compression method              2 bytes
+    io << [storage_mode].pack(C_UINT2)
+    # last mod file time              2 bytes
+    io << [to_binary_dos_time(mtime)].pack(C_UINT2)
+    # last mod file date              2 bytes
+    io << [to_binary_dos_date(mtime)].pack(C_UINT2)
+    # crc-32                          4 bytes
+    io << [crc32].pack(C_UINT4)
+
+    # compressed size              4 bytes
+    # uncompressed size            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
+      io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4)
+      io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4)
     else
-      io << [compressed_size].pack(C_UINT4) # compressed size              4 bytes
-      io << [uncompressed_size].pack(C_UINT4) # uncompressed size            4 bytes
+      io << [compressed_size].pack(C_UINT4)
+      io << [uncompressed_size].pack(C_UINT4)
     end
 
     # Filename should not be longer than 0xFFFF otherwise this wont fit here
-    io << [filename.bytesize].pack(C_UINT2) # file name length                2 bytes
+    # file name length                2 bytes
+    io << [filename.bytesize].pack(C_UINT2)
 
     extra_fields = StringIO.new
     if add_zip64
@@ -175,23 +203,25 @@ class ZipKit::ZipWriter
     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
+    # extra field length              2 bytes
+    io << [extra_fields.size].pack(C_UINT2)
+    # file comment length             2 bytes
+    io << [0].pack(C_UINT2)
 
     # 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
+    # disk number start               2 bytes
+    io << if add_zip64
       [TWO_BYTE_MAX_UINT].pack(C_UINT2)
     else
       [0].pack(C_UINT2)
     end
-    io << [0].pack(C_UINT2) # internal file attributes        2 bytes
+    # internal file attributes        2 bytes
+    io << [0].pack(C_UINT2)
 
     # 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)
@@ -199,17 +229,23 @@ class ZipKit::ZipWriter
       unix_permissions ||= DEFAULT_FILE_UNIX_PERMISSIONS
       generate_external_attrs(unix_permissions, FILE_TYPE_FILE)
     end
+
+    # external file attributes        4 bytes
     io << [external_attrs].pack(C_UINT4)
 
-    io << if add_zip64 # relative offset of local header 4 bytes
+    # relative offset of local header 4 bytes
+    io << if add_zip64
       [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)
+    # file name (variable size)
+    io << filename
+    # extra field (variable size)
+    io << extra_fields.string
+    # file comment (variable size)
+    # (empty)
   end
 
   # Writes the data descriptor following the file data for a file whose local file header
@@ -222,19 +258,25 @@ class ZipKit::ZipWriter
   # @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
+    # 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
+    io << [0x08074b50].pack(C_UINT4)
+
+    # crc-32                          4 bytes
+    io << [crc32].pack(C_UINT4)
 
     # 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
+    # So also use the opportune moment to switch the entry to Zip64 if needed.
+    # We switch if either of the sizes requires ZIP64, so that both values are encoded similarly.
     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
+    # compressed size                 4 bytes, or 8 bytes for ZIP64
+    io << [compressed_size].pack(pack_spec)
+    # uncompressed size               4 bytes, or 8 bytes for ZIP64
+    io << [uncompressed_size].pack(pack_spec)
   end
 
   # Writes the "end of central directory record" (including the Zip6 salient bits if necessary)
@@ -243,9 +285,9 @@ class ZipKit::ZipWriter
   # @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)
+  # @param comment[String] the comment for the archive (defaults to ZIP_KIT_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)
+  def write_end_of_central_directory(io:, start_of_central_directory_location:, central_directory_size:, num_files_in_archive:, comment: ZIP_KIT_COMMENT)
     zip64_eocdr_offset = start_of_central_directory_location + central_directory_size
 
     zip64_required = central_directory_size > FOUR_BYTE_MAX_UINT ||
@@ -256,71 +298,88 @@ class ZipKit::ZipWriter
     # 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
+      # zip64 end of central dir signature                       4 bytes  (0x06064b50)
+      io << [0x06064b50].pack(C_UINT4)
+
+      # 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
+      io << [44].pack(C_UINT8)
+
+      # version made by                 2 bytes
+      io << MADE_BY_SIGNATURE
+      # version needed to extract       2 bytes
+      io << [VERSION_NEEDED_TO_EXTRACT_ZIP64].pack(C_UINT2)
+      # 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 << [0].pack(C_UINT4)
+      # 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
+      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
+      io << [num_files_in_archive].pack(C_UINT8)
+      # size of the central directory   8 bytes
+      io << [central_directory_size].pack(C_UINT8)
+      # offset of start of central directory with respect to
+      # the starting disk number        8 bytes
+      io << [start_of_central_directory_location].pack(C_UINT8)
+      # zip64 extensible data sector (variable size)
+      # (blank for us)
+
+      # 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
+      io << [0x07064b50].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
+      io << [0].pack(C_UINT4)
+      # 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
+      io << [zip64_eocdr_offset].pack(C_UINT8)
+      # total number of disks           4 bytes
+      io << [1].pack(C_UINT4)
     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
+    # end of central dir signature     4 bytes  (0x06054b50)
+    io << [0x06054b50].pack(C_UINT4)
+    # number of this disk              2 bytes
+    io << [0].pack(C_UINT2)
+    # number of the disk with the
     # start of the central directory 2 bytes
+    io << [0].pack(C_UINT2)
 
-    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
+    # total number of entries in the
+    # central directory on this disk   2 bytes
+    # total number of entries in
     # 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)
+      io << [TWO_BYTE_MAX_UINT].pack(C_UINT2)
     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
+      io << [num_files_in_archive].pack(C_UINT2)
+      io << [num_files_in_archive].pack(C_UINT2)
     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
+    # size of the central directory    4 bytes
+    # offset of start of central
     # directory with respect to
     # the starting disk number        4 bytes
+    if zip64_required
+      io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4)
+      io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4)
     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
+      io << [central_directory_size].pack(C_UINT4)
+      io << [start_of_central_directory_location].pack(C_UINT4)
     end
-    io << [comment.bytesize].pack(C_UINT2) # .ZIP file comment length        2 bytes
-    io << comment # .ZIP file comment       (variable size)
+    # .ZIP file comment length        2 bytes
+    io << [comment.bytesize].pack(C_UINT2)
+    # .ZIP file comment       (variable size)
+    io << comment
   end
 
   private
@@ -332,10 +391,14 @@ class ZipKit::ZipWriter
   # @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
+      # 2 bytes    Tag for this "extra" block type
+      0x0001, C_UINT2,
+      # 2 bytes    Size of this "extra" block. For us it will always be 16 (2x8)
+      16, C_UINT2,
+      # 8 bytes    Original uncompressed file size
+      uncompressed_size, C_UINT8,
+      # 8 bytes    Size of compressed data
+      compressed_size, C_UINT8
     ]
     pack_array(data_and_packspecs)
   end
@@ -377,10 +440,14 @@ class ZipKit::ZipWriter
     #       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.
+      # tag for this extra block type ("UT")
+      0x5455, C_UINT2,
+      # the size of this block (1 byte used for the Flag + 3 longs used for the timestamp)
+      (1 + 4), C_UINT2,
+      # encode a single byte
+      flags, C_CHAR,
+      # Use a signed int, not the unsigned one used by the rest of the ZIP spec.
+      mtime.utc.to_i, C_INT4
     ]
     # The atime and ctime can be omitted if not present
     pack_array(data_and_packspecs)
@@ -399,12 +466,18 @@ class ZipKit::ZipWriter
   # @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
+      # 2 bytes    Tag for this "extra" block type
+      0x0001, C_UINT2,
+      # 2 bytes    Size of this "extra" block. For us it will always be 28
+      28, C_UINT2,
+      # 8 bytes    Original uncompressed file size
+      uncompressed_size, C_UINT8,
+      # 8 bytes    Size of compressed data
+      compressed_size, C_UINT8,
+      # 8 bytes    Offset of local header record
+      local_file_header_location, C_UINT8,
+      # 4 bytes    Number of the disk on which this file starts
+      0, C_UINT4
     ]
     pack_array(data_and_packspecs)
   end
@@ -424,7 +497,10 @@ class ZipKit::ZipWriter
   #
   # 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"
+  #  [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".
+  # This might seem like a "clever optimisation" but the issue is that `pack` needs an array allocated per call, and
+  # we output very verbosely - value-by-value. This might be quite a few array allocs. Using something like this
+  # helps us save the array allocs
   def pack_array(values_to_packspecs)
     values, packspecs = values_to_packspecs.partition.each_with_index { |_, i| i.even? }
     values.pack(packspecs.join)