162 lines
3.9 KiB
Markdown
162 lines
3.9 KiB
Markdown
# 📄 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.
|
||
|