186 lines
4.6 KiB
Markdown
186 lines
4.6 KiB
Markdown
# 📄 agent.md — Mesh Agent (Rust pragmatique)
|
||
|
||
## 1. Description
|
||
**Mesh Agent** est un agent desktop multi-OS (Linux / Windows / macOS) conçu pour compléter Mesh (app web) avec des capacités locales avancées.
|
||
|
||
Objectifs :
|
||
- **Flux lourds P2P** (faible charge serveur)
|
||
- **Binaires multi-OS** simples à déployer
|
||
- Terminal/SSH partagé robuste
|
||
- Partage fichiers/dossiers performant
|
||
- Notifications directes Gotify
|
||
|
||
L’agent communique :
|
||
- avec le **Mesh Server** (REST + WebSocket) pour auth/permissions/signalisation,
|
||
- avec les **autres clients/agents** en **P2P** pour les flux data,
|
||
- avec **Gotify** pour les notifications.
|
||
|
||
---
|
||
|
||
## 2. Architecture (control plane vs data plane)
|
||
- **Control plane** : Mesh Server
|
||
- Auth
|
||
- Rooms & ACL
|
||
- Tokens de capacités (TTL court)
|
||
- Signalisation (WS)
|
||
- Événements + notifications Gotify
|
||
- **Data plane** : P2P
|
||
- Audio/Vidéo/Écran : WebRTC (côté client web)
|
||
- Fichiers/Dossiers/Terminal : P2P via **QUIC** (recommandé V1)
|
||
- fallback possible : WebRTC DataChannel (V2) ou HTTP temporaire (exception)
|
||
|
||
Le serveur ne transporte pas de média ni de transferts lourds.
|
||
|
||
---
|
||
|
||
## 3. Fonctions principales
|
||
### 3.1 Partage fichiers & dossiers (P2P)
|
||
- Envoi fichier : chunks + reprise + checksum
|
||
- Envoi dossier :
|
||
- mode simple : **zip à la volée**
|
||
- mode sync (optionnel) : watcher + manifest + diff
|
||
- Débit contrôlé + backpressure
|
||
|
||
### 3.2 Terminal / SSH share (preview + contrôle)
|
||
- L’agent lance une session locale via **PTY** (bash/pwsh) et peut lancer `ssh user@host`.
|
||
- Diffuse la sortie terminal en P2P.
|
||
- Modes :
|
||
- **preview (lecture seule)** par défaut
|
||
- **take control** (un seul contrôleur à la fois)
|
||
|
||
### 3.3 Notifications
|
||
- Envoi direct vers Gotify (agent → Gotify)
|
||
- Notifications OS locales (optionnel V1)
|
||
|
||
### 3.4 Intégration OS
|
||
- Tray icon (optionnel)
|
||
- Auto-start (optionnel)
|
||
- Identité machine : `device_id`
|
||
|
||
---
|
||
|
||
## 4. Stack technique (Rust)
|
||
### Runtime / réseau
|
||
- **Rust stable**
|
||
- **tokio** (async)
|
||
- **reqwest** (HTTP)
|
||
- **tokio-tungstenite** (WebSocket)
|
||
- **quinn** (QUIC P2P) — recommandé pour data plane (fichiers/terminal)
|
||
|
||
### Terminal
|
||
- Unix : **portable-pty** (ou equivalent) pour PTY
|
||
- Windows : **ConPTY** (crate dédiée / wrapper)
|
||
|
||
### FS / sync
|
||
- notify (watcher cross-platform)
|
||
- hashing (blake3 recommandé)
|
||
|
||
### Config / logs
|
||
- serde + toml/yaml
|
||
- tracing + tracing-subscriber
|
||
|
||
### Packaging
|
||
- binaire unique par OS
|
||
- install : MSI (Windows), deb/rpm (Linux), dmg/pkg (macOS) — V1/V2
|
||
|
||
---
|
||
|
||
## 5. Structure recommandée
|
||
```
|
||
agent/
|
||
Cargo.toml
|
||
src/
|
||
main.rs
|
||
config/
|
||
mod.rs
|
||
mesh/
|
||
rest.rs
|
||
ws.rs
|
||
types.rs
|
||
p2p/
|
||
mod.rs
|
||
quic/
|
||
endpoint.rs
|
||
protocol.rs
|
||
fallback_http/
|
||
mod.rs
|
||
share/
|
||
file_send.rs
|
||
folder_zip.rs
|
||
folder_sync/
|
||
manifest.rs
|
||
diff.rs
|
||
watcher.rs
|
||
terminal/
|
||
mod.rs
|
||
pty_unix.rs
|
||
conpty_windows.rs
|
||
stream.rs
|
||
notifications/
|
||
gotify.rs
|
||
router.rs
|
||
os/
|
||
autostart.rs
|
||
tray.rs
|
||
tests/
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Protocole & permissions
|
||
- Toutes les actions P2P sont autorisées par **capability tokens** (TTL court), émis par le serveur :
|
||
- `share:file`, `share:folder`, `terminal:view`, `terminal:control`
|
||
- Le P2P (QUIC) utilise un **handshake applicatif** :
|
||
- échange d’un token de session (issu du serveur)
|
||
- validation côté pair avant d’accepter un flux
|
||
|
||
---
|
||
|
||
## 7. Sécurité (résumé)
|
||
- Les secrets SSH ne sortent jamais de la machine partageuse.
|
||
- Terminal share : preview-only par défaut.
|
||
- Chiffrement transport : QUIC (TLS 1.3), WebSocket/TLS.
|
||
- Logs sans contenu sensible.
|
||
|
||
---
|
||
|
||
## 8. TODO
|
||
### MVP (priorité)
|
||
- [ ] Config + identité `device_id`
|
||
- [ ] Connexion WS au serveur (auth)
|
||
- [ ] Réception events (room, terminal, share)
|
||
- [ ] Notifications Gotify
|
||
- [ ] Terminal preview (PTY) + stream P2P (QUIC)
|
||
|
||
### V1
|
||
- [ ] Envoi fichier P2P (QUIC)
|
||
- [ ] Envoi dossier (zip) P2P
|
||
- [ ] Take control terminal (arbitrage via serveur)
|
||
- [ ] Diagnostics (mode P2P, erreurs, stats)
|
||
|
||
### V2
|
||
- [ ] Sync dossier (manifest/diff)
|
||
- [ ] Tray + autostart multi-OS
|
||
- [ ] Fallback HTTP serveur (temporaire) si P2P impossible
|
||
- [ ] WebRTC DataChannel agent (si besoin compat)
|
||
|
||
---
|
||
|
||
## 9. Améliorations futures
|
||
- `.meshignore`
|
||
- Diff binaire + dédup
|
||
- Chiffrement applicatif E2E optionnel
|
||
- Tunnel SSH (TCP-like) au-dessus de QUIC (avancé)
|
||
|
||
---
|
||
|
||
## 10. Changelog
|
||
```
|
||
0.1.0 – Rust agent skeleton (WS + Gotify)
|
||
0.2.0 – Terminal share preview (QUIC)
|
||
0.3.0 – File transfer (QUIC)
|
||
0.4.0 – Folder zip + take control
|
||
0.5.0 – Folder sync (beta)
|
||
```
|
||
|