mesh/docs/signaling.md

📄 signaling.md — Mesh WebRTC Signaling & ICE Strategy

1. Objectif

Ce document décrit la signalisation WebRTC, la stratégie ICE / STUN / TURN, et les règles d’optimisation des flux pour Mesh.

Objectifs :

• Connexions client ↔ client directes par défaut
• Charge serveur minimale
• Fallback robuste (NAT strict)
• Sécurité et contrôle centralisé

---

2. Rappels d’architecture

• Control plane : Mesh Server (WebSocket)
• Media/Data plane : WebRTC P2P
• Le serveur ne transporte aucun flux média ou fichier

Client A  ── P2P (RTP/DataChannel) ── Client B
    │               ▲
    └────── WS ─────┘
         Mesh Server

---

3. WebRTC : rôles

• Offerer : initiateur du flux (call/share/file/terminal)
• Answerer : pair cible
• Signaling server : Mesh Server (WS JSON)

---

4. ICE configuration

STUN (obligatoire)

Utilisé pour la découverte d’IP publiques.

Exemples :

• stun:stun.l.google.com:19302
• stun:stun.mesh.local:3478

TURN (fallback)

Utilisé uniquement si le P2P direct échoue.

• Recommandé : coturn
• Transport : UDP en priorité, TCP en fallback

turn:turn.mesh.local:3478?transport=udp
turn:turn.mesh.local:3478?transport=tcp

Authentification :

• Credentials temporaires (REST API TURN)
• TTL court

---

5. Politique ICE Mesh

Priorité des candidats :

1. host
2. srflx (STUN)
3. relay (TURN)

Règles :

• Ne jamais forcer TURN
• Logguer si relay utilisé (diagnostic)

---

6. Séquence de signalisation (exemple : partage écran)

1. Client A → Server : screen.share.request
2. Server : vérifie droits + émet capability token
3. Server → Client B : screen.share.granted
4. A ↔ Server ↔ B : échange SDP (offer/answer)
5. A ↔ Server ↔ B : ICE candidates
6. A ↔ B : flux P2P direct

---

7. DataChannel (fichiers, terminal)

Paramètres recommandés

• ordered: true
• maxPacketLifeTime: null
• maxRetransmits: null

Sous-canaux logiques

• file-transfer
• folder-sync
• terminal-stream
• terminal-input

---

8. Optimisations performance

• Chunking (64–256 KB)
• Backpressure (bufferedAmount)
• Pause/reprise
• Hash par chunk

---

9. Fallback HTTP (exceptionnel)

Si WebRTC impossible :

• Upload temporaire serveur
• URL signée + expiration
• Nettoyage automatique

---

10. Sécurité

• DTLS / SRTP natif WebRTC
• Capability token requis avant offer
• Vérification fingerprint SDP
• TTL court TURN

---

11. Diagnostics

Expose localement :

• mode ICE utilisé (host/srflx/relay)
• latence RTT
• débit moyen
• pertes

---

12. TODO

• ICE restarts
• QUIC (WebTransport)
• TCP-over-DataChannel
• Priorisation flux (media > data)

---

13. Changelog

0.1.0 – Base signaling + ICE
0.2.0 – DataChannel optimisation