zip_kit 6.3.2 → 6.3.3

data/rbi/zip_kit.rbs

@@ -0,0 +1,2000 @@
+module ZipKit
+  VERSION: untyped
+
+  class Railtie < Rails::Railtie
+  end
+
+  # A ZIP archive contains a flat list of entries. These entries can implicitly
+  # create directories when the archive is expanded. For example, an entry with
+  # the filename of "some folder/file.docx" will make the unarchiving application
+  # create a directory called "some folder" automatically, and then deposit the
+  # file "file.docx" in that directory. These "implicit" directories can be
+  # arbitrarily nested, and create a tree structure of directories. That structure
+  # however is implicit as the archive contains a flat list.
+  # 
+  # This creates opportunities for conflicts. For example, imagine the following
+  # structure:
+  # 
+  # * `something/` - specifies an empty directory with the name "something"
+  # * `something` - specifies a file, creates a conflict
+  # 
+  # This can be prevented with filename uniqueness checks. It does get funkier however
+  # as the rabbit hole goes down:
+  # 
+  # * `dir/subdir/another_subdir/yet_another_subdir/file.bin` - declares a file and directories
+  # * `dir/subdir/another_subdir/yet_another_subdir` - declares a file at one of the levels, creates a conflict
+  # 
+  # The results of this ZIP structure aren't very easy to predict as they depend on the
+  # application that opens the archive. For example, BOMArchiveHelper on macOS will expand files
+  # as they are declared in the ZIP, but once a conflict occurs it will fail with "error -21". It
+  # is not very transparent to the user why unarchiving fails, and it has to - and can reliably - only
+  # be prevented when the archive gets created.
+  # 
+  # Unfortunately that conflicts with another "magical" feature of ZipKit which automatically
+  # "fixes" duplicate filenames - filenames (paths) which have already been added to the archive.
+  # This fix is performed by appending (1), then (2) and so forth to the filename so that the
+  # conflict is avoided. This is not possible to apply to directories, because when one of the
+  # path components is reused in multiple filenames it means those entities should end up in
+  # the same directory (subdirectory) once the archive is opened.
+  # 
+  # The `PathSet` keeps track of entries as they get added using 2 Sets (cheap presence checks),
+  # one for directories and one for files. It will raise a `Conflict` exception if there are
+  # files clobbering one another, or in case files collide with directories.
+  class PathSet
+    def initialize: () -> void
+
+    # Adds a directory path to the set of known paths, including
+    # all the directories that contain it. So, calling
+    #    add_directory_path("dir/dir2/dir3")
+    # will add "dir", "dir/dir2", "dir/dir2/dir3".
+    # 
+    # _@param_ `path` — the path to the directory to add
+    def add_directory_path: (String path) -> void
+
+    # Adds a file path to the set of known paths, including
+    # all the directories that contain it. Once a file has been added,
+    # it is no longer possible to add a directory having the same path
+    # as this would cause conflict.
+    # 
+    # The operation also adds all the containing directories for the file, so
+    #    add_file_path("dir/dir2/file.doc")
+    # will add "dir" and "dir/dir2" as directories, "dir/dir2/dir3".
+    # 
+    # _@param_ `file_path` — the path to the directory to add
+    def add_file_path: (String file_path) -> void
+
+    # Tells whether a specific full path is already known to the PathSet.
+    # Can be a path for a directory or for a file.
+    # 
+    # _@param_ `path_in_archive` — the path to check for inclusion
+    def include?: (String path_in_archive) -> bool
+
+    # Clears the contained sets
+    def clear: () -> void
+
+    # sord omit - no YARD type given for "path_in_archive", using untyped
+    # Adds the directory or file path to the path set
+    def add_directory_or_file_path: (untyped path_in_archive) -> void
+
+    # sord omit - no YARD type given for "path", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def non_empty_path_components: (untyped path) -> untyped
+
+    # sord omit - no YARD type given for "path", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def path_and_ancestors: (untyped path) -> untyped
+
+    class Conflict < StandardError
+    end
+
+    class FileClobbersDirectory < ZipKit::PathSet::Conflict
+    end
+
+    class DirectoryClobbersFile < ZipKit::PathSet::Conflict
+    end
+  end
+
+  # Is used to write ZIP archives without having to read them back or to overwrite
+  # data. It outputs into any object that supports `<<` or `write`, namely:
+  # 
+  # * `Array` - will contain binary strings
+  # * `File` - data will be written to it as it gets generated
+  # * `IO` (`Socket`, `StringIO`) - data gets written into it
+  # * `String` - in binary encoding and unfrozen - also makes a decent output target
+  # 
+  # or anything else that responds to `#<<` or `#write`.
+  # 
+  # You can also combine output through the `Streamer` with direct output to the destination,
+  # all while preserving the correct offsets in the ZIP file structures. This allows usage
+  # of `sendfile()` or socket `splice()` calls for "through" proxying.
+  # 
+  # If you want to avoid data descriptors - or write data bypassing the Streamer -
+  # you need to know the CRC32 (as a uint) and the filesize upfront,
+  # before the writing of the entry body starts.
+  # 
+  # ## Using the Streamer with runtime compression
+  # 
+  # You can use the Streamer with data descriptors (the CRC32 and the sizes will be
+  # written after the file data). This allows non-rewinding on-the-fly compression.
+  # The streamer will pick the optimum compression method ("stored" or "deflated")
+  # depending on the nature of the byte stream you send into it (by using a small buffer).
+  # If you are compressing large files, the Deflater object that the Streamer controls
+  # will be regularly flushed to prevent memory inflation.
+  # 
+  #     ZipKit::Streamer.open(file_socket_or_string) do |zip|
+  #       zip.write_file('mov.mp4') do |sink|
+  #         File.open('mov.mp4', 'rb'){|source| IO.copy_stream(source, sink) }
+  #       end
+  #       zip.write_file('long-novel.txt') do |sink|
+  #         File.open('novel.txt', 'rb'){|source| IO.copy_stream(source, sink) }
+  #       end
+  #     end
+  # 
+  # The central directory will be written automatically at the end of the `open` block.
+  # 
+  # ## Using the Streamer with entries of known size and having a known CRC32 checksum
+  # 
+  # Streamer allows "IO splicing" - in this mode it will only control the metadata output,
+  # but you can write the data to the socket/file outside of the Streamer. For example, when
+  # using the sendfile gem:
+  # 
+  #     ZipKit::Streamer.open(socket) do | zip |
+  #       zip.add_stored_entry(filename: "myfile1.bin", size: 9090821, crc32: 12485)
+  #       socket.sendfile(tempfile1)
+  #       zip.simulate_write(tempfile1.size)
+  # 
+  #       zip.add_stored_entry(filename: "myfile2.bin", size: 458678, crc32: 89568)
+  #       socket.sendfile(tempfile2)
+  #       zip.simulate_write(tempfile2.size)
+  #     end
+  # 
+  # Note that you need to use `simulate_write` in this case. This needs to happen since Streamer
+  # writes absolute offsets into the ZIP (local file header offsets and the like),
+  # and it relies on the output object to tell it how many bytes have been written
+  # so far. When using `sendfile` the Ruby write methods get bypassed entirely, and the
+  # offsets in the IO will not be updated - which will result in an invalid ZIP.
+  # 
+  # 
+  # ## On-the-fly deflate -using the Streamer with async/suspended writes and data descriptors
+  # 
+  # If you are unable to use the block versions of `write_deflated_file` and `write_stored_file`
+  # there is an option to use a separate writer object. It gets returned from `write_deflated_file`
+  # and `write_stored_file` if you do not provide them with a block, and will accept data writes.
+  # Do note that you _must_ call `#close` on that object yourself:
+  # 
+  #     ZipKit::Streamer.open(socket) do | zip |
+  #       w = zip.write_stored_file('mov.mp4')
+  #       IO.copy_stream(source_io, w)
+  #       w.close
+  #     end
+  # 
+  # The central directory will be written automatically at the end of the `open` block. If you need
+  # to manage the Streamer manually, or defer the central directory write until appropriate, use
+  # the constructor instead and call `Streamer#close`:
+  # 
+  #     zip = ZipKit::Streamer.new(out_io)
+  #     .....
+  #     zip.close
+  # 
+  # Calling {Streamer#close} **will not** call `#close` on the underlying IO object.
+  class Streamer
+    include ZipKit::WriteShovel
+    STORED: untyped
+    DEFLATED: untyped
+    EntryBodySizeMismatch: untyped
+    InvalidOutput: untyped
+    Overflow: untyped
+    UnknownMode: untyped
+    OffsetOutOfSync: 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
+    # returns, the Streamer will have it's `close` method called, which will write out the central
+    # directory of the archive to the output.
+    # 
+    # _@param_ `stream` — the destination IO for the ZIP (should respond to `tell` and `<<`)
+    # 
+    # _@param_ `kwargs_for_new` — keyword arguments for #initialize
+    def self.open: (IO stream, **::Hash[untyped, untyped] kwargs_for_new) -> untyped
+
+    # sord duck - #<< looks like a duck type, replacing with untyped
+    # Creates a new Streamer on top of the given IO-ish object.
+    # 
+    # _@param_ `writable` — the destination IO for the ZIP. Anything that responds to `<<` can be used.
+    # 
+    # _@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
+
+    # Writes a part of a zip entry body (actual binary data of the entry) into the output stream.
+    # 
+    # _@param_ `binary_data` — a String in binary encoding
+    # 
+    # _@return_ — self
+    def <<: (String binary_data) -> untyped
+
+    # Advances the internal IO pointer to keep the offsets of the ZIP file in
+    # check. Use this if you are going to use accelerated writes to the socket
+    # (like the `sendfile()` call) after writing the headers, or if you
+    # just need to figure out the size of the archive.
+    # 
+    # _@param_ `num_bytes` — how many bytes are going to be written bypassing the Streamer
+    # 
+    # _@return_ — position in the output stream / ZIP archive
+    def simulate_write: (Integer num_bytes) -> Integer
+
+    # Writes out the local header for an entry (file in the ZIP) that is using
+    # the deflated storage model (is compressed). Once this method is called,
+    # the `<<` method has to be called to write the actual contents of the body.
+    # 
+    # Note that the deflated body that is going to be written into the output
+    # has to be _precompressed_ (pre-deflated) before writing it into the
+    # Streamer, because otherwise it is impossible to know it's size upfront.
+    # 
+    # _@param_ `filename` — the name of the file in the entry
+    # 
+    # _@param_ `modification_time` — the modification time of the file in the archive
+    # 
+    # _@param_ `compressed_size` — the size of the compressed entry that is going to be written into the archive
+    # 
+    # _@param_ `uncompressed_size` — the size of the entry when uncompressed, in bytes
+    # 
+    # _@param_ `crc32` — the CRC32 checksum of the entry when uncompressed
+    # 
+    # _@param_ `use_data_descriptor` — whether the entry body will be followed by a data descriptor
+    # 
+    # _@param_ `unix_permissions` — which UNIX permissions to set, normally the default should be used
+    # 
+    # _@return_ — the offset the output IO is at after writing the entry header
+    def add_deflated_entry: (
+                              filename: String,
+                              ?modification_time: Time,
+                              ?compressed_size: Integer,
+                              ?uncompressed_size: Integer,
+                              ?crc32: Integer,
+                              ?unix_permissions: Integer?,
+                              ?use_data_descriptor: bool
+                            ) -> Integer
+
+    # Writes out the local header for an entry (file in the ZIP) that is using
+    # the stored storage model (is stored as-is).
+    # Once this method is called, the `<<` method has to be called one or more
+    # times to write the actual contents of the body.
+    # 
+    # _@param_ `filename` — the name of the file in the entry
+    # 
+    # _@param_ `modification_time` — the modification time of the file in the archive
+    # 
+    # _@param_ `size` — the size of the file when uncompressed, in bytes
+    # 
+    # _@param_ `crc32` — the CRC32 checksum of the entry when uncompressed
+    # 
+    # _@param_ `use_data_descriptor` — whether the entry body will be followed by a data descriptor. When in use
+    # 
+    # _@param_ `unix_permissions` — which UNIX permissions to set, normally the default should be used
+    # 
+    # _@return_ — the offset the output IO is at after writing the entry header
+    def add_stored_entry: (
+                            filename: String,
+                            ?modification_time: Time,
+                            ?size: Integer,
+                            ?crc32: Integer,
+                            ?unix_permissions: Integer?,
+                            ?use_data_descriptor: bool
+                          ) -> 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
+    # 
+    # _@param_ `modification_time` — the modification time of the directory in the archive
+    # 
+    # _@param_ `unix_permissions` — which UNIX permissions to set, normally the default should be used
+    # 
+    # _@return_ — the offset the output IO is at after writing the entry header
+    def add_empty_directory: (dirname: String, ?modification_time: Time, ?unix_permissions: Integer?) -> Integer
+
+    # Opens the stream for a file stored in the archive, and yields a writer
+    # for that file to the block.
+    # The writer will buffer a small amount of data and see whether compression is
+    # effective for the data being output. If compression turns out to work well -
+    # for instance, if the output is mostly text - it is going to create a deflated
+    # file inside the zip. If the compression benefits are negligible, it will
+    # create a stored file inside the zip. It will delegate either to `write_deflated_file`
+    # or to `write_stored_file`.
+    # 
+    # Using a block, the write will be terminated with a data descriptor outright.
+    # 
+    #     zip.write_file("foo.txt") do |sink|
+    #       IO.copy_stream(source_file, sink)
+    #     end
+    # 
+    # If deferred writes are desired (for example - to integrate with an API that
+    # does not support blocks, or to work with non-blocking environments) the method
+    # has to be called without a block. In that case it returns the sink instead,
+    # permitting to write to it in a deferred fashion. When `close` is called on
+    # the sink, any remanining compression output will be flushed and the data
+    # descriptor is going to be written.
+    # 
+    # Note that even though it does not have to happen within the same call stack,
+    # call sequencing still must be observed. It is therefore not possible to do
+    # this:
+    # 
+    #     writer_for_file1 = zip.write_file("somefile.jpg")
+    #     writer_for_file2 = zip.write_file("another.tif")
+    #     writer_for_file1 << data
+    #     writer_for_file2 << data
+    # 
+    # because it is likely to result in an invalid ZIP file structure later on.
+    # So using this facility in async scenarios is certainly possible, but care
+    # and attention is recommended.
+    # 
+    # _@param_ `filename` — the name of the file in the archive
+    # 
+    # _@param_ `modification_time` — the modification time of the file in the archive
+    # 
+    # _@param_ `unix_permissions` — which UNIX permissions to set, normally the default should be used
+    # 
+    # _@return_ — without a block - the Writable sink which has to be closed manually
+    def write_file: (String filename, ?modification_time: Time, ?unix_permissions: Integer?) ?{ (ZipKit::Streamer::Writable sink) -> void } -> ZipKit::Streamer::Writable
+
+    # Opens the stream for a stored file in the archive, and yields a writer
+    # for that file to the block.
+    # Once the write completes, a data descriptor will be written with the
+    # actual compressed/uncompressed sizes and the CRC32 checksum.
+    # 
+    # Using a block, the write will be terminated with a data descriptor outright.
+    # 
+    #     zip.write_stored_file("foo.txt") do |sink|
+    #       IO.copy_stream(source_file, sink)
+    #     end
+    # 
+    # If deferred writes are desired (for example - to integrate with an API that
+    # does not support blocks, or to work with non-blocking environments) the method
+    # has to be called without a block. In that case it returns the sink instead,
+    # permitting to write to it in a deferred fashion. When `close` is called on
+    # the sink, any remanining compression output will be flushed and the data
+    # descriptor is going to be written.
+    # 
+    # Note that even though it does not have to happen within the same call stack,
+    # call sequencing still must be observed. It is therefore not possible to do
+    # this:
+    # 
+    #     writer_for_file1 = zip.write_stored_file("somefile.jpg")
+    #     writer_for_file2 = zip.write_stored_file("another.tif")
+    #     writer_for_file1 << data
+    #     writer_for_file2 << data
+    # 
+    # because it is likely to result in an invalid ZIP file structure later on.
+    # So using this facility in async scenarios is certainly possible, but care
+    # and attention is recommended.
+    # 
+    # If an exception is raised inside the block that is passed to the method, a `rollback!` call
+    # will be performed automatically and the entry just written will be omitted from the ZIP
+    # central directory. This can be useful if you want to rescue the exception and reattempt
+    # adding the ZIP file. Note that you will need to call `write_deflated_file` again to start a
+    # new file - you can't keep writing to the one that failed.
+    # 
+    # _@param_ `filename` — the name of the file in the archive
+    # 
+    # _@param_ `modification_time` — the modification time of the file in the archive
+    # 
+    # _@param_ `unix_permissions` — which UNIX permissions to set, normally the default should be used
+    # 
+    # _@return_ — without a block - the Writable sink which has to be closed manually
+    def write_stored_file: (String filename, ?modification_time: Time, ?unix_permissions: Integer?) ?{ (ZipKit::Streamer::Writable sink) -> void } -> ZipKit::Streamer::Writable
+
+    # Opens the stream for a deflated file in the archive, and yields a writer
+    # for that file to the block. Once the write completes, a data descriptor
+    # will be written with the actual compressed/uncompressed sizes and the
+    # CRC32 checksum.
+    # 
+    # Using a block, the write will be terminated with a data descriptor outright.
+    # 
+    #     zip.write_stored_file("foo.txt") do |sink|
+    #       IO.copy_stream(source_file, sink)
+    #     end
+    # 
+    # If deferred writes are desired (for example - to integrate with an API that
+    # does not support blocks, or to work with non-blocking environments) the method
+    # has to be called without a block. In that case it returns the sink instead,
+    # permitting to write to it in a deferred fashion. When `close` is called on
+    # the sink, any remanining compression output will be flushed and the data
+    # descriptor is going to be written.
+    # 
+    # Note that even though it does not have to happen within the same call stack,
+    # call sequencing still must be observed. It is therefore not possible to do
+    # this:
+    # 
+    #     writer_for_file1 = zip.write_deflated_file("somefile.jpg")
+    #     writer_for_file2 = zip.write_deflated_file("another.tif")
+    #     writer_for_file1 << data
+    #     writer_for_file2 << data
+    #     writer_for_file1.close
+    #     writer_for_file2.close
+    # 
+    # because it is likely to result in an invalid ZIP file structure later on.
+    # So using this facility in async scenarios is certainly possible, but care
+    # and attention is recommended.
+    # 
+    # If an exception is raised inside the block that is passed to the method, a `rollback!` call
+    # will be performed automatically and the entry just written will be omitted from the ZIP
+    # central directory. This can be useful if you want to rescue the exception and reattempt
+    # adding the ZIP file. Note that you will need to call `write_deflated_file` again to start a
+    # new file - you can't keep writing to the one that failed.
+    # 
+    # _@param_ `filename` — the name of the file in the archive
+    # 
+    # _@param_ `modification_time` — the modification time of the file in the archive
+    # 
+    # _@param_ `unix_permissions` — which UNIX permissions to set, normally the default should be used
+    # 
+    # _@return_ — without a block - the Writable sink which has to be closed manually
+    def write_deflated_file: (String filename, ?modification_time: Time, ?unix_permissions: Integer?) ?{ (ZipKit::Streamer::Writable sink) -> void } -> ZipKit::Streamer::Writable
+
+    # Closes the archive. Writes the central directory, and switches the writer into
+    # a state where it can no longer be written to.
+    # 
+    # Once this method is called, the `Streamer` should be discarded (the ZIP archive is complete).
+    # 
+    # _@return_ — the offset the output IO is at after closing the archive
+    def close: () -> Integer
+
+    # Sets up the ZipWriter with wrappers if necessary. The method is called once, when the Streamer
+    # gets instantiated - the Writer then gets reused. This method is primarily there so that you
+    # can override it.
+    # 
+    # _@return_ — the writer to perform writes with
+    def create_writer: () -> ZipKit::ZipWriter
+
+    # Updates the last entry written with the CRC32 checksum and compressed/uncompressed
+    # sizes. For stored entries, `compressed_size` and `uncompressed_size` are the same.
+    # After updating the entry will immediately write the data descriptor bytes
+    # to the output.
+    # 
+    # _@param_ `crc32` — the CRC32 checksum of the entry when uncompressed
+    # 
+    # _@param_ `compressed_size` — the size of the compressed segment within the ZIP
+    # 
+    # _@param_ `uncompressed_size` — the size of the entry once uncompressed
+    # 
+    # _@return_ — the offset the output IO is at after writing the data descriptor
+    def update_last_entry_and_write_data_descriptor: (crc32: Integer, compressed_size: Integer, uncompressed_size: Integer) -> Integer
+
+    # Removes the buffered local entry for the last file written. This can be used when rescuing from exceptions
+    # when you want to skip the file that failed writing into the ZIP from getting written out into the
+    # ZIP central directory. This is useful when, for example, you encounter errors retrieving the file
+    # that you want to place inside the ZIP from a remote storage location and some network exception
+    # gets raised. `write_deflated_file` and `write_stored_file` will rollback for you automatically.
+    # Of course it is not possible to remove the failed entry from the ZIP file entirely, as the data
+    # is likely already on the wire. However, excluding the entry from the central directory of the ZIP
+    # file will allow better-behaved ZIP unarchivers to extract the entries which did store correctly,
+    # provided they read the ZIP from the central directory and not straight-ahead.
+    # Rolling back does not perform any writes.
+    # 
+    # `rollback!` gets called for you if an exception is raised inside the block of `write_file`,
+    # `write_deflated_file` and `write_stored_file`.
+    # 
+    # _@return_ — position in the output stream / ZIP archive
+    # 
+    # ```ruby
+    # zip.add_stored_entry(filename: "data.bin", size: 4.megabytes, crc32: the_crc)
+    # while chunk = remote.read(65*2048)
+    #   zip << chunk
+    # rescue Timeout::Error
+    #   zip.rollback!
+    #   # and proceed to the next file
+    # end
+    # ```
+    def rollback!: () -> Integer
+
+    # sord omit - no YARD type given for "writable", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def yield_or_return_writable: (untyped writable) -> untyped
+
+    # sord omit - no YARD return type given, using untyped
+    def verify_offsets!: () -> untyped
+
+    # sord omit - no YARD type given for "filename:", using untyped
+    # sord omit - no YARD type given for "modification_time:", using untyped
+    # sord omit - no YARD type given for "crc32:", using untyped
+    # sord omit - no YARD type given for "storage_mode:", using untyped
+    # sord omit - no YARD type given for "compressed_size:", using untyped
+    # 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 return type given, using untyped
+    def add_file_and_write_local_header: (
+                                           filename: untyped,
+                                           modification_time: untyped,
+                                           crc32: untyped,
+                                           storage_mode: untyped,
+                                           compressed_size: untyped,
+                                           uncompressed_size: untyped,
+                                           use_data_descriptor: untyped,
+                                           unix_permissions: untyped
+                                         ) -> 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
+
+    # Writes the given data to the output stream. Allows the object to be used as
+    # a target for `IO.copy_stream(from, to)`
+    # 
+    # _@param_ `bytes` — the binary string to write (part of the uncompressed file)
+    # 
+    # _@return_ — the number of bytes written (will always be the bytesize of `bytes`)
+    def write: (String bytes) -> Integer
+
+    # Is used internally by Streamer to keep track of entries in the archive during writing.
+    # Normally you will not have to use this class directly
+    class Entry < Struct
+      def initialize: () -> void
+
+      # sord omit - no YARD return type given, using untyped
+      def total_bytes_used: () -> untyped
+
+      # sord omit - no YARD return type given, using untyped
+      # Set the general purpose flags for the entry. We care about is the EFS
+      # bit (bit 11) which should be set if the filename is UTF8. If it is, we need to set the
+      # bit so that the unarchiving application knows that the filename in the archive is UTF-8
+      # encoded, and not some DOS default. For ASCII entries it does not matter.
+      # Additionally, we care about bit 3 which toggles the use of the postfix data descriptor.
+      def gp_flags: () -> untyped
+
+      def filler?: () -> bool
+
+      # Returns the value of attribute filename
+      attr_accessor filename: Object
+
+      # Returns the value of attribute crc32
+      attr_accessor crc32: Object
+
+      # Returns the value of attribute compressed_size
+      attr_accessor compressed_size: Object
+
+      # Returns the value of attribute uncompressed_size
+      attr_accessor uncompressed_size: Object
+
+      # Returns the value of attribute storage_mode
+      attr_accessor storage_mode: Object
+
+      # Returns the value of attribute mtime
+      attr_accessor mtime: Object
+
+      # Returns the value of attribute use_data_descriptor
+      attr_accessor use_data_descriptor: Object
+
+      # Returns the value of attribute local_header_offset
+      attr_accessor local_header_offset: Object
+
+      # Returns the value of attribute bytes_used_for_local_header
+      attr_accessor bytes_used_for_local_header: Object
+
+      # Returns the value of attribute bytes_used_for_data_descriptor
+      attr_accessor bytes_used_for_data_descriptor: Object
+
+      # Returns the value of attribute unix_permissions
+      attr_accessor unix_permissions: Object
+    end
+
+    # Is used internally by Streamer to keep track of entries in the archive during writing.
+    # Normally you will not have to use this class directly
+    class Filler < Struct
+      def filler?: () -> bool
+
+      # Returns the value of attribute total_bytes_used
+      attr_accessor total_bytes_used: Object
+    end
+
+    # Gets yielded from the writing methods of the Streamer
+    # and accepts the data being written into the ZIP for deflate
+    # or stored modes. Can be used as a destination for `IO.copy_stream`
+    # 
+    #    IO.copy_stream(File.open('source.bin', 'rb), writable)
+    class Writable
+      include ZipKit::WriteShovel
+
+      # sord omit - no YARD type given for "streamer", using untyped
+      # sord omit - no YARD type given for "writer", using untyped
+      # Initializes a new Writable with the object it delegates the writes to.
+      # Normally you would not need to use this method directly
+      def initialize: (untyped streamer, untyped writer) -> void
+
+      # Writes the given data to the output stream
+      # 
+      # _@param_ `string` — the string to write (part of the uncompressed file)
+      def <<: (String string) -> self
+
+      # sord omit - no YARD return type given, using untyped
+      # Flushes the writer and recovers the CRC32/size values. It then calls
+      # `update_last_entry_and_write_data_descriptor` on the given Streamer.
+      def close: () -> untyped
+
+      # sord omit - no YARD return type given, using untyped
+      def release_resources_on_failure!: () -> untyped
+
+      # Writes the given data to the output stream. Allows the object to be used as
+      # a target for `IO.copy_stream(from, to)`
+      # 
+      # _@param_ `bytes` — the binary string to write (part of the uncompressed file)
+      # 
+      # _@return_ — the number of bytes written (will always be the bytesize of `bytes`)
+      def write: (String bytes) -> Integer
+    end
+
+    # Will be used to pick whether to store a file in the `stored` or
+    # `deflated` mode, by compressing the first N bytes of the file and
+    # comparing the stored and deflated data sizes. If deflate produces
+    # a sizable compression gain for this data, it will create a deflated
+    # file inside the ZIP archive. If the file doesn't compress well, it
+    # will use the "stored" mode for the entry. About 128KB of the
+    # file will be buffered to pick the appropriate storage mode. The
+    # Heuristic will call either `write_stored_file` or `write_deflated_file`
+    # on the Streamer passed into it once it knows which compression
+    # method should be applied
+    class Heuristic < ZipKit::Streamer::Writable
+      include ZipKit::ZlibCleanup
+      BYTES_WRITTEN_THRESHOLD: untyped
+      MINIMUM_VIABLE_COMPRESSION: untyped
+
+      # sord omit - no YARD type given for "streamer", using untyped
+      # sord omit - no YARD type given for "filename", using untyped
+      # sord omit - no YARD type given for "**write_file_options", using untyped
+      def initialize: (untyped streamer, untyped filename, **untyped write_file_options) -> void
+
+      # sord infer - argument name in single @param inferred as "bytes"
+      def <<: (String bytes) -> self
+
+      # sord omit - no YARD return type given, using untyped
+      def close: () -> untyped
+
+      # sord omit - no YARD return type given, using untyped
+      def release_resources_on_failure!: () -> untyped
+
+      # sord omit - no YARD return type given, using untyped
+      def decide: () -> untyped
+
+      # sord warn - "Zlib::Deflater?" does not appear to be a type
+      # This method is used to flush and close the native zlib handles
+      # should an archiving routine encounter an error. This is necessary,
+      # since otherwise unclosed deflaters may hang around in memory
+      # indefinitely, creating leaks.
+      # 
+      # _@param_ `deflater` — the deflater to safely finish and close
+      # 
+      # _@return_ — void
+      def safely_dispose_of_incomplete_deflater: (SORD_ERROR_ZlibDeflater deflater) -> untyped
+    end
+
+    # Sends writes to the given `io`, and also registers all the data passing
+    # through it in a CRC32 checksum calculator. Is made to be completely
+    # interchangeable with the DeflatedWriter in terms of interface.
+    class StoredWriter
+      include ZipKit::WriteShovel
+      CRC32_BUFFER_SIZE: untyped
+
+      # sord omit - no YARD type given for "io", using untyped
+      def initialize: (untyped io) -> void
+
+      # Writes the given data to the contained IO object.
+      # 
+      # _@param_ `data` — data to be written
+      # 
+      # _@return_ — self
+      def <<: (String data) -> untyped
+
+      # Returns the amount of data written and the CRC32 checksum. The return value
+      # can be directly used as the argument to {Streamer#update_last_entry_and_write_data_descriptor}
+      # 
+      # _@return_ — a hash of `{crc32, compressed_size, uncompressed_size}`
+      def finish: () -> ::Hash[untyped, untyped]
+
+      # sord omit - no YARD return type given, using untyped
+      def release_resources_on_failure!: () -> untyped
+
+      # Writes the given data to the output stream. Allows the object to be used as
+      # a target for `IO.copy_stream(from, to)`
+      # 
+      # _@param_ `bytes` — the binary string to write (part of the uncompressed file)
+      # 
+      # _@return_ — the number of bytes written (will always be the bytesize of `bytes`)
+      def write: (String bytes) -> Integer
+    end
+
+    # Sends writes to the given `io` compressed using a `Zlib::Deflate`. Also
+    # registers data passing through it in a CRC32 checksum calculator. Is made to be completely
+    # interchangeable with the StoredWriter in terms of interface.
+    class DeflatedWriter
+      include ZipKit::WriteShovel
+      include ZipKit::ZlibCleanup
+      CRC32_BUFFER_SIZE: untyped
+
+      # sord omit - no YARD type given for "io", using untyped
+      def initialize: (untyped io) -> void
+
+      # Writes the given data into the deflater, and flushes the deflater
+      # after having written more than FLUSH_EVERY_N_BYTES bytes of data
+      # 
+      # _@param_ `data` — data to be written
+      # 
+      # _@return_ — self
+      def <<: (String data) -> untyped
+
+      # Returns the amount of data received for writing, the amount of
+      # compressed data written and the CRC32 checksum. The return value
+      # can be directly used as the argument to {Streamer#update_last_entry_and_write_data_descriptor}
+      # 
+      # _@return_ — a hash of `{crc32, compressed_size, uncompressed_size}`
+      def finish: () -> ::Hash[untyped, untyped]
+
+      # sord omit - no YARD return type given, using untyped
+      def release_resources_on_failure!: () -> untyped
+
+      # sord warn - "Zlib::Deflater?" does not appear to be a type
+      # This method is used to flush and close the native zlib handles
+      # should an archiving routine encounter an error. This is necessary,
+      # since otherwise unclosed deflaters may hang around in memory
+      # indefinitely, creating leaks.
+      # 
+      # _@param_ `deflater` — the deflater to safely finish and close
+      # 
+      # _@return_ — void
+      def safely_dispose_of_incomplete_deflater: (SORD_ERROR_ZlibDeflater deflater) -> untyped
+
+      # Writes the given data to the output stream. Allows the object to be used as
+      # a target for `IO.copy_stream(from, to)`
+      # 
+      # _@param_ `bytes` — the binary string to write (part of the uncompressed file)
+      # 
+      # _@return_ — the number of bytes written (will always be the bytesize of `bytes`)
+      def write: (String bytes) -> Integer
+    end
+  end
+
+  # An object that fakes just-enough of an IO to be dangerous
+  # - or, more precisely, to be useful as a source for the FileReader
+  # central directory parser. Effectively we substitute an IO object
+  # for an object that fetches parts of the remote file over HTTP using `Range:`
+  # headers. The `RemoteIO` acts as an adapter between an object that performs the
+  # actual fetches over HTTP and an object that expects a handful of IO methods to be
+  # available.
+  class RemoteIO
+    # sord warn - URI wasn't able to be resolved to a constant in this project
+    # _@param_ `url` — the HTTP/HTTPS URL of the object to be retrieved
+    def initialize: ((String | URI) url) -> void
+
+    # sord omit - no YARD return type given, using untyped
+    # Emulates IO#seek
+    # 
+    # _@param_ `offset` — absolute offset in the remote resource to seek to
+    # 
+    # _@param_ `mode` — The seek mode (only SEEK_SET is supported)
+    def seek: (Integer offset, ?Integer mode) -> untyped
+
+    # Emulates IO#size.
+    # 
+    # _@return_ — the size of the remote resource
+    def size: () -> Integer
+
+    # Emulates IO#read, but requires the number of bytes to read
+    # The read will be limited to the
+    # size of the remote resource relative to the current offset in the IO,
+    # so if you are at offset 0 in the IO of size 10, doing a `read(20)`
+    # will only return you 10 bytes of result, and not raise any exceptions.
+    # 
+    # _@param_ `n_bytes` — how many bytes to read, or `nil` to read all the way to the end
+    # 
+    # _@return_ — the read bytes
+    def read: (?Integer? n_bytes) -> String
+
+    # Returns the current pointer position within the IO
+    def tell: () -> Integer
+
+    # Only used internally when reading the remote ZIP.
+    # 
+    # _@param_ `range` — the HTTP range of data to fetch from remote
+    # 
+    # _@return_ — the response body of the ranged request
+    def request_range: (::Range[untyped] range) -> String
+
+    # For working with S3 it is a better idea to perform a GET request for one byte, since doing a HEAD
+    # request needs a different permission - and standard GET presigned URLs are not allowed to perform it
+    # 
+    # _@return_ — the size of the remote resource, parsed either from Content-Length or Content-Range header
+    def request_object_size: () -> Integer
+
+    # sord omit - no YARD type given for "a", using untyped
+    # sord omit - no YARD type given for "b", using untyped
+    # sord omit - no YARD type given for "c", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def clamp: (untyped a, untyped b, untyped c) -> untyped
+  end
+
+  # 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.
+  # 
+  # The primary reason the writer is a separate object is because it is kept stateless. That is, all the data that
+  # is needed for writing a piece of the ZIP (say, the EOCD record, or a data descriptor) can be written
+  # without depending on data available elsewhere. This makes the writer very easy to test, since each of
+  # it's methods outputs something that only depends on the method's arguments. For example, we use this
+  # to test writing Zip64 files which, when tested in a streaming fashion, would need tricky IO stubs
+  # to wind IO objects back and forth by large offsets. Instead, we can just write out the EOCD record
+  # with given offsets as arguments.
+  # 
+  # Since some methods need a lot of data about the entity being written, everything is passed via
+  # keyword arguments - this way it is much less likely that you can make a mistake writing something.
+  # 
+  # Another reason for having a separate Writer is that most ZIP libraries attach the methods for
+  # writing out the file headers to some sort of Entry object, which represents a file within the ZIP.
+  # However, when you are diagnosing issues with the ZIP files you produce, you actually want to have
+  # absolute _most_ of the code responsible for writing the actual encoded bytes available to you on
+  # one screen. Altering or checking that code then becomes much, much easier. The methods doing the
+  # writing are also intentionally left very verbose - so that you can follow what is happening at
+  # all times.
+  # 
+  # All methods of the writer accept anything that responds to `<<` as `io` argument - you can use
+  # that to output to String objects, or to output to Arrays that you can later join together.
+  class ZipWriter
+    FOUR_BYTE_MAX_UINT: untyped
+    TWO_BYTE_MAX_UINT: untyped
+    ZIP_KIT_COMMENT: untyped
+    VERSION_MADE_BY: untyped
+    VERSION_NEEDED_TO_EXTRACT: untyped
+    VERSION_NEEDED_TO_EXTRACT_ZIP64: untyped
+    DEFAULT_FILE_UNIX_PERMISSIONS: untyped
+    DEFAULT_DIRECTORY_UNIX_PERMISSIONS: untyped
+    FILE_TYPE_FILE: untyped
+    FILE_TYPE_DIRECTORY: untyped
+    MADE_BY_SIGNATURE: untyped
+    C_UINT4: untyped
+    C_UINT2: untyped
+    C_UINT8: untyped
+    C_CHAR: untyped
+    C_INT4: untyped
+
+    # sord duck - #<< looks like a duck type, replacing with untyped
+    # Writes the local file header, that precedes the actual file _data_.
+    # 
+    # _@param_ `io` — the buffer to write the local file header to
+    # 
+    # _@param_ `filename` — the name of the file in the archive
+    # 
+    # _@param_ `compressed_size` — The size of the compressed (or stored) data - how much space it uses in the ZIP
+    # 
+    # _@param_ `uncompressed_size` — The size of the file once extracted
+    # 
+    # _@param_ `crc32` — The CRC32 checksum of the file
+    # 
+    # _@param_ `mtime` — the modification time to be recorded in the ZIP
+    # 
+    # _@param_ `gp_flags` — bit-packed general purpose flags
+    # 
+    # _@param_ `storage_mode` — 8 for deflated, 0 for stored...
+    def write_local_file_header: (
+                                   io: untyped,
+                                   filename: String,
+                                   compressed_size: Integer,
+                                   uncompressed_size: Integer,
+                                   crc32: Integer,
+                                   gp_flags: Integer,
+                                   mtime: Time,
+                                   storage_mode: Integer
+                                 ) -> void
+
+    # sord duck - #<< looks like a duck type, replacing with untyped
+    # sord omit - no YARD type given for "local_file_header_location:", using untyped
+    # sord omit - no YARD type given for "storage_mode:", using untyped
+    # Writes the file header for the central directory, for a particular file in the archive. When writing out this data,
+    # ensure that the CRC32 and both sizes (compressed/uncompressed) are correct for the entry in question.
+    # 
+    # _@param_ `io` — the buffer to write the local file header to
+    # 
+    # _@param_ `filename` — the name of the file in the archive
+    # 
+    # _@param_ `compressed_size` — The size of the compressed (or stored) data - how much space it uses in the ZIP
+    # 
+    # _@param_ `uncompressed_size` — The size of the file once extracted
+    # 
+    # _@param_ `crc32` — The CRC32 checksum of the file
+    # 
+    # _@param_ `mtime` — the modification time to be recorded in the ZIP
+    # 
+    # _@param_ `gp_flags` — bit-packed general purpose flags
+    # 
+    # _@param_ `unix_permissions` — the permissions for the file, or nil for the default to be used
+    def write_central_directory_file_header: (
+                                               io: untyped,
+                                               local_file_header_location: untyped,
+                                               gp_flags: Integer,
+                                               storage_mode: untyped,
+                                               compressed_size: Integer,
+                                               uncompressed_size: Integer,
+                                               mtime: Time,
+                                               crc32: Integer,
+                                               filename: String,
+                                               ?unix_permissions: Integer?
+                                             ) -> void
+
+    # 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
+    # was written with general-purpose flag bit 3 set. If the one of the sizes exceeds the Zip64 threshold,
+    # the data descriptor will have the sizes written out as 8-byte values instead of 4-byte values.
+    # 
+    # _@param_ `io` — the buffer to write the local file header to
+    # 
+    # _@param_ `crc32` — The CRC32 checksum of the file
+    # 
+    # _@param_ `compressed_size` — The size of the compressed (or stored) data - how much space it uses in the ZIP
+    # 
+    # _@param_ `uncompressed_size` — The size of the file once extracted
+    def write_data_descriptor: (
+                                 io: untyped,
+                                 compressed_size: Integer,
+                                 uncompressed_size: Integer,
+                                 crc32: Integer
+                               ) -> void
+
+    # sord duck - #<< looks like a duck type, replacing with untyped
+    # Writes the "end of central directory record" (including the Zip6 salient bits if necessary)
+    # 
+    # _@param_ `io` — the buffer to write the central directory to.
+    # 
+    # _@param_ `start_of_central_directory_location` — byte offset of the start of central directory form the beginning of ZIP file
+    # 
+    # _@param_ `central_directory_size` — the size of the central directory (only file headers) in bytes
+    # 
+    # _@param_ `num_files_in_archive` — How many files the archive contains
+    # 
+    # _@param_ `comment` — the comment for the archive (defaults to ZIP_KIT_COMMENT)
+    def write_end_of_central_directory: (
+                                          io: untyped,
+                                          start_of_central_directory_location: Integer,
+                                          central_directory_size: Integer,
+                                          num_files_in_archive: Integer,
+                                          ?comment: String
+                                        ) -> void
+
+    # Writes the Zip64 extra field for the local file header. Will be used by `write_local_file_header` when any sizes given to it warrant that.
+    # 
+    # _@param_ `compressed_size` — The size of the compressed (or stored) data - how much space it uses in the ZIP
+    # 
+    # _@param_ `uncompressed_size` — The size of the file once extracted
+    def zip_64_extra_for_local_file_header: (compressed_size: Integer, uncompressed_size: Integer) -> String
+
+    # sord omit - no YARD type given for "mtime", using untyped
+    # sord omit - no YARD return type given, using untyped
+    # Writes the extended timestamp information field for local headers.
+    # 
+    # The spec defines 2
+    # different formats - the one for the local file header can also accomodate the
+    # atime and ctime, whereas the one for the central directory can only take
+    # the mtime - and refers the reader to the local header extra to obtain the
+    # remaining times
+    def timestamp_extra_for_local_file_header: (untyped mtime) -> untyped
+
+    # Writes the Zip64 extra field for the central directory header.It differs from the extra used in the local file header because it
+    # also contains the location of the local file header in the ZIP as an 8-byte int.
+    # 
+    # _@param_ `compressed_size` — The size of the compressed (or stored) data - how much space it uses in the ZIP
+    # 
+    # _@param_ `uncompressed_size` — The size of the file once extracted
+    # 
+    # _@param_ `local_file_header_location` — Byte offset of the start of the local file header from the beginning of the ZIP archive
+    def zip_64_extra_for_central_directory_file_header: (compressed_size: Integer, uncompressed_size: Integer, local_file_header_location: Integer) -> String
+
+    # sord omit - no YARD type given for "t", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def to_binary_dos_time: (untyped t) -> untyped
+
+    # sord omit - no YARD type given for "t", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def to_binary_dos_date: (untyped t) -> untyped
+
+    # sord omit - no YARD type given for "values_to_packspecs", using untyped
+    # sord omit - no YARD return type given, using untyped
+    # Unzips a given array of tuples of "numeric value, pack specifier" and then packs all the odd
+    # values using specifiers from all the even values. It is harder to explain than to show:
+    # 
+    #   pack_array([1, 'V', 2, 'v', 148, 'v]) #=> "\x01\x00\x00\x00\x02\x00\x94\x00"
+    # 
+    # will do the following two transforms:
+    # 
+    #  [1, 'V', 2, 'v', 148, 'v] -> [1,2,148], ['V','v','v'] -> [1,2,148].pack('Vvv') -> "\x01\x00\x00\x00\x02\x00\x94\x00".
+    # This might seem like a "clever optimisation" but the issue is that `pack` needs an array allocated per call, and
+    # we output very verbosely - value-by-value. This might be quite a few array allocs. Using something like this
+    # helps us save the array allocs
+    def pack_array: (untyped values_to_packspecs) -> untyped
+
+    # sord omit - no YARD type given for "unix_permissions_int", using untyped
+    # sord omit - no YARD type given for "file_type_int", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def generate_external_attrs: (untyped unix_permissions_int, untyped file_type_int) -> untyped
+  end
+
+  # Acts as a converter between callers which send data to the `#<<` method (such as all the ZipKit
+  # writer methods, which push onto anything), and a given block. Every time `#<<` gets called on the BlockWrite,
+  # the block given to the constructor will be called with the same argument. ZipKit uses this object
+  # when integrating with Rack and in the OutputEnumerator. Normally you wouldn't need to use it manually but
+  # you always can. BlockWrite will also ensure the binary string encoding is forced onto any string
+  # that passes through it.
+  # 
+  # For example, you can create a Rack response body like so:
+  # 
+  #     class MyRackResponse
+  #       def each
+  #         writer = ZipKit::BlockWrite.new {|chunk| yield(chunk) }
+  #         writer << "Hello" << "world" << "!"
+  #       end
+  #     end
+  #     [200, {}, MyRackResponse.new]
+  class BlockWrite
+    include ZipKit::WriteShovel
+
+    # Creates a new BlockWrite.
+    # 
+    # _@param_ `block` — The block that will be called when this object receives the `<<` message
+    def initialize: () ?{ (String bytes) -> void } -> void
+
+    # 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).
+    def <<: (String buf) -> ZipKit::BlockWrite
+
+    # Writes the given data to the output stream. Allows the object to be used as
+    # a target for `IO.copy_stream(from, to)`
+    # 
+    # _@param_ `bytes` — the binary string to write (part of the uncompressed file)
+    # 
+    # _@return_ — the number of bytes written (will always be the bytesize of `bytes`)
+    def write: (String bytes) -> Integer
+  end
+
+  # A very barebones ZIP file reader. Is made for maximum interoperability, but at the same
+  # time we attempt to keep it somewhat concise.
+  # 
+  # ## REALLY CRAZY IMPORTANT STUFF: SECURITY IMPLICATIONS
+  # 
+  # Please **BEWARE** - using this is a security risk if you are reading files that have been
+  # supplied by users. This implementation has _not_ been formally verified for correctness. As
+  # ZIP files contain relative offsets in lots of places it might be possible for a maliciously
+  # crafted ZIP file to put the decode procedure in an endless loop, make it attempt huge reads
+  # from the input file and so on. Additionally, the reader module for deflated data has
+  # no support for ZIP bomb protection. So either limit the `FileReader` usage to the files you
+  # trust, or triple-check all the inputs upfront. Patches to make this reader more secure
+  # are welcome of course.
+  # 
+  # ## Usage
+  # 
+  #     File.open('zipfile.zip', 'rb') do |f|
+  #       entries = ZipKit::FileReader.read_zip_structure(io: f)
+  #       entries.each do |e|
+  #         File.open(e.filename, 'wb') do |extracted_file|
+  #           ex = e.extractor_from(f)
+  #           extracted_file << ex.extract(1024 * 1024) until ex.eof?
+  #         end
+  #       end
+  #     end
+  # 
+  # ## Supported features
+  # 
+  # * Deflate and stored storage modes
+  # * Zip64 (extra fields and offsets)
+  # * Data descriptors
+  # 
+  # ## Unsupported features
+  # 
+  # * Archives split over multiple disks/files
+  # * Any ZIP encryption
+  # * EFS language flag and InfoZIP filename extra field
+  # * CRC32 checksums are _not_ verified
+  # 
+  # ## Mode of operation
+  # 
+  # By default, `FileReader` _ignores_ the data in local file headers (as it is
+  # often unreliable). It reads the ZIP file "from the tail", finds the
+  # end-of-central-directory signatures, then reads the central directory entries,
+  # reconstitutes the entries with their filenames, attributes and so on, and
+  # sets these entries up with the absolute _offsets_ into the source file/IO object.
+  # These offsets can then be used to extract the actual compressed data of
+  # the files and to expand it.
+  # 
+  # ## Recovering damaged or incomplete ZIP files
+  # 
+  # If the ZIP file you are trying to read does not contain the central directory
+  # records `read_zip_structure` will not work, since it starts the read process
+  # from the EOCD marker at the end of the central directory and then crawls
+  # "back" in the IO to figure out the rest. You can explicitly apply a fallback
+  # for reading the archive "straight ahead" instead using `read_zip_straight_ahead`
+  # - the method will instead scan your IO from the very start, skipping over
+  # the actual entry data. This is less efficient than central directory parsing since
+  # it involves a much larger number of reads (1 read from the IO per entry in the ZIP).
+  class FileReader
+    ReadError: untyped
+    UnsupportedFeature: untyped
+    InvalidStructure: untyped
+    LocalHeaderPending: untyped
+    MissingEOCD: untyped
+    C_UINT4: untyped
+    C_UINT2: untyped
+    C_UINT8: untyped
+    MAX_END_OF_CENTRAL_DIRECTORY_RECORD_SIZE: untyped
+    MAX_LOCAL_HEADER_SIZE: untyped
+    SIZE_OF_USABLE_EOCD_RECORD: untyped
+
+    # sord duck - #tell looks like a duck type, replacing with untyped
+    # sord duck - #seek looks like a duck type, replacing with untyped
+    # sord duck - #read looks like a duck type with an equivalent RBS interface, replacing with _Reader
+    # sord duck - #size looks like a duck type, replacing with untyped
+    # Parse an IO handle to a ZIP archive into an array of Entry objects.
+    # 
+    # _@param_ `io` — an IO-ish object
+    # 
+    # _@param_ `read_local_headers` — whether the local headers must be read upfront. When reading a locally available ZIP file this option will not have much use since the small reads from the file handle are not going to be that important. However, if you are using remote reads to decipher a ZIP file located on an HTTP server, the operation _must_ perform an HTTP request for _each entry in the ZIP file_ to determine where the actual file data starts. This, for a ZIP archive of 1000 files, will incur 1000 extra HTTP requests - which you might not want to perform upfront, or - at least - not want to perform _at once_. When the option is set to `false`, you will be getting instances of `LazyEntry` instead of `Entry`. Those objects will raise an exception when you attempt to access their compressed data offset in the ZIP (since the reads have not been performed yet). As a rule, this option can be left in it's default setting (`true`) unless you want to _only_ read the central directory, or you need to limit the number of HTTP requests.
+    # 
+    # _@return_ — an array of entries within the ZIP being parsed
+    def read_zip_structure: (io: (untyped | _Reader), ?read_local_headers: bool) -> ::Array[ZipEntry]
+
+    # sord duck - #tell looks like a duck type, replacing with untyped
+    # sord duck - #read looks like a duck type with an equivalent RBS interface, replacing with _Reader
+    # sord duck - #seek looks like a duck type, replacing with untyped
+    # sord omit - no YARD return type given, using untyped
+    # Sometimes you might encounter truncated ZIP files, which do not contain
+    # any central directory whatsoever - or where the central directory is
+    # truncated. In that case, employing the technique of reading the ZIP
+    # "from the end" is impossible, and the only recourse is reading each
+    # local file header in sucession. If the entries in such a ZIP use data
+    # descriptors, you would need to scan after the entry until you encounter
+    # the data descriptor signature - and that might be unreliable at best.
+    # Therefore, this reading technique does not support data descriptors.
+    # It can however recover the entries you still can read if these entries
+    # contain all the necessary information about the contained file.
+    # 
+    # headers from @return [Array<ZipEntry>] an array of entries that could be
+    # recovered before hitting EOF
+    # 
+    # _@param_ `io` — the IO-ish object to read the local file
+    def read_zip_straight_ahead: (io: (untyped | _Reader)) -> untyped
+
+    # sord duck - #read looks like a duck type with an equivalent RBS interface, replacing with _Reader
+    # Parse the local header entry and get the offset in the IO at which the
+    # actual compressed data of the file starts within the ZIP.
+    # The method will eager-read the entire local header for the file
+    # (the maximum size the local header may use), starting at the given offset,
+    # and will then compute its size. That size plus the local header offset
+    # given will be the compressed data offset of the entry (read starting at
+    # this offset to get the data).
+    # 
+    # the compressed data offset
+    # 
+    # _@param_ `io` — an IO-ish object the ZIP file can be read from
+    # 
+    # _@return_ — the parsed local header entry and
+    def read_local_file_header: (io: _Reader) -> ::Array[(ZipEntry | Integer)]
+
+    # sord duck - #seek looks like a duck type, replacing with untyped
+    # sord duck - #read looks like a duck type with an equivalent RBS interface, replacing with _Reader
+    # sord omit - no YARD return type given, using untyped
+    # Get the offset in the IO at which the actual compressed data of the file
+    # starts within the ZIP. The method will eager-read the entire local header
+    # for the file (the maximum size the local header may use), starting at the
+    # given offset, and will then compute its size. That size plus the local
+    # header offset given will be the compressed data offset of the entry
+    # (read starting at this offset to get the data).
+    # 
+    # local file header is supposed to begin @return [Integer] absolute offset
+    # (0-based) of where the compressed data begins for this file within the ZIP
+    # 
+    # _@param_ `io` — an IO-ish object the ZIP file can be read from
+    # 
+    # _@param_ `local_file_header_offset` — absolute offset (0-based) where the
+    def get_compressed_data_offset: (io: (untyped | _Reader), local_file_header_offset: Integer) -> untyped
+
+    # Parse an IO handle to a ZIP archive into an array of Entry objects, reading from the end
+    # of the IO object.
+    # 
+    # _@param_ `options` — any options the instance method of the same name accepts
+    # 
+    # _@return_ — an array of entries within the ZIP being parsed
+    # 
+    # _@see_ `#read_zip_structure`
+    def self.read_zip_structure: (**::Hash[untyped, untyped] options) -> ::Array[ZipEntry]
+
+    # Parse an IO handle to a ZIP archive into an array of Entry objects, reading from the start of
+    # the file and parsing local file headers one-by-one
+    # 
+    # _@param_ `options` — any options the instance method of the same name accepts
+    # 
+    # _@return_ — an array of entries within the ZIP being parsed
+    # 
+    # _@see_ `#read_zip_straight_ahead`
+    def self.read_zip_straight_ahead: (**::Hash[untyped, untyped] options) -> ::Array[ZipEntry]
+
+    # sord omit - no YARD type given for "entries", using untyped
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def read_local_headers: (untyped entries, untyped io) -> untyped
+
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def skip_ahead_2: (untyped io) -> untyped
+
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def skip_ahead_4: (untyped io) -> untyped
+
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def skip_ahead_8: (untyped io) -> untyped
+
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD type given for "absolute_pos", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def seek: (untyped io, untyped absolute_pos) -> untyped
+
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD type given for "signature_magic_number", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def assert_signature: (untyped io, untyped signature_magic_number) -> untyped
+
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD type given for "n", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def skip_ahead_n: (untyped io, untyped n) -> untyped
+
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD type given for "n_bytes", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def read_n: (untyped io, untyped n_bytes) -> untyped
+
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def read_2b: (untyped io) -> untyped
+
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def read_4b: (untyped io) -> untyped
+
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def read_8b: (untyped io) -> untyped
+
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def read_cdir_entry: (untyped io) -> untyped
+
+    # sord omit - no YARD type given for "file_io", using untyped
+    # sord omit - no YARD type given for "zip_file_size", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def get_eocd_offset: (untyped file_io, untyped zip_file_size) -> untyped
+
+    # sord omit - no YARD type given for "of_substring", using untyped
+    # sord omit - no YARD type given for "in_string", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def all_indices_of_substr_in_str: (untyped of_substring, untyped in_string) -> untyped
+
+    # sord omit - no YARD type given for "in_str", using untyped
+    # sord omit - no YARD return type given, using untyped
+    # We have to scan the maximum possible number
+    # of bytes that the EOCD can theoretically occupy including the comment after it,
+    # and we have to find a combination of:
+    #   [EOCD signature, <some ZIP medatata>, comment byte size, comment of size]
+    # at the end. To do so, we first find all indices of the signature in the trailer
+    # string, and then check whether the bytestring starting at the signature and
+    # ending at the end of string satisfies that given pattern.
+    def locate_eocd_signature: (untyped in_str) -> untyped
+
+    # sord omit - no YARD type given for "file_io", using untyped
+    # sord omit - no YARD type given for "eocd_offset", using untyped
+    # sord omit - no YARD return type given, using untyped
+    # Find the Zip64 EOCD locator segment offset. Do this by seeking backwards from the
+    # EOCD record in the archive by fixed offsets
+    #          get_zip64_eocd_location is too high. [15.17/15]
+    def get_zip64_eocd_location: (untyped file_io, untyped eocd_offset) -> untyped
+
+    # sord omit - no YARD type given for "io", using untyped
+    # sord omit - no YARD type given for "zip64_end_of_cdir_location", using untyped
+    # sord omit - no YARD return type given, using untyped
+    # num_files_and_central_directory_offset_zip64 is too high. [21.12/15]
+    def num_files_and_central_directory_offset_zip64: (untyped io, untyped zip64_end_of_cdir_location) -> untyped
+
+    # sord omit - no YARD type given for "file_io", using untyped
+    # sord omit - no YARD type given for "eocd_offset", using untyped
+    # sord omit - no YARD return type given, using untyped
+    # Start of the central directory offset
+    def num_files_and_central_directory_offset: (untyped file_io, untyped eocd_offset) -> untyped
+
+    # sord omit - no YARD return type given, using untyped
+    # Is provided as a stub to be overridden in a subclass if you need it. Will report
+    # during various stages of reading. The log message is contained in the return value
+    # of `yield` in the method (the log messages are lazy-evaluated).
+    def log: () -> untyped
+
+    # sord omit - no YARD type given for "extra_fields_str", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def parse_out_extra_fields: (untyped extra_fields_str) -> untyped
+
+    # Rubocop: convention: Missing top-level class documentation comment.
+    class StoredReader
+      # sord omit - no YARD type given for "from_io", using untyped
+      # sord omit - no YARD type given for "compressed_data_size", using untyped
+      def initialize: (untyped from_io, untyped compressed_data_size) -> void
+
+      # sord omit - no YARD type given for "n_bytes", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def extract: (?untyped n_bytes) -> untyped
+
+      def eof?: () -> bool
+    end
+
+    # Rubocop: convention: Missing top-level class documentation comment.
+    class InflatingReader
+      # sord omit - no YARD type given for "from_io", using untyped
+      # sord omit - no YARD type given for "compressed_data_size", using untyped
+      def initialize: (untyped from_io, untyped compressed_data_size) -> void
+
+      # sord omit - no YARD type given for "n_bytes", using untyped
+      # sord omit - no YARD return type given, using untyped
+      def extract: (?untyped n_bytes) -> untyped
+
+      def eof?: () -> bool
+    end
+
+    # Represents a file within the ZIP archive being read. This is different from
+    # the Entry object used in Streamer for ZIP writing, since during writing more
+    # data can be kept in memory for immediate use.
+    class ZipEntry
+      # sord omit - no YARD type given for "from_io", using untyped
+      # Returns a reader for the actual compressed data of the entry.
+      # 
+      #   reader = entry.extractor_from(source_file)
+      #   outfile << reader.extract(512 * 1024) until reader.eof?
+      # 
+      # _@return_ — the reader for the data
+      def extractor_from: (untyped from_io) -> (StoredReader | InflatingReader)
+
+      # _@return_ — at what offset you should start reading
+      # for the compressed data in your original IO object
+      def compressed_data_offset: () -> Integer
+
+      # Tells whether the compressed data offset is already known for this entry
+      def known_offset?: () -> bool
+
+      # Tells whether the entry uses a data descriptor (this is defined
+      # by bit 3 in the GP flags).
+      def uses_data_descriptor?: () -> bool
+
+      # sord infer - inferred type of parameter "offset" as Integer using getter's return type
+      # sord omit - no YARD return type given, using untyped
+      # Sets the offset at which the compressed data for this file starts in the ZIP.
+      # By default, the value will be set by the Reader for you. If you use delayed
+      # reading, you need to set it by using the `get_compressed_data_offset` on the Reader:
+      # 
+      #     entry.compressed_data_offset = reader.get_compressed_data_offset(io: file,
+      #            local_file_header_offset: entry.local_header_offset)
+      def compressed_data_offset=: (Integer offset) -> untyped
+
+      # _@return_ — bit-packed version signature of the program that made the archive
+      attr_accessor made_by: Integer
+
+      # _@return_ — ZIP version support needed to extract this file
+      attr_accessor version_needed_to_extract: Integer
+
+      # _@return_ — bit-packed general purpose flags
+      attr_accessor gp_flags: Integer
+
+      # _@return_ — Storage mode (0 for stored, 8 for deflate)
+      attr_accessor storage_mode: Integer
+
+      # _@return_ — the bit-packed DOS time
+      attr_accessor dos_time: Integer
+
+      # _@return_ — the bit-packed DOS date
+      attr_accessor dos_date: Integer
+
+      # _@return_ — the CRC32 checksum of this file
+      attr_accessor crc32: Integer
+
+      # _@return_ — size of compressed file data in the ZIP
+      attr_accessor compressed_size: Integer
+
+      # _@return_ — size of the file once uncompressed
+      attr_accessor uncompressed_size: Integer
+
+      # _@return_ — the filename
+      attr_accessor filename: String
+
+      # _@return_ — disk number where this file starts
+      attr_accessor disk_number_start: Integer
+
+      # _@return_ — internal attributes of the file
+      attr_accessor internal_attrs: Integer
+
+      # _@return_ — external attributes of the file
+      attr_accessor external_attrs: Integer
+
+      # _@return_ — at what offset the local file header starts
+      # in your original IO object
+      attr_accessor local_file_header_offset: Integer
+
+      # _@return_ — the file comment
+      attr_accessor comment: String
+    end
+  end
+
+  # Used when you need to supply a destination IO for some
+  # write operations, but want to discard the data (like when
+  # estimating the size of a ZIP)
+  module NullWriter
+    # _@param_ `_` — the data to write
+    def self.<<: (String _) -> self
+  end
+
+  # Alows reading the central directory of a remote ZIP file without
+  # downloading the entire file. The central directory provides the
+  # offsets at which the actual file contents is located. You can then
+  # use the `Range:` HTTP headers to download those entries separately.
+  # 
+  # Please read the security warning in `FileReader` _VERY CAREFULLY_
+  # before you use this module.
+  module RemoteUncap
+    # {ZipKit::FileReader} when reading
+    # files within the remote archive
+    # 
+    # _@param_ `uri` — the HTTP(S) URL to read the ZIP footer from
+    # 
+    # _@param_ `reader_class` — which class to use for reading
+    # 
+    # _@param_ `options_for_zip_reader` — any additional options to give to
+    # 
+    # _@return_ — metadata about the
+    def self.files_within_zip_at: (String uri, ?reader_class: Class, **::Hash[untyped, untyped] options_for_zip_reader) -> ::Array[ZipKit::FileReader::ZipEntry]
+  end
+
+  # A simple stateful class for keeping track of a CRC32 value through multiple writes
+  class StreamCRC32
+    include ZipKit::WriteShovel
+    STRINGS_HAVE_CAPACITY_SUPPORT: untyped
+    CRC_BUF_SIZE: untyped
+
+    # Compute a CRC32 value from an IO object. The object should respond to `read` and `eof?`
+    # 
+    # _@param_ `io` — the IO to read the data from
+    # 
+    # _@return_ — the computed CRC32 value
+    def self.from_io: (IO io) -> Integer
+
+    # Creates a new streaming CRC32 calculator
+    def initialize: () -> void
+
+    # Append data to the CRC32. Updates the contained CRC32 value in place.
+    # 
+    # _@param_ `blob` — the string to compute the CRC32 from
+    def <<: (String blob) -> self
+
+    # Returns the CRC32 value computed so far
+    # 
+    # _@return_ — the updated CRC32 value for all the blobs so far
+    def to_i: () -> Integer
+
+    # Appends a known CRC32 value to the current one, and combines the
+    # contained CRC32 value in-place.
+    # 
+    # _@param_ `crc32` — the CRC32 value to append
+    # 
+    # _@param_ `blob_size` — the size of the daata the `crc32` is computed from
+    # 
+    # _@return_ — the updated CRC32 value for all the blobs so far
+    def append: (Integer crc32, Integer blob_size) -> Integer
+
+    # Writes the given data to the output stream. Allows the object to be used as
+    # a target for `IO.copy_stream(from, to)`
+    # 
+    # _@param_ `bytes` — the binary string to write (part of the uncompressed file)
+    # 
+    # _@return_ — the number of bytes written (will always be the bytesize of `bytes`)
+    def write: (String bytes) -> Integer
+  end
+
+  # Some operations (such as CRC32) benefit when they are performed
+  # on larger chunks of data. In certain use cases, it is possible that
+  # the consumer of ZipKit is going to be writing small chunks
+  # in rapid succession, so CRC32 is going to have to perform a lot of
+  # CRC32 combine operations - and this adds up. Since the CRC32 value
+  # is usually not needed until the complete output has completed
+  # we can buffer at least some amount of data before computing CRC32 over it.
+  # We also use this buffer for output via Rack, where some amount of buffering
+  # helps reduce the number of syscalls made by the webserver. ZipKit performs
+  # lots of very small writes, and some degree of speedup (about 20%) can be achieved
+  # with a buffer of a few KB.
+  # 
+  # Note that there is no guarantee that the write buffer is going to flush at or above
+  # the given `buffer_size`, because for writes which exceed the buffer size it will
+  # first `flush` and then write through the oversized chunk, without buffering it. This
+  # helps conserve memory. Also note that the buffer will *not* duplicate strings for you
+  # and *will* yield the same buffer String over and over, so if you are storing it in an
+  # Array you might need to duplicate it.
+  # 
+  # Note also that the WriteBuffer assumes that the object it `<<`-writes into is going
+  # to **consume** in some way the string that it passes in. After the `<<` method returns,
+  # the WriteBuffer will be cleared, and it passes the same String reference on every call
+  # to `<<`. Therefore, if you need to retain the output of the WriteBuffer in, say, an Array,
+  # you might need to `.dup` the `String` it gives you.
+  class WriteBuffer
+    # sord duck - #<< looks like a duck type, replacing with untyped
+    # 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` — How many bytes to buffer
+    def initialize: (untyped writable, Integer buffer_size) -> void
+
+    # Appends the given data to the write buffer, and flushes the buffer into the
+    # writable if the buffer size exceeds the `buffer_size` given at initialization
+    # 
+    # _@param_ `string` — data to be written
+    # 
+    # _@return_ — self
+    def <<: (String string) -> untyped
+
+    # Explicitly flushes the buffer if it contains anything
+    # 
+    # _@return_ — self
+    def flush: () -> untyped
+  end
+
+  # A lot of objects in ZipKit accept bytes that may be sent
+  # to the `<<` operator (the "shovel" operator). This is in the tradition
+  # of late Jim Weirich and his Builder gem. In [this presentation](https://youtu.be/1BVFlvRPZVM?t=2403)
+  # he justifies this design very eloquently. In ZipKit we follow this example.
+  # However, there is a number of methods in Ruby - including the standard library -
+  # which expect your object to implement the `write` method instead. Since the `write`
+  # method can be expressed in terms of the `<<` method, why not allow all ZipKit
+  # "IO-ish" things to also respond to `write`? This is what this module does.
+  # Jim would be proud. We miss you, Jim.
+  module WriteShovel
+    # Writes the given data to the output stream. Allows the object to be used as
+    # a target for `IO.copy_stream(from, to)`
+    # 
+    # _@param_ `bytes` — the binary string to write (part of the uncompressed file)
+    # 
+    # _@return_ — the number of bytes written (will always be the bytesize of `bytes`)
+    def write: (String bytes) -> Integer
+  end
+
+  module ZlibCleanup
+    # sord warn - "Zlib::Deflater?" does not appear to be a type
+    # This method is used to flush and close the native zlib handles
+    # should an archiving routine encounter an error. This is necessary,
+    # since otherwise unclosed deflaters may hang around in memory
+    # indefinitely, creating leaks.
+    # 
+    # _@param_ `deflater` — the deflater to safely finish and close
+    # 
+    # _@return_ — void
+    def safely_dispose_of_incomplete_deflater: (SORD_ERROR_ZlibDeflater deflater) -> untyped
+  end
+
+  # Permits Deflate compression in independent blocks. The workflow is as follows:
+  # 
+  # * Run every block to compress through deflate_chunk, remove the header,
+  #   footer and adler32 from the result
+  # * Write out the compressed block bodies (the ones deflate_chunk returns)
+  #   to your output, in sequence
+  # * Write out the footer (\03\00)
+  # 
+  # The resulting stream is guaranteed to be handled properly by all zip
+  # unarchiving tools, including the BOMArchiveHelper/ArchiveUtility on OSX.
+  # 
+  # You could also build a compressor for Rubyzip using this module quite easily,
+  # even though this is outside the scope of the library.
+  # 
+  # When you deflate the chunks separately, you need to write the end marker
+  # yourself (using `write_terminator`).
+  # If you just want to deflate a large IO's contents, use
+  # `deflate_in_blocks_and_terminate` to have the end marker written out for you.
+  # 
+  # Basic usage to compress a file in parts:
+  # 
+  #     source_file = File.open('12_gigs.bin', 'rb')
+  #     compressed = Tempfile.new
+  #     # Will not compress everything in memory, but do it per chunk to spare
+  #       memory. `compressed`
+  #     # will be written to at the end of each chunk.
+  #     ZipKit::BlockDeflate.deflate_in_blocks_and_terminate(source_file,
+  #                                                             compressed)
+  # 
+  # You can also do the same to parts that you will later concatenate together
+  # elsewhere, in that case you need to skip the end marker:
+  # 
+  #     compressed = Tempfile.new
+  #     ZipKit::BlockDeflate.deflate_in_blocks(File.open('part1.bin', 'rb),
+  #                                               compressed)
+  #     ZipKit::BlockDeflate.deflate_in_blocks(File.open('part2.bin', 'rb),
+  #                                               compressed)
+  #     ZipKit::BlockDeflate.deflate_in_blocks(File.open('partN.bin', 'rb),
+  #                                               compressed)
+  #     ZipKit::BlockDeflate.write_terminator(compressed)
+  # 
+  # You can also elect to just compress strings in memory (to splice them later):
+  # 
+  #     compressed_string = ZipKit::BlockDeflate.deflate_chunk(big_string)
+  class BlockDeflate
+    DEFAULT_BLOCKSIZE: untyped
+    END_MARKER: untyped
+    VALID_COMPRESSIONS: untyped
+
+    # Write the end marker (\x3\x0) to the given IO.
+    # 
+    # `output_io` can also be a {ZipKit::Streamer} to expedite ops.
+    # 
+    # _@param_ `output_io` — the stream to write to (should respond to `:<<`)
+    # 
+    # _@return_ — number of bytes written to `output_io`
+    def self.write_terminator: (IO output_io) -> Integer
+
+    # Compress a given binary string and flush the deflate stream at byte boundary.
+    # The returned string can be spliced into another deflate stream.
+    # 
+    # _@param_ `bytes` — Bytes to compress
+    # 
+    # _@param_ `level` — Zlib compression level (defaults to `Zlib::DEFAULT_COMPRESSION`)
+    # 
+    # _@return_ — compressed bytes
+    def self.deflate_chunk: (String bytes, ?level: Integer) -> String
+
+    # Compress the contents of input_io into output_io, in blocks
+    # of block_size. Aligns the parts so that they can be concatenated later.
+    # Writes deflate end marker (\x3\x0) into `output_io` as the final step, so
+    # the contents of `output_io` can be spliced verbatim into a ZIP archive.
+    # 
+    # Once the write completes, no more parts for concatenation should be written to
+    # the same stream.
+    # 
+    # `output_io` can also be a {ZipKit::Streamer} to expedite ops.
+    # 
+    # _@param_ `input_io` — the stream to read from (should respond to `:read`)
+    # 
+    # _@param_ `output_io` — the stream to write to (should respond to `:<<`)
+    # 
+    # _@param_ `level` — Zlib compression level (defaults to `Zlib::DEFAULT_COMPRESSION`)
+    # 
+    # _@param_ `block_size` — The block size to use (defaults to `DEFAULT_BLOCKSIZE`)
+    # 
+    # _@return_ — number of bytes written to `output_io`
+    def self.deflate_in_blocks_and_terminate: (
+                                                IO input_io,
+                                                IO output_io,
+                                                ?level: Integer,
+                                                ?block_size: Integer
+                                              ) -> Integer
+
+    # Compress the contents of input_io into output_io, in blocks
+    # of block_size. Align the parts so that they can be concatenated later.
+    # Will not write the deflate end marker (\x3\x0) so more parts can be written
+    # later and succesfully read back in provided the end marker wll be written.
+    # 
+    # `output_io` can also be a {ZipKit::Streamer} to expedite ops.
+    # 
+    # _@param_ `input_io` — the stream to read from (should respond to `:read`)
+    # 
+    # _@param_ `output_io` — the stream to write to (should respond to `:<<`)
+    # 
+    # _@param_ `level` — Zlib compression level (defaults to `Zlib::DEFAULT_COMPRESSION`)
+    # 
+    # _@param_ `block_size` — The block size to use (defaults to `DEFAULT_BLOCKSIZE`)
+    # 
+    # _@return_ — number of bytes written to `output_io`
+    def self.deflate_in_blocks: (
+                                  IO input_io,
+                                  IO output_io,
+                                  ?level: Integer,
+                                  ?block_size: Integer
+                                ) -> Integer
+  end
+
+  # Helps to estimate archive sizes
+  class SizeEstimator
+    # Creates a new estimator with a Streamer object. Normally you should use
+    # `estimate` instead an not use this method directly.
+    # 
+    # _@param_ `streamer`
+    def initialize: (ZipKit::Streamer streamer) -> void
+
+    # Performs the estimate using fake archiving. It needs to know the sizes of the
+    # entries upfront. Usage:
+    # 
+    #     expected_zip_size = SizeEstimator.estimate do | estimator |
+    #       estimator.add_stored_entry(filename: "file.doc", size: 898291)
+    #       estimator.add_deflated_entry(filename: "family.tif",
+    #               uncompressed_size: 89281911, compressed_size: 121908)
+    #     end
+    # 
+    # _@param_ `kwargs_for_streamer_new` — Any options to pass to Streamer, see {Streamer#initialize}
+    # 
+    # _@return_ — the size of the resulting archive, in bytes
+    def self.estimate: (**untyped kwargs_for_streamer_new) ?{ (SizeEstimator estimator) -> void } -> Integer
+
+    # Add a fake entry to the archive, to see how big it is going to be in the end.
+    # 
+    # _@param_ `filename` — the name of the file (filenames are variable-width in the ZIP)
+    # 
+    # _@param_ `size` — size of the uncompressed entry
+    # 
+    # _@param_ `use_data_descriptor` — whether there is going to be a data descriptor written after the entry body, to specify size. You must enable this if you are going to be using {Streamer#write_stored_file} as otherwise your estimated size is not going to be accurate
+    # 
+    # _@return_ — self
+    def add_stored_entry: (filename: String, size: Integer, ?use_data_descriptor: bool) -> untyped
+
+    # Add a fake entry to the archive, to see how big it is going to be in the end.
+    # 
+    # _@param_ `filename` — the name of the file (filenames are variable-width in the ZIP)
+    # 
+    # _@param_ `uncompressed_size` — size of the uncompressed entry
+    # 
+    # _@param_ `compressed_size` — size of the compressed entry
+    # 
+    # _@param_ `use_data_descriptor` — whether there is going to be a data descriptor written after the entry body, to specify size. You must enable this if you are going to be using {Streamer#write_deflated_file} as otherwise your estimated size is not going to be accurate
+    # 
+    # _@return_ — self
+    def add_deflated_entry: (
+                              filename: String,
+                              uncompressed_size: Integer,
+                              compressed_size: Integer,
+                              ?use_data_descriptor: bool
+                            ) -> untyped
+
+    # Add an empty directory to the archive.
+    # 
+    # _@param_ `dirname` — the name of the directory
+    # 
+    # _@return_ — self
+    def add_empty_directory_entry: (dirname: String) -> untyped
+  end
+
+  # A tiny wrapper over any object that supports :<<.
+  # Adds :tell and :advance_position_by. This is needed for write destinations
+  # which do not respond to `#pos` or `#tell`. A lot of ZIP archive format parts
+  # include "offsets in archive" - a byte offset from the start of file. Keeping
+  # track of this value is what this object will do. It also allows "advancing"
+  # this value if data gets written using a bypass (such as `IO#sendfile`)
+  class WriteAndTell
+    include ZipKit::WriteShovel
+
+    # sord omit - no YARD type given for "io", using untyped
+    def initialize: (untyped io) -> void
+
+    # sord omit - no YARD type given for "bytes", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def <<: (untyped bytes) -> untyped
+
+    # sord omit - no YARD type given for "num_bytes", using untyped
+    # sord omit - no YARD return type given, using untyped
+    def advance_position_by: (untyped num_bytes) -> untyped
+
+    # sord omit - no YARD return type given, using untyped
+    def tell: () -> untyped
+
+    # Writes the given data to the output stream. Allows the object to be used as
+    # a target for `IO.copy_stream(from, to)`
+    # 
+    # _@param_ `bytes` — the binary string to write (part of the uncompressed file)
+    # 
+    # _@return_ — the number of bytes written (will always be the bytesize of `bytes`)
+    def write: (String bytes) -> Integer
+  end
+
+  # Should be included into a Rails controller for easy ZIP output from any action.
+  module RailsStreaming
+    # Opens a {ZipKit::Streamer} and yields it to the caller. The output of the streamer
+    # will be sent through to the HTTP response body as it gets produced.
+    # 
+    # Note that there is an important difference in how this method works, depending whether
+    # you use it in a controller which includes `ActionController::Live` vs. one that does not.
+    # With a standard `ActionController` this method will assign a response body, but streaming
+    # will begin when your action method returns. With `ActionController::Live` the streaming
+    # will begin immediately, before the method returns. In all other aspects the method should
+    # stream correctly in both types of controllers.
+    # 
+    # If you encounter buffering (streaming does not start for a very long time) you probably
+    # have a piece of Rack middleware in your stack which buffers. Known offenders are `Rack::ContentLength`,
+    # `Rack::MiniProfiler` and `Rack::ETag`. ZipKit will try to work around these but it is not
+    # always possible. If you encounter buffering, examine your middleware stack and try to suss
+    # out whether any middleware might be buffering. You can also try setting `use_chunked_transfer_encoding`
+    # to `true` - this is not recommended but sometimes necessary, for example to bypass `Rack::ContentLength`.
+    # 
+    # _@param_ `filename` — name of the file for the Content-Disposition header
+    # 
+    # _@param_ `type` — the content type (MIME type) of the archive being output
+    # 
+    # _@param_ `use_chunked_transfer_encoding` — whether to forcibly encode output as chunked. Normally you should not need this.
+    # 
+    # _@param_ `output_enumerator_options` — options that will be passed to the OutputEnumerator - these include options for the Streamer. See {ZipKit::OutputEnumerator#initialize} for the full list of options.
+    # 
+    # _@return_ — always returns true
+    def zip_kit_stream: (
+                          ?filename: String,
+                          ?_type: String,
+                          ?use_chunked_transfer_encoding: bool,
+                          **::Hash[untyped, untyped] output_enumerator_options
+                        ) ?{ (ZipKit::Streamer zip) -> void } -> bool
+  end
+
+  # The output enumerator makes it possible to "pull" from a ZipKit streamer
+  # object instead of having it "push" writes to you. It will "stash" the block which
+  # writes the ZIP archive through the streamer, and when you call `each` on the Enumerator
+  # it will yield you the bytes the block writes. Since it is an enumerator you can
+  # use `next` to take chunks written by the ZipKit streamer one by one. It can be very
+  # convenient when you need to segment your ZIP output into bigger chunks for, say,
+  # uploading them to a cloud storage provider such as S3.
+  # 
+  # Another use of the `OutputEnumerator` is as a Rack response body - since a Rack
+  # response body object must support `#each` yielding successive binary strings.
+  # Which is exactly what `OutputEnumerator` does.
+  # 
+  # The enumerator can provide you some more conveinences for HTTP output - correct streaming
+  # headers and a body with chunked transfer encoding.
+  # 
+  #     iterable_zip_body = ZipKit::OutputEnumerator.new do | streamer |
+  #       streamer.write_file('big.csv') do |sink|
+  #         CSV(sink) do |csv_writer|
+  #           csv_writer << Person.column_names
+  #           Person.all.find_each do |person|
+  #             csv_writer << person.attributes.values
+  #           end
+  #         end
+  #       end
+  #     end
+  # 
+  # You can grab the headers one usually needs for streaming from `#streaming_http_headers`:
+  # 
+  #     [200, iterable_zip_body.streaming_http_headers, iterable_zip_body]
+  # 
+  # to bypass things like `Rack::ETag` and the nginx buffering.
+  class OutputEnumerator
+    DEFAULT_WRITE_BUFFER_SIZE: untyped
+
+    # Creates a new OutputEnumerator enumerator. The enumerator can be read from using `each`,
+    # and the creation of the ZIP is in lockstep with the caller calling `each` on the returned
+    # output enumerator object. This can be used when the calling program wants to stream the
+    # output of the ZIP archive and throttle that output, or split it into chunks, or use it
+    # as a generator.
+    # 
+    # For example:
+    # 
+    #     # The block given to {output_enum} won't be executed immediately - rather it
+    #     # will only start to execute when the caller starts to read from the output
+    #     # by calling `each`
+    #     body = ::ZipKit::OutputEnumerator.new(writer: CustomWriter) do |streamer|
+    #       streamer.add_stored_entry(filename: 'large.tif', size: 1289894, crc32: 198210)
+    #       streamer << large_file.read(1024*1024) until large_file.eof?
+    #       ...
+    #     end
+    # 
+    #     body.each do |bin_string|
+    #       # Send the output somewhere, buffer it in a file etc.
+    #       # The block passed into `initialize` will only start executing once `#each`
+    #       # is called
+    #       ...
+    #     end
+    # 
+    # _@param_ `streamer_options` — options for Streamer, see {ZipKit::Streamer.new}
+    # 
+    # _@param_ `write_buffer_size` — By default all ZipKit writes are unbuffered. For output to sockets it is beneficial to bulkify those writes so that they are roughly sized to a socket buffer chunk. This object will bulkify writes for you in this way (so `each` will yield not on every call to `<<` from the Streamer but at block size boundaries or greater). Set the parameter to 0 for unbuffered writes.
+    # 
+    # _@param_ `blk` — a block that will receive the Streamer object when executing. The block will not be executed immediately but only once `each` is called on the OutputEnumerator
+    def initialize: (?write_buffer_size: Integer, **::Hash[untyped, untyped] streamer_options) -> void
+
+    # sord omit - no YARD return type given, using untyped
+    # Executes the block given to the constructor with a {ZipKit::Streamer}
+    # and passes each written chunk to the block given to the method. This allows one
+    # to "take" output of the ZIP piecewise. If called without a block will return an Enumerator
+    # that you can pull data from using `next`.
+    # 
+    # **NOTE** Because the `WriteBuffer` inside this object can reuse the buffer, it is important
+    #    that the `String` that is yielded **either** gets consumed eagerly (written byte-by-byte somewhere, or `#dup`-ed)
+    #    since the write buffer will clear it after your block returns. If you expand this Enumerator
+    #    eagerly into an Array you might notice that a lot of the segments of your ZIP output are
+    #    empty - this means that you need to duplicate them.
+    def each: () -> untyped
+
+    # Returns a Hash of HTTP response headers you are likely to need to have your response stream correctly.
+    # This is on the {ZipKit::OutputEnumerator} class since those headers are common, independent of the
+    # particular response body getting served. You might want to override the headers with your particular
+    # ones - for example, specific content types are needed for files which are, technically, ZIP files
+    # but are of a file format built "on top" of ZIPs - such as ODTs, [pkpass files](https://developer.apple.com/documentation/walletpasses/building_a_pass)
+    # and ePubs.
+    # 
+    # More value, however, is in the "technical" headers this method will provide. It will take the following steps to make sure streaming works correctly.
+    # 
+    # * `Last-Modified` will be set to "now" so that the response is considered "fresh" by `Rack::ETag`. This is done so that `Rack::ETag` won't try to
+    #      calculate a lax ETag value and thus won't start buffering your response out of nowhere
+    # * `Content-Encoding` will be set to `identity`. This is so that proxies or the Rack middleware that applies compression to the response (like gzip)
+    #      is not going to try to compress your response. It also tells the receiving browsers (or downstream proxies) that they should not attempt to
+    #      open or uncompress the response before saving it or passing it onwards.
+    # * `X-Accel-Buffering` will be set to 'no` - this tells both nginx and the Google Cloud load balancer that the response should not be buffered
+    # 
+    # These header values are known to get as close as possible to guaranteeing streaming on most environments where Ruby web applications may be hosted.
+    def self.streaming_http_headers: () -> ::Hash[untyped, untyped]
+
+    # Returns a Hash of HTTP response headers for this particular response. This used to contain "Content-Length" for
+    # presized responses, but is now effectively a no-op.
+    # 
+    # _@see_ `[ZipKit::OutputEnumerator.streaming_http_headers]`
+    def streaming_http_headers: () -> ::Hash[untyped, untyped]
+
+    # Returns a tuple of `headers, body` - headers are a `Hash` and the body is
+    # an object that can be used as a Rack response body. This method used to accept arguments
+    # but will now just ignore them.
+    def to_headers_and_rack_response_body: () -> ::Array[untyped]
+  end
+
+  # A body wrapper that emits chunked responses, creating valid
+  # Transfer-Encoding::Chunked HTTP response body. This is copied from Rack::Chunked::Body,
+  # because Rack is not going to include that class after version 3.x
+  # Rails has a substitute class for this inside ActionController::Streaming,
+  # but that module is a private constant in the Rails codebase, and is thus
+  # considered "private" from the Rails standpoint. It is not that much code to
+  # carry, so we copy it into our code.
+  class RackChunkedBody
+    TERM: untyped
+    TAIL: untyped
+
+    # sord duck - #each looks like a duck type with an equivalent RBS interface, replacing with _Each[untyped]
+    # _@param_ `body` — the enumerable that yields bytes, usually a `OutputEnumerator`
+    def initialize: (_Each[untyped] body) -> void
+
+    # sord omit - no YARD return type given, using untyped
+    # For each string yielded by the response body, yield
+    # the element in chunked encoding - and finish off with a terminator
+    def each: () -> untyped
+  end
+
+  module UniquifyFilename
+    # sord duck - #include? looks like a duck type, replacing with untyped
+    # Makes a given filename unique by appending a (n) suffix
+    # between just before the filename extension. So "file.txt" gets
+    # transformed into "file (1).txt". The transformation is applied
+    # repeatedly as long as the generated filename is present
+    # in `while_included_in` object
+    # 
+    # _@param_ `path` — the path to make unique
+    # 
+    # _@param_ `while_included_in` — an object that stores the list of already used paths
+    # 
+    # _@return_ — the path as is, or with the suffix required to make it unique
+    def self.call: (String path, untyped while_included_in) -> String
+  end
+
+  # Contains a file handle which can be closed once the response finishes sending.
+  # It supports `to_path` so that `Rack::Sendfile` can intercept it.
+  # This class is deprecated and is going to be removed in zip_kit 7.x
+  # @api deprecated
+  class RackTempfileBody
+    TEMPFILE_NAME_PREFIX: untyped
+
+    # sord omit - no YARD type given for "env", using untyped
+    # sord duck - #each looks like a duck type with an equivalent RBS interface, replacing with _Each[untyped]
+    # _@param_ `body` — the enumerable that yields bytes, usually a `OutputEnumerator`. The `body` will be read in full immediately and closed.
+    def initialize: (untyped env, _Each[untyped] body) -> void
+
+    # Returns the size of the contained `Tempfile` so that a correct
+    # Content-Length header can be set
+    def size: () -> Integer
+
+    # Returns the path to the `Tempfile`, so that Rack::Sendfile can send this response
+    # using the downstream webserver
+    def to_path: () -> String
+
+    # Stream the file's contents if `Rack::Sendfile` isn't present.
+    def each: () -> void
+
+    # sord omit - no YARD return type given, using untyped
+    def flush: () -> untyped
+
+    # sord omit - no YARD type given for :tempfile, using untyped
+    attr_reader tempfile: untyped
+  end
+end