Skip to content

Upgrading archive 3 to 4

Breaking3.6.1 → 4.6.0Breaking13Security9Deprecated2New37Changed40Fixed123Other1

BreakingUpgrade verdict

13 breaking changes and 9 security fixes.

  • Damaged archives now decode quietly by default instead of raising an error. You must ask for errors or checksum checks explicitly.
  • Extraction helpers now skip damaged entries by default and only raise errors when you ask them to.
  • Two checksum helper classes are gone, so code that used them will stop compiling.
  • If your code calls decodeBuffer on a decoder, you now need to call decodeStream instead.
Top 5 of 24 that need code or config changes

Dart SDK requirement changed in 4.0.0: ^3.0.0 → >=3.0.0 <4.0.0.

Breaking13
All decoders and extraction helpers no longer throw on damaged data by default; use throwOnError and verify to opt in.
XZDecoderTarDecoderZipDecoderGZipDecoderZLibDecoderBZip2DecoderZstdDecoderextractFileToDisk
extractFileToDisk accepts verify and throwOnError; extractArchiveToDisk and extractArchiveToDiskSync accept throwOnError, and damaged archives no longer throw by default.
extractFileToDiskextractArchiveToDiskextractArchiveToDiskSyncverifythrowOnError
Removes the Adler32 and Crc32 classes.
Adler32Crc32
Renames decodeBuffer to decodeStream in the various decoder classes.
decodeBufferdecodeStream
Renames InputStream to InputMemoryStream.
InputStreamInputMemoryStream
Renames OutputStream to OutputMemoryStream.
OutputStreamOutputMemoryStream
All decoders now honor verify: true instead of ignoring it, with documented gaps in dart:io based gzip and zlib decoders.
GZipDecoderZLibDecoderGZipDecoderWebZLibDecoderWeb
Adds writeRange and reserve to OutputStream and readInto and viewBytes to InputStream; implementers must add them.
OutputStream.writeRangeOutputStream.reserveInputStream.readIntoInputStream.viewBytes
Zip entry lastModTime is now seconds since epoch; the old DOS value moves to ArchiveFile.lastModDosTime.
lastModTimeArchiveFile.lastModDosTime
CompressionType gains lzma and xz values, so exhaustive switches over it need new cases.
CompressionTypeCompressionType.lzmaCompressionType.xz
ArchiveFile.lastModDateTime now returns a local DateTime from lastModTime in seconds since epoch, and ZipDecoder reads the UT extra field so ZipEncoder output round-trips across time zones.
ArchiveFile.lastModDateTimelastModTimeZipDecoderZipEncoder
extractFileToDisk now calls callback for a zip entry after it is written, as it does for tar, instead of during central directory reading.
extractFileToDisk
ZipDirectory.read no longer reads every entry's local header; ZipFileHeader reads its file lazily.
ZipDirectory.readZipFileHeaderZipFileHeader.fileZipDecoderZipDirectory
Security9
Fixes symlink scopes for extractFileToDisk that could overwrite an existing file on disk outside the output dir.
extractFileToDisk
Fixes XZDecoder hanging forever on a truncated .xz read from a file or decode stream, including .tar.xz in extractFileToDisk.
XZDecoderextractFileToDisk
Limits tar long name and pax header entries to TarFile.maxMetadataSize (1 MB) to prevent huge memory use from small archives.
TarFile.maxMetadataSize
Adds maxOutputSize to decodeBytes and decodeStream on GZipDecoder, ZLibDecoder, BZip2Decoder and ZstdDecoder, and maxSize to extraction functions.
maxOutputSizedecodeBytesdecodeStreamGZipDecoderZLibDecoderBZip2DecoderZstdDecodermaxSize
ZstdDecoder now checks content size as each block decodes and refuses blocks that overflow it, even past maxWindowSize.
ZstdDecodermaxWindowSize
XZDecoder limits the LZMA2 dictionary to maxDictionarySize (256 MB default), takes maxOutputSize, and no longer preallocates gigabytes from a tiny archive's index.
XZDecodermaxDictionarySizemaxOutputSize
Extraction creates symbolic links after all other entries and refuses links whose path runs through another link.
extractTarFiles now keeps entries inside the output directory and decodes as it reads instead of using a leftover temp file.
extractTarFilesextractFileToDisk
Fixes a zip64 compressed size overflow that could crash the decoder when reading an untrusted archive; sizes are now clamped to bytes present.
Deprecated2
Deprecates AesDecrypt in favor of the exported AesCtr; Sha1, HmacSha1, pbkdf2HmacSha1 and Sha256 are now exported.
AesDecryptAesCtrSha1HmacSha1pbkdf2HmacSha1Sha256
Deprecates the ignored fileSize parameter of the FileBuffer read methods.
FileBufferfileSize