mirror of https://github.com/CloudNebulaProject/wayray.git synced 2026-04-10 13:10:41 +00:00

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.1 KiB

Raw Blame History

Network Transport

WayRay uses QUIC as its network transport protocol, providing encrypted, multiplexed, low-latency communication between server and client.

Why QUIC?

Stream Multiplexing

WayRay transmits multiple types of data simultaneously: display frames, input events, audio, and USB data. With TCP, a lost packet on the display stream would block input delivery (head-of-line blocking). QUIC's independent streams eliminate this -- each data type flows independently.

Built-in Encryption

QUIC mandates TLS 1.3. Every WayRay connection is encrypted by default, with no option to disable it. This is security by design, not by configuration.

0-RTT Reconnection

When a client reconnects to a server it has connected to before, QUIC can resume the connection in zero round trips. This is critical for session mobility -- when you move your token to a new terminal, the reconnection must be fast.

Connection Migration

If a client's IP address changes (e.g., switching from WiFi to Ethernet), QUIC can migrate the connection without dropping it. The session continues seamlessly.

Stream Layout

Stream	Purpose	Direction	Reliability
0	Control	Bidirectional	Reliable
1	Display	Server -> Client	Semi-reliable*
2	Input	Client -> Server	Reliable
3	Audio	Bidirectional	Semi-reliable*
4+	USB	Bidirectional	Reliable

*Semi-reliable: uses short-lived streams or datagrams so that old data is dropped rather than blocking new data.

Priority

Input has the highest priority. A keystroke must reach the server even if a large display frame is in transit. QUIC's flow control and WayRay's priority scheme ensure input events are never delayed by display data.

Firewall Considerations

QUIC runs over UDP. Some corporate firewalls block non-standard UDP traffic. If you encounter connectivity issues:

Ensure UDP port 4433 (default) is open between client and server
If UDP is blocked entirely, a future version of WayRay will support TCP fallback via WebSocket tunneling

2.1 KiB Raw Blame History