42 lines
4.4 KiB
Markdown
42 lines
4.4 KiB
Markdown
## Why
|
||
|
||
The `drive` VFS already abstracts file operations behind a structural `DriveStorage` view, but there is no way to mount a compressed archive (zip, tar, gz, tgz, rar, 7z) as a drive. Users routinely receive bundles whose extension lies about the real compression (a `.zip` that is actually a 7z stream, a `.tar.gz` renamed `.bin`) or whose contents are split across multi-volume sets (`.part1.rar`/`.r00`–`.r99`, `.7z.001`–`.7z.NNN`, multi-file split-zip). Treating those archives as first-class drives lets every existing drive consumer (sharing, hydrate-from, file-operations, plugins) browse, read, and (where the format permits) write archive contents without ad-hoc extraction.
|
||
|
||
## What Changes
|
||
|
||
- Add a shared `@suaveplan/drive-storage-archive-core` package: format sniffing by magic bytes (extension is advisory only), split-volume reassembly, central-directory caching, password/encryption hook contract, and a streaming `EntryReader` abstraction so per-format adapters only implement the format-specific decode path.
|
||
- Add six per-format storage adapters, each implementing the `DriveStorage` contract over an underlying `AbstractStorage` (or raw byte source) holding the archive bytes:
|
||
- `@suaveplan/drive-storage-zip` — ZIP / ZIP64 / split-zip (`.z01`–`.zNN` + `.zip`), read-write with rewrite-on-flush.
|
||
- `@suaveplan/drive-storage-tar` — POSIX/USTAR/PAX, sparse files, long-name extensions; read-write (append + rewrite on delete).
|
||
- `@suaveplan/drive-storage-gz` — single-stream gzip wrapping one logical entry; read-write.
|
||
- `@suaveplan/drive-storage-tgz` — composition of `tar` over `gz` (and `.tar.bz2`, `.tar.xz`, `.tar.zst` via pluggable codec); read-mostly, write via full rewrite.
|
||
- `@suaveplan/drive-storage-rar` — RAR4 + RAR5 + multi-volume (`.partN.rar`, legacy `.r00`–`.r99`); **read-only** (writing RAR is patent-encumbered).
|
||
- `@suaveplan/drive-storage-7z` — 7z LZMA/LZMA2/BCJ filters + multi-volume (`.7z.001`–`.7z.NNN`); read-write via rewrite-on-flush.
|
||
- Public factory `openArchiveStorage(source, { format?, password?, splitParts?, mode? })` that auto-detects format from magic bytes, discovers split volumes through a sibling-resolver callback on the host storage, and returns a `DriveStorage` ready to hand to `new Drive(...)`.
|
||
- Mode flags: `read-only` | `copy-on-write` (in-memory overlay, materialise on `flush()`) | `rewrite` (write directly back through host storage on each mutation). RAR is locked to `read-only`.
|
||
- Error codes namespaced per package (`ARCHIVE_*`, `ZIP_*`, `TAR_*`, `GZ_*`, `RAR_*`, `SEVENZ_*`) registered in each package's error registry.
|
||
|
||
## Capabilities
|
||
|
||
### New Capabilities
|
||
|
||
- `drive-storage-archive-core`: shared format sniffing, split-volume reassembly, mode/flush contract, password hook, codec registry, error taxonomy, and conformance harness all per-format adapters run against.
|
||
- `drive-storage-zip`: ZIP/ZIP64/split-zip adapter exposing archive entries as a `DriveStorage`.
|
||
- `drive-storage-tar`: POSIX/USTAR/PAX tar adapter exposing tar entries as a `DriveStorage`.
|
||
- `drive-storage-gz`: single-entry gzip adapter exposing the wrapped stream as a `DriveStorage`.
|
||
- `drive-storage-tgz`: composed tar-over-codec adapter (gzip/bzip2/xz/zstd) exposing entries as a `DriveStorage`.
|
||
- `drive-storage-rar`: read-only RAR4/RAR5 + multi-volume adapter exposing rar entries as a `DriveStorage`.
|
||
- `drive-storage-7z`: 7z + multi-volume adapter exposing 7z entries as a `DriveStorage`.
|
||
|
||
### Modified Capabilities
|
||
|
||
_None — drive's `DriveStorage` view is already satisfied; no requirement changes to existing specs._
|
||
|
||
## Impact
|
||
|
||
- New packages under `packages/drive/drive-storage-{zip,tar,gz,tgz,rar,7z}` plus `packages/drive/drive-storage-archive-core` (seven total). All universal-tier where the codec is pure-TS, server-tier where native bindings are needed (RAR, optionally 7z LZMA SDK).
|
||
- New dependencies on pure-TS codec libraries via Bun catalog (`fflate` for deflate, `pako` fallback, `lzma-native` or wasm `lzma`, `xz-decompress`, `@zip.js/zip.js` is **not** used — we implement directly for streaming + split support).
|
||
- Drive consumers (`drive-sharing`, `drive-template`, `drive-react-sharing`) gain transparent archive browsing with no API changes.
|
||
- Bin: optional `suaveplan-archive` CLI in `drive-storage-archive-core` for listing/extracting any supported archive from the shell. (Decision deferred to design.md.)
|
||
- Test surface: `runArchiveConformance` harness in `drive-storage-archive-core/testing` exercised by all six adapters.
|