224 lines
4.4 KiB
Markdown
224 lines
4.4 KiB
Markdown
# 📄 protocol-events.md — Mesh Event & Signaling Protocol (v2, Rust pragmatique)
|
||
|
||
## 1. Objectif
|
||
Ce document définit le protocole d’événements Mesh pour :
|
||
- signalisation WebRTC (média),
|
||
- orchestration des connexions P2P (data),
|
||
- autorisations (capabilities),
|
||
- notifications Gotify.
|
||
|
||
Séparation :
|
||
- **Control plane** : Mesh Server (REST + WebSocket)
|
||
- **Media plane** : WebRTC (clients web)
|
||
- **Data plane** : QUIC P2P (agents Rust)
|
||
|
||
---
|
||
|
||
## 2. Transports
|
||
- **WSS** : Client/Agent ↔ Mesh Server
|
||
- **WebRTC** : audio/vidéo/écran (client ↔ client)
|
||
- **QUIC (TLS 1.3)** : fichiers/dossiers/terminal (agent ↔ agent)
|
||
|
||
---
|
||
|
||
## 3. Format WS
|
||
```json
|
||
{
|
||
"type": "event.type",
|
||
"id": "uuid",
|
||
"timestamp": "ISO-8601",
|
||
"from": "peer_id|device_id|server",
|
||
"to": "peer_id|device_id|room_id|server",
|
||
"payload": {}
|
||
}
|
||
```
|
||
Payload recommandé : `room_id`, `target_peer_id`, `target_device_id`, `cap_token`, `session_id`.
|
||
|
||
---
|
||
|
||
## 4. Identités
|
||
- `user_id` : utilisateur
|
||
- `peer_id` : client web
|
||
- `device_id` : agent
|
||
- `room_id` : room (2–4)
|
||
|
||
---
|
||
|
||
## 5. Capabilities (JWT TTL court)
|
||
Contenu : `sub`, `room_id`, `caps[]`, `exp` (+ option `target_*`, `max_size`, `max_rate`).
|
||
|
||
Caps typiques :
|
||
- `call`, `screen`
|
||
- `share:file`, `share:folder`
|
||
- `terminal:view`, `terminal:control`
|
||
|
||
Règles :
|
||
- aucune session P2P ne démarre sans cap_token valide.
|
||
- terminal : input interdit sans `terminal:control`.
|
||
|
||
---
|
||
|
||
## 6. Système
|
||
### `system.hello`
|
||
Client/Agent → Server
|
||
```json
|
||
{ "peer_type": "client|agent", "version": "x.y.z" }
|
||
```
|
||
|
||
### `system.welcome`
|
||
Server → Client/Agent
|
||
```json
|
||
{ "peer_id": "...", "user_id": "..." }
|
||
```
|
||
|
||
---
|
||
|
||
## 7. Rooms / présence
|
||
### `room.join`
|
||
```json
|
||
{ "room_id": "..." }
|
||
```
|
||
|
||
### `room.joined`
|
||
```json
|
||
{ "peer_id": "...", "role": "member", "room_id": "..." }
|
||
```
|
||
|
||
### `presence.update`
|
||
```json
|
||
{ "peer_id": "...", "status": "online|busy|sharing" }
|
||
```
|
||
|
||
---
|
||
|
||
## 8. Chat
|
||
### `chat.message.send`
|
||
```json
|
||
{ "room_id": "...", "content": "hello" }
|
||
```
|
||
|
||
### `chat.message.created`
|
||
```json
|
||
{ "message_id": "...", "from": "...", "content": "hello" }
|
||
```
|
||
|
||
---
|
||
|
||
## 9. WebRTC signaling (média)
|
||
### `rtc.offer`
|
||
```json
|
||
{ "room_id": "...", "target_peer_id": "...", "sdp": "...", "cap_token": "..." }
|
||
```
|
||
|
||
### `rtc.answer`
|
||
```json
|
||
{ "room_id": "...", "target_peer_id": "...", "sdp": "...", "cap_token": "..." }
|
||
```
|
||
|
||
### `rtc.ice`
|
||
```json
|
||
{ "room_id": "...", "target_peer_id": "...", "candidate": {}, "cap_token": "..." }
|
||
```
|
||
|
||
---
|
||
|
||
## 10. QUIC P2P sessions (data plane)
|
||
Les flux data (file/folder/terminal) utilisent une session QUIC orchestrée par le serveur.
|
||
|
||
### 10.1 Création
|
||
#### `p2p.session.request`
|
||
Agent A → Server
|
||
```json
|
||
{
|
||
"room_id": "...",
|
||
"target_device_id": "...",
|
||
"kind": "file|folder|terminal",
|
||
"cap_token": "...",
|
||
"meta": { "name": "...", "size": 123 }
|
||
}
|
||
```
|
||
|
||
#### `p2p.session.created`
|
||
Server → A et Server → B
|
||
```json
|
||
{
|
||
"session_id": "uuid",
|
||
"kind": "file|folder|terminal",
|
||
"expires_in": 180,
|
||
"auth": {
|
||
"session_token": "...",
|
||
"fingerprint": "..."
|
||
},
|
||
"endpoints": {
|
||
"a": { "ip": "x.x.x.x", "port": 45432 },
|
||
"b": { "ip": "y.y.y.y", "port": 45433 }
|
||
}
|
||
}
|
||
```
|
||
|
||
### 10.2 Handshake applicatif
|
||
Premier message sur un stream QUIC :
|
||
|
||
`P2P_HELLO`
|
||
```json
|
||
{ "t": "P2P_HELLO", "session_id": "...", "session_token": "...", "from_device_id": "..." }
|
||
```
|
||
|
||
Réponse : `P2P_OK` ou `P2P_DENY`.
|
||
|
||
---
|
||
|
||
## 11. Data messages (sur QUIC)
|
||
### 11.1 Fichier
|
||
- `FILE_META` (nom, taille, hash)
|
||
- `FILE_CHUNK` (offset, bytes)
|
||
- `FILE_ACK` (last_offset)
|
||
- `FILE_DONE` (hash final)
|
||
|
||
### 11.2 Dossier
|
||
- `FOLDER_MODE` (zip|sync)
|
||
- (zip) `ZIP_META` / `ZIP_CHUNK` / `ZIP_DONE`
|
||
- (sync, V2) `MANIFEST` / `DIFF_CHUNK` / `CONFLICT`
|
||
|
||
### 11.3 Terminal
|
||
- `TERM_OUT` (UTF-8)
|
||
- `TERM_RESIZE` (cols/rows)
|
||
- `TERM_IN` (input) — seulement si contrôle accordé
|
||
|
||
---
|
||
|
||
## 12. Contrôle terminal
|
||
Arbitrage via WS :
|
||
- `terminal.control.take`
|
||
- `terminal.control.granted`
|
||
- `terminal.control.release`
|
||
|
||
---
|
||
|
||
## 13. Notifications (Gotify)
|
||
Événements notifiables :
|
||
- `chat.message.created`
|
||
- `call.missed`
|
||
- `share.completed`
|
||
- `terminal.share.started`
|
||
- `agent.offline`
|
||
|
||
---
|
||
|
||
## 14. Erreurs
|
||
`error`
|
||
```json
|
||
{ "code": "CAP_EXPIRED", "message": "Capability token expired" }
|
||
```
|
||
|
||
Codes suggérés : `CAP_REQUIRED`, `CAP_EXPIRED`, `ROOM_NOT_FOUND`, `P2P_SESSION_DENIED`, `UNROUTABLE`.
|
||
|
||
---
|
||
|
||
## 15. Changelog
|
||
```
|
||
0.1.0 – Base events + WebRTC signaling
|
||
0.2.0 – QUIC sessions for data plane (file/folder/terminal)
|
||
```
|
||
|