Class: ZipKit::ZipWriter
- Inherits:
-
Object
- Object
- ZipKit::ZipWriter
- Defined in:
- lib/zip_kit/zip_writer.rb
Overview
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.
Constant Summary collapse
- DEFAULT_FILE_UNIX_PERMISSIONS =
0o644
- DEFAULT_DIRECTORY_UNIX_PERMISSIONS =
0o755
- C_CHAR =
For bit-encoded strings
"C"
- C_INT4 =
Encode a 4-byte signed little-endian int
"l<"
Instance Method Summary collapse
-
#write_central_directory_file_header(io:, local_file_header_location:, gp_flags:, storage_mode:, compressed_size:, uncompressed_size:, mtime:, crc32:, filename:, unix_permissions: nil) ⇒ void
Writes the file header for the central directory, for a particular file in the archive.
-
#write_data_descriptor(io:, compressed_size:, uncompressed_size:, crc32:) ⇒ void
Writes the data descriptor following the file data for a file whose local file header was written with general-purpose flag bit 3 set.
-
#write_end_of_central_directory(io:, start_of_central_directory_location:, central_directory_size:, num_files_in_archive:, comment: ZIP_KIT_COMMENT) ⇒ void
Writes the "end of central directory record" (including the Zip6 salient bits if necessary).
-
#write_local_file_header(io:, filename:, compressed_size:, uncompressed_size:, crc32:, gp_flags:, mtime:, storage_mode:) ⇒ void
Writes the local file header, that precedes the actual file data.
Instance Method Details
#write_central_directory_file_header(io:, local_file_header_location:, gp_flags:, storage_mode:, compressed_size:, uncompressed_size:, mtime:, crc32:, filename:, unix_permissions: nil) ⇒ void
This method returns an undefined value.
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.
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 |
# File 'lib/zip_kit/zip_writer.rb', line 146 def write_central_directory_file_header(io:, local_file_header_location:, gp_flags:, storage_mode:, compressed_size:, uncompressed_size:, mtime:, crc32:, filename:, unix_permissions: nil) # At this point if the header begins somewhere beyound 0xFFFFFFFF we _have_ to record the offset # of the local file header as a zip64 extra field, so we give up, give in, you loose, love will always win... add_zip64 = (local_file_header_location > FOUR_BYTE_MAX_UINT) || (compressed_size > FOUR_BYTE_MAX_UINT) || (uncompressed_size > FOUR_BYTE_MAX_UINT) # central file header signature 4 bytes (0x02014b50) io << [0x02014b50].pack(C_UINT4) # version made by 2 bytes io << MADE_BY_SIGNATURE # version needed to extract 2 bytes io << if add_zip64 [VERSION_NEEDED_TO_EXTRACT_ZIP64].pack(C_UINT2) else [VERSION_NEEDED_TO_EXTRACT].pack(C_UINT2) end # general purpose bit flag 2 bytes io << [gp_flags].pack(C_UINT2) # compression method 2 bytes io << [storage_mode].pack(C_UINT2) # last mod file time 2 bytes io << [to_binary_dos_time(mtime)].pack(C_UINT2) # last mod file date 2 bytes io << [to_binary_dos_date(mtime)].pack(C_UINT2) # crc-32 4 bytes io << [crc32].pack(C_UINT4) # compressed size 4 bytes # uncompressed size 4 bytes if add_zip64 io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4) io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4) else io << [compressed_size].pack(C_UINT4) io << [uncompressed_size].pack(C_UINT4) end # Filename should not be longer than 0xFFFF otherwise this wont fit here # file name length 2 bytes io << [filename.bytesize].pack(C_UINT2) extra_fields = StringIO.new if add_zip64 extra_fields << zip_64_extra_for_central_directory_file_header(local_file_header_location: local_file_header_location, compressed_size: compressed_size, uncompressed_size: uncompressed_size) end extra_fields << (mtime) # extra field length 2 bytes io << [extra_fields.size].pack(C_UINT2) # file comment length 2 bytes io << [0].pack(C_UINT2) # For The Unarchiver < 3.11.1 this field has to be set to the overflow value if zip64 is used # because otherwise it does not properly advance the pointer when reading the Zip64 extra field # https://bitbucket.org/WAHa_06x36/theunarchiver/pull-requests/2/bug-fix-for-zip64-extra-field-parser/diff # disk number start 2 bytes io << if add_zip64 [TWO_BYTE_MAX_UINT].pack(C_UINT2) else [0].pack(C_UINT2) end # internal file attributes 2 bytes io << [0].pack(C_UINT2) # Because the add_empty_directory method will create a directory with a trailing "/", # this check can be used to assign proper permissions to the created directory. external_attrs = if filename.end_with?("/") ||= DEFAULT_DIRECTORY_UNIX_PERMISSIONS generate_external_attrs(, FILE_TYPE_DIRECTORY) else ||= DEFAULT_FILE_UNIX_PERMISSIONS generate_external_attrs(, FILE_TYPE_FILE) end # external file attributes 4 bytes io << [external_attrs].pack(C_UINT4) # relative offset of local header 4 bytes io << if add_zip64 [FOUR_BYTE_MAX_UINT].pack(C_UINT4) else [local_file_header_location].pack(C_UINT4) end # file name (variable size) io << filename # extra field (variable size) io << extra_fields.string # file comment (variable size) # (empty) end |
#write_data_descriptor(io:, compressed_size:, uncompressed_size:, crc32:) ⇒ void
This method returns an undefined value.
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.
260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 |
# File 'lib/zip_kit/zip_writer.rb', line 260 def write_data_descriptor(io:, compressed_size:, uncompressed_size:, crc32:) # Although not originally assigned a signature, the value # 0x08074b50 has commonly been adopted as a signature value # for the data descriptor record. io << [0x08074b50].pack(C_UINT4) # crc-32 4 bytes io << [crc32].pack(C_UINT4) # If one of the sizes is above 0xFFFFFFF use ZIP64 lengths (8 bytes) instead. A good unarchiver # will decide to unpack it as such if it finds the Zip64 extra for the file in the central directory. # So also use the opportune moment to switch the entry to Zip64 if needed. # We switch if either of the sizes requires ZIP64, so that both values are encoded similarly. requires_zip64 = compressed_size > FOUR_BYTE_MAX_UINT || uncompressed_size > FOUR_BYTE_MAX_UINT pack_spec = requires_zip64 ? C_UINT8 : C_UINT4 # compressed size 4 bytes, or 8 bytes for ZIP64 io << [compressed_size].pack(pack_spec) # uncompressed size 4 bytes, or 8 bytes for ZIP64 io << [uncompressed_size].pack(pack_spec) end |
#write_end_of_central_directory(io:, start_of_central_directory_location:, central_directory_size:, num_files_in_archive:, comment: ZIP_KIT_COMMENT) ⇒ void
This method returns an undefined value.
Writes the "end of central directory record" (including the Zip6 salient bits if necessary)
290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 |
# File 'lib/zip_kit/zip_writer.rb', line 290 def write_end_of_central_directory(io:, start_of_central_directory_location:, central_directory_size:, num_files_in_archive:, comment: ZIP_KIT_COMMENT) zip64_eocdr_offset = start_of_central_directory_location + central_directory_size zip64_required = central_directory_size > FOUR_BYTE_MAX_UINT || start_of_central_directory_location > FOUR_BYTE_MAX_UINT || zip64_eocdr_offset > FOUR_BYTE_MAX_UINT || num_files_in_archive > TWO_BYTE_MAX_UINT # Then, if zip64 is used if zip64_required # [zip64 end of central directory record] # zip64 end of central dir signature 4 bytes (0x06064b50) io << [0x06064b50].pack(C_UINT4) # size of zip64 end of central # directory record 8 bytes # (this is ex. the 12 bytes of the signature and the size value itself). # Without the extensible data sector (which we are not using) # it is always 44 bytes. io << [44].pack(C_UINT8) # version made by 2 bytes io << MADE_BY_SIGNATURE # version needed to extract 2 bytes io << [VERSION_NEEDED_TO_EXTRACT_ZIP64].pack(C_UINT2) # number of this disk 4 bytes io << [0].pack(C_UINT4) # number of the disk with the start of the central directory 4 bytes io << [0].pack(C_UINT4) # total number of entries in the # central directory on this disk 8 bytes io << [num_files_in_archive].pack(C_UINT8) # total number of entries in the # central directory 8 bytes io << [num_files_in_archive].pack(C_UINT8) # size of the central directory 8 bytes io << [central_directory_size].pack(C_UINT8) # offset of start of central directory with respect to # the starting disk number 8 bytes io << [start_of_central_directory_location].pack(C_UINT8) # zip64 extensible data sector (variable size) # (blank for us) # zip64 end of central dir locator # signature 4 bytes (0x07064b50) io << [0x07064b50].pack(C_UINT4) # number of the disk with the start of the zip64 end of # central directory 4 bytes io << [0].pack(C_UINT4) # relative offset of the zip64 # end of central directory record 8 bytes # (note: "relative" is actually "from the start of the file") io << [zip64_eocdr_offset].pack(C_UINT8) # total number of disks 4 bytes io << [1].pack(C_UINT4) end # Then the end of central directory record: # end of central dir signature 4 bytes (0x06054b50) io << [0x06054b50].pack(C_UINT4) # number of this disk 2 bytes io << [0].pack(C_UINT2) # number of the disk with the # start of the central directory 2 bytes io << [0].pack(C_UINT2) # total number of entries in the # central directory on this disk 2 bytes # total number of entries in # the central directory 2 bytes if zip64_required # the number of entries will be read from the zip64 part of the central directory io << [TWO_BYTE_MAX_UINT].pack(C_UINT2) io << [TWO_BYTE_MAX_UINT].pack(C_UINT2) else io << [num_files_in_archive].pack(C_UINT2) io << [num_files_in_archive].pack(C_UINT2) end # size of the central directory 4 bytes # offset of start of central # directory with respect to # the starting disk number 4 bytes if zip64_required io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4) io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4) else io << [central_directory_size].pack(C_UINT4) io << [start_of_central_directory_location].pack(C_UINT4) end # .ZIP file comment length 2 bytes io << [comment.bytesize].pack(C_UINT2) # .ZIP file comment (variable size) io << comment end |
#write_local_file_header(io:, filename:, compressed_size:, uncompressed_size:, crc32:, gp_flags:, mtime:, storage_mode:) ⇒ void
This method returns an undefined value.
Writes the local file header, that precedes the actual file data.
74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 |
# File 'lib/zip_kit/zip_writer.rb', line 74 def write_local_file_header(io:, filename:, compressed_size:, uncompressed_size:, crc32:, gp_flags:, mtime:, storage_mode:) requires_zip64 = compressed_size > FOUR_BYTE_MAX_UINT || uncompressed_size > FOUR_BYTE_MAX_UINT # local file header signature 4 bytes (0x04034b50) io << [0x04034b50].pack(C_UINT4) # version needed to extract 2 bytes io << if requires_zip64 [VERSION_NEEDED_TO_EXTRACT_ZIP64].pack(C_UINT2) else [VERSION_NEEDED_TO_EXTRACT].pack(C_UINT2) end # general purpose bit flag 2 bytes io << [gp_flags].pack(C_UINT2) # compression method 2 bytes io << [storage_mode].pack(C_UINT2) # last mod file time 2 bytes io << [to_binary_dos_time(mtime)].pack(C_UINT2) # last mod file date 2 bytes io << [to_binary_dos_date(mtime)].pack(C_UINT2) # crc-32 4 bytes io << [crc32].pack(C_UINT4) if requires_zip64 # compressed size 4 bytes io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4) # uncompressed size 4 bytes io << [FOUR_BYTE_MAX_UINT].pack(C_UINT4) else # compressed size 4 bytes io << [compressed_size].pack(C_UINT4) # uncompressed size 4 bytes io << [uncompressed_size].pack(C_UINT4) end # Filename should not be longer than 0xFFFF otherwise this wont fit here # file name length 2 bytes io << [filename.bytesize].pack(C_UINT2) extra_fields = StringIO.new # Interesting tidbit: # https://social.technet.microsoft.com/Forums/windows/en-US/6a60399f-2879-4859-b7ab-6ddd08a70948 # TL;DR of it is: Windows 7 Explorer _will_ open Zip64 entries. However, it desires to have the # Zip64 extra field as _the first_ extra field. if requires_zip64 extra_fields << zip_64_extra_for_local_file_header(compressed_size: compressed_size, uncompressed_size: uncompressed_size) end extra_fields << (mtime) # extra field length 2 bytes io << [extra_fields.size].pack(C_UINT2) # file name (variable size) io << filename # Contents of the extra fields (variable size) io << extra_fields.string end |