webmanager-mvp/project_docs/DIRECTORY_MOVE_V1_DESIGN.md

DIRECTORY_MOVE_V1_DESIGN.md

1. Scope

Doel van Directory Move v1 is om directory-verplaatsing toe te voegen binnen het bestaande move/task/securitymodel, zonder het huidige veiligheidsniveau of de voorspelbaarheid van de backend te verzwakken.

In scope voor v1:

• directory move als expliciete uitbreiding van de bestaande move-operatie
• task-based uitvoering
• conflictcontrole op destination
• beveiligde padvalidatie via bestaand path_guard
• duidelijke foutstatussen bij ongeldige of gevaarlijke moves

Out of scope voor v1:

• geen rollbackmechanisme
• geen cancel/retry
• geen gedeeltelijke recovery van half-voltooide cross-root moves
• geen symlink-following buiten whitelist
• geen speciale merge- of overwrite-semantiek
• geen multi-select directory move als aparte batch-semantiek buiten bestaande sequentiële task-aanmaak

---

2. Same-root versus cross-root

Directory move binnen dezelfde root

Dit is de veiligste en simpelste stap.

Kenmerken:

• kan meestal native via rename()/move op directoryniveau
• snel en atomair binnen hetzelfde filesystem/root
• geen inhoudelijke recursieve file copy nodig
• veel minder kans op partial failure

Directory move tussen verschillende roots

Dit is aanzienlijk complexer.

Kenmerken:

• vereist recursieve copy van directory tree
• daarna delete van source tree
• progressmeting en foutafhandeling worden lastiger
• partial failure is realistischer
• rollback is ingewikkeld en in v1 ongewenst

Aanbevolen scopekeuze

Aanbevolen v1:

• alleen same-root directory move ondersteunen
• cross-root directory move nog niet ondersteunen

Reden:

• sluit goed aan op bestaand taskmodel zonder grote complexiteitsexplosie
• beperkt regressierisico
• voorkomt een half-robuste recursieve copy+delete-implementatie zonder rollback

---

3. Semantiek

Wanneer is het een echte move

Directory move is van toepassing als:

• source een directory is
• destination een volledig doelpad is
• destination nog niet bestaat

Binnen same-root:

• de operatie gebruikt native rename/move op directoryniveau
• dit geldt zowel voor verplaatsen naar andere parent als voor directory move binnen dezelfde root met andere naam

Destination bestaat al

Gedrag v1:

• destination mag niet bestaan
• response: already_exists

Geen merge in v1.

Nested destinations

Verboden gevallen:

• source naar een child van zichzelf
• source naar een pad in eigen subtree

Voorbeeld:

• source: /Volumes/8TB/Shows
• destination: /Volumes/8TB/Shows/Archive/Shows

Dit moet direct geblokkeerd worden.

Aanbevolen fout:

• invalid_request met duidelijke boodschap zoals Destination cannot be inside source

Verplaatsen van map in zichzelf

Ook verboden:

• destination exact gelijk aan source
• destination onder source subtree

Dit moet vóór task-creatie worden afgewezen.

---

4. Taskmodel

Directory move blijft task-based, ook voor same-root moves.

Progressmeting

Voor same-root native directory move is echte byte-progress meestal niet beschikbaar.

Aanbevolen v1:

• gebruik vooral done_items / total_items
• voor same-root kan dat minimaal zijn:
  • total_items = 1
  • done_items = 0 -> 1
• done_bytes / total_bytes mogen null blijven in v1 voor same-root directory move

Fail-fast gedrag

Aanbevolen v1:

• fail-fast
• zodra de move-operatie faalt, task -> failed

Partial failure

Voor same-root native directory move is partial failure veel minder waarschijnlijk.

• of de rename slaagt
• of de rename faalt

Dus v1-model:

• geen expliciete partial-successstatus
• eindstatus blijft:
  • completed
  • failed

Rollback

Geen rollback in v1.

Voor same-root native rename is dat meestal niet nodig. Voor cross-root zou rollback wel relevant worden, maar die scope wordt niet aanbevolen voor v1.

---

5. Security

Symlinkgedrag in directory trees

Aanbevolen v1-beleid:

• source directory zelf mag geen symlink zijn
• bij same-root native rename wordt de tree niet recursief gevolgd of gekopieerd, dus child-symlinks hoeven niet actief gevolgd te worden voor uitvoering
• toch blijft containmentcontrole op source en destination verplicht

Traversal en containment

• bron- en destination-pad blijven via bestaand path_guard
• destination binnen whitelist verplicht
• destination mag niet buiten root escapen
• nested destination-in-source moet expliciet extra gevalideerd worden

PathGuard-impact

Bestaand path_guard blijft basis voor:

• whitelistvalidatie
• traversalblokkade
• symlink containment check op bron/destination-resolutie

Aanvullend nodig voor directory move:

• helper of servicecheck om te bepalen of destination in subtree van source ligt

Escapes buiten whitelist voorkomen

Bij same-root-only v1:

• containment blijft relatief eenvoudig
• geen recursieve copy over child nodes nodig
• dus ook minder attack surface dan cross-root recursieve tree copy

---

6. Backend-impact

Waarschijnlijk te wijzigen delen:

• webui/backend/app/services/move_task_service.py
• webui/backend/app/tasks_runner.py
• webui/backend/app/fs/filesystem_adapter.py
• mogelijk webui/backend/app/api/schemas.py alleen als taskdetail-documentatie wordt aangescherpt
• mogelijk kleine aanvulling in path_guard.py of move-service validatiehelpers

Bestaande move-logica die hergebruikt kan worden

Herbruikbaar:

• task-creatie
• repository-persistency
• statusflow queued -> running -> completed/failed
• destination-exists checks
• parent directory validation
• algemene error mapping

Nieuw voor directory move:

• source typecheck moet directory toestaan in same-root-case
• same-root task runner moet directory rename kunnen uitvoeren
• nested-destination-validatie

Rename binnen zelfde parent blijft apart

Ja.

Aanbevolen scheiding:

• rename endpoint blijft aparte, directe single-path operatie
• move blijft task-based voor echte moves
• ook als een same-root directory move technisch op rename lijkt, blijft het semantisch onderdeel van move

Dat houdt UI- en API-rollen duidelijk.

---

7. UI-impact

Move-knop en F6 bij exact 1 directory

Aanbevolen gedrag:

• F6 / Move-knop blijven dezelfde popupflow gebruiken
• exact 1 directory geselecteerd:
  • zelfde parent + andere naam -> huidige rename route blijft toegestaan
  • andere parent binnen dezelfde root -> task-based directory move toegestaan in v1
  • cross-root destination -> blokkeren met duidelijke melding, bijvoorbeeld:
    • Cross-root directory move is not supported in v1

Multi-select met directories

Aanbevolen v1:

• geen gemengde halfslimme batchflow
• als multi-select directories bevat:
  • alleen toestaan als alle geselecteerde directories voldoen aan same-root move-semantiek, of
  • eenvoudiger en veiliger voor v1: nog blokkeren met duidelijke melding

Aanbevolen eerste stap:

• multi-select met directories nog blokkeren
• melding:
  • Batch directory move is not supported in v1

Reden:

• beperkt scope en regressierisico
• houdt UI-flow voorspelbaar

---

8. Teststrategie

Golden tests

Toe te voegen voor move-API:

• same-root directory move success
• directory destination exists -> already_exists
• directory source not found
• directory source is symlink -> blokkade
• nested destination blocked
• exact same source/destination blocked
• cross-root directory move blocked

Regressietests

• file move success same-root blijft werken
• file move success cross-root blijft werken als huidige scope dat al ondersteunt
• rename endpoint blijft ongewijzigd
• browse en delete blijven ongewijzigd

Securitytests

• traversal source
• traversal destination
• symlink source rejection
• destination inside source rejection
• destination outside whitelist rejection

Runtime edge cases

• rename/move van lege directory
• rename/move van directory met inhoud binnen same-root
• permission failure -> io_error
• destination parent ontbreekt -> bestaande foutmapping

---

9. Aanbeveling

Aanbevolen v1-richting:

• alleen same-root directory move ondersteunen
• cross-root directory move nog niet ondersteunen

Korte motivatie:

• laagste complexiteit
• beste aansluiting op bestaand taskmodel
• minimale partial-failure kans
• veel kleiner regressie- en securityrisico dan recursieve cross-root tree copy+delete

Praktische v1-scope:

• exact 1 directory
• same-root move task-based
• nested destination geblokkeerd
• destination exists geblokkeerd
• cross-root directory move expliciet geweigerd
• batch directory move nog niet

Dat is de veiligste eerste stap met duidelijke semantiek en goede testbaarheid.