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

3.2 KiB

Raw Blame History

WayRay - SunRay-like Thin Client Wayland Compositor

Project Overview

WayRay is a modern reimplementation of Oracle/Sun's SunRay thin client architecture as a Wayland compositor written in Rust. The goal is to provide stateless thin client computing with session mobility, hot-desking, and zero-state endpoints over a modern protocol stack.

Target Platforms

illumos (OpenIndiana, OmniOS, SmartOS) - Primary target, honoring SunRay's Solaris heritage
Linux - Full support with optional GPU acceleration
Architecture is headless-first: Smithay with default-features = false, no dependency on DRM/KMS, libinput, udev, or libseat in the core path. Platform-specific backends behind feature flags.

Language & Stack

Language: Rust (edition 2024)
Compositor Framework: Smithay (Wayland compositor library)
Event Loop: calloop (callback-based, not async)
Networking: QUIC via quinn for low-latency multiplexed transport
Encoding: H.264/AV1 via VAAPI/NVENC for display, Opus for audio
Error Reporting: miette with diagnostic patterns for user-facing errors
ORM: SeaORM for any database needs (never raw SQL)
Logging: tracing crate

Architecture

WayRay consists of four main components:

wayray-server (compositor) - Smithay-based Wayland compositor that runs applications, captures framebuffers, and transmits them to clients. Exposes a pluggable WM protocol.
wayray-client (viewer) - Lightweight display client that decodes frames, renders them locally, captures input, and sends it to the server
wayray-protocol - Shared protocol definitions for the WayRay wire protocol over QUIC
wayray-ctl - CLI management tool for server/session administration

Documentation

docs/ai/plans/ - Implementation plans
docs/ai/adr/ - Architecture Decision Records
docs/architecture/ - System architecture documentation
docs/protocols/ - Protocol specifications
book/ - mdbook user guide (build with mdbook build book/)

Key Design Decisions

Headless-first: No hard dependency on GPU, DRM, or Linux-specific subsystems
illumos + Linux: Portable core, platform-specific backends behind feature flags
Pluggable Window Management: External WM process via custom Wayland protocol (River-inspired two-phase transaction model). Ships with built-in floating WM as default.
QUIC over TCP for network transport (multiplexing, 0-RTT reconnect)
PixmanRenderer for headless server (no GPU needed), GlesRenderer when GPU available
Damage-tracked differential frame encoding
Smart card / token-based session mobility (hot-desking)
Userspace USB forwarding over QUIC (not kernel USB/IP, for portability)
Audio: PipeWire (Linux) or PulseAudio (illumos/Linux) behind trait abstraction
shm_open fallback when memfd_create unavailable (illumos portability)

Conventions

Use miette's diagnostic pattern for all user-facing errors with helpful messages
Never use raw SQL - use SeaORM entities
Docker builds must use current Rust version with target-platform-specific caches
Clean up unused variables but investigate if design changes caused them to become unused
Use context7 for library documentation lookups

3.2 KiB Raw Blame History