zip_tricks 5.1.0 → 5.6.0

data/lib/zip_tricks/streamer/deflated_writer.rb

@@ -4,13 +4,6 @@
 # registers data passing through it in a CRC32 checksum calculator. Is made to be completely
 # interchangeable with the StoredWriter in terms of interface.
 class ZipTricks::Streamer::DeflatedWriter
-  # After how many bytes of incoming data the deflater for the
-  # contents must be flushed. This is done to prevent unreasonable
-  # memory use when archiving large files, and to ensure we write to
-  # the socket often enough while still maintaining acceptable
-  # compression
-  FLUSH_EVERY_N_BYTES = 1024 * 1024 * 5
-
   # The amount of bytes we will buffer before computing the intermediate
   # CRC32 checksums. Benchmarks show that the optimum is 64KB (see
   # `bench/buffered_crc32_bench.rb), if that is exceeded Zlib is going
@@ -18,11 +11,10 @@ class ZipTricks::Streamer::DeflatedWriter
   CRC32_BUFFER_SIZE = 64 * 1024
 
   def initialize(io)
-    @compressed_io = ZipTricks::WriteAndTell.new(io)
-    @uncompressed_size = 0
+    @compressed_io = io
     @deflater = ::Zlib::Deflate.new(Zlib::DEFAULT_COMPRESSION, -::Zlib::MAX_WBITS)
-    @crc = ZipTricks::WriteBuffer.new(ZipTricks::StreamCRC32.new, CRC32_BUFFER_SIZE)
-    @bytes_since_last_flush = 0
+    @crc = ZipTricks::StreamCRC32.new
+    @crc_buf = ZipTricks::WriteBuffer.new(@crc, CRC32_BUFFER_SIZE)
   end
 
   # Writes the given data into the deflater, and flushes the deflater
@@ -31,13 +23,8 @@ class ZipTricks::Streamer::DeflatedWriter
   # @param data[String] data to be written
   # @return self
   def <<(data)
-    @uncompressed_size += data.bytesize
-    @bytes_since_last_flush += data.bytesize
-    @compressed_io << @deflater.deflate(data)
-    @crc << data
-
-    interim_flush
-
+    @deflater.deflate(data) { |chunk| @compressed_io << chunk }
+    @crc_buf << data
     self
   end
 
@@ -45,18 +32,12 @@ class ZipTricks::Streamer::DeflatedWriter
   # compressed data written and the CRC32 checksum. The return value
   # can be directly used as the argument to {Streamer#update_last_entry_and_write_data_descriptor}
   #
-  # @param data[String] data to be written
   # @return [Hash] a hash of `{crc32, compressed_size, uncompressed_size}`
   def finish
     @compressed_io << @deflater.finish until @deflater.finished?
-    {crc32: @crc.to_i, compressed_size: @compressed_io.tell, uncompressed_size: @uncompressed_size}
-  end
-
-  private
-
-  def interim_flush
-    return if @bytes_since_last_flush < FLUSH_EVERY_N_BYTES
-    @compressed_io << @deflater.flush
-    @bytes_since_last_flush = 0
+    @crc_buf.flush
+    {crc32: @crc.to_i, compressed_size: @deflater.total_out, uncompressed_size: @deflater.total_in}
+  ensure
+    @deflater.close
   end
 end

data/lib/zip_tricks/streamer/entry.rb

@@ -4,7 +4,7 @@
 # Normally you will not have to use this class directly
 class ZipTricks::Streamer::Entry < Struct.new(:filename, :crc32, :compressed_size,
                                               :uncompressed_size, :storage_mode, :mtime,
-                                              :use_data_descriptor)
+                                              :use_data_descriptor, :local_header_offset, :bytes_used_for_local_header, :bytes_used_for_data_descriptor, :unix_permissions)
   def initialize(*)
     super
     filename.force_encoding(Encoding::UTF_8)
@@ -15,6 +15,10 @@ class ZipTricks::Streamer::Entry < Struct.new(:filename, :crc32, :compressed_siz
                            end)
   end
 
+  def total_bytes_used
+    bytes_used_for_local_header + compressed_size + bytes_used_for_data_descriptor
+  end
+
   # Set the general purpose flags for the entry. We care about is the EFS
   # bit (bit 11) which should be set if the filename is UTF8. If it is, we need to set the
   # bit so that the unarchiving application knows that the filename in the archive is UTF-8

data/lib/zip_tricks/streamer/stored_writer.rb

@@ -12,7 +12,8 @@ class ZipTricks::Streamer::StoredWriter
 
   def initialize(io)
     @io = ZipTricks::WriteAndTell.new(io)
-    @crc = ZipTricks::WriteBuffer.new(ZipTricks::StreamCRC32.new, CRC32_BUFFER_SIZE)
+    @crc_compute = ZipTricks::StreamCRC32.new
+    @crc = ZipTricks::WriteBuffer.new(@crc_compute, CRC32_BUFFER_SIZE)
   end
 
   # Writes the given data to the contained IO object.
@@ -28,9 +29,9 @@ class ZipTricks::Streamer::StoredWriter
   # Returns the amount of data written and the CRC32 checksum. The return value
   # can be directly used as the argument to {Streamer#update_last_entry_and_write_data_descriptor}
   #
-  # @param data[String] data to be written
   # @return [Hash] a hash of `{crc32, compressed_size, uncompressed_size}`
   def finish
-    {crc32: @crc.to_i, compressed_size: @io.tell, uncompressed_size: @io.tell}
+    @crc.flush
+    {crc32: @crc_compute.to_i, compressed_size: @io.tell, uncompressed_size: @io.tell}
   end
 end

data/lib/zip_tricks/streamer.rb

@@ -91,8 +91,9 @@ class ZipTricks::Streamer
   InvalidOutput = Class.new(ArgumentError)
   Overflow = Class.new(StandardError)
   UnknownMode = Class.new(StandardError)
+  OffsetOutOfSync = Class.new(StandardError)
 
-  private_constant :DeflatedWriter, :StoredWriter, :STORED, :DEFLATED
+  private_constant :STORED, :DEFLATED
 
   # Creates a new Streamer on top of the given IO-ish object and yields it. Once the given block
   # returns, the Streamer will have it's `close` method called, which will write out the central
@@ -130,28 +131,26 @@ class ZipTricks::Streamer
   #     end
   #
   # @param kwargs_for_new [Hash] keyword arguments for {Streamer.new}
-  # @return [Enumerator] the enumerator you can read bytestrings of the ZIP from using `each`
+  # @return [ZipTricks::OutputEnumerator] the enumerator you can read bytestrings of the ZIP from by calling `each`
   def self.output_enum(**kwargs_for_new, &zip_streamer_block)
     ZipTricks::OutputEnumerator.new(**kwargs_for_new, &zip_streamer_block)
   end
 
   # Creates a new Streamer on top of the given IO-ish object.
   #
-  # @param stream[IO] the destination IO for the ZIP. Anything that responds to `<<` can be used.
+  # @param writable[#<<] 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
   # @param auto_rename_duplicate_filenames[Boolean] whether duplicate filenames, when encountered,
   #    should be suffixed with (1), (2) etc. Default value is `false` - if
   #    dupliate names are used an exception will be raised
-  def initialize(stream, writer: create_writer, auto_rename_duplicate_filenames: false)
-    raise InvalidOutput, 'The stream must respond to #<<' unless stream.respond_to?(:<<)
-
-    @dedupe_filenames = auto_rename_duplicate_filenames
-    @out = ZipTricks::WriteAndTell.new(stream)
+  def initialize(writable, writer: create_writer, auto_rename_duplicate_filenames: false)
+    raise InvalidOutput, 'The writable must respond to #<<' unless writable.respond_to?(:<<)
+    @out = ZipTricks::WriteAndTell.new(writable)
     @files = []
-    @local_header_offsets = []
     @path_set = ZipTricks::PathSet.new
     @writer = writer
+    @dedupe_filenames = auto_rename_duplicate_filenames
   end
 
   # Writes a part of a zip entry body (actual binary data of the entry) into the output stream.
@@ -201,21 +200,20 @@ class ZipTricks::Streamer
   # @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
+  # @param unix_permissions[Fixnum?] which UNIX permissions to set, normally the default should be used
   # @return [Integer] the offset the output IO is at after writing the entry header
-  def add_deflated_entry(filename:, modification_time: Time.now.utc, compressed_size: 0, uncompressed_size: 0, crc32: 0, use_data_descriptor: false)
+  def add_deflated_entry(filename:, modification_time: Time.now.utc, compressed_size: 0, uncompressed_size: 0, crc32: 0, unix_permissions: nil, use_data_descriptor: false)
     add_file_and_write_local_header(filename: filename,
                                     modification_time: modification_time,
                                     crc32: crc32,
                                     storage_mode: DEFLATED,
                                     compressed_size: compressed_size,
                                     uncompressed_size: uncompressed_size,
+                                    unix_permissions: unix_permissions,
                                     use_data_descriptor: use_data_descriptor)
     @out.tell
   end
 
-  # 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
@@ -226,14 +224,16 @@ class ZipTricks::Streamer
   # @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
+  # @param unix_permissions[Fixnum?] which UNIX permissions to set, normally the default should be used
   # @return [Integer] the offset the output IO is at after writing the entry header
-  def add_stored_entry(filename:, modification_time: Time.now.utc,  size: 0, crc32: 0, use_data_descriptor: false)
+  def add_stored_entry(filename:, modification_time: Time.now.utc,  size: 0, crc32: 0, unix_permissions: nil, use_data_descriptor: false)
     add_file_and_write_local_header(filename: filename,
                                     modification_time: modification_time,
                                     crc32: crc32,
                                     storage_mode: STORED,
                                     compressed_size: size,
                                     uncompressed_size: size,
+                                    unix_permissions: unix_permissions,
                                     use_data_descriptor: use_data_descriptor)
     @out.tell
   end
@@ -242,14 +242,16 @@ class ZipTricks::Streamer
   #
   # @param dirname [String] the name of the directory in the archive
   # @param modification_time [Time] the modification time of the directory in the archive
+  # @param unix_permissions[Fixnum?] which UNIX permissions to set, normally the default should be used
   # @return [Integer] the offset the output IO is at after writing the entry header
-  def add_empty_directory(dirname:, modification_time: Time.now.utc)
+  def add_empty_directory(dirname:, modification_time: Time.now.utc, unix_permissions: nil)
     add_file_and_write_local_header(filename: dirname.to_s + '/',
                                     modification_time: modification_time,
                                     crc32: 0,
                                     storage_mode: STORED,
                                     compressed_size: 0,
                                     uncompressed_size: 0,
+                                    unix_permissions: unix_permissions,
                                     use_data_descriptor: false)
     @out.tell
   end
@@ -287,14 +289,16 @@ class ZipTricks::Streamer
   #
   # @param filename[String] the name of the file in the archive
   # @param modification_time [Time] the modification time of the file in the archive
+  # @param unix_permissions[Fixnum?] which UNIX permissions to set, normally the default should be used
   # @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, modification_time: Time.now.utc)
+  def write_stored_file(filename, modification_time: Time.now.utc, unix_permissions: nil)
     add_stored_entry(filename: filename,
                      modification_time: modification_time,
                      use_data_descriptor: true,
                      crc32: 0,
-                     size: 0)
+                     size: 0,
+                     unix_permissions: unix_permissions)
 
     writable = Writable.new(self, StoredWriter.new(@out))
     if block_given?
@@ -339,14 +343,16 @@ class ZipTricks::Streamer
   #
   # @param filename[String] the name of the file in the archive
   # @param modification_time [Time] the modification time of the file in the archive
+  # @param unix_permissions[Fixnum?] which UNIX permissions to set, normally the default should be used
   # @yield [#<<, #write] an object that the file contents must be written to
-  def write_deflated_file(filename, modification_time: Time.now.utc)
+  def write_deflated_file(filename, modification_time: Time.now.utc, unix_permissions: nil)
     add_deflated_entry(filename: filename,
                        modification_time: modification_time,
                        use_data_descriptor: true,
                        crc32: 0,
                        compressed_size: 0,
-                       uncompressed_size: 0)
+                       uncompressed_size: 0,
+                       unix_permissions: unix_permissions)
 
     writable = Writable.new(self, DeflatedWriter.new(@out))
     if block_given?
@@ -363,21 +369,24 @@ class ZipTricks::Streamer
   #
   # @return [Integer] the offset the output IO is at after closing the archive
   def close
+    # Make sure offsets are in order
+    verify_offsets!
+
     # Record the central directory offset, so that it can be written into the EOCD record
     cdir_starts_at = @out.tell
 
     # Write out the central directory entries, one for each file
-    @files.each_with_index do |entry, i|
-      header_loc = @local_header_offsets.fetch(i)
+    @files.each do |entry|
       @writer.write_central_directory_file_header(io: @out,
-                                                  local_file_header_location: header_loc,
+                                                  local_file_header_location: entry.local_header_offset,
                                                   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)
+                                                  filename: entry.filename,
+                                                  unix_permissions: entry.unix_permissions)
     end
 
     # Record the central directory size, for the EOCDR
@@ -423,15 +432,40 @@ class ZipTricks::Streamer
     last_entry.compressed_size = compressed_size
     last_entry.uncompressed_size = uncompressed_size
 
+    offset_before_data_descriptor = @out.tell
     @writer.write_data_descriptor(io: @out,
                                   crc32: last_entry.crc32,
                                   compressed_size: last_entry.compressed_size,
                                   uncompressed_size: last_entry.uncompressed_size)
+    last_entry.bytes_used_for_data_descriptor = @out.tell - offset_before_data_descriptor
+
     @out.tell
   end
 
   private
 
+  def verify_offsets!
+    # We need to check whether the offsets noted for the entries actually make sense
+    computed_offset = @files.map(&:total_bytes_used).inject(0, &:+)
+    actual_offset = @out.tell
+    if computed_offset != actual_offset
+      message = <<-EMS
+The offset of the Streamer output IO is out of sync with the expected value. All entries written so far,
+including their compressed bodies, local headers and data descriptors, add up to a certain offset,
+but this offset does not match the actual offset of the IO.
+
+Entries add up to #{computed_offset} bytes and the IO is at #{actual_offset} bytes.
+
+This can happen if you write local headers for an entry, write the "body" of the entry directly to the IO
+object which is your destination, but do not adjust the offset known to the Streamer object. To adjust
+the offfset you need to call `Streamer#simulate_write(body_size)` after outputting the entry. Otherwise
+the local header offsets of the entries you write are going to be incorrect and some ZIP applications
+are going to have problems opening your archive.
+EMS
+      raise OffsetOutOfSync, message
+    end
+  end
+
   def add_file_and_write_local_header(
       filename:,
       modification_time:,
@@ -439,7 +473,8 @@ class ZipTricks::Streamer
       storage_mode:,
       compressed_size:,
       uncompressed_size:,
-      use_data_descriptor:)
+      use_data_descriptor:,
+      unix_permissions:)
 
     # Clean backslashes
     filename = remove_backslash(filename)
@@ -464,16 +499,19 @@ class ZipTricks::Streamer
       uncompressed_size = 0
     end
 
+    local_header_starts_at = @out.tell
+
     e = Entry.new(filename,
                   crc32,
                   compressed_size,
                   uncompressed_size,
                   storage_mode,
                   modification_time,
-                  use_data_descriptor)
-
-    @files << e
-    @local_header_offsets << @out.tell
+                  use_data_descriptor,
+                  _local_file_header_offset = local_header_starts_at,
+                  _bytes_used_for_local_header = 0,
+                  _bytes_used_for_data_descriptor = 0,
+                  unix_permissions)
 
     @writer.write_local_file_header(io: @out,
                                     gp_flags: e.gp_flags,
@@ -483,6 +521,9 @@ class ZipTricks::Streamer
                                     mtime: e.mtime,
                                     filename: e.filename,
                                     storage_mode: e.storage_mode)
+    e.bytes_used_for_local_header = @out.tell - e.local_header_offset
+
+    @files << e
   end
 
   def remove_backslash(filename)

data/lib/zip_tricks/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ZipTricks
-  VERSION = '5.1.0'
+  VERSION = '5.6.0'
 end

data/lib/zip_tricks/write_and_tell.rb

@@ -10,9 +10,8 @@ class ZipTricks::WriteAndTell
 
   def <<(bytes)
     return self if bytes.nil?
-    binary_bytes = binary(bytes)
-    @io << binary_bytes
-    @pos += binary_bytes.bytesize
+    @io << bytes.b
+    @pos += bytes.bytesize
     self
   end
 
@@ -23,13 +22,4 @@ class ZipTricks::WriteAndTell
   def tell
     @pos
   end
-
-  private
-
-  def binary(str)
-    return str if str.encoding == Encoding::BINARY
-    str.force_encoding(Encoding::BINARY)
-  rescue RuntimeError # the string is frozen
-    str.dup.force_encoding(Encoding::BINARY)
-  end
 end

data/lib/zip_tricks/write_buffer.rb

@@ -7,13 +7,34 @@
 # 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. ZipTricks 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 ZipTricks::WriteBuffer
   # Creates a new WriteBuffer bypassing into a given writable object
   #
-  # @param writable[#<<] An object that responds to `#<<` with string as argument
+  # @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)
-    @buf = StringIO.new
+    # 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
@@ -24,28 +45,27 @@ class ZipTricks::WriteBuffer
   # @param data[String] data to be written
   # @return self
   def <<(data)
-    @buf << data
-    flush! if @buf.size > @buffer_size
+    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!
-    @writable << @buf.string if @buf.size > 0
-    @buf.truncate(0)
-    @buf.rewind
+  def flush
+    unless @buf.empty?
+      @writable << @buf
+      @buf.clear
+    end
     self
   end
 
-  # Flushes the buffer and returns the result of `#to_i` of the contained `writable`.
-  # Primarily facilitates working with StreamCRC32 objects where you finish the
-  # computation by retrieving the CRC as an integer
-  #
-  # @return [Integer] the return value of `writable#to_i`
-  def to_i
-    flush!
-    @writable.to_i
-  end
+  # `flush!` was renamed to `flush` but we preserve this method for backwards compatibility
+  alias_method :flush!, :flush
 end

data/lib/zip_tricks/zip_writer.rb

@@ -31,22 +31,10 @@ class ZipTricks::ZipWriter
   VERSION_MADE_BY                        = 52
   VERSION_NEEDED_TO_EXTRACT              = 20
   VERSION_NEEDED_TO_EXTRACT_ZIP64        = 45
-  DEFAULT_EXTERNAL_ATTRS = begin
-    # These need to be set so that the unarchived files do not become executable on UNIX, for
-    # security purposes. Strictly speaking we would want to make this user-customizable,
-    # but for now just putting in sane defaults will do. For example, Trac with zipinfo does this:
-    # zipinfo.external_attr = 0644 << 16L # permissions -r-wr--r--.
-    # We snatch the incantations from Rubyzip for this.
-    unix_perms = 0o644
-    file_type_file = 0o10
-    (file_type_file << 12 | (unix_perms & 0o7777)) << 16
-  end
-  EMPTY_DIRECTORY_EXTERNAL_ATTRS = begin
-    # Applies permissions to an empty directory.
-    unix_perms = 0o755
-    file_type_dir = 0o04
-    (file_type_dir << 12 | (unix_perms & 0o7777)) << 16
-  end
+  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
@@ -57,14 +45,15 @@ class ZipTricks::ZipWriter
   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 = 'N' # Encode a 4-byte signed little-endian int
+  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,
-                   :DEFAULT_EXTERNAL_ATTRS,
+                   :FILE_TYPE_FILE,
+                   :FILE_TYPE_DIRECTORY,
                    :MADE_BY_SIGNATURE,
                    :C_UINT4,
                    :C_UINT2,
@@ -118,7 +107,7 @@ class ZipTricks::ZipWriter
     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(mtime)
+    extra_fields << timestamp_extra_for_local_file_header(mtime)
 
     io << [extra_fields.size].pack(C_UINT2)                # extra field length              2 bytes
 
@@ -136,6 +125,7 @@ class ZipTricks::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
   # @return [void]
   def write_central_directory_file_header(io:,
                                           local_file_header_location:,
@@ -145,7 +135,9 @@ class ZipTricks::ZipWriter
                                           uncompressed_size:,
                                           mtime:,
                                           crc32:,
-                                          filename:)
+                                          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) ||
@@ -182,7 +174,7 @@ class ZipTricks::ZipWriter
                                                                      compressed_size: compressed_size,
                                                                      uncompressed_size: uncompressed_size)
     end
-    extra_fields << timestamp_extra(mtime)
+    extra_fields << timestamp_extra_for_central_directory_entry(mtime)
 
     io << [extra_fields.size].pack(C_UINT2)                 # extra field length              2 bytes
 
@@ -195,16 +187,20 @@ class ZipTricks::ZipWriter
       [TWO_BYTE_MAX_UINT].pack(C_UINT2)
     else
       [0].pack(C_UINT2)
-          end
+    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.
-    io << if filename.end_with?('/')
-      [EMPTY_DIRECTORY_EXTERNAL_ATTRS].pack(C_UINT4)
+    # 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
-      [DEFAULT_EXTERNAL_ATTRS].pack(C_UINT4)           # external file attributes        4 bytes
+      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)
@@ -345,12 +341,14 @@ class ZipTricks::ZipWriter
     pack_array(data_and_packspecs)
   end
 
-  # Writes the extended timestamp information field. The spec defines 2
+  # 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(mtime)
+  def timestamp_extra_for_local_file_header(mtime)
     #         Local-header version:
     #
     #         Value         Size        Description
@@ -378,16 +376,21 @@ class ZipTricks::ZipWriter
     #       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 = 0b10000000 # Set bit 1 only to indicate only mtime is present
+    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 + 1 long used for the timestamp)
+      (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 long, not the unsigned one used by the rest of the ZIP spec.
+      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.
   #
@@ -427,4 +430,8 @@ class ZipTricks::ZipWriter
     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