mesh/docs/protocol_events_v_2.md

📄 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

{
  "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

{ "peer_type": "client|agent", "version": "x.y.z" }

system.welcome

Server → Client/Agent

{ "peer_id": "...", "user_id": "..." }

---

7. Rooms / présence

room.join

{ "room_id": "..." }

room.joined

{ "peer_id": "...", "role": "member", "room_id": "..." }

presence.update

{ "peer_id": "...", "status": "online|busy|sharing" }

---

8. Chat

chat.message.send

{ "room_id": "...", "content": "hello" }

chat.message.created

{ "message_id": "...", "from": "...", "content": "hello" }

---

9. WebRTC signaling (média)

rtc.offer

{ "room_id": "...", "target_peer_id": "...", "sdp": "...", "cap_token": "..." }

rtc.answer

{ "room_id": "...", "target_peer_id": "...", "sdp": "...", "cap_token": "..." }

rtc.ice

{ "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

{
  "room_id": "...",
  "target_device_id": "...",
  "kind": "file|folder|terminal",
  "cap_token": "...",
  "meta": { "name": "...", "size": 123 }
}

p2p.session.created

Server → A et Server → B

{
  "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

{ "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

{ "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)