Mount Archive Export#

The Mount Archive Export feature provides a POST /mounts/files/export endpoint that streams a ZIP archive of all files within one or more mounts. It was introduced as part of the drive UI refactor 1 and hardened across two follow-up PRs 2 3.

Key source files:

• Router / handler: api/oss/src/apis/fastapi/mounts/router.py — export_mount_files() handler 3
• Streaming utilities: api/oss/src/apis/fastapi/mounts/utils.py — stream_mounts_archive(), iter_archive_members(), zip-slip helpers, _content_disposition_attachment() 2
• Service layer: api/oss/src/core/mounts/service.py — build_archive_work_list() 2
• DTOs: api/oss/src/core/mounts/dtos.py — MountArchiveSource 3
• Object store: api/oss/src/core/store/storage.py — ObjectStore.get_object(), list_objects_page() 2
• Acceptance tests: api/oss/tests/pytest/acceptance/mounts/test_mounts_basics.py — TestMountArchiveExport 4
• Unit tests: api/oss/tests/pytest/unit/test_mounts_file_ops.py — zip-slip, mtime regression, archive work-list tests 2 4

Request Shape#

The endpoint accepts a list of MountArchiveSource objects, each specifying 3:

An optional filename query parameter controls the Content-Disposition attachment name. The route was renamed from POST /files/archive to POST /files/export to eliminate a naming collision with the mount "archive" lifecycle verb (soft-delete) that shared the same router prefix 3.

Eager Precomputation Before Streaming#

Previously the endpoint returned HTTP 200 and began streaming before validating mounts, causing truncated or empty ZIPs on errors. The fix separates work-list building from streaming 2:

1. build_archive_work_list() — called eagerly before StreamingResponse is constructed. It resolves each MountArchiveSource, validates that the mount exists (raises 404 if not), builds the full list of (zip_entry_name, store_key) pairs, and pre-filters unsafe zip-slip paths. Errors raised here produce correct HTTP status codes (404/503).

2. iter_archive_members(work) — receives the precomputed work list and performs bounded-concurrency object-store reads, keeping up to _ARCHIVE_READ_CONCURRENCY in-flight reads in a deque while yielding members to the stream_zip library.

Object-Store-Backed Streaming#

Each file entry is fetched from the object store via ObjectStore.get_object() and yielded as a streaming chunk sequence to stream_zip. A known performance issue exists: get_object() currently opens a fresh aiohttp.ClientSession per call, creating a new TCP/TLS connection for each file. Against a remote S3 endpoint with 5,000-file mounts at 8-way concurrency, this results in ~47 seconds of pure TLS handshake overhead. Issue #5414 tracks the fix: hold one long-lived session on the ObjectStore class and reuse it across calls 5. The cost is negligible for the bundled local SeaweedFS instance.

A separate mtime conversion bug was found and regression-tested: StoreObject.mtime is stored in epoch milliseconds, but datetime.fromtimestamp() expects seconds. Passing raw ms values causes ValueError after the 200 headers are already sent, producing a silently broken ZIP 4.

Zip-Slip Prevention#

The zip-slip mitigations live in utils.py 3:

• _zip_segments(path) — splits on both / and \ (backslash is treated as a separator by Windows extractors)
• _has_unsafe_zip_segment(segments) — flags empty, ., or .. segments
• _safe_zip_segments(path) — returns only the safe segments

Entries with .. or backslash traversal in their store key are skipped with a warning log rather than rewritten. Rewriting (e.g., turning a/../report.txt → a/report.txt) risks silently overwriting a legitimate a/report.txt entry that may also be in the archive 3.

The POST /mounts/files/export endpoint also validates source_path inputs using validate_file_path(), returning HTTP 422 for paths like ../evil before archive construction begins 4.

Content-Disposition Hardening & Path Validation#

_content_disposition_attachment() produces a dual-format header to handle non-ASCII archive names 3:

• ASCII fallback (filename=...): stripped to printable latin-1-safe characters, preventing HTTP 500 errors for CJK or emoji filenames
• RFC 5987 encoding (filename*=UTF-8''...): carries the exact percent-encoded filename for clients that support it

validate_file_path() (used for source_path inputs) uses a denylist approach: it rejects only absolute paths, empty/./.. segments, NUL bytes, and control characters—accepting real-world names like Next.js route groups (app/(auth)/[slug]), npm scopes (@scope/pkg), and non-ASCII characters 3.