diff --git a/CLAUDE.md b/CLAUDE.md index 841d109..5792781 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -43,6 +43,9 @@ WayRay consists of four main components: - **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. +- **Compositor, not a DE**: Cannot run GNOME/KDE (they ARE compositors). Desktop composed from independent Wayland clients (WM + panel + launcher + apps). Like Sway's ecosystem. +- **Greeter as Wayland client**: Login screen is a regular Wayland app, not a separate compositor. External session launcher handles PAM/user env (like greetd for Sway). +- **WayRay does NOT own**: user auth, home dir mounting, PAM, user environment setup. Those are the host system's job. WayRay owns the compositor session and token binding. - 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 diff --git a/docs/ai/adr/010-greeter-session-launch.md b/docs/ai/adr/010-greeter-session-launch.md new file mode 100644 index 0000000..bfb4a63 --- /dev/null +++ b/docs/ai/adr/010-greeter-session-launch.md @@ -0,0 +1,169 @@ +# ADR-010: Greeter and Session Launch Architecture + +## Status +Accepted + +## Context +WayRay is a compositor, not a login manager. But thin clients need a login screen -- when a token arrives with no existing session, the user must authenticate before getting a desktop. We cannot run GNOME/KDE as desktop environments because they ARE Wayland compositors (Mutter/KWin) and cannot run inside WayRay. + +### The Wayland DE Problem + +On X11, desktop environments were clients of the X server. GNOME, KDE, XFCE all ran on any X server including SunRay's Xnewt. On Wayland, DEs are tightly coupled to their compositor: + +| DE | Compositor | Can run on WayRay? | +|----|-----------|-------------------| +| GNOME Shell | Mutter | No -- Mutter IS a compositor | +| KDE Plasma | KWin | No -- KWin IS a compositor | +| XFCE4 (Wayland) | xfwm4/labwc | No -- needs its own compositor | +| Budgie (Wayland) | Magpie | No -- needs its own compositor | + +What DOES work: all individual applications from these DEs (Nautilus, Dolphin, Firefox, etc.) are standard Wayland clients. + +## Decision + +### WayRay Does Not Own User Authentication or Environment Setup + +WayRay's responsibility boundary: + +**WayRay owns:** +- Wayland compositor (rendering, protocol, encoding, transport) +- Session lifecycle (active, suspended, resumed, destroyed) +- Token-to-session binding (which token maps to which compositor session) +- WM protocol (pluggable window management) + +**WayRay does NOT own:** +- User authentication (PAM, LDAP, Kerberos) +- User environment (home dirs, NFS/ZFS mounts, shell, env vars) +- Desktop environment selection +- System-level session management (logind, zones) + +### Session Launch Flow + +``` +┌──────────┐ token ┌──────────────┐ +│ Client │──────────────►│ WayRay │ +│ (viewer) │ │ Server │ +└──────────┘ └──────┬───────┘ + │ + Does session exist + for this token? + │ + ┌──────────────┼──────────────┐ + │ YES │ NO + v v + Resume session ┌──────────────┐ + (sub-500ms) │ Session │ + │ Launcher │ + │ (external) │ + └──────┬───────┘ + │ + 1. Create user environment + (PAM, mount home, etc.) + 2. Start WayRay compositor + session for this user + 3. Launch greeter as first + Wayland client + │ + v + ┌──────────────┐ + │ Greeter │ + │ (Wayland │ + │ client) │ + └──────┬───────┘ + │ + User enters credentials + Greeter authenticates via PAM + │ + v + Launch user's configured + session (WM, panel, apps) + Greeter exits +``` + +### The Session Launcher + +A separate daemon/service (not part of WayRay) that: +1. Listens for "new session needed" events from WayRay +2. Creates the user environment (PAM session, mount home, set env vars) +3. Starts a WayRay compositor session for that user +4. Launches the greeter inside it + +This is analogous to: +- SunRay: SRSS session manager + dtlogin +- Sway: greetd + gtkgreet/regreet +- GNOME: GDM + gnome-shell (but GDM IS a compositor; our greeter is a client) + +We provide a **reference session launcher** (`wayray-session-launcher`) but the interface is a simple protocol/hook so admins can replace it with their own. + +### The Greeter + +A Wayland client application that: +- Displays a login form (username + password, or smart card PIN) +- Authenticates via PAM +- On success, signals the session launcher to proceed with user session setup +- Exits + +We ship a reference greeter (`wayray-greeter`) but any Wayland client implementing the greeter protocol works. Community can build GTK, Qt, or TUI-based greeters. + +### The User Session (Desktop Experience) + +After authentication, the session launcher starts the user's configured environment: + +```toml +# Example: ~/.config/wayray/session.toml + +# Window manager (connects via wayray_wm_manager_v1 protocol) +wm = "wayray-wm-floating" +# wm = "wayray-wm-tiling" +# wm = "/usr/local/bin/my-custom-wm" + +# Panel (layer-shell Wayland client) +panel = "waybar" + +# App launcher +launcher = "fuzzel" + +# Notification daemon +notifications = "mako" + +# Autostart applications +autostart = [ + "foot", # Terminal + "nm-applet", # Network manager tray +] +``` + +This composes a full desktop from independent Wayland clients: +- **WM**: Pluggable via our protocol (ADR-009) +- **Panel**: waybar, ironbar, or custom (layer-shell protocol) +- **Launcher**: fuzzel, wofi, tofi (layer-shell protocol) +- **Notifications**: mako, fnott (layer-shell protocol) +- **Apps**: any Wayland or X11 (via XWayland) application + +### Integration Points + +WayRay exposes hooks for the session launcher: + +``` +Event: session_requested(token) -> session_launcher handles it +Event: session_authenticated(user, token) -> launcher sets up user env +Event: session_logout(session_id) -> launcher tears down user env +``` + +The interface is intentionally minimal -- a few events over a Unix socket or D-Bus. This keeps WayRay decoupled from any specific auth/provisioning stack. + +## Rationale + +- **Separation of concerns**: WayRay is a compositor, not a login system. Authentication and environment provisioning vary wildly between deployments (LDAP vs local, NFS vs ZFS, containers vs bare metal). WayRay shouldn't know or care. +- **SunRay precedent**: SunRay's SRSS managed display sessions. dtlogin handled authentication. Solaris handled user environments. Same separation. +- **greetd precedent**: The Wayland ecosystem already solved this -- greetd + gtkgreet for Sway proves the external greeter model works. +- **Composability**: Administrators can swap any component. Corporate deploy with SSO greeter and locked-down session config. University deploy with student self-service. Home user with minimal auto-login. +- **Greeter as Wayland client**: No special rendering path. The greeter is just the first app that runs in the session. It uses the same compositor, same encoding, same network transport as everything else. + +## Consequences + +- Must define a stable session launcher interface (events/hooks) +- Must ship a reference greeter and reference session launcher for out-of-box usability +- Users expecting "GNOME over thin client" will be disappointed -- we should be clear in docs that WayRay provides a composable desktop, not a DE +- The session.toml concept needs careful design for both simplicity and flexibility +- Must support `wlr-layer-shell` protocol for panels, launchers, and notification daemons diff --git a/docs/ai/plans/001-implementation-roadmap.md b/docs/ai/plans/001-implementation-roadmap.md index 03110cf..4cba71a 100644 --- a/docs/ai/plans/001-implementation-roadmap.md +++ b/docs/ai/plans/001-implementation-roadmap.md @@ -102,18 +102,33 @@ - Session storage: in-memory with optional persistence (SeaORM + SQLite) - Session timeout and cleanup policies -### 3.2 Authentication -- Token-based session identification (smart card ID, badge, or software token) -- PAM integration for user authentication -- Session-token binding in session store +### 3.2 Greeter and Session Launch +- Define session launcher interface (events over Unix socket: session_requested, session_authenticated, session_logout) +- Implement reference session launcher (`wayray-session-launcher`) that: + - Receives "new session needed" events from WayRay + - Creates user environment (delegates to PAM, system tools) + - Starts WayRay compositor session for the user + - Launches greeter as first Wayland client +- Implement reference greeter (`wayray-greeter`) as a Wayland client: + - Login form (username + password) + - Authenticates via PAM through session launcher + - On success, session launcher starts user's configured session (WM, panel, apps) + - Greeter exits +- User session config: `~/.config/wayray/session.toml` (WM, panel, launcher, autostart apps) +- Support `wlr-layer-shell` protocol for panels, launchers, notification daemons -### 3.3 Hot-Desking (Session Mobility) +### 3.3 Token-Based Session Identity +- Token-based session identification (smart card ID, badge, or software token) +- Session-token binding in session store +- WayRay does NOT own authentication -- delegates to session launcher / PAM + +### 3.4 Hot-Desking (Session Mobility) - Token insertion triggers session lookup across server pool - Session reconnection: rebind existing session to new client endpoint - Session disconnect: unbind from client, keep session running - Sub-second reconnection target (< 500ms) -### 3.4 Multi-Server Support +### 3.5 Multi-Server Support - Server discovery protocol (mDNS or custom) - Session registry: which sessions live on which servers - Cross-server session redirect diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index 1592f9c..1e31838 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -145,6 +145,34 @@ Frame encoding adapts to content type and network conditions: 4. Client captures microphone, encodes to Opus, sends to server 5. 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_v1` protocol (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): +1. Token arrives, no session exists +2. Session launcher creates user environment (PAM, mounts) +3. Greeter (a Wayland client) authenticates the user +4. Session launcher starts user's configured session (WM, panel, apps) + ## Comparison with SunRay | Feature | SunRay | WayRay | @@ -153,8 +181,11 @@ Frame encoding adapts to content type and network conditions: | 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 | USB/IP or usbredir | +| 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 |