29 lines
2.9 KiB
Markdown
29 lines
2.9 KiB
Markdown
# Architecture
|
|
|
|
Archive Tools is a relocatable static React application. It has no backend, persistence, telemetry or runtime network dependency.
|
|
|
|
## Layers
|
|
|
|
- `src/archive/paths.ts` owns cross-platform path assessment and collision keys. It rejects traversal, absolute/drive/UNC paths, controls, ambiguous segments, Windows devices, alternate streams and excessive depth/length.
|
|
- `src/archive/zip.ts` uses exactly pinned `@zip.js/zip.js` for ZIP/ZIP64 inventory, CRC-checked reads and deterministic writing. Listing uses bounded entry iteration. Content reads request strict local/central-header agreement, CRC-32 validation and overlapping-entry checks.
|
|
- `src/archive/tar.ts` is a checked-offset TAR/USTAR/PAX reader and deterministic writer. Every header checksum is validated. PAX metadata is capped before UTF-8 decoding.
|
|
- `src/archive/gzip.ts` streams compressed input through fflate in small chunks, stops at the expanded-byte ceiling and independently checks the single-member CRC-32 and ISIZE footer. Concatenated members are unsupported.
|
|
- `src/archive/service.ts` detects formats, applies aggregate policies and exposes inspection, reading, safe repackaging, creation and reports.
|
|
- `src/archive/preview.ts` recognizes only bounded plain text, bytes and static raster images. Nested archives are never recursively expanded.
|
|
- `src/archive/compare.ts` compares normalized inventories without interpreting content.
|
|
- `src/components/workspaces` contains React views. Imported text is rendered through React text nodes; there is no `dangerouslySetInnerHTML`.
|
|
|
|
## Data flow
|
|
|
|
Inspection checks the source size and format before parsing. ZIP inventory reads only archive metadata. TAR and gzip inputs are held in memory only after the source ceiling is satisfied and gzip expansion is stopped at its output ceiling. TAR/gzip payloads remain in the current React document solely to support later previews and selection; replacing the document releases those references.
|
|
|
|
Preview and extraction never write source paths to the local filesystem. A selected entry is decoded into a bounded in-memory buffer, verified, and passed to a new deterministic ZIP writer using its already-assessed normalized path.
|
|
|
|
## Determinism
|
|
|
|
Creation sorts normalized paths by code-unit order. ZIP uses zip.js's bundled DEFLATE implementation at level 6 with native compression streams and workers disabled, fixed DOS dates, normalized regular-file modes, no extended timestamps and no data descriptors. TAR uses zero timestamps/IDs, regular mode `0644`, USTAR when possible and deterministic PAX path headers otherwise. gzip uses level 6 and mtime zero.
|
|
|
|
## Memory model
|
|
|
|
The parser refuses unsafe declared sizes before entry decompression. A bounded writable collects ZIP output and stops when actual output crosses the operation ceiling. gzip is pushed in 32 KiB source chunks and output is counted before retention. Creation and TAR parsing are deliberately capped because they currently use in-memory output/payloads.
|