mesh/docs/signaling_v_2.md

📄 signaling.md — Mesh Signaling & Connectivity (v2)

1. Objectif

Documenter :

• la signalisation WebRTC (média) via Mesh Server,
• la stratégie ICE/STUN/TURN,
• la stratégie data-plane QUIC (agents Rust) et ses contraintes réseau,
• les optimisations et diagnostics.

---

2. Architecture

• Control plane : Mesh Server (WS)
• Media plane : WebRTC (clients web)
• Data plane : QUIC P2P (agents Rust)

Le serveur ne transporte aucun flux média ou transfert lourd.

---

3. WebRTC (média) — ICE

STUN (obligatoire)

Découverte IP publique.

TURN (fallback)

Relais si P2P direct échoue.

Politique candidats :

1. host
2. srflx
3. relay

Recommandations :

• Ne pas forcer TURN
• Logguer quand relay est utilisé
• Credentials temporaires TURN (V1+)

---

4. WebRTC — séquence

1. Action (call/screen) demandée au serveur
2. Serveur valide ACL + émet cap_token
3. Échange SDP/ICE via WS (rtc.offer/answer/ice)
4. Flux média direct A↔B

---

5. QUIC P2P (data plane) — stratégie

• QUIC = TLS 1.3 natif + multiplexing streams
• Sessions orchestrées via p2p.session.request/created
• Connexion directe agent↔agent sur UDP

Contraintes réseau

• UDP sortant requis.
• Certains NAT/CGNAT peuvent compliquer la traversée.

Stratégie :

• privilégier LAN
• documenter l’ouverture/autorisation UDP côté WAN
• fallback exceptionnel : HTTP temporaire via serveur

---

6. Optimisations transferts

• chunks 64–256 KB
• backpressure
• reprise par offset
• hashing blake3 (chunk + final)

---

7. Sécurité

• Actions gated by capability token TTL court.
• QUIC : TLS 1.3.
• Terminal : preview-only par défaut, contrôle arbitré par serveur.

---

8. Diagnostics

Exposer :

• WebRTC : host/srflx/relay
• QUIC : latence, débit, pertes, retries
• erreurs : sessions refusées, tokens expirés

---

9. Changelog

0.1.0 – WebRTC signaling + ICE
0.2.0 – QUIC data-plane sessions (agent Rust)

---

Consignes de gestion du contexte et des fichiers CLAUDE.md (obligatoire)

Utilisation de plusieurs fichiers CLAUDE.md

• Utilisez **plus d’un fichier **`` dans le projet.
• Conservez un ``** général à la racine** du dépôt Mesh (vision globale, règles communes).
• Ajoutez des ``** spécifiques dans les sous-dossiers** (server/, agent/, client/, infra/, etc.) afin de fournir à Claude un contexte ciblé et local.
• Chaque fichier CLAUDE.md de sous-dossier doit compléter le fichier racine, sans le contredire.

Gestion de la fenêtre de contexte

Au fil d’une session longue, la fenêtre de contexte de Claude peut se saturer, entraînant une perte de précision ou l’oubli d’instructions importantes.

Pour éviter cela, appliquer systématiquement les pratiques suivantes :

1. Réinitialisation stratégique du contexte

• Utiliser régulièrement la commande :

  /clear
  

• En particulier :
  • entre deux tâches distinctes,
  • entre conception et implémentation,
  • entre implémentation et revue.

Cette commande efface l’historique courant et permet de repartir sur une ardoise vierge, en s’appuyant uniquement sur les fichiers CLAUDE.md pertinents.

2. Utilisation de sous-agents

Pour les flux de travail complexes ou multi-étapes, déléguer explicitement à des sous-agents.

Exemple :

« Tu viens d’écrire le code du partage de fichiers. Maintenant, utilise un sous-agent pour effectuer une revue de sécurité de ce code. »

Avantages :

• séparation claire des responsabilités,
• contexte dédié pour chaque analyse,
• réduction du bruit dans la conversation principale.

Principe fondamental

Le **contexte de référence du projet Mesh doit toujours être porté par les fichiers **``, et non par l’historique de la conversation. L’historique n’est qu’un support temporaire.

Ces consignes sont obligatoires pour toute utilisation de Claude dans le cadre du projet Mesh.