zip_kit 6.3.6 → 6.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 687884a060911fe25101e41be05bd32f4b50068c2ac592acec9937e5b0912f47
-  data.tar.gz: c209fb4839008ca84b956839db24ff65d8ec3ae390c4666aabe34743258409ec
+  metadata.gz: 67a468ca21123613319181955fd418268f661dc8beaee1c5eab2054395759478
+  data.tar.gz: 33047d74b3e2caaa47ce7ef1868bb5b2dba260e3dc97e116fa0b7fba4c6ec07d
 SHA512:
-  metadata.gz: bf6bf944be2ec57fd53950c046f5ed28565c5d97f73edc91fbaf1094319d0c2ad47b0a6c6ae1194e69f7fdab3e85beb479b41755e499497fe7f4ab2423529858
-  data.tar.gz: 1d54ad55c06b14297057bc594ff45f74a551b453e9cc5d846595abf238289ed0b7b9175177d089db87bceb9601c9322773a44d4601d3a6b32fb30f331f7bbcff
+  metadata.gz: 219f3a08a9413835762ee7af7108324e1d2819f3a4a4e4d35c1451b2ad60453f09b8e5783070c879fa644b87199c4e825d40978894489ded72f90ddc99b73a79
+  data.tar.gz: 532ca543f7dc346385336ba11e876f14667825d5ef67b6bd1b308ef91c1306591a203adf638894b8a720e1d0abeed0af9ac66ff941dc5b41229261719d47fd21

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## Unreleased
 
+* Add `Streamer.new(io, ocf: true)` for writing EPUB (OCF) and OpenDocument containers. The first entry must then be a stored `mimetype` file with its sizes in the local header, and `Streamer::OCFViolation` is raised otherwise. That entry is written without the extended timestamp extra field, which those formats forbid - before, they could not be produced with ZipKit at all. File names get checked against the OCF rules as well: valid UTF-8, no forbidden characters, segments of at most 255 bytes not ending with a `.`, and no two names in a directory which only differ by case or Unicode normalization.
+* Add `Streamer#write_mimetype_file` and `SizeEstimator#add_mimetype_entry`
+* Add the `extended_timestamp:` keyword argument to `ZipWriter#write_local_file_header` and `ZipWriter#write_central_directory_file_header`
+
 ## 6.3.6
 
 * Fix the end of central directory record counting entries discarded by `rollback!`, which made archives with a rolled back entry unreadable for readers which check the entry count (including `ZipKit::FileReader`).

data/README.md

@@ -228,6 +228,25 @@ end
 Check out the `examples/` directory at the root of the project. This will give you a good idea
 of various use cases the library supports.
 
+### Writing EPUB and OpenDocument files
+
+EPUB books (OCF containers) and OpenDocument files are ZIP archives which must start with a `mimetype`
+entry that is stored, has its sizes in the local header and has no extra fields - readers find the media type
+at byte 38 of the file. Pass `ocf: true` to make the Streamer enforce that, and write the entry with `write_mimetype_file`:
+
+```ruby
+ZipKit::Streamer.open(epub_file, ocf: true) do |zip|
+  zip.write_mimetype_file("application/epub+zip")
+  zip.write_file("META-INF/container.xml") { |sink| sink << container_xml }
+  zip.write_file("OEBPS/package.opf") { |sink| sink << package_opf }
+end
+```
+
+If the first entry would make the archive non-conformant, `ZipKit::Streamer::OCFViolation` gets raised
+before anything is written. The same happens for file names those formats do not allow: names which are not
+UTF-8, contain characters like `:`, `?` or `*`, have a segment longer than 255 bytes or ending with a `.`,
+or which only differ from another name in the same directory by case or Unicode normalization.
+
 ### Computing the CRC32 value of a large file
 
 `BlockCRC32` computes the CRC32 checksum of an IO in a streaming fashion.

data/lib/zip_kit/size_estimator.rb

@@ -81,6 +81,16 @@ class ZipKit::SizeEstimator
     self
   end
 
+  # Add the `mimetype` entry an EPUB (OCF) or OpenDocument container starts with,
+  # see {Streamer#write_mimetype_file}.
+  #
+  # @param media_type [String] the media type, like "application/epub+zip"
+  # @return self
+  def add_mimetype_entry(media_type:)
+    @streamer.write_mimetype_file(media_type)
+    self
+  end
+
   # Add an empty directory to the archive.
   #
   # @param dirname [String] the name of the directory

data/lib/zip_kit/streamer/entry.rb

@@ -4,7 +4,7 @@
 # Normally you will not have to use this class directly
 class ZipKit::Streamer::Entry < Struct.new(:filename, :crc32, :compressed_size,
   :uncompressed_size, :storage_mode, :mtime,
-  :use_data_descriptor, :local_header_offset, :bytes_used_for_local_header, :bytes_used_for_data_descriptor, :unix_permissions)
+  :use_data_descriptor, :local_header_offset, :bytes_used_for_local_header, :bytes_used_for_data_descriptor, :unix_permissions, :extended_timestamp)
   def initialize(*)
     super
     filename.force_encoding(Encoding::UTF_8)

data/lib/zip_kit/streamer.rb

@@ -85,6 +85,22 @@ require "set"
 #     zip.close
 #
 # Calling {Streamer#close} **will not** call `#close` on the underlying IO object.
+#
+# ## Writing EPUB and OpenDocument containers
+#
+# EPUB (via its Open Container Format, OCF) and OpenDocument are ZIP files with an extra rule: the
+# first entry must be a file called `mimetype`, stored without compression and with no extra fields
+# in its local header. Readers check this by looking at the raw bytes at fixed offsets: the media type
+# must start at byte 38 of the file. Pass `ocf: true` and write the `mimetype` file first:
+#
+#     ZipKit::Streamer.open(epub_file, ocf: true) do |zip|
+#       zip.write_mimetype_file("application/epub+zip")
+#       zip.write_file("META-INF/container.xml") { |sink| sink << container_xml }
+#       ...
+#     end
+#
+# With `ocf: true` the Streamer will raise {OCFViolation} if the first entry it is asked to write
+# would make the archive non-conformant, or if a file name is not allowed in such a container.
 class ZipKit::Streamer
   autoload :DeflatedWriter, File.dirname(__FILE__) + "/streamer/deflated_writer.rb"
   autoload :Writable, File.dirname(__FILE__) + "/streamer/writable.rb"
@@ -99,12 +115,28 @@ class ZipKit::Streamer
   DEFLATED = 8
 
   EntryBodySizeMismatch = Class.new(StandardError)
+  OCFViolation = Class.new(StandardError)
   InvalidOutput = Class.new(ArgumentError)
   Overflow = Class.new(StandardError)
   UnknownMode = Class.new(StandardError)
   OffsetOutOfSync = Class.new(StandardError)
 
-  private_constant :STORED, :DEFLATED
+  # Characters which may not appear in file names inside an OCF container, see
+  # https://www.w3.org/TR/epub-33/#sec-container-filenames - a trailing "." is not allowed either
+  OCF_FORBIDDEN_CHARACTERS = begin
+    ranges = [0x22, 0x2A, 0x3A, 0x3C, 0x3E, 0x3F, 0x5C, 0x7C].map { |c| [c, c] }
+    ranges << [0x00, 0x1F] # C0
+    ranges << [0x7F, 0x9F] # DEL and C1
+    ranges << [0xE000, 0xF8FF] # Private Use Area
+    ranges << [0xFDD0, 0xFDEF] # noncharacters
+    ranges << [0xFFF0, 0xFFFF] # Specials, includes the U+FFFE and U+FFFF noncharacters
+    ranges += (1..14).map { |plane| [plane * 0x10000 + 0xFFFE, plane * 0x10000 + 0xFFFF] } # noncharacters
+    ranges << [0xF0000, 0x10FFFF] # Supplementary Private Use Areas
+    Regexp.new("[" + ranges.map { |from, to| format("\\u{%X}-\\u{%X}", from, to) }.join + "]").freeze
+  end
+  OCF_MAX_FILENAME_BYTES = 255
+
+  private_constant :STORED, :DEFLATED, :OCF_FORBIDDEN_CHARACTERS, :OCF_MAX_FILENAME_BYTES
 
   # 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
@@ -127,7 +159,14 @@ class ZipKit::Streamer
   # @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(writable, writer: create_writer, auto_rename_duplicate_filenames: false)
+  # @param ocf[Boolean] whether the archive must be an OCF container (EPUB) or an OpenDocument package.
+  #    When set, the first entry must be a stored `mimetype` file without a data descriptor - use
+  #    {#write_mimetype_file} for it - and {OCFViolation} gets raised otherwise. That entry will be
+  #    written without the extended timestamp extra field, which those formats forbid. All file names
+  #    get checked against the OCF rules too: valid UTF-8, no forbidden characters, no names longer
+  #    than 255 bytes or ending with a ".", and no two names in a directory which only differ by case
+  #    or Unicode normalization.
+  def initialize(writable, writer: create_writer, auto_rename_duplicate_filenames: false, ocf: false)
     raise InvalidOutput, "The writable must respond to #<< or #write" unless writable.respond_to?(:<<) || writable.respond_to?(:write)
 
     @out = ZipKit::WriteAndTell.new(writable)
@@ -135,6 +174,8 @@ class ZipKit::Streamer
     @path_set = ZipKit::PathSet.new
     @writer = writer
     @dedupe_filenames = auto_rename_duplicate_filenames
+    @ocf = ocf
+    @ocf_folded_paths = {}
   end
 
   # Writes a part of a zip entry body (actual binary data of the entry) into the output stream.
@@ -211,6 +252,31 @@ class ZipKit::Streamer
     @out.tell
   end
 
+  # Writes the `mimetype` file which EPUB (OCF) and OpenDocument containers have to start with.
+  # The entry is stored, has no data descriptor and no extra fields, so that the media type
+  # ends up at byte 38 of the archive if this is the first entry.
+  #
+  # @param media_type[String] the media type, like "application/epub+zip"
+  # @param modification_time [Time] the modification time of the file in the archive
+  # @return [Integer] the offset the output IO is at after writing the entry
+  def write_mimetype_file(media_type, modification_time: Time.now.utc)
+    unless media_type.ascii_only? && media_type.match?(/\A[[:graph:]]+\z/)
+      raise OCFViolation, "The media type must be ASCII without whitespace or padding, but was #{media_type.inspect}"
+    end
+    media_type = media_type.b
+    add_file_and_write_local_header(filename: "mimetype",
+      modification_time: modification_time,
+      crc32: Zlib.crc32(media_type),
+      storage_mode: STORED,
+      compressed_size: media_type.bytesize,
+      uncompressed_size: media_type.bytesize,
+      unix_permissions: nil,
+      use_data_descriptor: false,
+      extended_timestamp: false)
+    @out << media_type
+    @out.tell
+  end
+
   # Adds an empty directory to the archive with a size of 0 and permissions of 755.
   #
   # @param dirname [String] the name of the directory in the archive
@@ -425,7 +491,8 @@ class ZipKit::Streamer
         mtime: entry.mtime,
         crc32: entry.crc32,
         filename: entry.filename,
-        unix_permissions: entry.unix_permissions)
+        unix_permissions: entry.unix_permissions,
+        extended_timestamp: entry.extended_timestamp)
     end
 
     # Record the central directory size, for the EOCDR
@@ -440,6 +507,7 @@ class ZipKit::Streamer
     # Clear the files so that GC will not have to trace all the way to here to deallocate them
     @files.clear
     @path_set.clear
+    @ocf_folded_paths.clear
 
     # and return the final offset
     @out.tell
@@ -509,8 +577,11 @@ class ZipKit::Streamer
 
     # Recreate the path set from remaining entries (PathSet does not support cheap deletes yet)
     @path_set.clear
+    @ocf_folded_paths.clear
     @files.each do |e|
-      @path_set.add_directory_or_file_path(e.filename) unless e.filler?
+      next if e.filler?
+      @path_set.add_directory_or_file_path(e.filename)
+      register_ocf_folded_path(e.filename) if @ocf
     end
 
     # Create filler for the truncated or unusable local file entry that did get written into the output
@@ -572,7 +643,8 @@ class ZipKit::Streamer
     compressed_size:,
     uncompressed_size:,
     use_data_descriptor:,
-    unix_permissions:
+    unix_permissions:,
+    extended_timestamp: true
   )
     # Set state needed for proper rollback later. If write_local_file_header
     # does manage to write _some_ bytes, but fails later (we write in tiny bits sometimes)
@@ -585,10 +657,21 @@ class ZipKit::Streamer
     raise UnknownMode, "Unknown compression mode #{storage_mode}" unless [STORED, DEFLATED].include?(storage_mode)
     raise Overflow, "Filename is too long" if filename.bytesize > 0xFFFF
 
+    # Going by the offset and not by the entries, since a rolled back `mimetype` leaves a filler behind
+    if @ocf && @out.tell.zero?
+      verify_ocf_mimetype_entry!(filename, storage_mode, use_data_descriptor)
+      extended_timestamp = false
+    elsif @ocf && (@files.empty? || @files.first.filler?)
+      raise OCFViolation, "The \"mimetype\" entry of an OCF container must start at offset 0, " \
+        "but #{@out.tell} bytes have already been output"
+    end
+
     # If we need to massage filenames to enforce uniqueness,
     # do so before we check for file/directory conflicts
     filename = ZipKit::UniquifyFilename.call(filename, @path_set) if @dedupe_filenames
 
+    verify_ocf_filename!(filename) if @ocf
+
     # Make sure there is no file/directory clobbering (conflicts), or - if deduping is disabled -
     # no duplicate filenames/paths
     if filename.end_with?("/")
@@ -596,6 +679,7 @@ class ZipKit::Streamer
     else
       @path_set.add_file_path(filename)
     end
+    register_ocf_folded_path(filename) if @ocf
 
     if use_data_descriptor
       crc32 = 0
@@ -615,7 +699,8 @@ class ZipKit::Streamer
       _local_file_header_offset = local_header_starts_at,
       _bytes_used_for_local_header = 0,
       _bytes_used_for_data_descriptor = 0,
-      unix_permissions)
+      unix_permissions,
+      extended_timestamp)
 
     @writer.write_local_file_header(io: @out,
       gp_flags: e.gp_flags,
@@ -624,7 +709,8 @@ class ZipKit::Streamer
       uncompressed_size: e.uncompressed_size,
       mtime: e.mtime,
       filename: e.filename,
-      storage_mode: e.storage_mode)
+      storage_mode: e.storage_mode,
+      extended_timestamp: e.extended_timestamp)
 
     e.bytes_used_for_local_header = @out.tell - e.local_header_offset
 
@@ -632,6 +718,62 @@ class ZipKit::Streamer
     @remove_last_file_at_rollback = true
   end
 
+  def verify_ocf_mimetype_entry!(filename, storage_mode, use_data_descriptor)
+    problem = if filename != "mimetype"
+      "it is #{filename.inspect}"
+    elsif storage_mode != STORED
+      "it is compressed"
+    elsif use_data_descriptor
+      "it uses a data descriptor (sizes are not known upfront)"
+    end
+    return unless problem
+
+    message = "The first entry of an OCF container must be a stored \"mimetype\" file without a data descriptor, " \
+      "but #{problem}. Use `write_mimetype_file` to write it."
+    raise OCFViolation, message
+  end
+
+  def verify_ocf_filename!(filename)
+    path = filename.dup.force_encoding(Encoding::UTF_8)
+    raise OCFViolation, "File names in an OCF container must be UTF-8, but #{filename.inspect} is not" unless path.valid_encoding?
+
+    path.chomp("/").split("/", -1).each do |name|
+      problem = if name.empty?
+        "has an empty path segment"
+      elsif name.bytesize > OCF_MAX_FILENAME_BYTES
+        "has a segment longer than #{OCF_MAX_FILENAME_BYTES} bytes"
+      elsif name.end_with?(".")
+        "has a segment ending with a \".\""
+      elsif (char = name[OCF_FORBIDDEN_CHARACTERS])
+        "contains the forbidden character U+%04X" % char.ord
+      end
+      raise OCFViolation, "The file name #{path.inspect} is not allowed in an OCF container: it #{problem}" if problem
+    end
+
+    each_ocf_folded_prefix(path) do |prefix, folded|
+      existing = @ocf_folded_paths[folded]
+      if existing && existing != prefix
+        raise OCFViolation, "The file name #{path.inspect} is not allowed in an OCF container: " \
+          "#{prefix.inspect} only differs from #{existing.inspect} by case or Unicode normalization"
+      end
+    end
+  end
+
+  def register_ocf_folded_path(filename)
+    each_ocf_folded_prefix(filename.dup.force_encoding(Encoding::UTF_8)) do |prefix, folded|
+      @ocf_folded_paths[folded] ||= prefix
+    end
+  end
+
+  # Directories have to be unique too, so "OEBPS/a.xhtml" and "oebps/b.xhtml" clash on "OEBPS"
+  def each_ocf_folded_prefix(path)
+    segments = path.chomp("/").split("/")
+    segments.each_index do |i|
+      prefix = segments[0..i].join("/")
+      yield(prefix, prefix.unicode_normalize(:nfc).downcase(:fold))
+    end
+  end
+
   def remove_backslash(filename)
     filename.tr("\\", "_")
   end

data/lib/zip_kit/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ZipKit
-  VERSION = "6.3.6"
+  VERSION = "6.4.0"
 end

data/lib/zip_kit/zip_writer.rb

@@ -72,8 +72,13 @@ class ZipKit::ZipWriter
   # @param mtime[Time]  the modification time to be recorded in the ZIP
   # @param gp_flags[Integer] bit-packed general purpose flags
   # @param storage_mode[Integer] 8 for deflated, 0 for stored...
+  # @param extended_timestamp[Boolean] whether to add the extended timestamp ("UT") extra field. The DOS date
+  #   and time get written regardless, but they carry local time with 2-second precision - which is why the
+  #   extra field is there by default. Some formats built on top of ZIP forbid extra fields on certain entries
+  #   though: EPUB (OCF) and OpenDocument require their `mimetype` entry to have none. Normally `Streamer`
+  #   decides this for you, see the `ocf:` option of {Streamer#initialize}
   # @return [void]
-  def write_local_file_header(io:, filename:, compressed_size:, uncompressed_size:, crc32:, gp_flags:, mtime:, storage_mode:)
+  def write_local_file_header(io:, filename:, compressed_size:, uncompressed_size:, crc32:, gp_flags:, mtime:, storage_mode:, extended_timestamp: true)
     requires_zip64 = compressed_size > FOUR_BYTE_MAX_UINT || uncompressed_size > FOUR_BYTE_MAX_UINT
 
     # local file header signature     4 bytes  (0x04034b50)
@@ -121,7 +126,7 @@ class ZipKit::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_for_local_file_header(mtime)
+    extra_fields << timestamp_extra_for_local_file_header(mtime) if extended_timestamp
 
     # extra field length              2 bytes
     io << [extra_fields.size].pack(C_UINT2)
@@ -144,6 +149,8 @@ class ZipKit::ZipWriter
   # @param mtime[Time]  the modification time to be recorded in the ZIP
   # @param gp_flags[Integer] bit-packed general purpose flags
   # @param unix_permissions[Integer] the permissions for the file, or nil for the default to be used
+  # @param extended_timestamp[Boolean] whether to add the extended timestamp ("UT") extra field,
+  #   see {#write_local_file_header}
   # @return [void]
   def write_central_directory_file_header(io:,
     local_file_header_location:,
@@ -154,7 +161,8 @@ class ZipKit::ZipWriter
     mtime:,
     crc32:,
     filename:,
-    unix_permissions: nil)
+    unix_permissions: nil,
+    extended_timestamp: true)
     # 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) ||
@@ -203,7 +211,7 @@ class ZipKit::ZipWriter
         compressed_size: compressed_size,
         uncompressed_size: uncompressed_size)
     end
-    extra_fields << timestamp_extra_for_central_directory_entry(mtime)
+    extra_fields << timestamp_extra_for_central_directory_entry(mtime) if extended_timestamp
 
     # extra field length              2 bytes
     io << [extra_fields.size].pack(C_UINT2)

data/rbi/zip_kit.rbi

@@ -186,15 +186,44 @@ module ZipKit
   #     zip.close
   # 
   # Calling {Streamer#close} **will not** call `#close` on the underlying IO object.
+  # 
+  # ## Writing EPUB and OpenDocument containers
+  # 
+  # EPUB (via its Open Container Format, OCF) and OpenDocument are ZIP files with an extra rule: the
+  # first entry must be a file called `mimetype`, stored without compression and with no extra fields
+  # in its local header. Readers check this by looking at the raw bytes at fixed offsets: the media type
+  # must start at byte 38 of the file. Pass `ocf: true` and write the `mimetype` file first:
+  # 
+  #     ZipKit::Streamer.open(epub_file, ocf: true) do |zip|
+  #       zip.write_mimetype_file("application/epub+zip")
+  #       zip.write_file("META-INF/container.xml") { |sink| sink << container_xml }
+  #       ...
+  #     end
+  # 
+  # With `ocf: true` the Streamer will raise {OCFViolation} if the first entry it is asked to write
+  # would make the archive non-conformant, or if a file name is not allowed in such a container.
   class Streamer
     include ZipKit::WriteShovel
     STORED = T.let(0, T.untyped)
     DEFLATED = T.let(8, T.untyped)
     EntryBodySizeMismatch = T.let(Class.new(StandardError), T.untyped)
+    OCFViolation = T.let(Class.new(StandardError), T.untyped)
     InvalidOutput = T.let(Class.new(ArgumentError), T.untyped)
     Overflow = T.let(Class.new(StandardError), T.untyped)
     UnknownMode = T.let(Class.new(StandardError), T.untyped)
     OffsetOutOfSync = T.let(Class.new(StandardError), T.untyped)
+    OCF_FORBIDDEN_CHARACTERS = T.let(begin
+  ranges = [0x22, 0x2A, 0x3A, 0x3C, 0x3E, 0x3F, 0x5C, 0x7C].map { |c| [c, c] }
+  ranges << [0x00, 0x1F] # C0
+  ranges << [0x7F, 0x9F] # DEL and C1
+  ranges << [0xE000, 0xF8FF] # Private Use Area
+  ranges << [0xFDD0, 0xFDEF] # noncharacters
+  ranges << [0xFFF0, 0xFFFF] # Specials, includes the U+FFFE and U+FFFF noncharacters
+  ranges += (1..14).map { |plane| [plane * 0x10000 + 0xFFFE, plane * 0x10000 + 0xFFFF] } # noncharacters
+  ranges << [0xF0000, 0x10FFFF] # Supplementary Private Use Areas
+  Regexp.new("[" + ranges.map { |from, to| format("\\u{%X}-\\u{%X}", from, to) }.join + "]").freeze
+end, T.untyped)
+    OCF_MAX_FILENAME_BYTES = T.let(255, T.untyped)
 
     # sord omit - no YARD return type given, using untyped
     # Creates a new Streamer on top of the given IO-ish object and yields it. Once the given block
@@ -215,8 +244,17 @@ module ZipKit
     # _@param_ `writer` — the object to be used as the writer. Defaults to an instance of ZipKit::ZipWriter, normally you won't need to override it
     # 
     # _@param_ `auto_rename_duplicate_filenames` — 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
-    sig { params(writable: T.untyped, writer: ZipKit::ZipWriter, auto_rename_duplicate_filenames: T::Boolean).void }
-    def initialize(writable, writer: create_writer, auto_rename_duplicate_filenames: false); end
+    # 
+    # _@param_ `ocf` — whether the archive must be an OCF container (EPUB) or an OpenDocument package. When set, the first entry must be a stored `mimetype` file without a data descriptor - use {#write_mimetype_file} for it - and {OCFViolation} gets raised otherwise. That entry will be written without the extended timestamp extra field, which those formats forbid. All file names get checked against the OCF rules too: valid UTF-8, no forbidden characters, no names longer than 255 bytes or ending with a ".", and no two names in a directory which only differ by case or Unicode normalization.
+    sig do
+      params(
+        writable: T.untyped,
+        writer: ZipKit::ZipWriter,
+        auto_rename_duplicate_filenames: T::Boolean,
+        ocf: T::Boolean
+      ).void
+    end
+    def initialize(writable, writer: create_writer, auto_rename_duplicate_filenames: false, ocf: false); end
 
     # Writes a part of a zip entry body (actual binary data of the entry) into the output stream.
     # 
@@ -303,6 +341,18 @@ module ZipKit
     end
     def add_stored_entry(filename:, modification_time: Time.now.utc, size: 0, crc32: 0, unix_permissions: nil, use_data_descriptor: false); end
 
+    # Writes the `mimetype` file which EPUB (OCF) and OpenDocument containers have to start with.
+    # The entry is stored, has no data descriptor and no extra fields, so that the media type
+    # ends up at byte 38 of the archive if this is the first entry.
+    # 
+    # _@param_ `media_type` — the media type, like "application/epub+zip"
+    # 
+    # _@param_ `modification_time` — the modification time of the file in the archive
+    # 
+    # _@return_ — the offset the output IO is at after writing the entry
+    sig { params(media_type: String, modification_time: Time).returns(Integer) }
+    def write_mimetype_file(media_type, modification_time: Time.now.utc); end
+
     # Adds an empty directory to the archive with a size of 0 and permissions of 755.
     # 
     # _@param_ `dirname` — the name of the directory in the archive
@@ -554,6 +604,7 @@ module ZipKit
     # sord omit - no YARD type given for "uncompressed_size:", using untyped
     # sord omit - no YARD type given for "use_data_descriptor:", using untyped
     # sord omit - no YARD type given for "unix_permissions:", using untyped
+    # sord omit - no YARD type given for "extended_timestamp:", using untyped
     # sord omit - no YARD return type given, using untyped
     sig do
       params(
@@ -564,10 +615,34 @@ module ZipKit
         compressed_size: T.untyped,
         uncompressed_size: T.untyped,
         use_data_descriptor: T.untyped,
-        unix_permissions: T.untyped
+        unix_permissions: T.untyped,
+        extended_timestamp: T.untyped
       ).returns(T.untyped)
     end
-    def add_file_and_write_local_header(filename:, modification_time:, crc32:, storage_mode:, compressed_size:, uncompressed_size:, use_data_descriptor:, unix_permissions:); end
+    def add_file_and_write_local_header(filename:, modification_time:, crc32:, storage_mode:, compressed_size:, uncompressed_size:, use_data_descriptor:, unix_permissions:, extended_timestamp: true); end
+
+    # sord omit - no YARD type given for "filename", using untyped
+    # sord omit - no YARD type given for "storage_mode", using untyped
+    # sord omit - no YARD type given for "use_data_descriptor", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(filename: T.untyped, storage_mode: T.untyped, use_data_descriptor: T.untyped).returns(T.untyped) }
+    def verify_ocf_mimetype_entry!(filename, storage_mode, use_data_descriptor); end
+
+    # sord omit - no YARD type given for "filename", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(filename: T.untyped).returns(T.untyped) }
+    def verify_ocf_filename!(filename); end
+
+    # sord omit - no YARD type given for "filename", using untyped
+    # sord omit - no YARD return type given, using untyped
+    sig { params(filename: T.untyped).returns(T.untyped) }
+    def register_ocf_folded_path(filename); end
+
+    # sord omit - no YARD type given for "path", using untyped
+    # sord omit - no YARD return type given, using untyped
+    # Directories have to be unique too, so "OEBPS/a.xhtml" and "oebps/b.xhtml" clash on "OEBPS"
+    sig { params(path: T.untyped).returns(T.untyped) }
+    def each_ocf_folded_prefix(path); end
 
     # sord omit - no YARD type given for "filename", using untyped
     # sord omit - no YARD return type given, using untyped
@@ -648,6 +723,10 @@ module ZipKit
       # Returns the value of attribute unix_permissions
       sig { returns(Object) }
       attr_accessor :unix_permissions
+
+      # Returns the value of attribute extended_timestamp
+      sig { returns(Object) }
+      attr_accessor :extended_timestamp
     end
 
     # Is used internally by Streamer to keep track of entries in the archive during writing.
@@ -979,6 +1058,8 @@ end, T.untyped)
     # _@param_ `gp_flags` — bit-packed general purpose flags
     # 
     # _@param_ `storage_mode` — 8 for deflated, 0 for stored...
+    # 
+    # _@param_ `extended_timestamp` — whether to add the extended timestamp ("UT") extra field. The DOS date and time get written regardless, but they carry local time with 2-second precision - which is why the extra field is there by default. Some formats built on top of ZIP forbid extra fields on certain entries though: EPUB (OCF) and OpenDocument require their `mimetype` entry to have none. Normally `Streamer` decides this for you, see the `ocf:` option of {Streamer#initialize}
     sig do
       params(
         io: T.untyped,
@@ -988,10 +1069,11 @@ end, T.untyped)
         crc32: Integer,
         gp_flags: Integer,
         mtime: Time,
-        storage_mode: Integer
+        storage_mode: Integer,
+        extended_timestamp: T::Boolean
       ).void
     end
-    def write_local_file_header(io:, filename:, compressed_size:, uncompressed_size:, crc32:, gp_flags:, mtime:, storage_mode:); end
+    def write_local_file_header(io:, filename:, compressed_size:, uncompressed_size:, crc32:, gp_flags:, mtime:, storage_mode:, extended_timestamp: true); end
 
     # sord duck - #<< looks like a duck type, replacing with untyped
     # sord omit - no YARD type given for "local_file_header_location:", using untyped
@@ -1014,6 +1096,8 @@ end, T.untyped)
     # _@param_ `gp_flags` — bit-packed general purpose flags
     # 
     # _@param_ `unix_permissions` — the permissions for the file, or nil for the default to be used
+    # 
+    # _@param_ `extended_timestamp` — whether to add the extended timestamp ("UT") extra field, see {#write_local_file_header}
     sig do
       params(
         io: T.untyped,
@@ -1025,10 +1109,11 @@ end, T.untyped)
         mtime: Time,
         crc32: Integer,
         filename: String,
-        unix_permissions: T.nilable(Integer)
+        unix_permissions: T.nilable(Integer),
+        extended_timestamp: T::Boolean
       ).void
     end
-    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); end
+    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, extended_timestamp: true); end
 
     # sord duck - #<< looks like a duck type, replacing with untyped
     # Writes the data descriptor following the file data for a file whose local file header
@@ -2030,6 +2115,15 @@ end, T.untyped)
     end
     def add_deflated_entry(filename:, uncompressed_size:, compressed_size:, use_data_descriptor: false); end
 
+    # Add the `mimetype` entry an EPUB (OCF) or OpenDocument container starts with,
+    # see {Streamer#write_mimetype_file}.
+    # 
+    # _@param_ `media_type` — the media type, like "application/epub+zip"
+    # 
+    # _@return_ — self
+    sig { params(media_type: String).returns(T.untyped) }
+    def add_mimetype_entry(media_type:); end
+
     # Add an empty directory to the archive.
     # 
     # _@param_ `dirname` — the name of the directory

data/rbi/zip_kit.rbs

@@ -177,15 +177,34 @@ module ZipKit
   #     zip.close
   # 
   # Calling {Streamer#close} **will not** call `#close` on the underlying IO object.
+  # 
+  # ## Writing EPUB and OpenDocument containers
+  # 
+  # EPUB (via its Open Container Format, OCF) and OpenDocument are ZIP files with an extra rule: the
+  # first entry must be a file called `mimetype`, stored without compression and with no extra fields
+  # in its local header. Readers check this by looking at the raw bytes at fixed offsets: the media type
+  # must start at byte 38 of the file. Pass `ocf: true` and write the `mimetype` file first:
+  # 
+  #     ZipKit::Streamer.open(epub_file, ocf: true) do |zip|
+  #       zip.write_mimetype_file("application/epub+zip")
+  #       zip.write_file("META-INF/container.xml") { |sink| sink << container_xml }
+  #       ...
+  #     end
+  # 
+  # With `ocf: true` the Streamer will raise {OCFViolation} if the first entry it is asked to write
+  # would make the archive non-conformant, or if a file name is not allowed in such a container.
   class Streamer
     include ZipKit::WriteShovel
     STORED: untyped
     DEFLATED: untyped
     EntryBodySizeMismatch: untyped
+    OCFViolation: untyped
     InvalidOutput: untyped
     Overflow: untyped
     UnknownMode: untyped
     OffsetOutOfSync: untyped
+    OCF_FORBIDDEN_CHARACTERS: untyped
+    OCF_MAX_FILENAME_BYTES: untyped
 
     # sord omit - no YARD return type given, using untyped
     # Creates a new Streamer on top of the given IO-ish object and yields it. Once the given block
@@ -205,7 +224,14 @@ module ZipKit
     # _@param_ `writer` — the object to be used as the writer. Defaults to an instance of ZipKit::ZipWriter, normally you won't need to override it
     # 
     # _@param_ `auto_rename_duplicate_filenames` — 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: (untyped writable, ?writer: ZipKit::ZipWriter, ?auto_rename_duplicate_filenames: bool) -> void
+    # 
+    # _@param_ `ocf` — whether the archive must be an OCF container (EPUB) or an OpenDocument package. When set, the first entry must be a stored `mimetype` file without a data descriptor - use {#write_mimetype_file} for it - and {OCFViolation} gets raised otherwise. That entry will be written without the extended timestamp extra field, which those formats forbid. All file names get checked against the OCF rules too: valid UTF-8, no forbidden characters, no names longer than 255 bytes or ending with a ".", and no two names in a directory which only differ by case or Unicode normalization.
+    def initialize: (
+                      untyped writable,
+                      ?writer: ZipKit::ZipWriter,
+                      ?auto_rename_duplicate_filenames: bool,
+                      ?ocf: bool
+                    ) -> void
 
     # Writes a part of a zip entry body (actual binary data of the entry) into the output stream.
     # 
@@ -284,6 +310,17 @@ module ZipKit
                             ?use_data_descriptor: bool
                           ) -> Integer
 
+    # Writes the `mimetype` file which EPUB (OCF) and OpenDocument containers have to start with.
+    # The entry is stored, has no data descriptor and no extra fields, so that the media type
+    # ends up at byte 38 of the archive if this is the first entry.
+    # 
+    # _@param_ `media_type` — the media type, like "application/epub+zip"
+    # 
+    # _@param_ `modification_time` — the modification time of the file in the archive
+    # 
+    # _@return_ — the offset the output IO is at after writing the entry
+    def write_mimetype_file: (String media_type, ?modification_time: Time) -> Integer
+
     # Adds an empty directory to the archive with a size of 0 and permissions of 755.
     # 
     # _@param_ `dirname` — the name of the directory in the archive
@@ -504,6 +541,7 @@ module ZipKit
     # sord omit - no YARD type given for "uncompressed_size:", using untyped
     # sord omit - no YARD type given for "use_data_descriptor:", using untyped
     # sord omit - no YARD type given for "unix_permissions:", using untyped
+    # sord omit - no YARD type given for "extended_timestamp:", using untyped
     # sord omit - no YARD return type given, using untyped
     def add_file_and_write_local_header: (
                                            filename: untyped,
@@ -513,9 +551,29 @@ module ZipKit
                                            compressed_size: untyped,
                                            uncompressed_size: untyped,
                                            use_data_descriptor: untyped,
-                                           unix_permissions: untyped
+                                           unix_permissions: untyped,
+                                           ?extended_timestamp: untyped
                                          ) -> untyped
 
+    # sord omit - no YARD type given for "filename", using untyped
+    # sord omit - no YARD type given for "storage_mode", using untyped
+    # sord omit - no YARD type given for "use_data_descriptor", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def verify_ocf_mimetype_entry!: (untyped filename, untyped storage_mode, untyped use_data_descriptor) -> untyped
+
+    # sord omit - no YARD type given for "filename", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def verify_ocf_filename!: (untyped filename) -> untyped
+
+    # sord omit - no YARD type given for "filename", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def register_ocf_folded_path: (untyped filename) -> untyped
+
+    # sord omit - no YARD type given for "path", using untyped
+    # sord omit - no YARD return type given, using untyped
+    # Directories have to be unique too, so "OEBPS/a.xhtml" and "oebps/b.xhtml" clash on "OEBPS"
+    def each_ocf_folded_prefix: (untyped path) -> untyped
+
     # sord omit - no YARD type given for "filename", using untyped
     # sord omit - no YARD return type given, using untyped
     def remove_backslash: (untyped filename) -> untyped
@@ -578,6 +636,9 @@ module ZipKit
 
       # Returns the value of attribute unix_permissions
       attr_accessor unix_permissions: Object
+
+      # Returns the value of attribute extended_timestamp
+      attr_accessor extended_timestamp: Object
     end
 
     # Is used internally by Streamer to keep track of entries in the archive during writing.
@@ -873,6 +934,8 @@ module ZipKit
     # _@param_ `gp_flags` — bit-packed general purpose flags
     # 
     # _@param_ `storage_mode` — 8 for deflated, 0 for stored...
+    # 
+    # _@param_ `extended_timestamp` — whether to add the extended timestamp ("UT") extra field. The DOS date and time get written regardless, but they carry local time with 2-second precision - which is why the extra field is there by default. Some formats built on top of ZIP forbid extra fields on certain entries though: EPUB (OCF) and OpenDocument require their `mimetype` entry to have none. Normally `Streamer` decides this for you, see the `ocf:` option of {Streamer#initialize}
     def write_local_file_header: (
                                    io: untyped,
                                    filename: String,
@@ -881,7 +944,8 @@ module ZipKit
                                    crc32: Integer,
                                    gp_flags: Integer,
                                    mtime: Time,
-                                   storage_mode: Integer
+                                   storage_mode: Integer,
+                                   ?extended_timestamp: bool
                                  ) -> void
 
     # sord duck - #<< looks like a duck type, replacing with untyped
@@ -905,6 +969,8 @@ module ZipKit
     # _@param_ `gp_flags` — bit-packed general purpose flags
     # 
     # _@param_ `unix_permissions` — the permissions for the file, or nil for the default to be used
+    # 
+    # _@param_ `extended_timestamp` — whether to add the extended timestamp ("UT") extra field, see {#write_local_file_header}
     def write_central_directory_file_header: (
                                                io: untyped,
                                                local_file_header_location: untyped,
@@ -915,7 +981,8 @@ module ZipKit
                                                mtime: Time,
                                                crc32: Integer,
                                                filename: String,
-                                               ?unix_permissions: Integer?
+                                               ?unix_permissions: Integer?,
+                                               ?extended_timestamp: bool
                                              ) -> void
 
     # sord duck - #<< looks like a duck type, replacing with untyped
@@ -1780,6 +1847,14 @@ module ZipKit
                               ?use_data_descriptor: bool
                             ) -> untyped
 
+    # Add the `mimetype` entry an EPUB (OCF) or OpenDocument container starts with,
+    # see {Streamer#write_mimetype_file}.
+    # 
+    # _@param_ `media_type` — the media type, like "application/epub+zip"
+    # 
+    # _@return_ — self
+    def add_mimetype_entry: (media_type: String) -> untyped
+
     # Add an empty directory to the archive.
     # 
     # _@param_ `dirname` — the name of the directory

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zip_kit
 version: !ruby/object:Gem::Version
-  version: 6.3.6
+  version: 6.4.0
 platform: ruby
 authors:
 - Julik Tarkhanov
@@ -11,7 +11,7 @@ authors:
 - Felix Bünemann
 bindir: exe
 cert_chain: []
-date: 2026-10-02 00:00:00.000000000 Z
+date: 2026-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler