Voor remote client agent
This commit is contained in:
kodi
@@ -0,0 +1,338 @@
|
||||
# Remote Client Shares Implementation Phases V1.1
|
||||
|
||||
## Doel
|
||||
|
||||
Dit document splitst `REMOTE_CLIENT_SHARES_V1_DESIGN.md` op in pragmatische implementatiefases.
|
||||
|
||||
Uitgangspunten:
|
||||
|
||||
- geen overengineering
|
||||
- elke fase moet zelfstandig waarde leveren
|
||||
- WebManager mag nooit blokkeren op remote agents
|
||||
- bestaande storage-functionaliteit moet intact blijven
|
||||
- `/Clients` blijft een aparte source, geen uitbreiding van lokale filesystem roots
|
||||
|
||||
---
|
||||
|
||||
## Overzicht
|
||||
|
||||
### Phase 1
|
||||
|
||||
Client registry, identiteit en statusmodel.
|
||||
|
||||
### Phase 2
|
||||
|
||||
Browse van remote client shares via virtuele `Clients` root.
|
||||
|
||||
### Phase 3
|
||||
|
||||
Info, tekstpreview, eenvoudige image preview en download voor remote shares.
|
||||
|
||||
### Later
|
||||
|
||||
Alle write-acties, bookmarks/startup paths en cross-source flows.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Client Registry
|
||||
|
||||
## Doel
|
||||
|
||||
WebManager moet remote agents kennen, identificeren en hun status betrouwbaar kunnen bijhouden.
|
||||
|
||||
## Resultaat
|
||||
|
||||
De backend en UI kunnen een lijst van bekende clients tonen, inclusief stabiele identiteit en basisstatus.
|
||||
|
||||
## In scope
|
||||
|
||||
- remote client registratie
|
||||
- heartbeat endpoint
|
||||
- opslag van client metadata
|
||||
- statusmodel met gescheiden velden
|
||||
- lijstendpoint voor bekende clients
|
||||
- registratie-auth
|
||||
- agent-access-auth contract vastleggen
|
||||
|
||||
## Niet in scope
|
||||
|
||||
- browsen in shares
|
||||
- file operations
|
||||
- download
|
||||
- rename/delete/mkdir
|
||||
|
||||
## Beslissingen
|
||||
|
||||
- `client_id` is leidend
|
||||
- `display_name` is niet leidend
|
||||
- browse-routing mag niet afhankelijk zijn van alleen displaynaam
|
||||
- `last_seen`, `status`, `last_error` en `reachable_at` blijven logisch gescheiden
|
||||
|
||||
## Backendwerk
|
||||
|
||||
Nieuwe onderdelen:
|
||||
|
||||
- repository voor remote clients
|
||||
- service voor registratie en heartbeat
|
||||
- statusafleiding
|
||||
- opslag van auth- en endpointmetadata
|
||||
- routes:
|
||||
- `POST /api/clients/register`
|
||||
- `POST /api/clients/heartbeat`
|
||||
- `GET /api/clients`
|
||||
|
||||
Waarschijnlijk te wijzigen:
|
||||
|
||||
- [main.py](/workspace/webmanager-mvp/webui/backend/app/main.py)
|
||||
- [dependencies.py](/workspace/webmanager-mvp/webui/backend/app/dependencies.py)
|
||||
|
||||
Waarschijnlijk nieuw:
|
||||
|
||||
- `webui/backend/app/api/routes_clients.py`
|
||||
- `webui/backend/app/services/remote_client_service.py`
|
||||
- `webui/backend/app/db/remote_client_repository.py`
|
||||
|
||||
## Agentwerk
|
||||
|
||||
- vaste config inlezen
|
||||
- `client_id` beheren
|
||||
- registratie naar WebManager
|
||||
- periodieke heartbeat
|
||||
- agent-access-token config toevoegen
|
||||
|
||||
## UI-werk
|
||||
|
||||
Minimaal:
|
||||
|
||||
- geen browse-integratie nodig
|
||||
- een eenvoudige clientlijst of debug-status is voldoende
|
||||
|
||||
## Acceptatiecriteria
|
||||
|
||||
- agent kan zich registreren
|
||||
- client verschijnt in `GET /api/clients`
|
||||
- `last_seen` wordt bijgewerkt
|
||||
- `status` wordt afgeleid zonder te flappen
|
||||
- `last_error` en `reachable_at` bestaan als apart concept
|
||||
- server blijft normaal werken als er geen agents bestaan
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Browse via `/Clients`
|
||||
|
||||
## Doel
|
||||
|
||||
Remote clients en hun shares moeten zichtbaar worden in dezelfde browse-ervaring als server storage, zonder lokale services te vervormen.
|
||||
|
||||
## Resultaat
|
||||
|
||||
De gebruiker kan navigeren naar:
|
||||
|
||||
- `/Clients`
|
||||
- `/Clients/<client>`
|
||||
- `/Clients/<client>/<share>`
|
||||
|
||||
## In scope
|
||||
|
||||
- virtuele root `/Clients`
|
||||
- clientlijst als directories
|
||||
- sharelijst per client als directories
|
||||
- browse binnen share
|
||||
- offline foutafhandeling
|
||||
- agent-auth op browsecalls
|
||||
|
||||
## Niet in scope
|
||||
|
||||
- view/download
|
||||
- edit
|
||||
- rename/delete/mkdir
|
||||
- bookmarks/startup paths
|
||||
|
||||
## Beslissingen
|
||||
|
||||
- `/Clients` wordt vroeg in de backend-route afgehandeld
|
||||
- remote paden mogen niet in gewone lokale `PathGuard` resolution terechtkomen
|
||||
- lokale browse-services blijven verantwoordelijk voor alleen lokale server sources
|
||||
|
||||
## Backendwerk
|
||||
|
||||
Waarschijnlijk te wijzigen:
|
||||
|
||||
- [routes_browse.py](/workspace/webmanager-mvp/webui/backend/app/api/routes_browse.py)
|
||||
|
||||
Liever niet verbreden:
|
||||
|
||||
- [path_guard.py](/workspace/webmanager-mvp/webui/backend/app/security/path_guard.py)
|
||||
|
||||
Nieuwe onderdelen:
|
||||
|
||||
- browse-facade voor remote client paden
|
||||
- agent HTTP client met korte timeouts en auth
|
||||
|
||||
## UI-werk
|
||||
|
||||
Waarschijnlijk te wijzigen:
|
||||
|
||||
- [app.js](/workspace/webmanager-mvp/webui/html/app.js)
|
||||
|
||||
Benodigd:
|
||||
|
||||
- rootnavigatie voor `/Clients`
|
||||
- breadcrumbs voor client/share-paden
|
||||
- render van client/status/share directories
|
||||
- nette foutmelding bij offline client
|
||||
|
||||
## Agentwerk
|
||||
|
||||
Nieuwe browse endpoint(s):
|
||||
|
||||
- `GET /health`
|
||||
- `GET /api/list?share=...&path=...`
|
||||
|
||||
## Acceptatiecriteria
|
||||
|
||||
- `/Clients` toont bekende clients
|
||||
- `/Clients/<client>` toont alleen toegestane shares
|
||||
- `/Clients/<client>/<share>` toont directory-inhoud
|
||||
- offline client geeft een snelle fout, geen hang
|
||||
- `/Volumes` gedrag blijft intact
|
||||
- lokale browse-code blijft logisch gescheiden van remote browse-code
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: Info, Preview, Download
|
||||
|
||||
## Doel
|
||||
|
||||
Remote shares moeten read-only bruikbaar worden voor dagelijkse taken.
|
||||
|
||||
## Resultaat
|
||||
|
||||
Gebruiker kan bestanden in remote shares inspecteren, bekijken en downloaden.
|
||||
|
||||
## In scope
|
||||
|
||||
- file info
|
||||
- tekstpreview
|
||||
- eenvoudige image preview
|
||||
- download van remote bestanden
|
||||
- expliciete resource-limieten
|
||||
|
||||
## Niet in scope
|
||||
|
||||
- edit
|
||||
- rename/delete/mkdir
|
||||
- upload
|
||||
- cross-source copy/move
|
||||
|
||||
## Beslissingen
|
||||
|
||||
- tekstpreview krijgt een harde limiet
|
||||
- text/binary-detectie moet expliciet zijn
|
||||
- downloads worden gestreamd
|
||||
- geen grote in-memory buffering voor download
|
||||
|
||||
## Backendwerk
|
||||
|
||||
Nieuwe facade of routes voor remote file actions:
|
||||
|
||||
- info
|
||||
- read/view
|
||||
- download
|
||||
|
||||
Belangrijk:
|
||||
|
||||
- backend vertaalt WebManager-pad naar agent-call
|
||||
- timeouts en foutmapping blijven streng
|
||||
- source-aware afhandeling blijft gescheiden van lokale file ops
|
||||
|
||||
Waarschijnlijk geraakt:
|
||||
|
||||
- `routes_files.py` of parallelle remote-fileroute
|
||||
- aparte service-laag voor remote file proxying
|
||||
|
||||
## UI-werk
|
||||
|
||||
Waarschijnlijk te wijzigen:
|
||||
|
||||
- [app.js](/workspace/webmanager-mvp/webui/html/app.js)
|
||||
|
||||
Benodigd:
|
||||
|
||||
- source-aware afhandeling voor `View`
|
||||
- downloadknop moet remote paths ondersteunen
|
||||
- properties/info moet ook werken voor remote paden
|
||||
|
||||
## Agentwerk
|
||||
|
||||
Nieuwe endpoints:
|
||||
|
||||
- `GET /api/info`
|
||||
- `GET /api/read`
|
||||
- `GET /api/download`
|
||||
|
||||
## Acceptatiecriteria
|
||||
|
||||
- file info werkt voor remote paden
|
||||
- tekstbestand kan bekeken worden binnen limieten
|
||||
- afbeelding kan bekeken worden als ondersteund
|
||||
- download van remote bestand werkt via streaming
|
||||
- foutafhandeling blijft lokaal tot betreffende pane/actie
|
||||
|
||||
---
|
||||
|
||||
## Later
|
||||
|
||||
Deze onderdelen horen niet in V1.1.
|
||||
|
||||
### Write-acties
|
||||
|
||||
- mkdir
|
||||
- rename
|
||||
- delete
|
||||
- upload
|
||||
|
||||
### UI-integraties
|
||||
|
||||
- bookmarks voor `/Clients/...`
|
||||
- startup paths voor `/Clients/...`
|
||||
|
||||
### Cross-source flows
|
||||
|
||||
- `/Volumes/...` naar `/Clients/...`
|
||||
- `/Clients/...` naar `/Volumes/...`
|
||||
|
||||
Dit vereist expliciete transfersemantiek en hoort niet in de eerste read-mostly release.
|
||||
|
||||
### Zwaardere netwerkmodellen
|
||||
|
||||
- reverse-connect
|
||||
- tunnelmodel
|
||||
- relay-infrastructuur
|
||||
|
||||
### Sterkere pairing
|
||||
|
||||
- pair codes
|
||||
- per-agent secret rotation
|
||||
- signed registration
|
||||
|
||||
---
|
||||
|
||||
## Aanbevolen volgorde
|
||||
|
||||
1. Phase 1 volledig afronden.
|
||||
2. Daarna Phase 2 volledig afronden.
|
||||
3. Daarna Phase 3 read-only afronden.
|
||||
4. Alles daarna alleen oppakken als een concrete productbehoefte dat rechtvaardigt.
|
||||
|
||||
---
|
||||
|
||||
## Beslisadvies
|
||||
|
||||
Als er snel waarde geleverd moet worden, is de beste minimale keten:
|
||||
|
||||
1. registry
|
||||
2. browse
|
||||
3. info/preview/download
|
||||
|
||||
Daarmee ontstaat een bruikbare remote client bron zonder write-complexiteit, contractbreuk in lokale services of half-afgewerkte transferlogica.
|
||||
Reference in New Issue
Block a user