mirror of
https://github.com/CloudNebulaProject/wayray.git
synced 2026-04-10 13:10:41 +00:00
a373ea1c41
WayRay is a compositor, not a DE or login system. GNOME/KDE cannot run on WayRay (they ARE compositors). The desktop is composed from independent Wayland clients (pluggable WM + panel + launcher + apps). - ADR-010: Greeter as Wayland client, external session launcher handles PAM/user env (like greetd for Sway) - Clarify scope: WayRay owns compositor session + token binding, not user auth, home dirs, or environment setup - Update roadmap with greeter phase and session.toml config - Update architecture overview with scope boundary section
12 KiB
12 KiB
WayRay Architecture Overview
Vision
WayRay is a modern reimagining of Oracle/Sun's SunRay thin client system, built as a native Wayland compositor. Where SunRay used proprietary hardware and the ALP protocol over UDP, WayRay uses commodity hardware, the Wayland protocol for local application rendering, and QUIC for network transport.
System Architecture
┌─────────────────────────────────────────────────────────┐
│ WayRay Server │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ App 1 │ │ App 2 │ │ App N │ Wayland │
│ │ (foot) │ │ (firefox)│ │ (...) │ Clients │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ └──────────────┼──────────────┘ │
│ │ Wayland Protocol │
│ v │
│ ┌───────────────────────────────────────┐ │
│ │ Smithay Compositor │ │
│ │ │ │
│ │ ┌─────────┐ ┌──────────┐ │ │
│ │ │ XDG │ │ Layer │ Protocol │ │
│ │ │ Shell │ │ Shell │ Handlers │ │
│ │ └─────────┘ └──────────┘ │ │
│ │ │ │
│ │ ┌─────────┐ ┌──────────┐ │ │
│ │ │ Seat │ │ Output │ │ │
│ │ │ (input) │ │ Manager │ │ │
│ │ └─────────┘ └──────────┘ │ │
│ │ │ │
│ │ ┌─────────────────────────┐ │ │
│ │ │ Renderer │ │ │
│ │ │ (Pixman or GLES) │ │ │
│ │ │ │ │ │
│ │ │ OutputDamageTracker │ │ │
│ │ │ ExportMem (framebuffer) │ │ │
│ │ └─────────────────────────┘ │ │
│ └───────────────┬───────────────────────┘ │
│ │ │
│ v │
│ ┌───────────────────────────────────────┐ │
│ │ Frame Encoder │ │
│ │ │ │
│ │ Damage Regions -> Tile Classification│ │
│ │ -> Lossless (zstd) / Lossy (H.264) │ │
│ └───────────────┬───────────────────────┘ │
│ │ │
│ ┌───────────────┴───────────────────────┐ │
│ │ Session Manager │ │
│ │ │ │
│ │ Token -> Session mapping │ │
│ │ Session lifecycle │ │
│ │ Multi-server coordination │ │
│ └───────────────┬───────────────────────┘ │
│ │ │
│ ┌───────────────┴───────────────────────┐ │
│ │ QUIC Transport (quinn) │ │
│ │ │ │
│ │ Stream 0: Control │ │
│ │ Stream 1: Display (frames) │ │
│ │ Stream 2: Input (keyboard/mouse) │ │
│ │ Stream 3: Audio (Opus) │ │
│ │ Stream 4+: USB devices │ │
│ └───────────────┬───────────────────────┘ │
└──────────────────┼───────────────────────────────────────┘
│
│ QUIC / TLS 1.3
│ (Network)
│
┌──────────────────┼───────────────────────────────────────┐
│ │ WayRay Client │
│ ┌───────────────┴───────────────────────┐ │
│ │ QUIC Transport (quinn) │ │
│ └───────────────┬───────────────────────┘ │
│ │ │
│ ┌───────────┬───┴──────┬────────────┬───────────┐ │
│ │ │ │ │ │ │
│ v v v v v │
│ ┌─────┐ ┌──────┐ ┌────────┐ ┌────────┐ ┌─────┐ │
│ │Ctrl │ │Frame │ │ Input │ │ Audio │ │ USB │ │
│ │ │ │Decode│ │Capture │ │Play/Cap│ │Fwd │ │
│ └─────┘ └──┬───┘ └───┬────┘ └────────┘ └─────┘ │
│ │ │ │
│ v │ │
│ ┌──────────────┐ │ │
│ │ wgpu/winit │ │ │
│ │ Display │<─────┘ (cursor, HiDPI) │
│ └──────────────┘ │
│ │
│ ┌──────────────┐ │
│ │ Token │ Smart Card / NFC / Software Token │
│ │ Provider │ │
│ └──────────────┘ │
└───────────────────────────────────────────────────────┘
Core Principles
1. Stateless Client
The WayRay client stores no user data, no session state, and no application state. If the client device is lost or destroyed, nothing is lost. All state lives on the server.
2. Session Mobility
A session is bound to a token, not a device. Insert your token into any WayRay client on the network and your desktop follows you -- all windows, all applications, exact state preserved.
3. Server-Side Rendering
All Wayland clients run on the server. The compositor renders everything server-side and transmits compressed frames to the client. The client is purely a decoder + display + input capture device.
4. Adaptive Encoding
Frame encoding adapts to content type and network conditions:
- Text/UI: lossless compression (perfect rendering)
- Video: lossy hardware encoding (H.264/AV1)
- Low bandwidth: aggressive compression, lower framerate
- LAN: minimal compression, high framerate
5. Security by Default
- All network traffic encrypted via TLS 1.3 (QUIC mandates it)
- No data at rest on client devices
- Session authentication via PAM
- USB device policies for access control
Data Flow
Display (Server -> Client)
- Wayland applications commit surface updates
- Smithay compositor renders all surfaces into output framebuffer
- OutputDamageTracker identifies changed regions since last frame
- Frame encoder processes damaged regions (tile-based, content-adaptive)
- Encoded frame sent over QUIC display stream
- Client decodes frame regions, uploads to GPU, displays
Input (Client -> Server)
- Client captures keyboard/mouse/touch events
- Events serialized with timestamps and keymaps
- Sent over QUIC input stream (highest priority)
- Server deserializes and injects into Smithay Seat
- Seat forwards to focused Wayland client
Audio (Bidirectional)
- Server applications output audio to PipeWire virtual sink
- Audio frames encoded to Opus, sent over QUIC audio stream
- Client decodes Opus, plays through local audio device
- Client captures microphone, encodes to Opus, sends to server
- Server feeds decoded audio into PipeWire virtual source
Scope Boundary: What WayRay Owns
WayRay is a compositor, not a desktop environment or login system.
WayRay owns:
- Wayland compositor (rendering, protocol, encoding, transport)
- Session lifecycle (active, suspended, resumed, destroyed)
- Token-to-session binding
- Pluggable WM protocol
WayRay does NOT own:
- User authentication (PAM, LDAP, Kerberos)
- User environment (home dirs, mounts, shell, env vars)
- Desktop environment (WayRay cannot host GNOME/KDE -- they are compositors)
The desktop experience is composed from independent Wayland clients:
- Window manager via
wayray_wm_manager_v1protocol (floating, tiling, custom) - Panel/taskbar (waybar, etc.) via
wlr-layer-shell - App launcher (fuzzel, wofi) via
wlr-layer-shell - Notification daemon (mako, fnott) via
wlr-layer-shell - Any Wayland or X11 application
Login flow is handled by an external session launcher (like greetd for Sway):
- Token arrives, no session exists
- Session launcher creates user environment (PAM, mounts)
- Greeter (a Wayland client) authenticates the user
- Session launcher starts user's configured session (WM, panel, apps)
Comparison with SunRay
| Feature | SunRay | WayRay |
|---|---|---|
| Display Protocol | ALP (proprietary, UDP) | WayRay Protocol (QUIC) |
| Compositor | X server (Xnewt) | Wayland (Smithay) |
| Client Hardware | Purpose-built DTU | Any Linux/macOS/Windows device |
| Session Mobility | Smart card | Pluggable tokens (smart card, NFC, software) |
| Login Screen | dtlogin (X11 client) | wayray-greeter (Wayland client) |
| Desktop | CDE/GNOME on X11 | Composable: pluggable WM + panel + launcher |
| Audio | Custom ALP channel | Opus over QUIC |
| USB Forwarding | Custom | Userspace over QUIC |
| Encryption | Optional ALP encryption | Mandatory TLS 1.3 |
| Multi-server | Failover groups | Distributed session registry |
| Platform | Solaris | illumos + Linux |
| Client OS | Proprietary RTOS | Native application |