zip_kit 6.3.5 → 6.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83cdf922faca6692b384bc30ba8290f0f15a4567ebce61fccb792a5b5d7993fc
-  data.tar.gz: ba3a6fee022ba663d77306850246ac8b33ba5d1e10d81f636ace18cc882dc99f
+  metadata.gz: 67a468ca21123613319181955fd418268f661dc8beaee1c5eab2054395759478
+  data.tar.gz: 33047d74b3e2caaa47ce7ef1868bb5b2dba260e3dc97e116fa0b7fba4c6ec07d
 SHA512:
-  metadata.gz: ad24aba7c7359f01a11e94ddd1e469fdac2a77c59ece3a113cacebaf900e1cec9a9eee462b385c05d9f1789f9f5c6b48da5098b060e2c5b2c99cc5e312c4d435
-  data.tar.gz: 96eb1200ee5bdf95e2c9f6b8f91d856607f7981f0eabf7c5cee75dbb3efa200c7642f0886ffdad1965da123281c9cfe8d545614616702cadf4dc207da83a293d
+  metadata.gz: 219f3a08a9413835762ee7af7108324e1d2819f3a4a4e4d35c1451b2ad60453f09b8e5783070c879fa644b87199c4e825d40978894489ded72f90ddc99b73a79
+  data.tar.gz: 532ca543f7dc346385336ba11e876f14667825d5ef67b6bd1b308ef91c1306591a203adf638894b8a720e1d0abeed0af9ac66ff941dc5b41229261719d47fd21

data/.github/workflows/ci.yml

@@ -37,6 +37,20 @@ jobs:
           RUBYOPT: "--enable=frozen-string-literal --debug=frozen-string-literal"
         run: "bundle exec rspec --backtrace --fail-fast"
 
+  test_ractors:
+    name: "Ractor tests (Ruby 4.0)"
+    runs-on: ubuntu-22.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '4.0'
+          bundler-cache: true
+      - name: "Tests"
+        run: "bundle exec rspec --backtrace --fail-fast spec/zip_kit/ractor_spec.rb"
+
   lint_baseline_ruby: # We need to use syntax appropriate for the minimum supported Ruby version
     name: Lint (Ruby 2.6 syntax)
     runs-on: ubuntu-22.04

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## 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`).
+* Make ZipKit usable from within Ractors: freeze the computed String constants in `ZipWriter`, `BlockDeflate` and `RackChunkedBody`, and stop defining the raising `BlockWrite` methods with `define_method`. Ractor tests run on Ruby 4.0 in CI.
+
 ## 6.3.5
 
 * Make `WriteBuffer#<<` much faster for lots of tiny writes, like the XML fragments written by libraries such as caxlsx. Strings are no longer copied with `String#b` before being appended: on Ruby 3.4+ `String#append_as_bytes` is used, on older Rubies the string is converted only if Ruby refuses to append it. Mixing binary strings and non-ASCII strings still works, and the writable still always receives binary strings.

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/Rakefile

@@ -16,6 +16,14 @@ RSpec::Core::RakeTask.new(:spec)
 task :generate_typedefs do
   `bundle exec sord rbi/zip_kit.rbi`
   `bundle exec sord rbi/zip_kit.rbs`
+
+  # Sord inlines the VERSION literal, which would make every version bump produce a typedef diff
+  rbi_path = "rbi/zip_kit.rbi"
+  rbi = File.read(rbi_path).sub(/^(\s*)VERSION = T\.let\(.+\)$/, '\1VERSION = T.let(T.unsafe(nil), String)')
+  File.write(rbi_path, rbi)
+  rbs_path = "rbi/zip_kit.rbs"
+  rbs = File.read(rbs_path).sub(/^(\s*)VERSION: untyped$/, '\1VERSION: String')
+  File.write(rbs_path, rbs)
 end
 
 task default: [:spec, :standard, :generate_typedefs]

data/lib/zip_kit/block_deflate.rb

@@ -47,7 +47,7 @@
 
 class ZipKit::BlockDeflate
   DEFAULT_BLOCKSIZE = 1_024 * 1024 * 5
-  END_MARKER = [3, 0].pack("C*")
+  END_MARKER = [3, 0].pack("C*").freeze
   # Zlib::NO_COMPRESSION..
   VALID_COMPRESSIONS = (Zlib::DEFAULT_COMPRESSION..Zlib::BEST_COMPRESSION).to_a.freeze
   # Write the end marker (\x3\x0) to the given IO.

data/lib/zip_kit/block_write.rb

@@ -27,11 +27,18 @@ class ZipKit::BlockWrite
     @block = block
   end
 
-  # Make sure those methods raise outright
-  %i[seek pos= to_s].each do |m|
-    define_method(m) do |*_args|
-      raise "#{m} not supported - this IO adapter is non-rewindable"
-    end
+  # Make sure those methods raise outright. These are not created with define_method,
+  # because methods defined with a block can't be called from a non-main Ractor
+  def seek(*)
+    raise "seek not supported - this IO adapter is non-rewindable"
+  end
+
+  def pos=(*)
+    raise "pos= not supported - this IO adapter is non-rewindable"
+  end
+
+  def to_s(*)
+    raise "to_s not supported - this IO adapter is non-rewindable"
   end
 
   # Sends a string through to the block stored in the BlockWrite.

data/lib/zip_kit/rack_chunked_body.rb

@@ -9,7 +9,7 @@
 # carry, so we copy it into our code.
 class ZipKit::RackChunkedBody
   TERM = "\r\n"
-  TAIL = "0#{TERM}"
+  TAIL = "0\r\n"
 
   # @param body[#each] the enumerable that yields bytes, usually a `OutputEnumerator`
   def initialize(body)

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
@@ -412,11 +478,10 @@ class ZipKit::Streamer
     # 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 do |entry|
-      # Skip fillers which are standing in for broken/incomplete files
-      next if entry.filler?
-
+    # Write out the central directory entries, one for each file.
+    # Skip fillers which are standing in for broken/incomplete files
+    entries = @files.reject(&:filler?)
+    entries.each do |entry|
       @writer.write_central_directory_file_header(io: @out,
         local_file_header_location: entry.local_header_offset,
         gp_flags: entry.gp_flags,
@@ -426,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
@@ -436,11 +502,12 @@ class ZipKit::Streamer
     @writer.write_end_of_central_directory(io: @out,
       start_of_central_directory_location: cdir_starts_at,
       central_directory_size: cdir_size,
-      num_files_in_archive: @files.length)
+      num_files_in_archive: entries.length)
 
     # 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
@@ -510,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
@@ -573,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)
@@ -586,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?("/")
@@ -597,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
@@ -616,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,
@@ -625,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
 
@@ -633,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.5"
+  VERSION = "6.4.0"
 end

data/lib/zip_kit/zip_writer.rb

@@ -29,7 +29,7 @@ require "stringio"
 class ZipKit::ZipWriter
   FOUR_BYTE_MAX_UINT = 0xFFFFFFFF
   TWO_BYTE_MAX_UINT = 0xFFFF
-  ZIP_KIT_COMMENT = "Written using ZipKit %<version>s" % {version: ZipKit::VERSION}
+  ZIP_KIT_COMMENT = ("Written using ZipKit %<version>s" % {version: ZipKit::VERSION}).freeze
   VERSION_MADE_BY = 52
   VERSION_NEEDED_TO_EXTRACT = 20
   VERSION_NEEDED_TO_EXTRACT_ZIP64 = 45
@@ -40,7 +40,7 @@ class ZipKit::ZipWriter
   MADE_BY_SIGNATURE = begin
     # A combination of the VERSION_MADE_BY low byte and the OS type high byte
     os_type = 3 # UNIX
-    [VERSION_MADE_BY, os_type].pack("CC")
+    [VERSION_MADE_BY, os_type].pack("CC").freeze
   end
 
   C_UINT4 = "V" # Encode a 4-byte unsigned little-endian uint
@@ -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

@@ -1,6 +1,6 @@
 # typed: strong
 module ZipKit
-  VERSION = T.let("6.3.5", T.untyped)
+  VERSION = T.let(T.unsafe(nil), String)
 
   class Railtie < Rails::Railtie
   end
@@ -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.
@@ -942,7 +1021,7 @@ module ZipKit
   class ZipWriter
     FOUR_BYTE_MAX_UINT = T.let(0xFFFFFFFF, T.untyped)
     TWO_BYTE_MAX_UINT = T.let(0xFFFF, T.untyped)
-    ZIP_KIT_COMMENT = T.let("Written using ZipKit %<version>s" % {version: ZipKit::VERSION}, T.untyped)
+    ZIP_KIT_COMMENT = T.let(("Written using ZipKit %<version>s" % {version: ZipKit::VERSION}).freeze, T.untyped)
     VERSION_MADE_BY = T.let(52, T.untyped)
     VERSION_NEEDED_TO_EXTRACT = T.let(20, T.untyped)
     VERSION_NEEDED_TO_EXTRACT_ZIP64 = T.let(45, T.untyped)
@@ -953,7 +1032,7 @@ module ZipKit
     MADE_BY_SIGNATURE = T.let(begin
   # A combination of the VERSION_MADE_BY low byte and the OS type high byte
   os_type = 3 # UNIX
-  [VERSION_MADE_BY, os_type].pack("CC")
+  [VERSION_MADE_BY, os_type].pack("CC").freeze
 end, T.untyped)
     C_UINT4 = T.let("V", T.untyped)
     C_UINT2 = T.let("v", T.untyped)
@@ -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
@@ -1164,6 +1249,20 @@ end, T.untyped)
     sig { params(block: T.proc.params(bytes: String).void).void }
     def initialize(&block); end
 
+    # sord omit - no YARD return type given, using untyped
+    # Make sure those methods raise outright. These are not created with define_method,
+    # because methods defined with a block can't be called from a non-main Ractor
+    sig { returns(T.untyped) }
+    def seek; end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def pos=; end
+
+    # sord omit - no YARD return type given, using untyped
+    sig { returns(T.untyped) }
+    def to_s; end
+
     # Sends a string through to the block stored in the BlockWrite.
     # 
     # _@param_ `buf` — the string to write. Note that a zero-length String will not be forwarded to the block, as it has special meaning when used with chunked encoding (it indicates the end of the stream).
@@ -1879,7 +1978,7 @@ end, T.untyped)
   #     compressed_string = ZipKit::BlockDeflate.deflate_chunk(big_string)
   class BlockDeflate
     DEFAULT_BLOCKSIZE = T.let(1_024 * 1024 * 5, T.untyped)
-    END_MARKER = T.let([3, 0].pack("C*"), T.untyped)
+    END_MARKER = T.let([3, 0].pack("C*").freeze, T.untyped)
     VALID_COMPRESSIONS = T.let((Zlib::DEFAULT_COMPRESSION..Zlib::BEST_COMPRESSION).to_a.freeze, T.untyped)
 
     # Write the end marker (\x3\x0) to the given IO.
@@ -2016,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
@@ -2225,7 +2333,7 @@ end, T.untyped)
   # carry, so we copy it into our code.
   class RackChunkedBody
     TERM = T.let("\r\n", T.untyped)
-    TAIL = T.let("0#{TERM}", T.untyped)
+    TAIL = T.let("0\r\n", T.untyped)
 
     # sord duck - #each looks like a duck type, replacing with untyped
     # _@param_ `body` — the enumerable that yields bytes, usually a `OutputEnumerator`

data/rbi/zip_kit.rbs

@@ -1,5 +1,5 @@
 module ZipKit
-  VERSION: untyped
+  VERSION: String
 
   class Railtie < Rails::Railtie
   end
@@ -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
@@ -1038,6 +1105,17 @@ module ZipKit
     # _@param_ `block` — The block that will be called when this object receives the `<<` message
     def initialize: () ?{ (String bytes) -> void } -> void
 
+    # sord omit - no YARD return type given, using untyped
+    # Make sure those methods raise outright. These are not created with define_method,
+    # because methods defined with a block can't be called from a non-main Ractor
+    def seek: () -> untyped
+
+    # sord omit - no YARD return type given, using untyped
+    def pos=: () -> untyped
+
+    # sord omit - no YARD return type given, using untyped
+    def to_s: () -> untyped
+
     # Sends a string through to the block stored in the BlockWrite.
     # 
     # _@param_ `buf` — the string to write. Note that a zero-length String will not be forwarded to the block, as it has special meaning when used with chunked encoding (it indicates the end of the stream).
@@ -1769,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.5
+  version: 6.4.0
 platform: ruby
 authors:
 - Julik Tarkhanov
@@ -11,7 +11,7 @@ authors:
 - Felix Bünemann
 bindir: exe
 cert_chain: []
-date: 2026-09-30 00:00:00.000000000 Z
+date: 2026-10-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler