kodi
88 lines
2.3 KiB
Markdown
88 lines
2.3 KiB
Markdown
# BACKEND_V1_CONSOLIDATION.md
|
|
|
|
## Doel
|
|
Consolidatie van de huidige backend v1 contracten en beperkingen.
|
|
|
|
## Huidige endpoints
|
|
|
|
Directe endpoints (geen task-creatie):
|
|
- `GET /api/browse`
|
|
- `POST /api/files/mkdir`
|
|
- `POST /api/files/rename`
|
|
- `POST /api/files/delete`
|
|
- `GET /api/tasks`
|
|
- `GET /api/tasks/{task_id}`
|
|
|
|
Task-based create endpoints:
|
|
- `POST /api/files/copy`
|
|
- `POST /api/files/move`
|
|
|
|
## Semantiek per endpoint
|
|
|
|
### `GET /api/browse`
|
|
- Browse van een directory binnen whitelist roots.
|
|
- Hidden files standaard verborgen, optioneel via `show_hidden=true`.
|
|
|
|
### `POST /api/files/mkdir`
|
|
- Maakt directory op exact `parent_path + name`.
|
|
- Geen impliciete pad-normalisatie buiten `path_guard` validatie.
|
|
|
|
### `POST /api/files/rename`
|
|
- Hernoemt binnen dezelfde parent directory.
|
|
- Geen verborgen move naar andere map.
|
|
|
|
### `POST /api/files/delete`
|
|
- Verwijdert file direct.
|
|
- Verwijdert alleen lege directory.
|
|
- Non-empty directory => conflict.
|
|
|
|
### `POST /api/files/copy`
|
|
- File-only copy.
|
|
- `destination` is volledig doelpad (geen "copy into directory").
|
|
- Task wordt aangemaakt (`202`, `task_id`, `queued`) en daarna uitgevoerd.
|
|
|
|
### `POST /api/files/move`
|
|
- File-only move.
|
|
- `destination` is volledig doelpad.
|
|
- Task wordt aangemaakt (`202`, `task_id`, `queued`) en daarna uitgevoerd.
|
|
- Same-root: native move.
|
|
- Cross-root: copy + delete binnen dezelfde task.
|
|
|
|
### `GET /api/tasks`
|
|
- Lijst van tasks, gesorteerd op `created_at DESC`.
|
|
- Item bevat minimaal: `id`, `operation`, `status`, `source`, `destination`, `created_at`, `finished_at`.
|
|
|
|
### `GET /api/tasks/{task_id}`
|
|
- Detailstatus inclusief progress/foutvelden.
|
|
- Statusset: `queued`, `running`, `completed`, `failed`.
|
|
|
|
## Foutmodel per endpointgroep
|
|
|
|
### Browse/file-validatie
|
|
- `invalid_request`
|
|
- `path_traversal_detected`
|
|
- `path_outside_whitelist`
|
|
- `invalid_root_alias`
|
|
- `path_not_found`
|
|
- `type_conflict`
|
|
- `already_exists`
|
|
- `directory_not_empty` (delete)
|
|
|
|
### Task create runtime
|
|
- validatiefouten vóór task-creatie: directe API-fout, geen task
|
|
- runtime-fouten tijdens task-uitvoering: task naar `failed` met `io_error`
|
|
|
|
### Tasks read
|
|
- `task_not_found` bij onbekend task id
|
|
|
|
## Expliciete v1-beperkingen
|
|
|
|
- copy: file-only
|
|
- move: file-only
|
|
- delete: alleen file + lege directory
|
|
- geen recursive delete
|
|
- geen directory copy/move
|
|
- geen rollback
|
|
- geen cancel/retry
|
|
- geen batch-operaties
|