first
This commit is contained in:
Gilles Soulier
223
docs/protocol_events_v_2.md
Normal file
223
docs/protocol_events_v_2.md
Normal file
@@ -0,0 +1,223 @@
|
||||
# 📄 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)
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user