Import parser + validator + POST /api/import/preview (dry-run) #317

New issue

Open

opened 2026-06-28 00:17:44 +00:00 by james · 0 comments

james commented

2026-06-28 00:17:44 +00:00

Owner

Child of #286 (import preview — second slice).

Upload an export archive and return a dry-run summary without writing anything.

Scope

POST /api/import/preview (multipart upload) → dry-run summary JSON: counts per entity, format version, and what each mode (Replace / Merge-by-UUID / Import-as-copies) would do to the current account. Stateless — the client keeps the file; no server-side staging.
Archive parser + validator: gunzip + untar, parse each YAML doc, validate format version (formatVersion: 1), per-file zod schemas, referential integrity (cross-file UUID references resolve), media presence (referenced media/* entries exist).
Safety guards: tar path-traversal / zip-slip rejection, archive + per-entry size limits, content-type limits (reuse blob-storage validation where it applies).
RFC 7807 Problem Details for validation failures; auth required, user-scoped.
Both-engine where DB-touching (the preview itself is read-only, but shares parser/validator with ticket 3).

Depends on the export archive format from ticket 1 / the ADR.

Child of #286 (import preview — second slice). Upload an export archive and return a dry-run summary without writing anything. ## Scope - `POST /api/import/preview` (multipart upload) → dry-run summary JSON: counts per entity, format version, and what **each mode** (Replace / Merge-by-UUID / Import-as-copies) would do to the current account. Stateless — the client keeps the file; no server-side staging. - Archive parser + validator: gunzip + untar, parse each YAML doc, validate format version (`formatVersion: 1`), per-file zod schemas, referential integrity (cross-file UUID references resolve), media presence (referenced `media/*` entries exist). - Safety guards: tar path-traversal / zip-slip rejection, archive + per-entry size limits, content-type limits (reuse blob-storage validation where it applies). - RFC 7807 Problem Details for validation failures; auth required, user-scoped. - Both-engine where DB-touching (the preview itself is read-only, but shares parser/validator with ticket 3). Depends on the export archive format from ticket 1 / the ADR.

james referenced this issue

2026-06-28 00:32:44 +00:00

feat(api): export user domain data as a tar.gz archive #322