125 lines
3.3 KiB
Markdown
125 lines
3.3 KiB
Markdown
|
# Shade V3.11 — WebRTC P2P Transport
|
|||
|
|
|
|||
|
|
**Status:** Done — landet med `@shade/transport-webrtc` 0.4.0,
|
|||
|
|
`MultiTransportFallback` i `@shade/transfer`, og
|
|||
|
|
`shade.configureWebRTC()` i `@shade/sdk`. Se [docs/webrtc.md](../webrtc.md).
|
|||
|
|
**Effort:** XL (2–4 måneder)
|
|||
|
|
**Forrige:** V3.7
|
|||
|
|
**Adresserer:** V2.1-tillegg "P2P WebRTC transport"
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Mål
|
|||
|
|
|
|||
|
|
Direct peer-to-peer datakanal mellom Shade-klienter når NAT/firewall
|
|||
|
|
tillater. Primær gevinst: massiv throughput for `@shade/transfer`
|
|||
|
|
(filer, store payloads) og lav-latens for messaging når begge peere
|
|||
|
|
er online samtidig. E2EE bevart: WebRTC DTLS-SRTP er **transport** —
|
|||
|
|
payload er fortsatt Shade ratchet-krypto.
|
|||
|
|
|
|||
|
|
V3.11 lander i V4.0-vinduet og er foundation-only — sanntidsbruken
|
|||
|
|
(voice, video, broadcast) ligger i [V5.0](../V5.0.md) som downstream
|
|||
|
|
konsumer av denne datakanalen.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Scope
|
|||
|
|
|
|||
|
|
### Inn
|
|||
|
|
|
|||
|
|
- Ny pakke `@shade/transport-webrtc`.
|
|||
|
|
- Signaling via Shade control plane (eksisterende kanal — `Shade.send`).
|
|||
|
|
- ICE/STUN: bruk offentlige STUN-servere som default.
|
|||
|
|
- TURN: konfigurerbar TURN-relay som fallback.
|
|||
|
|
- DataChannel for `@shade/transfer`-chunks.
|
|||
|
|
- Auto-fallback: P2P → HTTP (eksisterende stack).
|
|||
|
|
|
|||
|
|
### Ut
|
|||
|
|
|
|||
|
|
- SFU/MCU (mange-til-mange topologi) — broadcast/video er V5.0.
|
|||
|
|
- Voice/video media-tracks — V3.11 er ren datakanal (DataChannel);
|
|||
|
|
audio/video over RTP er V5.0.
|
|||
|
|
- DTLS-fingerprint-binding til Shade-fingerprint (vurderes som hardening,
|
|||
|
|
men ikke krav).
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Design
|
|||
|
|
|
|||
|
|
### Connection-flow
|
|||
|
|
|
|||
|
|
```text
|
|||
|
|
A initierer:
|
|||
|
|
1. createOffer() → SDP
|
|||
|
|
2. shade.send(B, { kind: "webrtc-offer", sdp })
|
|||
|
|
3. B mottar over Shade-kanal, createAnswer()
|
|||
|
|
4. shade.send(A, { kind: "webrtc-answer", sdp })
|
|||
|
|
5. ICE-candidates exchange (samme kanal)
|
|||
|
|
6. DataChannel åpen
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### Wrapping
|
|||
|
|
|
|||
|
|
DataChannel sender ferdige `@shade/transfer`-chunks (allerede E2EE).
|
|||
|
|
WebRTC's egen DTLS-SRTP fungerer som transport-secrecy lag.
|
|||
|
|
|
|||
|
|
### Topologi
|
|||
|
|
|
|||
|
|
- 1:1 P2P direkte når mulig.
|
|||
|
|
- TURN-relay når NAT'er er for strenge (transport-only, ser ikke plaintext).
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Leveranser
|
|||
|
|
|
|||
|
|
### Pakker
|
|||
|
|
|
|||
|
|
- `@shade/transport-webrtc` — Connection, DataChannel-wrapper, ICE-config.
|
|||
|
|
- `@shade/transfer` utvides: `WebRTCTransferTransport` som drop-in.
|
|||
|
|
- `FallbackTransferTransport` får ny ledd: P2P → WS → HTTP.
|
|||
|
|
|
|||
|
|
### Tester
|
|||
|
|
|
|||
|
|
- Loopback unit: offer/answer/ICE i Bun via `node-datachannel` eller
|
|||
|
|
`wrtc`.
|
|||
|
|
- Integration: 100 MB transfer over P2P vs HTTP — P2P skal vinne på samme
|
|||
|
|
nettverk.
|
|||
|
|
- Failover: TURN-relay påtvinger relay-modus.
|
|||
|
|
- NAT-emulering (loopback med ulike NAT-typer hvis mulig).
|
|||
|
|
|
|||
|
|
### Dokumentasjon
|
|||
|
|
|
|||
|
|
- `docs/webrtc.md` — setup, STUN/TURN-config, NAT-traversal-håp og
|
|||
|
|
-realiteter.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Akseptansekriterier
|
|||
|
|
|
|||
|
|
- [ ] To klienter på samme LAN: P2P direct uten TURN, throughput > 5x
|
|||
|
|
HTTP-baseline.
|
|||
|
|
- [ ] To klienter bak strenge NAT'er: TURN-relay aktiveres automatisk.
|
|||
|
|
- [ ] Failover P2P-død → HTTP innen 5 s uten meldingstap.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Avhengigheter
|
|||
|
|
|
|||
|
|
- V3.7 — bridge-mønstre + fallback-arkitektur.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Risiko
|
|||
|
|
|
|||
|
|
- **NAT-traversal-helvete.** Mange edge-cases. Mitiger med tidlige
|
|||
|
|
integration-tester på faktiske NAT-konfigurasjoner.
|
|||
|
|
- **Browser-kompatibilitet.** Safari har sine egne RTC-quirks.
|
|||
|
|
- **TURN-koster.** TURN-relay = ekte trafikk gjennom server. Operatør må
|
|||
|
|
vite det.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Migrasjon
|
|||
|
|
|
|||
|
|
Opt-in. Eksisterende HTTP/WS-transport fungerer uendret.
|