CloudNebulaProject/wayray
1
0
Fork 0
mirror of https://github.com/CloudNebulaProject/wayray.git synced 2026-04-10 21:20:40 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
wayray/docs/ai/adr/002-network-transport.md
Till Wegmueller 167c6c17c6
Add project documentation, architecture decisions, and usage book 
Comprehensive documentation for WayRay, a SunRay-like thin client
Wayland compositor targeting illumos and Linux:

- CLAUDE.md: project context and conventions
- docs/ai/plans: 6-phase implementation roadmap
- docs/ai/adr: 9 architecture decision records (Smithay, QUIC,
  frame encoding, session management, rendering, audio, project
  structure, illumos support, pluggable window management)
- docs/architecture: system architecture overview with diagrams
- docs/protocols: WayRay wire protocol specification
- book/: mdbook user guide (introduction, concepts, server/client
  guides, admin, development)
- RESEARCH.md: deep research on remote display protocols
2026-03-28 20:47:16 +01:00

2.9 KiB
Raw Blame History

ADR-002: Network Transport Protocol

Status

Accepted

Context

WayRay must transmit display frames, input events, audio, and USB data between server and client with low latency. The transport must handle multiple independent data streams with different priority and reliability requirements.

Options Considered

1. TCP (multiple connections)

  • Reliable, ordered delivery
  • Head-of-line blocking: a lost display frame packet blocks all subsequent frames
  • No built-in multiplexing; need multiple connections or application-layer framing
  • Well-understood, simple implementation

2. UDP (custom protocol)

  • No head-of-line blocking
  • Must implement reliability, ordering, and congestion control ourselves
  • Maximum flexibility but significant implementation effort
  • What SunRay's ALP did (UDP for display/input, TCP for control)

3. QUIC (via quinn)

  • Built on UDP with TLS 1.3 encryption mandatory
  • Independent streams: loss on stream 1 doesn't block stream 2
  • 0-RTT connection resumption for fast session reconnection
  • Built-in congestion control and flow control
  • Multiplexing eliminates need for multiple connections
  • Connection migration: survives IP address changes (WiFi -> Ethernet)
  • quinn crate is mature and well-maintained in Rust

4. WebRTC

  • Designed for peer-to-peer media streaming
  • Overkill for our client-server architecture
  • Complex negotiation (ICE, STUN, TURN)
  • Good codec support but unnecessary complexity

Decision

Use QUIC via the quinn crate as the primary transport protocol.

Stream Architecture

Stream ID Channel Reliability Priority Direction
0 Control Reliable High Bidirectional
1 Display Unreliable* High Server -> Client
2 Input Reliable Highest Client -> Server
3 Audio Unreliable* Medium Bidirectional
4+ USB Reliable Low Bidirectional

*Unreliable streams use QUIC datagrams or short-lived unidirectional streams where old frames are discarded rather than retransmitted.

Rationale

  • Stream multiplexing maps naturally to our independent channels (display, input, audio, USB)
  • No head-of-line blocking between channels: a lost display frame doesn't delay input
  • 0-RTT reconnection enables sub-500ms session resumption for hot-desking
  • Connection migration supports client network changes without session interruption
  • TLS 1.3 mandatory means encryption is built-in, not an afterthought
  • quinn is production-quality Rust QUIC implementation
  • Avoids reinventing reliability/congestion control on raw UDP

Consequences

  • Requires TLS certificate management (self-signed for development, proper PKI for production)
  • QUIC is newer than TCP; some corporate firewalls may block UDP
    • Mitigation: fallback to TCP with WebSocket tunneling as future work
  • quinn is async (tokio), while Smithay uses calloop; need bridging between the two event loops