first

2026-01-05 13:13:08 +01:00
parent 8e14adafc6
commit 1d177e96a6
149 changed files with 29541 additions and 1 deletions
@@ -0,0 +1,144 @@
+# 📄 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
+```
+