4.6 KiB
4.6 KiB
📄 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)