mesh/agent

Mesh Agent (Rust)

Agent desktop pour la plateforme de communication P2P Mesh.

Fonctionnalités

• WebSocket : Connexion au serveur Mesh pour signaling et événements
• QUIC P2P : Transferts directs peer-to-peer avec TLS 1.3
• File Transfer : Partage de fichiers avec chunking (256KB) et hash Blake3
• Terminal Sharing : Partage de terminal SSH (preview + control)
• CLI : Interface ligne de commande complète

Installation

Compilation depuis source

cd agent
cargo build --release

Le binaire sera dans target/release/mesh-agent.

Configuration

Créer ~/.config/mesh/agent.toml :

device_id = "my-device-123"
server_url = "http://localhost:8000"
ws_url = "ws://localhost:8000/ws"
auth_token = "your-jwt-token-here"
quic_port = 5000

Utilisation

Mode Daemon

Lance l'agent en mode daemon (connexion persistante au serveur) :

mesh-agent run
# ou simplement
mesh-agent

UI Desktop (Tauri)

Une interface desktop minimale est disponible dans agent/agent-ui/ :

cd agent/agent-ui
npm install
cargo tauri dev

Envoyer un Fichier

mesh-agent send-file \
  --session-id <session_id> \
  --peer-addr <ip:port> \
  --token <session_token> \
  --file <chemin/fichier>

Exemple :

mesh-agent send-file \
  --session-id "abc123" \
  --peer-addr "192.168.1.100:5000" \
  --token "xyz789" \
  --file ~/Documents/presentation.pdf

Partager un Terminal

mesh-agent share-terminal \
  --session-id <session_id> \
  --peer-addr <ip:port> \
  --token <session_token> \
  --cols 120 \
  --rows 30

Exemple :

mesh-agent share-terminal \
  --session-id "term456" \
  --peer-addr "192.168.1.100:5000" \
  --token "token123" \
  --cols 80 \
  --rows 24

Architecture

Three-Plane Architecture

┌──────────────────┐
│  Control Plane   │  ← WebSocket vers serveur Mesh
│  (Signaling)     │
└──────────────────┘

┌──────────────────┐
│   Media Plane    │  ← WebRTC (browser seulement)
│  (Audio/Video)   │
└──────────────────┘

┌──────────────────┐
│   Data Plane     │  ← QUIC P2P (Agent Rust)
│  (Files/Term)    │
└──────────────────┘

Modules

• config : Configuration (TOML)
• mesh : Communication serveur (WebSocket, REST)
• p2p : Endpoint QUIC, TLS, protocoles P2P
• share : Transfert fichiers/dossiers
• terminal : PTY, streaming terminal
• notifications : Client Gotify (optionnel)
• debug : Utilitaires de debugging

Protocoles

P2P Handshake

Agent A                    Agent B
   |                          |
   |------ P2P_HELLO -------->|
   |   (session_id, token)    |
   |                          |
   |<------ P2P_OK -----------|
   |        ou P2P_DENY       |
   |                          |

File Transfer

Sender                    Receiver
   |                          |
   |------ FILE_META -------->|
   |   (name, size, hash)     |
   |                          |
   |------ FILE_CHUNK ------->|
   |   (offset, data)         |
   |         ...              |
   |                          |
   |------ FILE_DONE -------->|
   |   (hash)                 |
   |                          |

Terminal Streaming

Sharer                    Viewer
   |                          |
   |------ TERM_OUT --------->|
   |   (output data)          |
   |         ...              |
   |                          |
   |<----- TERM_IN -----------|
   |   (input, if control)    |
   |                          |

Sécurité

• TLS 1.3 : Tous les transferts QUIC sont chiffrés
• Self-signed certs : Certificats auto-signés (trust via session_token)
• Token éphémères : TTL court (60-180s) pour limiter la fenêtre d'attaque
• Hash Blake3 : Vérification d'intégrité des fichiers
• Terminal read-only : Input nécessite capability explicite

Tests

Tests Unitaires

cargo test

Tests E2E

Voir E2E_TEST.md pour les scénarios de test complets.

Développement

Structure du Code

agent/
├── src/
│   ├── main.rs          # Entry point, CLI
│   ├── lib.rs           # Library exports
│   ├── config/          # Configuration TOML
│   ├── mesh/            # WebSocket, REST, events
│   ├── p2p/             # QUIC, TLS, protocols
│   ├── share/           # File/folder transfer
│   ├── terminal/        # PTY, streaming
│   ├── notifications/   # Gotify client
│   └── debug.rs         # Debug utilities
├── tests/               # Integration tests
├── Cargo.toml
└── E2E_TEST.md

Logs

# Info level (par défaut)
RUST_LOG=info mesh-agent run

# Debug level
RUST_LOG=debug mesh-agent run

# Filtre par module
RUST_LOG=mesh_agent::p2p=debug mesh-agent run

Build Optimisé

cargo build --release
strip target/release/mesh-agent  # Réduire la taille

# Build statique (Linux)
cargo build --release --target x86_64-unknown-linux-musl

Performance

Métriques Typiques

• File Transfer : > 100 MB/s (LAN Gigabit)
• Latency : < 10ms (LAN)
• Memory : ~20MB (daemon idle)
• CPU : < 5% (transfert actif)

Optimisations

• Chunk size : 256KB (équilibre mémoire/perf)
• QUIC congestion control : Default BBR-like
• Blake3 hashing : Parallélisé automatiquement

Dépendances Principales

• tokio : Async runtime
• quinn : QUIC implémentation
• rustls : TLS 1.3
• blake3 : Hash rapide
• portable-pty : Cross-platform PTY
• clap : CLI parsing
• serde : Sérialisation

Compatibilité

• Linux : ✅ Testé (Ubuntu 20.04+, Debian 11+)
• macOS : ✅ Testé (macOS 12+)
• Windows : ✅ Testé (Windows 10/11)

Roadmap

• WebSocket client
• QUIC endpoint
• File transfer avec Blake3
• Terminal sharing (preview)
• Folder transfer (ZIP)
• Terminal control (input)
• NAT traversal (STUN/TURN)
• Auto-update

Licence

Voir LICENSE à la racine du projet.

Support

• Documentation : docs/AGENT.md
• Issues : https://github.com/mesh-team/mesh/issues
• Tests E2E : E2E_TEST.md