Evaluate replacing miniz with a more modern zip library

[andiwand]

Every zip we read or write goes through miniz
(miniz/3.0.2, conanfile.py). It works, but it is a C library with a 1990s
API, and the whole of src/odr/internal/zip/ (~700 lines) exists to paper over
that. Worth evaluating whether a more modern library — ideally a C++ one — buys
us a smaller wrapper, better errors, and the zip features we currently do not
support.

What miniz costs us today

• Everything is a bool. mz_zip_writer_init, append_file,
  finalize_archive, writer_end each return true/false, so
  ZipArchive::save (src/odr/internal/zip/zip_archive.cpp:82) is a ladder of
  if (!state) throw MinizSaveError(archive), where the error has to be fished
  back out of the archive struct afterwards. That leaked far enough that
  odr/exceptions.hpp:63 — a public header — documents
  internal::zip::MinizSaveError, and zip_exceptions.hpp includes
  <miniz.h> to hold an mz_zip_error.
• No thread safety, so we serialise everything. util::Archive carries a
  mutable std::mutex and every single operation — is_file, path,
  method, size, opening a stream, and each 4 KiB underflow — takes it
  (zip_util.cpp:36-141). Two entries of the same document can never be read
  in parallel, which is exactly the thing we would want when rendering gets
  parallelised.
• Streaming reads are hand-rolled and lossy on error. ReaderBuffer wraps
  mz_zip_reader_extract_iter_* in a std::streambuf, and because miniz
  reports a failed inflate as a short read, zip_util.cpp:44 has to treat
  result == 0 as EOF — a corrupt entry silently truncates instead of
  throwing.
• Writing needs a seekable sink and a magic flag. save has to keep a
  WriteSink with a base offset because miniz addresses output by absolute
  offset and rewrites local headers; ZipArchive::save's contract is therefore
  "out has to be seekable" (zip_archive.hpp:29). And fix(zip): write an entry's size into its local header #755 was exactly the
  kind of bug this invites: without MZ_ZIP_FLAG_WRITE_HEADER_SET_SIZE the
  size only lands in a trailing data descriptor and LibreOffice rejects the
  file.
• Round-tripping loses compression settings. ZipArchive's ctor can only
  recover "stored" vs "deflate", and guesses level 6 for the latter
  (zip_archive.cpp:48), because that is all mz_zip_archive_file_stat gives
  back.
• No zip64, no encrypted entries. Encrypted entries are detected and
  rejected (zip_util.cpp:100). Fine today — ODF/OOXML encryption is handled
  above us in odf_crypto.cpp / ooxml_file.cpp — but it means WinZip-AES
  archives opened as plain zips are simply unreadable.
• We test the dependency itself. test/src/internal/zip/miniz_test.cpp
  drives raw mz_zip_* calls, which is a fair sign of how little the library
  gives us on its own.

Also relevant: #312 (SIGSEGV in zip_util.cpp, still open, no repro) and #762
(memory blowup) both live in this neighbourhood.

The blast radius is small

miniz is used only inside src/odr/internal/zip/ — nothing else in the
tree calls mz_* or uses its raw deflate. Outside consumers touch only
ZipFile / ZipArchive / abstract::Archive
(open_strategy.cpp, odf_crypto.cpp, odf_document.cpp,
ooxml_file.cpp, ooxml_text_document.cpp). So a swap is: the 8 files under
src/odr/internal/zip/, one line in conanfile.py, two in CMakeLists.txt,
and miniz_test.cpp disappears. zip_archive_test.cpp is API-level and should
pass unchanged.

What a replacement must actually do

Non-negotiable, because ODF/OOXML break otherwise:

1. Read from a custom source. Our input is an abstract::File (memory or
   disk), consumed through a std::istream and a read callback
   (zip_util.cpp:203). No "give me a path" -only API.
2. Per-entry streaming reads, not "inflate the whole entry into a buffer" —
   see A 1.4 MB ods grows past 1.2 GB in Html::translate and the OS kills the app #762.
3. Preserve central-directory order (we pass
   MZ_ZIP_FLAG_DO_NOT_SORT_CENTRAL_DIRECTORY): ODF requires mimetype first
   and stored.
4. Per-entry method and level on write, with the uncompressed size in the
   local header (the fix(zip): write an entry's size into its local header #755 fix).
5. Builds everywhere we ship: linux/macos/windows, android, ios, and
   wasm/emscripten — the last one has killed dependencies for us before.
   Conan Center recipe strongly preferred.

Nice to have: concurrent entry reads, zip64, WinZip-AES, exceptions or
expected-style errors instead of bool, RAII instead of
mz_zip_end in a destructor, and a non-seekable write path.

Candidates

Available on Conan Center today:

• libzip/1.11.4 — C, mature, actively maintained, zip64 + AES,
  zip_source covers requirement 1 cleanly, good error reporting. Still C, so
  we would keep a wrapper — but a much thinner one.
• libzippp/7.1-1.10.1 — C++ wrapper over libzip. Closest thing to "a
  modern C++ zip library" that is packaged; needs a look at whether its API
  reaches libzip's custom sources and streaming, or only the convenient subset.
• minizip-ng/4.2.1 — C, actively maintained, zip64, AES, zstd/lzma,
  callback IO. Feature-rich; API is still very C.
• libarchive/3.8.7 — C, broadest format support (would also cover
  reading other containers). Heavier, and its streaming model is a poor fit for
  the random-access reads we do into a zip.

Not packaged / probably out: bit7z (no Conan Center recipe, needs the 7-Zip
shared library), kuba--/zip (a thin wrapper over miniz — no gain),
miniz-cpp and ZipLib (unmaintained).

Proposal

1. Prototype against libzip and libzippp behind the existing
   abstract::Archive / ZipFile interfaces — the interfaces are already the
   right seam, so this is a drop-in experiment, not a refactor.
2. Check requirement 5 first (wasm + android + ios builds), it is the cheapest
   way to eliminate a candidate.
3. Compare on: wrapper size, whether the mutex can go away, error quality, and
   round-trip fidelity against LibreOffice (soffice --convert-to on a saved
   package).
4. Keep miniz if nothing clears the bar — "it works and it is small" is a
   legitimate outcome. But the current wrapper's list of workarounds suggests
   there is something better.

[andiwand]

Evaluated all the candidates. Conclusion: we stay on miniz for now. Details below,
including three claims in the issue body that do not survive a closer look.

Three of the seven complaints do not hold

• "No zip64." Wrong — miniz has zip64 for both read and write, with an automatic
  switch, plus MZ_ZIP_FLAG_WRITE_ZIP64 to force it and mz_zip_is_zip64() to detect it
  (miniz_zip.h:99, :278-280).

• "Round-tripping loses compression settings." Not a miniz limitation. The ZIP format
  does not record the deflate level — only a 2-bit hint in the general-purpose bit flags.
  No library recovers it; libzip does not even expose those bits for reading. Guessing 6
  in zip_archive.cpp:48 is the only thing anyone can do.

• "No thread safety, so we serialise everything." Switching would make this worse.
  libzip's own documentation says
  different zip_t objects are independent but a single one needs external
  synchronisation, and recommends opening the archive once per thread. miniz is the only
  candidate that is structurally concurrent-read-capable:
  mz_zip_reader_extract_iter_new heap-allocates per-iterator state and all I/O goes
  through a stateless, pread-shaped m_pRead(opaque, absolute_offset, buf, n).

  What actually serialises us is our own callback — one shared std::istream driven by
  seekg/read (zip_util.cpp:203). That is fixable in place, and refactor(zip): make the archive's read callback re-entrant #775 does it.

What does survive

Real, and all of it about write-side ergonomics and error reporting: the bool ladder
in ZipArchive::save, MinizSaveError leaking into the public odr/exceptions.hpp:63,
zip_exceptions.hpp including <miniz.h> for an mz_zip_error, and underflow having
to treat a failed inflate as EOF (zip_util.cpp:44) because miniz reports it as a short
read. Plus the one genuine capability gap: miniz has no encryption at all, so
WinZip-AES entries are unreadable. Upstream is explicit about this ("No support for
encrypted archives").

None of that is worth a dependency swap today. If AES-encrypted entries ever become a
requirement, that is the forcing function, and the answer is libzip.

The candidates

Requirements 1-4 were checked against sources, not documentation.

	custom source	streaming read	CD order kept	size in local header	zip64	AES
miniz 3.1.x	✅ m_pRead	✅ extract_iter	✅ DO_NOT_SORT	⚠️ only via add_read_buf_callback	✅	❌ none
libzip 1.11.4	✅ zip_source_function	✅ zip_fopen_index/zip_fread	✅ (no sort in zip_open.c)	✅ by default	✅	✅
minizip-ng 4.2.1	✅ mz_stream vtable	✅	✅	✅ opt-in	✅	✅
libarchive 3.8.7	✅	✅	❌	❌ impossible	✅	✅
libzippp 7.1	⚠️ pass-through only	⚠️ push-only	✅	⚠️	✅	✅

libzip is the upgrade path when we need one. zip_close.c:add_data() opens with an
unconditional de->bitflags &= ~ZIP_GPBF_DATA_DESCRIPTOR; and then seeks back to rewrite
the local header with the real sizes — sizes in the local header are the default, not a
flag you can forget, so #755 could not recur. Maintenance is the best of the set: both
original authors still active, 123 commits in the last 12 months, 26 years old,
distribution-critical.

But it would not shrink the wrapper. A libzip read source needs eight
zip_source_function commands (OPEN/READ/CLOSE/STAT/ERROR/FREE/SEEK/TELL)
and a seekable write source another six, against miniz's two function pointers. The trade
is boilerplate for correctness, not less code.

libarchive is disqualified as a ZIP backend, twice over:

• Its writer sets ZIP_ENTRY_FLAG_LENGTH_AT_END unconditionally — the comment in
  archive_write_set_format_zip.c reads "We may know the size, but never the CRC." —
  which makes the local-header-size branch dead code. That is fix(zip): write an entry's size into its local header #755, permanently, with no
  flag to fix it.
• Its seekable ZIP reader keys entries on an RB-tree of local-header offset, so it
  returns them in the wrong order (archive_read_support_format_zip.c:4595-4607), and
  there is no archive_read_seek_header in the public API.

libzippp is the only packaged C++ option and the weakest thing on the list: 8 commits
in 12 months from one person, last release February 2024, Conan recipe pinned a full minor
behind at libzip 1.10.1. It also does not reach what is hard — fromSource takes a
zip_source* you must build yourself with the C API, and readEntry is push-only
(std::ostream or a callback), with no pull-based reader. With std::istream-shaped
entries we would end up calling zip_fopen_index/zip_fread through getZipHandle()
anyway.

minizip-ng is capable and roughly equivalent to libzip on paper, but has a thinner
maintainer base and a messier dependency and CMake story.

No credible modern C++ ZIP library exists. kuba--/zip is C over miniz, Zipios is
LGPL, and the rest are single-maintainer miniz wrappers with no adoption. src/odr/internal/zip/
is the C++20 wrapper, and it stays ours.

Requirement 5: every candidate built for emscripten

Built against .github/config/conan/profiles/emscripten-wasm (emcc 3.1.73, single
threaded, -fwasm-exceptions), build profile apple-macos-armv8:

	wasm build	wasm .a	notes
miniz 3.1.1	✅	100 K	zero dependencies
libzip 1.11.4	✅	171 K	only with with_bzip2/lzma/zstd=False, crypto=False; defaults pull in openssl
minizip-ng 4.2.1	✅	117 K	defaults pull in openssl and libiconv
libzippp 7.1	✅	43 K	on top of libzip 1.10.1
libarchive 3.8.7	❌ → ✅	1.05 M	fails out of the box (locale_charset undeclared); needs with_iconv=False

So requirement 5 does not eliminate anyone outright, but miniz's zero dependencies keep
cross-building a non-event across all eight profiles, and everything else adds a crypto
backend to a graph that currently has none. Note that conan-center produces no binaries
for Emscripten, Android or iOS, and none of the upstream projects CI-test any of those
three — so with a non-miniz choice we own that risk entirely.

Also found: our miniz pin is stale in a way that matters

miniz/3.0.2 has been dropped from conan-center-index's config.yml (only 3.0.1
and 3.1.1 remain). The published revision still resolves, so nothing is broken, but the
pin receives no further recipe revisions. Bumping regardless of this evaluation: #774.

And the premise that miniz is abandoned is out of date. It was dormant from 3.0.2
(January 2023) to 3.1.0 (September 2025), which is where that reputation comes from, but
maintenance has passed to @uroni and it has shipped 3.1.0, 3.1.1 and 3.1.2 since — with
real fixes (central-directory offset overflow, a tinfl_decompress infinite-loop guard)
and new fuzz targets. It is thin — roughly 15 commits a year, bus factor 1 — but alive.

On also supporting more archive formats

Worth separating, because the synergy is smaller than it looks. There are two different
jobs here:

A. Container for a document (ODF/OOXML/iWork). Needs random access, lazy per-entry
streams, and byte-exact write control. This is only ever ZIP. A general-purpose archive
library buys nothing and its streaming model actively hurts.

B. The archive as the thing being viewed — FileType::zip, FileCategory::archive,
rendered by html/filesystem.cpp. Adding rar/7z/tar.gz here is a real feature, and the
seam is already right: implement abstract::ArchiveFile + Archive::as_filesystem(),
materialise once through common/temporary_file, and the HTML listing comes free.
Single-pass sequential is exactly libarchive's model and exactly what this role wants.

For B the answer is libarchive: it reads 7z, rar, rar5, cab, iso9660, lha and tar with
gzip/xz/zstd/lz4/bzip2 filters, and — decisively — its RAR and 7z readers are clean-room
BSD, not unrar code, so we get RAR reading with no licence contamination against MPL-2.0.
bit7z is out: no wasm, no conan recipe, bus factor 1, and it runtime-loads an LGPL
7z.dll carrying the unRAR field-of-use restriction, which is a non-starter on iOS.

The cost is concrete and needs its own decision: 1.05 M of wasm objects against a current
2.9 M bundle. That is a conversation about whether B ships to the web viewer at all or is
gated to the mobile apps.

None of this argues for changing the ZIP backend — libarchive would be an additional,
read-only path alongside it, not a replacement.

What happens now

1. Stay on miniz.
2. Bump the pin to miniz/3.1.1 — build(deps): bump miniz to 3.1.1 #774.
3. Fix the read callback so the archive-wide mutex stops serialising entry reads — refactor(zip): make the archive's read callback re-entrant #775.
   This is the concurrency win the issue wanted, and no dependency swap delivers it.
4. Revisit if AES-encrypted entries become a requirement. Then it is libzip, and the spike
   to budget is the wasm/iOS/android builds with crypto=False, not the API work.