zip_kit 6.3.4 → 6.3.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f513e5300c8daa205994e7aa5a957c2270ea7378fab0dd13f57effd8f431d1ea
-  data.tar.gz: 9873a993a94a45339e9a1f383862ed1cc942db2fd23f4d09f6da70705afcf123
+  metadata.gz: 687884a060911fe25101e41be05bd32f4b50068c2ac592acec9937e5b0912f47
+  data.tar.gz: c209fb4839008ca84b956839db24ff65d8ec3ae390c4666aabe34743258409ec
 SHA512:
-  metadata.gz: 4e3ace1ea348f7232d04932981bb5a3d4fb2f1f5e32f01523d5420bff97cc119b7a54bc9bd0f2269f92785167fa2acfdf1e013551def137d69f02e559deae244
-  data.tar.gz: 41c9791db83d11845dfff560526bf4d32cfaf7a0be99933a20ef2677d2027064bd7dd8f1071ac6a7b1864362c6cefa439728b422dcdb9c7529394233ad1dd85b
+  metadata.gz: bf6bf944be2ec57fd53950c046f5ed28565c5d97f73edc91fbaf1094319d0c2ad47b0a6c6ae1194e69f7fdab3e85beb479b41755e499497fe7f4ab2423529858
+  data.tar.gz: 1d54ad55c06b14297057bc594ff45f74a551b453e9cc5d846595abf238289ed0b7b9175177d089db87bceb9601c9322773a44d4601d3a6b32fb30f331f7bbcff

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,3 +1,18 @@
+## Unreleased
+
+## 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.
+* `WriteBuffer` now flushes before a write would make the buffer exceed its size (instead of after), so that it never outputs chunks larger than the buffer size, and writes which are larger than the buffer size are still passed through without getting copied.
+* `WriteBuffer` no longer preallocates (and immediately discards) a zero-filled String of twice its buffer size, which makes writing ZIPs with lots of small files faster.
+* Require `stringio` in `ZipWriter`, which uses it. Previously writing a ZIP could fail with a `NameError` if nothing else in the process had loaded `stringio`.
+* Add `bench/write_buffer_bench.rb`
+
 ## 6.3.4
 
 * Fix a bug whereby `rollback!` would cause an exception without any entries having been written yet (rollback on first entry).

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/bench/write_buffer_bench.rb

@@ -0,0 +1,183 @@
+# Benchmarks ZipKit::WriteBuffer with lots of tiny writes (like the XML fragments
+# a library such as caxlsx produces) and with large writes, comparing it to the
+# previous implementations of WriteBuffer.
+#
+#   bundle exec ruby bench/write_buffer_bench.rb
+require "bundler"
+Bundler.setup
+
+require "benchmark"
+require "benchmark/ips"
+require_relative "../lib/zip_kit"
+
+# Initialization and flushing as in zip_kit 6.3.x. These are not subclasses of ZipKit::WriteBuffer
+# on purpose: with Ruby 3.4, instances of a subclass can have a different object shape, which
+# can make the instance variable caches of methods they share with ZipKit::WriteBuffer miss.
+module WriteBuffer63x
+  def initialize(writable, buffer_size)
+    @buf = ("\0".b * (buffer_size * 2)).clear
+    @buffer_size = buffer_size
+    @writable = writable
+  end
+
+  def flush
+    unless @buf.empty?
+      @writable << @buf
+      @buf.clear
+    end
+    self
+  end
+end
+
+# WriteBuffer#<< as of zip_kit 6.3.2
+class WriteBuffer632
+  include WriteBuffer63x
+
+  def <<(data)
+    if data.bytesize >= @buffer_size
+      flush unless @buf.empty?
+      @writable << data
+    else
+      @buf << data
+      flush if @buf.bytesize >= @buffer_size
+    end
+    self
+  end
+end
+
+# WriteBuffer#<< as of zip_kit 6.3.3/6.3.4, which copies every string with String#b
+class WriteBuffer634
+  include WriteBuffer63x
+
+  def <<(string)
+    if string.bytesize >= @buffer_size
+      flush
+      @writable << string.b
+    else
+      @buf << string.b
+      flush if @buf.bytesize >= @buffer_size
+    end
+    self
+  end
+end
+
+# The simplest possible buffer, which does not deal with encodings or large writes
+class NaiveBuffer
+  def initialize(io, buffer_size)
+    @io = io
+    @buffer_size = buffer_size
+    @buf = "".b
+  end
+
+  def <<(fragment)
+    @buf << fragment
+    flush if @buf.bytesize >= @buffer_size
+    self
+  end
+
+  def flush
+    return if @buf.empty?
+    @io << @buf
+    @buf.clear
+  end
+end
+
+BUFFER_SIZE = 64 * 1024
+IMPLEMENTATIONS = {
+  "WriteBuffer" => ZipKit::WriteBuffer,
+  "WriteBuffer (6.3.2)" => WriteBuffer632,
+  "WriteBuffer (6.3.4, String#b)" => WriteBuffer634,
+  "Naive String buffer" => NaiveBuffer
+}
+
+# Fragments like the ones produced by caxlsx when writing out a worksheet: mostly frozen
+# literals and short dynamic strings (UTF-8 or US-ASCII), mostly ASCII-only.
+fragments = []
+20_000.times do |row|
+  fragments << "<row r=\"" << (row + 1).to_s << "\">"
+  6.times do |col|
+    fragments << "<c r=\"" << "#{("A".ord + col).chr}#{row + 1}" << "\" s=\"" << "1" << "\""
+    fragments << ((col == 3) ? " t=\"inlineStr\"><is><t>Grüße, #{row}</t></is>" : "><v>#{row * col}</v>")
+    fragments << "</c>"
+  end
+  fragments << "</row>"
+end
+n_bytes = fragments.sum(&:bytesize)
+
+puts RUBY_DESCRIPTION
+puts "#{fragments.length} tiny writes (#{n_bytes} bytes, #{(n_bytes.to_f / fragments.length).round(1)} bytes per write on average)"
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+  IMPLEMENTATIONS.each do |name, buffer_class|
+    x.report("#{name}, tiny writes into CRC32") do
+      buf = buffer_class.new(ZipKit::StreamCRC32.new, BUFFER_SIZE)
+      fragments.each { |fragment| buf << fragment }
+      buf.flush
+    end
+  end
+  x.compare!
+end
+
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+  IMPLEMENTATIONS.each do |name, buffer_class|
+    x.report("#{name}, tiny writes into write_deflated_file") do
+      ZipKit::Streamer.open(ZipKit::NullWriter) do |zip|
+        zip.write_deflated_file("sheet.xml") do |sink|
+          buf = buffer_class.new(sink, BUFFER_SIZE)
+          fragments.each { |fragment| buf << fragment }
+          buf.flush
+        end
+      end
+    end
+  end
+  x.report("No buffer, tiny writes into write_deflated_file") do
+    ZipKit::Streamer.open(ZipKit::NullWriter) do |zip|
+      zip.write_deflated_file("sheet.xml") do |sink|
+        fragments.each { |fragment| sink << fragment }
+      end
+    end
+  end
+  x.compare!
+end
+
+large_chunk = Random.new(42).bytes(1024 * 1024)
+Benchmark.ips do |x|
+  x.config(time: 5, warmup: 2)
+  IMPLEMENTATIONS.each do |name, buffer_class|
+    x.report("#{name}, 64 writes of 1MB into CRC32") do
+      buf = buffer_class.new(ZipKit::StreamCRC32.new, BUFFER_SIZE)
+      64.times { buf << large_chunk }
+      buf.flush
+    end
+  end
+  x.compare!
+end
+
+__END__
+
+Apple M1 Pro, macOS 15.7
+
+ruby 3.4.1 (2024-12-25 revision 48d4efcb85) +PRISM [arm64-darwin24], without YJIT
+920000 tiny writes (5189483 bytes, 5.6 bytes per write on average)
+
+Comparison:
+Naive String buffer, tiny writes into CRC32:       12.1 i/s
+WriteBuffer, tiny writes into CRC32:       12.0 i/s - 1.01x  slower
+WriteBuffer (6.3.2), tiny writes into CRC32:       10.3 i/s - 1.17x  slower
+WriteBuffer (6.3.4, String#b), tiny writes into CRC32:        8.0 i/s - 1.51x  slower
+
+Comparison:
+Naive String buffer, tiny writes into write_deflated_file:        7.6 i/s
+WriteBuffer, tiny writes into write_deflated_file:        7.4 i/s - 1.02x  slower
+WriteBuffer (6.3.2), tiny writes into write_deflated_file:        6.8 i/s - 1.12x  slower
+WriteBuffer (6.3.4, String#b), tiny writes into write_deflated_file:        5.7 i/s - 1.33x  slower
+No buffer, tiny writes into write_deflated_file:        1.8 i/s - 4.18x  slower
+
+Comparison:
+WriteBuffer (6.3.2), 64 writes of 1MB into CRC32:      464.4 i/s
+WriteBuffer (6.3.4, String#b), 64 writes of 1MB into CRC32:      463.0 i/s - same-ish: difference falls within error
+WriteBuffer, 64 writes of 1MB into CRC32:      462.9 i/s - same-ish: difference falls within error
+Naive String buffer, 64 writes of 1MB into CRC32:      121.5 i/s - 3.82x  slower
+

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/streamer.rb

@@ -412,11 +412,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,
@@ -436,7 +435,7 @@ 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

data/lib/zip_kit/version.rb

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

data/lib/zip_kit/write_buffer.rb

@@ -12,10 +12,23 @@
 # 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
+# The WriteBuffer is also useful in front of a `write_file` / `write_deflated_file` writable
+# if you are going to be appending lots of tiny strings (like XML fragments) to it. Every write
+# into a writable goes through Zlib separately, so coalescing those writes into bigger chunks
+# is much faster.
+#
+# All strings appended to the WriteBuffer are appended as bytes, and the buffer String
+# given to the writable is always in binary encoding (`Encoding::BINARY`). You can therefore mix
+# binary strings and strings in other encodings (for instance UTF-8 with non-ASCII characters)
+# without getting an `Encoding::CompatibilityError`. No intermediate copies of the strings
+# you append (like `String#b` would create) are made.
+#
+# Note that there is no guarantee that the write buffer is going to flush at exactly
+# the given `buffer_size`. The buffer gets flushed when the next write would make it exceed
+# `buffer_size`, so the chunks it outputs are usually a bit smaller than that (strings with
+# multibyte characters can make it go slightly over). For writes of `buffer_size` or larger
+# 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.
 #
@@ -25,16 +38,19 @@
 # to `<<`. Therefore, if you need to retain the output of the WriteBuffer in, say, an Array,
 # you might need to `.dup` the `String` it gives you.
 class ZipKit::WriteBuffer
+  # String#append_as_bytes (Ruby 3.4+) appends the bytes of the string without any encoding
+  # negotiation, so the buffer always stays binary. Without it we use String#<<, see `append_bytes`.
+  APPEND_AS_BYTES = String.instance_methods.include?(:append_as_bytes)
+
   # Creates a new WriteBuffer bypassing into a given writable object
   #
   # @param writable[#<<] An object that responds to `#<<` with a String as argument
   # @param buffer_size[Integer] How many bytes to buffer
   def initialize(writable, buffer_size)
-    # Allocating the buffer using a zero-padded String as a variation
-    # on using capacity:, which JRuby apparently does not like very much. The
-    # desire here is that the buffer doesn't have to be resized during the lifetime
-    # of the object.
-    @buf = ("\0".b * (buffer_size * 2)).clear
+    # No capacity gets preallocated. String#clear releases the memory held by the String,
+    # so after the first flush the buffer would have to grow again anyway - and many
+    # WriteBuffers (like the ones used for the CRC32 of small ZIP entries) never fill up.
+    @buf = "".b
     @buffer_size = buffer_size
     @writable = writable
   end
@@ -45,11 +61,15 @@ class ZipKit::WriteBuffer
   # @param string[String] data to be written
   # @return self
   def <<(string)
-    if string.bytesize >= @buffer_size
-      flush # <- this is were we can output less than @buffer_size
+    if @buf.bytesize + string.bytesize < @buffer_size
+      APPEND_AS_BYTES ? @buf.append_as_bytes(string) : append_bytes(string)
+    elsif string.bytesize >= @buffer_size
+      flush
+      # String#b does not copy the bytes of a large String, the new String shares them
       @writable << string.b
     else
-      @buf << string.b
+      flush if @buf.bytesize + string.bytesize > @buffer_size
+      append_bytes(string)
       flush if @buf.bytesize >= @buffer_size
     end
     self
@@ -60,7 +80,8 @@ class ZipKit::WriteBuffer
   # @return self
   def flush
     unless @buf.empty?
-      @writable << @buf
+      # force_encoding does not copy the String, it only changes its encoding
+      @writable << @buf.force_encoding(Encoding::BINARY)
       @buf.clear
     end
     self
@@ -68,4 +89,19 @@ class ZipKit::WriteBuffer
 
   # `flush!` was renamed to `flush` but we preserve this method for backwards compatibility
   alias_method :flush!, :flush
+
+  private
+
+  # Appends the bytes of the string without copying it. Without String#append_as_bytes (Ruby < 3.4)
+  # String#<< is used, which may change the encoding of the buffer or raise if the encodings are
+  # incompatible - in that case we append the bytes of the string instead. The buffer is forced
+  # back into binary before it is handed to the writable, see `flush`.
+  def append_bytes(string)
+    return @buf.append_as_bytes(string) if APPEND_AS_BYTES
+
+    @buf << string
+  rescue Encoding::CompatibilityError
+    @buf.force_encoding(Encoding::BINARY)
+    @buf << string.b
+  end
 end

data/lib/zip_kit/zip_writer.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "stringio"
+
 # A low-level ZIP file data writer. You can use it to write out various headers and central directory elements
 # separately. The class handles the actual encoding of the data according to the ZIP format APPNOTE document.
 #
@@ -27,7 +29,7 @@
 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
@@ -38,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

data/rbi/zip_kit.rbi

@@ -1,6 +1,6 @@
 # typed: strong
 module ZipKit
-  VERSION = T.let("6.3.4", T.untyped)
+  VERSION = T.let(T.unsafe(nil), String)
 
   class Railtie < Rails::Railtie
   end
@@ -942,7 +942,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 +953,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)
@@ -1164,6 +1164,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).
@@ -1737,10 +1751,23 @@ end, T.untyped)
   # 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
+  # The WriteBuffer is also useful in front of a `write_file` / `write_deflated_file` writable
+  # if you are going to be appending lots of tiny strings (like XML fragments) to it. Every write
+  # into a writable goes through Zlib separately, so coalescing those writes into bigger chunks
+  # is much faster.
+  # 
+  # All strings appended to the WriteBuffer are appended as bytes, and the buffer String
+  # given to the writable is always in binary encoding (`Encoding::BINARY`). You can therefore mix
+  # binary strings and strings in other encodings (for instance UTF-8 with non-ASCII characters)
+  # without getting an `Encoding::CompatibilityError`. No intermediate copies of the strings
+  # you append (like `String#b` would create) are made.
+  # 
+  # Note that there is no guarantee that the write buffer is going to flush at exactly
+  # the given `buffer_size`. The buffer gets flushed when the next write would make it exceed
+  # `buffer_size`, so the chunks it outputs are usually a bit smaller than that (strings with
+  # multibyte characters can make it go slightly over). For writes of `buffer_size` or larger
+  # 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.
   # 
@@ -1750,6 +1777,8 @@ end, T.untyped)
   # 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 WriteBuffer
+    APPEND_AS_BYTES = T.let(String.instance_methods.include?(:append_as_bytes), T.untyped)
+
     # sord duck - #<< looks like a duck type, replacing with untyped
     # Creates a new WriteBuffer bypassing into a given writable object
     # 
@@ -1773,6 +1802,15 @@ end, T.untyped)
     # _@return_ — self
     sig { returns(T.untyped) }
     def flush; end
+
+    # sord omit - no YARD type given for "string", using untyped
+    # sord omit - no YARD return type given, using untyped
+    # Appends the bytes of the string without copying it. Without String#append_as_bytes (Ruby < 3.4)
+    # String#<< is used, which may change the encoding of the buffer or raise if the encodings are
+    # incompatible - in that case we append the bytes of the string instead. The buffer is forced
+    # back into binary before it is handed to the writable, see `flush`.
+    sig { params(string: T.untyped).returns(T.untyped) }
+    def append_bytes(string); end
   end
 
   # A lot of objects in ZipKit accept bytes that may be sent
@@ -1855,7 +1893,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.
@@ -2201,7 +2239,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
@@ -1038,6 +1038,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).
@@ -1510,10 +1521,23 @@ module ZipKit
   # 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
+  # The WriteBuffer is also useful in front of a `write_file` / `write_deflated_file` writable
+  # if you are going to be appending lots of tiny strings (like XML fragments) to it. Every write
+  # into a writable goes through Zlib separately, so coalescing those writes into bigger chunks
+  # is much faster.
+  # 
+  # All strings appended to the WriteBuffer are appended as bytes, and the buffer String
+  # given to the writable is always in binary encoding (`Encoding::BINARY`). You can therefore mix
+  # binary strings and strings in other encodings (for instance UTF-8 with non-ASCII characters)
+  # without getting an `Encoding::CompatibilityError`. No intermediate copies of the strings
+  # you append (like `String#b` would create) are made.
+  # 
+  # Note that there is no guarantee that the write buffer is going to flush at exactly
+  # the given `buffer_size`. The buffer gets flushed when the next write would make it exceed
+  # `buffer_size`, so the chunks it outputs are usually a bit smaller than that (strings with
+  # multibyte characters can make it go slightly over). For writes of `buffer_size` or larger
+  # 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.
   # 
@@ -1523,6 +1547,8 @@ module ZipKit
   # 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 WriteBuffer
+    APPEND_AS_BYTES: untyped
+
     # sord duck - #<< looks like a duck type, replacing with untyped
     # Creates a new WriteBuffer bypassing into a given writable object
     # 
@@ -1543,6 +1569,14 @@ module ZipKit
     # 
     # _@return_ — self
     def flush: () -> untyped
+
+    # sord omit - no YARD type given for "string", using untyped
+    # sord omit - no YARD return type given, using untyped
+    # Appends the bytes of the string without copying it. Without String#append_as_bytes (Ruby < 3.4)
+    # String#<< is used, which may change the encoding of the buffer or raise if the encodings are
+    # incompatible - in that case we append the bytes of the string instead. The buffer is forced
+    # back into binary before it is handed to the writable, see `flush`.
+    def append_bytes: (untyped string) -> untyped
   end
 
   # A lot of objects in ZipKit accept bytes that may be sent

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: zip_kit
 version: !ruby/object:Gem::Version
-  version: 6.3.4
+  version: 6.3.6
 platform: ruby
 authors:
 - Julik Tarkhanov
@@ -11,7 +11,7 @@ authors:
 - Felix Bünemann
 bindir: exe
 cert_chain: []
-date: 2025-11-17 00:00:00.000000000 Z
+date: 2026-10-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -367,6 +367,7 @@ files:
 - README.md
 - RUBYZIP_DIFFERENCES.md
 - Rakefile
+- bench/write_buffer_bench.rb
 - examples/archive_size_estimate.rb
 - examples/config.ru
 - examples/deferred_write.rb