# 📄 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
```