mesh/NEXT_STEPS.md

Prochaines Étapes - Projet Mesh

Date: 2026-01-04 Phase Actuelle: Agent Rust ✅ COMPLET Phase Suivante: Serveur Python + Tests E2E

---

🎉 Où en sommes-nous ?

Composants Terminés

✅ Agent Rust (100%)

• WebSocket Client: Connexion serveur + event routing
• QUIC Endpoint: TLS 1.3 + P2P handshake
• File Transfer: Chunking 256KB + Blake3 hash
• Terminal Streaming: PTY cross-platform
• CLI: run, send-file, share-terminal
• Tests: 14/14 passants
• Documentation: README, E2E_TEST, STATUS

Binaire: agent/target/release/mesh-agent (4,8 MB)

✅ Infrastructure (100%)

• Docker Compose
• Pre-commit hooks
• VS Code snippets
• Documentation complète

🟡 Serveur Python (~40%)

• Structure projet ✅
• Configuration ✅
• Health check API ✅
• À faire: Auth JWT, WebSocket, DB, P2P API

🟡 Client React (~40%)

• Setup Vite + React ✅
• Thème Monokai ✅
• Routing ✅
• À faire: Auth UI, WebSocket, Chat, WebRTC

---

🎯 Prochaine Priorité: Serveur Python

Objectif

Implémenter le Control Plane (serveur) pour permettre les tests E2E avec l'agent.

Tâches Critiques

1. Base de Données & Modèles (4h)

Fichiers à créer:

• server/app/models/user.py
• server/app/models/room.py
• server/app/models/session.py
• server/alembic/versions/001_initial.py

Actions:

• Définir modèles SQLAlchemy (User, Room, P2PSession)
• Créer migrations Alembic
• Tester connexion PostgreSQL

Validation:

cd server
poetry run alembic upgrade head
poetry run python -c "from app.models import User; print('OK')"

2. Authentification JWT (4h)

Fichiers à créer:

• server/app/auth/jwt.py
• server/app/api/auth.py
• server/app/schemas/auth.py

Actions:

• Endpoints /api/auth/register et /api/auth/login
• Génération JWT avec PyJWT
• Password hashing avec bcrypt
• Middleware authentication

Validation:

curl -X POST http://localhost:8000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"test","password":"test123"}'

# Doit retourner: {"access_token": "...", "token_type": "bearer"}

3. WebSocket Connection Manager (6h)

Fichiers à créer:

• server/app/ws/manager.py
• server/app/ws/handlers/system.py
• server/app/ws/handlers/room.py
• server/app/ws/handlers/p2p.py

Actions:

• ConnectionManager pour tracking clients WebSocket
• Event routing par type (system., room., p2p.*)
• Handlers pour system.hello, room.join, p2p.session.request
• Broadcast messages aux membres d'une room

Validation:

# Terminal 1
cd server
poetry run uvicorn app.main:app --reload

# Terminal 2 - Test WebSocket
wscat -c "ws://localhost:8000/ws?token=<jwt_token>"
> {"type":"system.hello","device_id":"test-device"}
# Doit retourner: {"type":"system.welcome",...}

4. API P2P Session Creation (4h)

Fichiers à créer:

• server/app/api/p2p.py
• server/app/schemas/p2p.py
• server/app/services/p2p.py

Actions:

• Endpoint POST /api/p2p/sessions
• Génération session_token avec TTL (60-180s)
• Stockage session en DB avec expires_at
• Event p2p.session.created via WebSocket

Validation:

curl -X POST http://localhost:8000/api/p2p/sessions \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "file",
    "target_device_id": "device-b",
    "ttl": 120
  }'

# Doit retourner:
# {
#   "session_id": "abc123",
#   "session_token": "xyz789",
#   "expires_at": "2026-01-04T23:00:00Z",
#   "endpoints": {
#     "initiator": {"ip": "192.168.1.50", "port": 5000},
#     "target": {"ip": "192.168.1.100", "port": 5000}
#   }
# }

---

🧪 Tests E2E Agent ↔ Serveur

Scénario 1: Connexion Agent → Serveur

Prérequis:

• Serveur running avec WebSocket
• Agent compilé avec config valide

Test:

# Terminal 1 - Serveur
cd server
poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000

# Terminal 2 - Agent
cd agent
RUST_LOG=info ./target/release/mesh-agent run

Résultat attendu:

• Agent logs: WebSocket connected, Sent system.hello
• Serveur logs: WebSocket client connected, Event: system.hello
• Agent reçoit system.welcome

Scénario 2: P2P Session Creation

Test:

# Terminal 1 - Agent A (daemon)
cd agent
RUST_LOG=info ./target/release/mesh-agent run

# Terminal 2 - Create P2P session (via API ou Web UI)
curl -X POST http://localhost:8000/api/p2p/sessions \
  -H "Authorization: Bearer <jwt>" \
  -d '{"kind":"file","target_device_id":"device-a","ttl":120}'

# Observer Agent A logs
# Attendu: "P2P session created: session_id=..., expires_in=120"

Scénario 3: File Transfer E2E

Test:

# Terminal 1 - Agent A (daemon, récepteur)
RUST_LOG=info ./target/release/mesh-agent run

# Terminal 2 - Agent B (sender)
RUST_LOG=info ./target/release/mesh-agent send-file \
  --session-id "session_from_server" \
  --peer-addr "192.168.1.50:5000" \
  --token "token_from_server" \
  --file test.txt

Résultat attendu:

• Agent B: Connecting to peer..., P2P connection established, File sent successfully!
• Agent A: Incoming QUIC connection, P2P handshake successful, File received
• Hash Blake3 identique des deux côtés

---

📋 Checklist Phase Serveur

Base de Données

• Modèles SQLAlchemy (User, Room, P2PSession)
• Migrations Alembic
• Connexion PostgreSQL testée
• CRUD operations (create, read, update, delete)

Authentification

• Endpoint /api/auth/register
• Endpoint /api/auth/login
• JWT generation (access_token)
• Password hashing (bcrypt)
• Middleware auth pour routes protégées

WebSocket

• ConnectionManager (tracking clients)
• Event routing par type
• Handler system.hello → system.welcome
• Handler room.join → room.joined
• Handler p2p.session.request → p2p.session.created
• Broadcast messages dans rooms

API P2P

• Endpoint POST /api/p2p/sessions
• Génération session_token (JWT ou random)
• TTL management (expires_at)
• Event p2p.session.created via WebSocket
• Endpoint info (IP:port des peers)

Tests

• Tests unitaires (pytest)
• Tests integration (DB, WebSocket)
• Tests E2E (Agent ↔ Serveur)

---

📚 Documentation à Consulter

Pour Serveur Python

1. server/CLAUDE.md - Guidelines serveur
2. docs/protocol_events_v_2.md - Events WebSocket
3. docs/signaling_v_2.md - P2P signaling
4. docs/security.md - Modèle sécurité

Pour Agent (référence)

1. agent/README.md - Usage agent
2. agent/E2E_TEST.md - Scénarios tests
3. docs/AGENT.md - Architecture agent

---

🚀 Commandes Utiles

Serveur

# Installer dépendances
cd server
poetry install

# Migrations DB
poetry run alembic upgrade head

# Lancer serveur dev
poetry run uvicorn app.main:app --reload

# Tests
poetry run pytest

# Linter
poetry run ruff check .

Agent (rappel)

# Compiler
cd agent
cargo build --release

# Tests
cargo test

# Lancer daemon
RUST_LOG=info ./target/release/mesh-agent run

Docker Compose (full stack)

# Démarrer tous les services
docker-compose up -d

# Logs
docker-compose logs -f mesh-server
docker-compose logs -f postgres

# Arrêter
docker-compose down

---

⚠️ Points d'Attention

Intégration Agent ↔ Serveur

1. Event Format:

   • Serveur et Agent utilisent le même format JSON
   • Champs: type, id, timestamp, from, to, payload
   • Voir server/app/schemas/events.py et agent/src/mesh/types.rs

2. Session Token Lifecycle:

   Client Web → POST /api/p2p/sessions
      ↓
   Serveur → Génère session_token (TTL 60-180s)
      ↓
   Serveur → Event p2p.session.created via WebSocket
      ↓
   Agent → Cache token localement
      ↓
   Agent → Valide token lors P2P_HELLO
   

3. QUIC Endpoint Discovery:

   • Agent envoie son QUIC port au serveur (system.hello)
   • Serveur stocke IP:port dans DB
   • API P2P retourne endpoints des 2 peers
   • Agents se connectent directement (P2P)

4. Firewall/NAT:

   • Pour MVP: Tests LAN seulement
   • Production: STUN/TURN à implémenter
   • Port UDP QUIC doit être ouvert

---

🎯 Objectif Final MVP

Définition of Done:

• 2 utilisateurs peuvent s'authentifier
• Chat en temps réel fonctionne
• Appel audio/vidéo WebRTC établi
• Fichier transféré via Agent QUIC ← VALIDABLE DÈS SERVEUR PRÊT
• Terminal partagé en preview
• Notifications Gotify reçues

Timeline Estimée:

• Serveur Python: 2-3 semaines
• Client React: 2-3 semaines
• Tests E2E & Debug: 1 semaine
• Total MVP: 5-7 semaines

---

📞 Rappel Workflow

1. Avant de commencer:

   • Lire CLAUDE.md du composant
   • Choisir tâche dans TODO.md
   • Utiliser /clear si changement de contexte

2. Pendant développement:

   • Itérations courtes (1-2h max)
   • Headers de traçabilité sur fichiers
   • Commentaires en français
   • Commits fréquents

3. Après implémentation:

   • Tester (unit + integration)
   • Mettre à jour DEVELOPMENT.md
   • Mettre à jour TODO.md
   • Documenter dans STATUS.md

---

Principe Fondamental:

La vérité du projet Mesh est dans les fichiers. La conversation n'est qu'un outil temporaire.

---

Dernière mise à jour: 2026-01-04 Prochaine action: Implémenter Serveur Python (Phase 1: Base de Données & Modèles)