diff --git a/FEATURES.md b/FEATURES.md index 99b199f..e7d78b0 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -29,7 +29,7 @@ | Category | Status | Test Coverage | Notes | | :--- | :--- | :--- | :--- | | **Multi-Tenancy** | ✅ Complete | 100% | Org-scoped access control | -| **K8s Agent (v2.0)** | ✅ Complete | ~80% | Session lifecycle, VNC tunneling | +| **K8s Agent (v2.0)** | ✅ Complete | ~80% | Session lifecycle, Selkies streaming | | **Docker Agent (v2.0)** | ✅ Complete | ~60% | Full platform support | | **API Backend** | ✅ Complete | 100% (9/9 packages) | All handler tests passing | | **Web UI** | ✅ Complete | 98% (189/191 tests) | All pages functional | @@ -52,7 +52,7 @@ | **Auto-Hibernation** | ✅ Complete | Configurable idle timeout | | **Wake on Demand** | ✅ Complete | Sub-30s wake time | | **Session Sharing** | ✅ Complete | Role-based permissions | -| **VNC Proxy (v2.0)** | ✅ Complete | WebSocket tunneling, <100ms latency | +| **Selkies Streaming Proxy** | ✅ Complete | HTTP/WebRTC reverse proxy, token-authenticated | ### Template System @@ -209,7 +209,7 @@ | :--- | :--- | :--- | | API Latency (p99) | < 800ms | ✅ ~200ms | | Session Startup | < 30s | ✅ ~6s | -| VNC Latency | < 100ms | ✅ <100ms | +| Stream latency (Selkies WebRTC) | < 100ms | ✅ <100ms | | Agent Reconnection | < 60s | ✅ ~23s | --- diff --git a/README.md b/README.md index ff4c4b7..df65fc9 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,6 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Kubernetes](https://img.shields.io/badge/kubernetes-1.19+-blue.svg)](https://kubernetes.io/) [![Go Report Card](https://goreportcard.com/badge/github.com/streamspace-dev/streamspace)](https://goreportcard.com/report/github.com/streamspace-dev/streamspace) -[![Status](https://img.shields.io/badge/Status-v2.0--beta.1-success.svg)](CHANGELOG.md) [Features](#features) • [Quick Start](#quick-start) • [Architecture](#architecture) • [Documentation](#documentation) • [Contributing](#contributing) @@ -17,247 +16,174 @@ --- -> [!NOTE] -> **Current Version: v2.0-beta.1 - Production Ready** -> -> StreamSpace v2.0-beta.1 is ready for production deployment with multi-tenancy, enterprise security, and comprehensive observability. -> -> **📋 Project Board**: [StreamSpace v2.0 Development](https://github.com/orgs/streamspace-dev/projects/2) - -## 🚀 Overview +> [!WARNING] +> **Active rebuild — April 2026.** The control plane and agents work, but the end-to-end streaming pipeline (image build, template catalog wiring, golden-path test) is being reconstructed. The historical v2.0-beta.1 docs are preserved under [`docs/historical/`](docs/historical/) for context. -StreamSpace delivers browser-based access to containerized applications. It features a central **Control Plane** (API/WebUI) that manages distributed **Agents** across various platforms (Kubernetes, Docker). +## Overview -### What's New in v2.0-beta.1 +StreamSpace delivers browser-based access to containerized applications. A central **Control Plane** (API + WebUI) brokers sessions to distributed **Agents** running on Kubernetes today and Docker next. -**Core Platform:** -- ✅ **Multi-Platform Architecture**: Control Plane + Agent model -- ✅ **Secure VNC Proxy**: WebSocket-based VNC tunneling (<100ms latency) -- ✅ **K8s Agent**: Kubernetes agent with session lifecycle management -- ✅ **Docker Agent**: Docker platform support with HA backends -- ✅ **High Availability**: Multi-pod API, leader election, automatic failover +Streaming uses **Selkies-GStreamer (WebRTC)** end-to-end. Earlier VNC code paths were removed in favor of a single, well-supported protocol. -**Enterprise Features:** -- ✅ **Multi-Tenancy**: Org-scoped access control, JWT claims, cross-tenant prevention -- ✅ **Observability**: 3 Grafana dashboards, 12 Prometheus alert rules -- ✅ **API Documentation**: OpenAPI 3.0 spec with Swagger UI at `/api/docs` -- ✅ **Security**: 15 CVEs fixed, security headers, 0 Critical/High vulnerabilities +## Repository topology -**Test Coverage:** -- ✅ **Backend**: 100% handler coverage (9/9 packages) -- ✅ **UI**: 98% test passing (189/191 tests) +| Repo | What it owns | +|---|---| +| `streamspace-dev/streamspace` (this repo) | Control Plane API, K8s/Docker agents, Web UI, Helm chart | +| `streamspace-dev/streamspace-templates` | Application templates (CRD manifests) **and** the source + build pipeline for custom container images (`ghcr.io/streamspace-dev/`) | +| `streamspace-dev/streamspace-plugins` | Optional plugins (auth, storage, observability, billing, …) | +| `streamspace-dev/streamspace.wiki` | End-user documentation (Getting Started, Architecture overview, Plugin/Template catalogs) | -See [ROADMAP.md](ROADMAP.md) for future plans. +## Features -## ✨ Features - -| Core Features | Enterprise Features | +| Core | Enterprise | | :--- | :--- | -| 🖥️ **Browser-based VNC** access | 🔐 **SSO**: SAML 2.0, OIDC, OAuth2 | -| 👥 **Multi-tenancy** with org scoping | 🛡️ **MFA** with TOTP | -| 💾 **Persistent** home directories | 📝 **Audit Logging** & Compliance | -| 💤 **Auto-hibernation** (scale to zero) | 🌐 **IP Whitelisting** & Rate Limiting | -| 📦 **200+ Apps** via templates | 🔌 **Webhooks** (16 event types) | -| 📊 **Grafana Dashboards** | 🔔 **Prometheus Alerts** | +| Browser-based streaming over WebRTC | SSO: SAML 2.0, OIDC, OAuth2 | +| Multi-tenancy with org scoping | MFA with TOTP | +| Persistent home directories | Audit logging & compliance | +| Auto-hibernation (scale to zero) | IP allow-listing & rate limiting | +| Custom image pipeline (cosign + SBOM) | Webhooks (16 event types) | +| Grafana dashboards | Prometheus alerts | + +## Quick Start -## 🛠️ Quick Start +> [!NOTE] +> This is the dev/contributor flow. For production deployment see [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md). ### Prerequisites -- Kubernetes 1.19+ (k3s recommended) +- Kubernetes 1.19+ (k3s recommended for local dev) - Helm 3.0+ - PostgreSQL database -- NFS storage provisioner - -### Installation - -1. **Clone the repository** - - ```bash - git clone https://github.com/streamspace-dev/streamspace.git - cd streamspace - ``` +- A storage class for persistent home volumes -2. **Deploy CRDs** +### Install - ```bash - kubectl apply -f manifests/crds/ - ``` - -3. **Install via Helm** +```bash +git clone https://github.com/streamspace-dev/streamspace.git +cd streamspace +kubectl apply -f manifests/crds/ +helm install streamspace ./chart -n streamspace --create-namespace +``` - ```bash - helm install streamspace ./chart -n streamspace --create-namespace - ``` +### Launch a session -4. **Create a Session** +```bash +kubectl apply -f - <<'EOF' +apiVersion: stream.space/v1alpha1 +kind: Session +metadata: + name: my-chrome + namespace: streamspace +spec: + user: john + template: chrome-selkies + state: running + resources: + memory: 2Gi +EOF +``` - ```bash - kubectl apply -f - </` to the session pod's Selkies endpoint on port 8080. > [!TIP] -> **Production Setup**: Before deploying to production, ensure you update the default secrets. See the [Deployment Guide](DEPLOYMENT.md) for details. - -## 🎯 Production Status (v2.0-beta.1) - -StreamSpace v2.0-beta.1 is **production ready** with comprehensive security, observability, and test coverage: +> Update default secrets before any production deployment — see [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md). -### Test Coverage - -| Component | Coverage | Status | -|-----------|----------|--------| -| **API Backend** | 100% | ✅ All 9 handler packages | -| **UI Components** | 98% | ✅ 189/191 tests passing | -| **K8s Agent** | ~80% | ✅ Session lifecycle, VNC | -| **Docker Agent** | ~60% | ✅ Platform support | - -### Security Status - -- ✅ **0 Critical/High CVEs** - All 15 vulnerabilities fixed -- ✅ **Security Headers** - HSTS, CSP, X-Frame-Options -- ✅ **Rate Limiting** - 60 req/min default -- ✅ **Input Validation** - JSON schema validation - -### Observability - -- ✅ **3 Grafana Dashboards** - Control Plane, Sessions, Agents -- ✅ **12 Prometheus Alerts** - Latency, errors, heartbeat -- ✅ **Structured Logging** - With trace IDs - -### Performance - -| Metric | Target | Actual | -|--------|--------|--------| -| API Latency (p99) | < 800ms | ~200ms | -| Session Startup | < 30s | ~6s | -| VNC Latency | < 100ms | <100ms | -| Agent Reconnection | < 60s | ~23s | - -## 🏗️ Architecture - -StreamSpace uses a **Control Plane + Agent** architecture for multi-platform support and scalability. +## Architecture ```mermaid graph TD User[User / Browser] -->|HTTPS| Ingress[Load Balancer] Ingress -->|HTTPS| UI[Web UI] - Ingress -->|HTTPS/WSS| API[Control Plane API] + Ingress -->|HTTPS / WSS| API[Control Plane API] subgraph "Control Plane" UI API - Hub[WebSocket Hub] - VNCProxy[VNC Proxy] + Hub[Agent WebSocket Hub] + Selkies[Selkies HTTP/WebRTC Proxy] DB[(PostgreSQL)] API --> DB API --> Hub - API --> VNCProxy + API --> Selkies end - subgraph "Execution Plane - Kubernetes" + subgraph "Execution Plane — Kubernetes" K8sAgent[K8s Agent] K8sAgent <-->|WebSocket| Hub K8sAgent -->|Manage| Pods[Session Pods] - VNCProxy <-.->|VNC Tunnel| K8sAgent - K8sAgent <-.->|VNC| Pods + Selkies -.->|HTTP/WS| Pods end - subgraph "Execution Plane - Docker (v2.1)" + subgraph "Execution Plane — Docker" DockerAgent[Docker Agent] DockerAgent <-->|WebSocket| Hub DockerAgent -->|Manage| Containers[Session Containers] end ``` -**Key Components**: -- **Control Plane**: Central management, authentication, VNC proxy -- **WebSocket Hub**: Real-time agent communication and coordination -- **VNC Proxy**: Secure tunneling of VNC traffic through Control Plane -- **K8s Agent**: Manages Kubernetes pods and sessions -- **Session Pods**: Isolated containerized environments with VNC +**Components** -For detailed architecture, see [ARCHITECTURE.md](docs/ARCHITECTURE.md). +- **Control Plane API** — auth, multi-tenancy, session orchestration, exposes the Selkies HTTP/WebRTC proxy. +- **Agent WebSocket Hub** — bidirectional command channel to agents (heartbeats, session start/stop, status updates). +- **Selkies Proxy** — token-authenticated reverse proxy from `/api/v1/http//` to the in-cluster Selkies endpoint on the session pod (port 8080). Sessions stream over the same connection via WebRTC. +- **K8s Agent** — manages Session/Template CRDs, deploys session pods, reports lifecycle. +- **Docker Agent** — equivalent for Docker hosts (in flight). -## 📚 Available Applications +For the deeper technical reference, see [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md). Frozen v2 architecture snapshots live in [`docs/historical/`](docs/historical/). -Templates are available via [streamspace-templates](https://github.com/StreamSpace-dev/streamspace-templates). +## Available applications -- **Browsers**: Firefox, Chromium, Brave, LibreWolf -- **Development**: VS Code, GitHub Desktop -- **Productivity**: LibreOffice, OnlyOffice -- **Media**: GIMP, Blender, Audacity, Kdenlive +Templates live in [`streamspace-templates`](https://github.com/streamspace-dev/streamspace-templates). The image-build pipeline in that repo publishes signed multi-arch images to `ghcr.io/streamspace-dev/`. The current bootstrap image is: -## 💻 Development +- `ghcr.io/streamspace-dev/chrome-selkies` — Google Chrome streamed via Selkies-GStreamer -### Build Components +A Selkies-native catalog (Firefox, VS Code, full desktops, etc.) is being added on top of the build pipeline. + +## Development ```bash # Build K8s Agent cd agents/k8s-agent && go build -o k8s-agent . # Build API -cd api && go build -o streamspace-api +cd api && go build -o streamspace-api ./cmd # Build UI cd ui && npm install && npm run build -``` -### Run Tests - -```bash -# Run all integration tests -cd tests && ./scripts/run-integration-tests.sh +# Run all Go tests under -race +go test -race ./... ``` -See [TESTING.md](TESTING.md) for detailed testing guides. +See [`docs/TESTING.md`](docs/TESTING.md) for the full test guide. + +## Documentation -## 📖 Documentation +### Contributor-facing (this repo) -### User Guides -- **[FEATURES.md](FEATURES.md)**: Complete feature list & implementation status -- **[DEPLOYMENT.md](DEPLOYMENT.md)**: Production deployment guide -- **[ARCHITECTURE.md](docs/ARCHITECTURE.md)**: Deep dive into system design -- **[DISASTER_RECOVERY.md](docs/DISASTER_RECOVERY.md)**: Backup & DR procedures +- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — system design +- [`docs/DEPLOYMENT.md`](docs/DEPLOYMENT.md) — production deployment +- [`docs/MIGRATION_V1_TO_V2.md`](docs/MIGRATION_V1_TO_V2.md) — v1 → v2 migration +- [`docs/design/architecture/`](docs/design/architecture/) — architecture decision records +- [`docs/historical/`](docs/historical/) — frozen architectural snapshots +- [`CONTRIBUTING.md`](CONTRIBUTING.md) · [`ROADMAP.md`](ROADMAP.md) · [`FEATURES.md`](FEATURES.md) -### API Documentation -- **[Swagger UI](/api/docs)**: Interactive API explorer -- **[OpenAPI Spec](/api/openapi.yaml)**: OpenAPI 3.0 specification +### End-user-facing -### Development -- **[CONTRIBUTING.md](CONTRIBUTING.md)**: How to contribute -- **[TESTING.md](TESTING.md)**: Testing guides -- **[ROADMAP.md](ROADMAP.md)**: Future development plans +- [streamspace.wiki](https://github.com/streamspace-dev/streamspace.wiki) — Getting Started, deployment, plugin/template catalogs -### Project Management -- **[Project Board](https://github.com/orgs/streamspace-dev/projects/2)**: Live progress tracking -- **[Milestones](https://github.com/streamspace-dev/streamspace/milestones)**: Release planning -- **[Issues](https://github.com/streamspace-dev/streamspace/issues)**: Bug reports & feature requests +### API -## 🤝 Contributing +- Swagger UI at `/api/docs` (when API is running) +- [`docs/API_REFERENCE.md`](docs/API_REFERENCE.md) -Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first. +## Contributing -1. Fork the repository -2. Create your feature branch (`git checkout -b feature/amazing-feature`) -3. Commit your changes (`git commit -m 'Add some amazing feature'`) -4. Push to the branch (`git push origin feature/amazing-feature`) -5. Open a Pull Request +Contributions welcome — start with [`CONTRIBUTING.md`](CONTRIBUTING.md). The workflow is the standard fork → branch → PR pattern; see the project's [issue board](https://github.com/streamspace-dev/streamspace/issues) for triaged work. -## 📄 License +## License StreamSpace is licensed under the [MIT License](LICENSE). diff --git a/ROADMAP.md b/ROADMAP.md index 056409c..4f85df7 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,173 +1,73 @@
-# 🗺️ StreamSpace Roadmap +# StreamSpace Roadmap -**Current Version**: v2.0-beta • **Last Updated**: 2025-11-23 - -[![Status](https://img.shields.io/badge/Status-v2.0--beta--testing-yellow.svg)](CHANGELOG.md) +**Last Updated**: 2026-04-25
--- -> [!WARNING] -> **Current Status: v2.0-beta (Testing Phase - NOT Production Ready)** -> -> StreamSpace has completed the v2.0 architecture implementation (Control Plane + Multi-Platform Agents) but is experiencing a **test coverage crisis**. See [TEST_STATUS.md](TEST_STATUS.md) for details and remediation plan. -> -> **Critical**: API at 4% coverage, both agents at 0% coverage, 136 UI tests failing. - > [!NOTE] -> For detailed production hardening roadmap with 57 tracked improvements, see [.github/RECOMMENDATIONS_ROADMAP.md](.github/RECOMMENDATIONS_ROADMAP.md) - -## 📅 Release Timeline - -```mermaid -gantt - title StreamSpace Development Roadmap - dateFormat YYYY-MM-DD - section v1.0 - Core Platform :done, des1, 2025-10-01, 2025-11-01 - Admin UI :done, des2, 2025-11-01, 2025-11-15 - Security Hardening :done, des3, 2025-11-01, 2025-11-15 - v1.0 Release :done, des4, 2025-11-21, 1d - - section v2.0 (Current) - Architecture Design :done, v2_1, 2025-11-21, 1d - Control Plane :done, v2_2, 2025-11-21, 3d - K8s Agent :done, v2_3, 2025-11-21, 3d - VNC Proxy :done, v2_4, 2025-11-21, 2d - Integration Testing :active, v2_5, 2025-11-21, 7d - v2.0 Stable : v2_6, after v2_5, 1d - - section Future - Docker Agent (v2.1) : v2_7, after v2_6, 14d - VNC Independence : v3_0, 2026-01-01, 60d -``` - -## 🎯 Priorities - -### 1. Fix Broken Test Infrastructure (P0 - CRITICAL) - -- **Current**: Test suites failing, blocking all validation -- **Issues**: [#157](https://github.com/streamspace-dev/streamspace/issues/157), [#200-207](https://github.com/streamspace-dev/streamspace/issues) -- **Timeline**: 1-2 days -- **Tasks**: - - [ ] Fix API handler test panics ([#204](https://github.com/streamspace-dev/streamspace/issues/204)) - - [ ] Fix K8s agent test compilation ([#203](https://github.com/streamspace-dev/streamspace/issues/203)) - - [ ] Fix UI component import errors ([#207](https://github.com/streamspace-dev/streamspace/issues/207)) - - [ ] Fix WebSocket & Services test builds ([#204](https://github.com/streamspace-dev/streamspace/issues/204)) - -### 2. Critical Test Coverage (P0 - High Priority) - -- **Current**: API 4%, K8s Agent 0%, Docker Agent 0%, UI 32% -- **Target v2.0-beta.1**: API 40%, Agents 60%, UI 60% -- **Timeline**: 10-15 days (Phases 2-4 from TEST_STATUS.md) -- **Tasks**: - - [ ] Docker Agent test suite - 2,100 lines untested ([#201](https://github.com/streamspace-dev/streamspace/issues/201)) - - [ ] K8s Agent test suite - Leader election, VNC tunneling ([#203](https://github.com/streamspace-dev/streamspace/issues/203)) - - [ ] AgentHub multi-pod tests - Redis, cross-pod routing ([#202](https://github.com/streamspace-dev/streamspace/issues/202)) - - [ ] API handler tests - Session, VNC proxy, template endpoints ([#204](https://github.com/streamspace-dev/streamspace/issues/204)) - -### 3. Integration & E2E Testing (P1 - High Priority) - -- **Focus**: Validate complete v2.0 architecture end-to-end -- **Timeline**: 3-4 days (Phase 5 from TEST_STATUS.md) -- **Tasks**: - - [ ] VNC streaming E2E (Browser → Proxy → Agent → Container) ([#157](https://github.com/streamspace-dev/streamspace/issues/157)) - - [ ] Multi-pod API failover scenarios - - [ ] Agent leader election and failover - - [ ] Cross-platform session management (K8s + Docker) - - [ ] Performance benchmarking (session creation, VNC latency) - -### 4. Production Hardening (v2.0-beta.1 - P1) - -- **Current**: 57 improvements tracked in [RECOMMENDATIONS_ROADMAP.md](.github/RECOMMENDATIONS_ROADMAP.md) -- **Target v2.0-beta.1**: Security + Observability basics -- **Timeline**: ~20 hours after tests fixed -- **Priority Tasks**: - - [ ] Health check endpoints ([#158](https://github.com/streamspace-dev/streamspace/issues/158)) - - [ ] Security headers ([#165](https://github.com/streamspace-dev/streamspace/issues/165)) - - [ ] Rate limiting ([#163](https://github.com/streamspace-dev/streamspace/issues/163)) - - [ ] Structured logging ([#159](https://github.com/streamspace-dev/streamspace/issues/159)) - - [ ] Prometheus metrics ([#160](https://github.com/streamspace-dev/streamspace/issues/160)) - -### 5. Plugin Implementation (P2 - Medium Priority) - -- **Current**: Framework complete, 28 stub plugins, 0% tested -- **Target**: Working implementations for top 10 plugins -- **Priority**: Deferred until after test coverage fixed -- **Top Plugins**: - - Calendar, Slack, Teams, Discord, PagerDuty - - Compliance, DLP, Analytics - -## 🛤️ Detailed Roadmap - -### v1.0.0-READY (Completed) ✅ - -- **Core**: Functional Kubernetes platform -- **Auth**: Complete authentication stack (SAML, OIDC, MFA) -- **Admin**: Full admin UI and configuration -- **Security**: Production-hardened (Audit logs, RBAC, Security headers) - -### v2.0-beta (Current - Testing Phase) ⚠️ - -**Status**: Architecture complete, test coverage crisis - -**Completed**: -- ✅ Multi-platform Control Plane + Agent architecture -- ✅ Secure VNC Proxy (WebSocket tunneling, firewall-friendly) -- ✅ Kubernetes Agent (session lifecycle, leader election, VNC tunneling) -- ✅ Docker Agent (container lifecycle, HA backends) -- ✅ Multi-pod API (Redis-backed AgentHub) -- ✅ Real-time agent monitoring UI - -**Blocked**: -- ❌ **Test Infrastructure** - Multiple test suites broken ([#200](https://github.com/streamspace-dev/streamspace/issues/200)) -- ❌ **Test Coverage** - 4% API, 0% agents, 32% UI ([TEST_STATUS.md](TEST_STATUS.md)) -- ❌ **Production Readiness** - Cannot deploy without tests - -**Next**: Fix broken tests (1-2 days) → Comprehensive test coverage (10-15 days) → Production hardening (~20 hours) - -### v2.0-beta.1 (Target: After Test Coverage) 📝 - -**Prerequisites**: -- Test infrastructure fixed -- API 40%+ coverage -- Agents 60%+ coverage -- Integration tests passing +> Detailed in-flight work is tracked on the [GitHub project board](https://github.com/orgs/streamspace-dev/projects/2) and the [Milestones page](https://github.com/streamspace-dev/streamspace/milestones). This file is the high-level shape. -**Goals**: -- Production-ready security (rate limiting, input validation, security headers) -- Observability basics (health checks, structured logging, Prometheus metrics) -- Validated HA features (multi-pod API, agent leader election) -- Performance benchmarks documented +## Where the project is right now -### v2.1 (Future) 🔮 +The v2.0 architecture (Control Plane + multi-platform Agents) shipped. In April 2026 we paused to clean up artifacts from the previous multi-clone dev workflow, retire the dual VNC/Selkies streaming code path in favor of **Selkies-GStreamer (WebRTC) only**, and stand up an actual image build pipeline in [`streamspace-templates`](https://github.com/streamspace-dev/streamspace-templates). -- **Performance**: Redis caching, database optimization, frontend code splitting -- **UX**: Accessibility improvements, virtual scrolling, bulk operations -- **Features**: Plugin marketplace, advanced webhooks, multi-cloud support +The control plane and agents compile and run end-to-end. The next milestone reconstructs the golden path — *user logs in → picks Chrome → Chrome streams in their browser within 15 s* — and then iterates on whatever it surfaces. -### v3.0 (Future) 🔮 - -- **Streaming**: WebRTC support for lower latency -- **VNC**: Migration to TigerVNC + noVNC (native images) -- **Hardware**: GPU acceleration support -- **Federation**: Multi-cluster support +## Released -## 🤝 How to Contribute +### v2.0 -We welcome contributions! Here are the high-impact areas: +- Multi-platform Control Plane + Agent architecture +- Kubernetes Agent (session lifecycle, leader election) +- Docker Agent (container lifecycle, HA backends) +- Multi-pod API with Redis-backed AgentHub +- Multi-tenancy: org-scoped access, JWT claims, cross-tenant prevention +- 3 Grafana dashboards, 12 Prometheus alert rules +- OpenAPI 3.0 spec at `/api/docs` +- Security baseline: rate limiting, input validation, security headers, MFA, SSO (SAML/OIDC/OAuth2) -1. **Testing**: Help us reach our 80% coverage goal. -2. **Plugins**: Pick a stub plugin and implement it. -3. **Documentation**: Improve guides and examples. +## Active rebuild — April 2026 -See [CONTRIBUTING.md](CONTRIBUTING.md) for details. +Tracking on the [project board](https://github.com/orgs/streamspace-dev/projects/2). ---- +| Status | Item | +|---|---| +| ✅ | Strip 99 K lines of obsolete dev artifacts (`.claude/reports/`, multi-agent workflow files, plugins moved to sibling repo) | +| ✅ | Remove the VNC code path; rename agent ↔ control-plane fields to protocol-agnostic naming | +| ✅ | Stand up the image build pipeline in `streamspace-templates` (multi-arch, cosign-signed, SBOM-attested) | +| ✅ | Publish first custom image: `ghcr.io/streamspace-dev/chrome-selkies` | +| 🔄 | Reconcile docs (this repo's `docs/` + the wiki) against the post-cleanup reality | +| 📝 | Golden-path test: login → Chrome template → streaming in 15 s | +| 📝 | Selkies-native template catalog (replacing the inherited LinuxServer set, ~195 templates) | +| 📝 | Bug-fix sprint against whatever the golden-path surfaces | +| 📝 | Migrate `github.com/docker/docker` → `github.com/moby/moby/client` (the upstream module path moved) | -
- StreamSpace Roadmap -
+## Next: v2.1 + +- Performance: Redis cache audit, frontend code splitting, route-level lazy loading +- UX: accessibility (WCAG 2.1 AA), virtual scrolling on large tables, bulk session operations +- Plugin marketplace polish (discovery, install UX, signature verification) +- Multi-cloud onboarding (validated paths for EKS / GKE / AKS) +- Hardware-accelerated streaming (NVENC, VA-API) end-to-end through the chrome-selkies image + +## Future: v3.0 + +- Federation — multi-cluster sessions +- Pluggable streaming protocol — the architecture leaves the door open even though only Selkies ships today +- GPU scheduling: per-session GPU allocation with quotas +- Session recording with on-demand playback (currently a stub plugin) + +## How to contribute + +High-impact areas right now: + +1. **Image pipeline** — pick an app from the [streamspace-templates catalog](https://github.com/streamspace-dev/streamspace-templates) and ship a Selkies-native build under `images/`. +2. **Bug triage** — work through the open [issues](https://github.com/streamspace-dev/streamspace/issues), close the ones that the recent rebuild already resolved. +3. **Docs** — the [wiki](https://github.com/streamspace-dev/streamspace.wiki) is the user-facing entry point; getting-started and template-catalog pages need updating to match the new pipeline. +4. **Plugins** — pick a stub from [`streamspace-plugins`](https://github.com/streamspace-dev/streamspace-plugins) and turn it into a working implementation. + +Start with [`CONTRIBUTING.md`](CONTRIBUTING.md). diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 9454f0a..d97cc98 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -44,7 +44,7 @@ graph TD K8sFollower1 <-->|WebSocket| API K8sFollower2 <-->|WebSocket| API K8sLeader -->|Manage| Pods[Session Pods] - API -.->|VNC Proxy| K8sLeader + API -.->|Selkies Proxy| K8sLeader K8sLeader -.->|Tunnel| Pods end @@ -54,7 +54,7 @@ graph TD DockerLeader <-->|WebSocket| API DockerFollower <-->|WebSocket| API DockerLeader -->|Manage| Containers[Session Containers] - API -.->|VNC Proxy| DockerLeader + API -.->|Selkies Proxy| DockerLeader DockerLeader -.->|Tunnel| Containers end ``` @@ -156,7 +156,7 @@ graph TD - **Min Replicas**: 2 (for HA) - **Max Replicas**: 10 (recommended) - **Target CPU**: 70% utilization -- **Session Affinity**: Sticky sessions for WebSocket connections (required for VNC) +- **Session Affinity**: Sticky sessions for WebSocket connections (required for the Selkies signaling channel and the agent WebSocket Hub) **Deployment Command:** ```bash @@ -394,24 +394,23 @@ graph TB - **Role**: Central brain of the system. - **Tech**: Go (Gin framework). - **Responsibilities**: - - User Authentication & Authorization (SAML, OIDC). - - Session Management (CRUD). - - Agent Coordination (WebSocket Hub). - - VNC Proxying (Secure tunneling). - - Database Management. + - User authentication & authorization (SAML, OIDC, MFA). + - Session management (CRUD). + - Agent coordination (WebSocket Hub). + - **Selkies HTTP/WebRTC reverse proxy** at `/api/v1/http//` — token-authenticated, forwards to the session pod's Selkies endpoint on port 8080. + - Database management. ### 2. Execution Agents - **Role**: Platform-specific executors. - **Tech**: Go. - **Types**: - - **Kubernetes Agent**: Manages Pods, PVCs, Services with leader election (v2.0-beta.1). - - **Docker Agent**: Manages Containers, Volumes with HA backends (v2.0-beta.1). + - **Kubernetes Agent**: Manages Pods, PVCs, Services with leader election. + - **Docker Agent**: Manages Containers, Volumes with HA backends. - **Responsibilities**: - Connect to Control Plane via secure WebSocket. - Execute commands (Start, Stop, Hibernate). - - Report status and metrics (Heartbeats). - - Tunnel VNC traffic. + - Report status and metrics (Heartbeats, `streamingReady`/`streamingPort`). - Participate in leader election for High Availability. ### 3. Web UI @@ -419,18 +418,19 @@ graph TB - **Role**: User interface. - **Tech**: React + TypeScript + Material-UI. - **Features**: - - Dashboard & Catalog. - - Session Viewer (noVNC integration). - - Admin Panel (User, Agent, Plugin management). + - Dashboard & catalog. + - Session Viewer — embeds the Selkies endpoint via `