184 lines
4.6 KiB
Markdown
184 lines
4.6 KiB
Markdown
# 📄 claude.md — Mesh (spécification générale, Rust pragmatique)
|
||
|
||
## 1. Description
|
||
**Mesh** est une application de communication pour petites équipes (2 à 4 personnes), **self-hosted**, optimisée pour :
|
||
- **faible charge serveur** (control plane uniquement),
|
||
- **flux directs P2P** (média + data),
|
||
- sécurité via autorisations centralisées,
|
||
- notifications via **Gotify**.
|
||
|
||
Fonctionnalités :
|
||
- chat,
|
||
- audio / vidéo,
|
||
- partage d’écran,
|
||
- partage fichiers & dossiers,
|
||
- partage de terminal (session SSH “preview” + contrôle),
|
||
- notifications (serveur + client/agent → Gotify).
|
||
|
||
---
|
||
|
||
## 2. Architecture globale
|
||
Séparation stricte :
|
||
- **Control plane** : Mesh Server (Python)
|
||
- **Media/Data plane** : P2P
|
||
|
||
```
|
||
┌──────────────┐
|
||
│ Gotify │
|
||
└──────▲───────┘
|
||
│
|
||
events/notify (server+agent)
|
||
│
|
||
Client Web ── P2P (WebRTC RTP) ── Client Web
|
||
│ \ / │
|
||
│ \ / │
|
||
│ \— P2P (QUIC data) ——--/ │
|
||
│ (agent↔agent) │
|
||
└────────── WS (signaling) ─────────┘
|
||
Mesh Server
|
||
```
|
||
|
||
- Audio/Vidéo/Écran : **WebRTC** (navigateurs)
|
||
- Fichiers/Dossiers/Terminal : **P2P data**
|
||
- recommandé V1 : **QUIC (TLS 1.3)** via Agent Rust (agent↔agent, agent↔client si support)
|
||
- option V2 : WebRTC DataChannel (si besoin d’unifier)
|
||
- fallback exceptionnel : HTTP temporaire via serveur
|
||
|
||
---
|
||
|
||
## 3. Stack technique (pragmatique)
|
||
### Serveur (Python)
|
||
- Python 3.12+
|
||
- FastAPI
|
||
- WebSocket `/ws` (signalisation + events)
|
||
- JWT (auth)
|
||
- Capabilities tokens TTL court
|
||
- SQLite (MVP), PostgreSQL (V1)
|
||
- Adapter notifications : Gotify
|
||
- Déploiement : Docker
|
||
|
||
### Client (Web)
|
||
- Vite + React + TypeScript (ou équivalent)
|
||
- WebRTC (call/screen)
|
||
- UI terminal : xterm.js
|
||
|
||
### Agent (Rust)
|
||
- tokio + reqwest + tokio-tungstenite
|
||
- QUIC P2P : quinn
|
||
- Terminal : portable-pty / ConPTY
|
||
- FS watcher : notify
|
||
- Logs : tracing
|
||
|
||
---
|
||
|
||
## 4. Rôles & responsabilités
|
||
### Mesh Server (control plane)
|
||
- Auth / sessions
|
||
- Rooms (2–4) + ACL
|
||
- Émission de capability tokens (TTL court)
|
||
- Signalisation WebRTC (offer/answer/ice)
|
||
- Arbitrage contrôle terminal (“take control”)
|
||
- Event bus + notifications Gotify
|
||
|
||
### Clients (web)
|
||
- UI + WebRTC call/screen
|
||
- Chat
|
||
- Signaling WS
|
||
- Terminal viewer
|
||
|
||
### Agents (Rust)
|
||
- Terminal share (PTY + stream)
|
||
- Partage fichiers/dossiers P2P
|
||
- Sync dossiers (optionnel)
|
||
- Notifications Gotify
|
||
|
||
---
|
||
|
||
## 5. Structure du dépôt
|
||
```
|
||
mesh/
|
||
server/
|
||
client/
|
||
agent/
|
||
infra/
|
||
docs/
|
||
```
|
||
|
||
Docs attendus :
|
||
- `protocol-events.md`
|
||
- `signaling.md`
|
||
- `security.md`
|
||
- `deployment.md`
|
||
|
||
---
|
||
|
||
## 6. Règles de permissions (capabilities)
|
||
Le serveur émet des tokens de capacités (TTL 60–180 s), scoppés :
|
||
- `room_id`
|
||
- `peer_id` / `device_id`
|
||
- `caps[]` ex: `call`, `screen`, `share:file`, `share:folder`, `terminal:view`, `terminal:control`
|
||
- option : `target_peer_id`, `max_size`, `max_rate`
|
||
|
||
Règles :
|
||
- aucune session P2P ne démarre sans token valide.
|
||
- terminal : `terminal:view` pour recevoir, `terminal:control` pour envoyer input.
|
||
|
||
---
|
||
|
||
## 7. Étapes du projet (roadmap)
|
||
### Phase 1 — Fondation (MVP control plane)
|
||
- [ ] Server skeleton FastAPI (auth/rooms/ws)
|
||
- [ ] Protocole events & signalling (WS)
|
||
- [ ] Capabilities tokens + validation
|
||
- [ ] Adapter Gotify (server)
|
||
|
||
### Phase 2 — Communication (Web)
|
||
- [ ] Chat (MVP)
|
||
- [ ] WebRTC audio/vidéo P2P
|
||
- [ ] Screen share P2P
|
||
|
||
### Phase 3 — Agent Rust (data plane)
|
||
- [ ] Agent Rust skeleton (WS + config + Gotify)
|
||
- [ ] Terminal share preview (PTY → P2P QUIC)
|
||
- [ ] Take control (arbitrage via serveur)
|
||
|
||
### Phase 4 — Partage data
|
||
- [ ] File transfer P2P (QUIC)
|
||
- [ ] Folder zip P2P
|
||
- [ ] Fallback HTTP (exception)
|
||
|
||
### Phase 5 — Sync & polish
|
||
- [ ] Folder sync (manifest/diff + conflits)
|
||
- [ ] Packaging multi-OS (MSI/deb/dmg)
|
||
- [ ] Monitoring minimal + diagnostics
|
||
|
||
---
|
||
|
||
## 8. TODO global
|
||
- [ ] RBAC simple (owner/member/guest)
|
||
- [ ] Quotas (taille, débit)
|
||
- [ ] Préférences notifications (par room / par event)
|
||
- [ ] Journaux & rotation
|
||
- [ ] Tests d’intégration (WS + tokens)
|
||
|
||
---
|
||
|
||
## 9. Améliorations futures
|
||
- Mobile native
|
||
- Federation Mesh↔Mesh
|
||
- Plugin system
|
||
- E2E applicatif optionnel
|
||
- TCP-like tunneling au-dessus de QUIC (SSH tunnel)
|
||
|
||
---
|
||
|
||
## 10. Changelog
|
||
```
|
||
0.1.0 – Architecture validée (Python server + Rust agent)
|
||
0.2.0 – MVP WebRTC (call/screen)
|
||
0.3.0 – Agent terminal preview (QUIC)
|
||
0.4.0 – File/folder transfer (QUIC)
|
||
0.5.0 – Folder sync (beta)
|
||
```
|
||
|