mirror of
https://github.com/CloudNebulaProject/wayray.git
synced 2026-04-10 21:20:40 +00:00
109 lines
4.2 KiB
Markdown
109 lines
4.2 KiB
Markdown
|
# ADR-004: Session Management and Hot-Desking
|
||
|
|
|
||
|
|
## Status
|
||
|
|
Accepted
|
||
|
|
|
||
|
|
## Context
|
||
|
|
SunRay's defining feature was session mobility: users could pull their smart card, walk to any terminal, insert the card, and their entire desktop appeared in under a second. WayRay must replicate this capability with modern technology.
|
||
|
|
|
||
|
|
## Design
|
||
|
|
|
||
|
|
### Session Lifecycle
|
||
|
|
|
||
|
|
```
|
||
|
|
token insert
|
||
|
|
[No Session] ───────────────> [Creating]
|
||
|
|
│
|
||
|
|
v
|
||
|
|
┌──────────> [Active] <──────────┐
|
||
|
|
│ │ │
|
||
|
|
│ token remove │ token insert │
|
||
|
|
│ v (new client)│
|
||
|
|
│ [Suspended] ──────────┘
|
||
|
|
│ │
|
||
|
|
│ timeout │
|
||
|
|
│ v
|
||
|
|
│ [Destroyed]
|
||
|
|
│
|
||
|
|
│ client reconnect
|
||
|
|
└──── (same token)
|
||
|
|
```
|
||
|
|
|
||
|
|
### Session Identity
|
||
|
|
- Each session is bound to a **token** (smart card ID, badge ID, or software token)
|
||
|
|
- The token is NOT the user's identity -- it's a session locator
|
||
|
|
- Authentication happens separately via PAM after session attachment
|
||
|
|
- Multiple tokens can map to the same user (e.g., badge + phone NFC)
|
||
|
|
|
||
|
|
### Session Storage
|
||
|
|
- Active session state: in-memory (fast lookup)
|
||
|
|
- Session metadata (token mappings, user associations): SQLite via SeaORM
|
||
|
|
- Session registry for multi-server: distributed key-value store (etcd or custom)
|
||
|
|
|
||
|
|
### Hot-Desking Flow
|
||
|
|
|
||
|
|
1. Client connects to any WayRay server with a token
|
||
|
|
2. Server checks local session registry for token
|
||
|
|
3. If not found locally, queries other servers in the group
|
||
|
|
4. If session found on another server:
|
||
|
|
- Source server suspends the session (detaches from old client)
|
||
|
|
- Source server provides session endpoint to requesting server
|
||
|
|
- Client is redirected to the source server
|
||
|
|
- Session resumes on source server with new client
|
||
|
|
5. If no session exists: create new session, authenticate user via PAM
|
||
|
|
6. Entire flow target: < 500ms
|
||
|
|
|
||
|
|
### Session Suspension
|
||
|
|
When a token is removed or client disconnects:
|
||
|
|
- Compositor continues running (all applications stay alive)
|
||
|
|
- Frame rendering pauses (no ExportMem, save CPU)
|
||
|
|
- Network streams close gracefully
|
||
|
|
- Session enters Suspended state with configurable timeout (default: 24 hours)
|
||
|
|
- After timeout: session destroyed, all applications terminated
|
||
|
|
|
||
|
|
## Options Considered for Token Mechanism
|
||
|
|
|
||
|
|
### 1. Smart Card (PC/SC)
|
||
|
|
- Direct SunRay heritage
|
||
|
|
- Requires hardware on client (smart card reader)
|
||
|
|
- Well-suited for enterprise/government environments
|
||
|
|
- Libraries: pcsc-rust crate
|
||
|
|
|
||
|
|
### 2. NFC / RFID
|
||
|
|
- Modern equivalent of smart card
|
||
|
|
- Phone-based NFC as software token
|
||
|
|
- Lower-friction than smart card insertion
|
||
|
|
|
||
|
|
### 3. Software Token
|
||
|
|
- UUID-based token stored on client device
|
||
|
|
- No hardware required
|
||
|
|
- Can be combined with TOTP/FIDO2 for security
|
||
|
|
- Most accessible for development and lightweight deployments
|
||
|
|
|
||
|
|
### 4. All of the above (pluggable)
|
||
|
|
- Token is an opaque identifier; the mechanism doesn't matter to session management
|
||
|
|
- Different authentication backends provide tokens via a trait
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
**Pluggable token system** with software tokens as the default, smart card and NFC as optional backends.
|
||
|
|
|
||
|
|
```rust
|
||
|
|
trait TokenProvider {
|
||
|
|
fn token_inserted(&self) -> Option<SessionToken>;
|
||
|
|
fn token_removed(&self) -> bool;
|
||
|
|
fn watch(&self) -> TokenEventStream;
|
||
|
|
}
|
||
|
|
```
|
||
|
|
|
||
|
|
## Rationale
|
||
|
|
- Session mobility is the core differentiator; it must work across arbitrary token types
|
||
|
|
- Software tokens lower the barrier to entry (no hardware needed)
|
||
|
|
- Smart card support honors the SunRay heritage for enterprise deployments
|
||
|
|
- Pluggable design avoids committing to a single mechanism
|
||
|
|
|
||
|
|
## Consequences
|
||
|
|
- Must handle race conditions: token inserted on two clients simultaneously
|
||
|
|
- Session redirect adds latency; must be optimized carefully
|
||
|
|
- Multi-server session registry is a distributed systems problem (consistency vs availability)
|
||
|
|
- Software tokens are less secure than hardware tokens (can be copied); mitigate with device binding
|