handlers

Overview ¶

Package handlers provides HTTP handlers for the StreamSpace API. This file implements session activity tracking and heartbeat management.

ACTIVITY TRACKING: - Session heartbeat recording to prevent auto-hibernation - Activity status queries (active, idle, hibernation eligibility) - Idle duration calculation - Last activity timestamp tracking

HEARTBEAT MECHANISM: - Clients send periodic heartbeats to indicate active usage - Updates session's lastActivity timestamp - Prevents idle timeout and auto-hibernation - Typically sent every 30-60 seconds from active sessions

ACTIVITY STATUS: - Is session currently active (recent heartbeat) - Is session idle (exceeded idle threshold) - Time since last activity - Should session be hibernated (idle + threshold exceeded) - Configurable idle thresholds per session

USE CASES: - Auto-hibernation prevention for active sessions - Resource optimization by hibernating idle sessions - User activity analytics - Session health monitoring

API Endpoints: - POST /api/v1/sessions/:id/heartbeat - Record session heartbeat - GET /api/v1/sessions/:id/activity - Get session activity status

Thread Safety: - Activity tracker is thread-safe with mutex protection - Kubernetes client operations are thread-safe

Dependencies: - Kubernetes: Session CRDs with status updates - Activity Tracker: In-memory tracking with persistence - External Services: None

Example Usage:

handler := NewActivityHandler(k8sClient, activityTracker)
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements the WebSocket handler for agent connections.

AGENT WEBSOCKET CONNECTION: - Agents connect to GET /api/v1/agents/connect?agent_id=xxx - Connection is upgraded from HTTP to WebSocket - Agent sends heartbeats every 10 seconds - Control Plane sends commands to agent - Agent sends back ack/complete/failed/status messages

MESSAGE FLOW: Control Plane → Agent:

• command: Execute a session command
• ping: Keep-alive ping
• shutdown: Graceful shutdown

Agent → Control Plane:

• heartbeat: Regular status update
• ack: Command acknowledged
• complete: Command completed
• failed: Command failed
• status: Session status update

CONNECTION LIFECYCLE: 1. Agent sends HTTP GET to /api/v1/agents/connect?agent_id=xxx 2. Handler validates agent exists in database 3. HTTP connection upgraded to WebSocket 4. Connection registered with AgentHub 5. readPump and writePump goroutines started 6. Agent sends heartbeats every 10 seconds 7. On disconnect, connection unregistered from hub

Thread Safety: - readPump and writePump run concurrently - Each connection has dedicated Send/Receive channels - Hub handles all synchronization

Package handlers provides HTTP handlers for the StreamSpace API. This file implements agent registration and management for the v2.0 multi-platform architecture.

AGENT ARCHITECTURE: - Agents are platform-specific execution agents (Kubernetes, Docker, VM, Cloud) - Agents connect to Control Plane via outbound WebSocket connection - Agents receive commands to start/stop/hibernate sessions - Agents tunnel VNC traffic back to Control Plane - Agents send heartbeats every 10 seconds

AGENT PLATFORMS: - kubernetes: Kubernetes cluster agent - docker: Docker host agent - vm: Virtual machine agent - cloud: Cloud provider agent (AWS, Azure, GCP)

AGENT STATUS: - online: Agent is connected and healthy - offline: Agent is disconnected - draining: Agent is not accepting new sessions

API Endpoints: - POST /api/v1/agents/register - Register agent (or re-register) - GET /api/v1/agents - List all agents (with filters) - GET /api/v1/agents/:agent_id - Get agent details - DELETE /api/v1/agents/:agent_id - Deregister agent - POST /api/v1/agents/:agent_id/heartbeat - Update heartbeat - POST /api/v1/agents/:agent_id/command - Send command to agent

Thread Safety: - All database operations are thread-safe

Dependencies: - Database: agents table (v2.0 schema) - Models: api/internal/models/agent.go - AgentHub: WebSocket connection manager - CommandDispatcher: Command queuing and dispatch

Example Usage:

handler := NewAgentHandler(database)
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements API key management for programmatic API access.

API KEY FEATURES: - Secure API key generation with cryptographic randomness - API key CRUD operations (create, list, revoke, delete) - Key metadata (name, description, scopes, rate limits) - Expiration support with configurable durations - Usage tracking (last used timestamp, use count) - Active/inactive state management

SECURITY: - Keys hashed with SHA-256 before storage (never stored in plaintext) - Prefix-based identification (first 8 characters for UI display) - Keys prefixed with "sk_" for easy identification - 32 bytes of cryptographic randomness (256 bits) - Keys only shown once during creation (cannot be retrieved later)

API KEY STRUCTURE: - Format: sk_{base64_encoded_random_bytes} - Storage: SHA-256 hash in database - Display: First 8 characters (sk_xxxxx...)

SCOPE MANAGEMENT: - Configurable scopes limit API key permissions - Examples: sessions:read, sessions:write, admin:all - Scope validation during API requests

RATE LIMITING: - Per-key rate limits independent of user limits - Configurable requests per time window - Tracked via use_count and last_used_at

EXPIRATION: - Optional expiration with duration strings (30d, 1y, etc.) - Automatic enforcement during authentication - Expired keys cannot authenticate

API Endpoints: - POST /api/v1/apikeys - Create new API key - GET /api/v1/apikeys - List user's API keys - GET /api/v1/apikeys/:id - Get API key details - PUT /api/v1/apikeys/:id - Update API key metadata - DELETE /api/v1/apikeys/:id - Delete/revoke API key - POST /api/v1/apikeys/:id/rotate - Rotate API key (generate new)

Thread Safety: - All database operations are thread-safe via connection pooling - Cryptographic random generation is thread-safe

Dependencies: - Database: api_keys table - External Services: None

Example Usage:

handler := NewAPIKeyHandler(database)
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements installed application management endpoints.

APPLICATION FEATURES: - Install applications from catalog templates - Custom display names for user dashboards - Application configuration management - Enable/disable applications - Group-based access control

ACCESS CONTROL: - Grant/revoke group access to applications - Multiple access levels (view, launch, admin) - Filter applications by user's group membership

API Endpoints: - GET /api/v1/applications - List all installed applications - POST /api/v1/applications - Install a new application - GET /api/v1/applications/:id - Get application details - PUT /api/v1/applications/:id - Update application - DELETE /api/v1/applications/:id - Delete application - PUT /api/v1/applications/:id/enabled - Enable/disable application - GET /api/v1/applications/:id/groups - Get groups with access - POST /api/v1/applications/:id/groups - Add group access - PUT /api/v1/applications/:id/groups/:groupId - Update group access level - DELETE /api/v1/applications/:id/groups/:groupId - Remove group access - GET /api/v1/applications/:id/config - Get template config options - GET /api/v1/applications/user - Get applications accessible to current user

Thread Safety: - All database operations are thread-safe via connection pooling

Dependencies: - Database: installed_applications, application_group_access tables

Example Usage:

handler := NewApplicationHandler(database, publisher, "kubernetes")
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements audit log retrieval and export for compliance and security.

AUDIT LOG VIEWER: - Retrieve audit logs with filtering and pagination - Export audit logs for compliance reports (CSV/JSON) - Search and analyze security events - Track user activity and system changes

COMPLIANCE SUPPORT: - SOC2: Audit trail of all system changes (1 year retention) - HIPAA: PHI access logging (6 year retention) - GDPR: Data processing activity records - ISO 27001: User activity logging

FILTERING CAPABILITIES: - Filter by user ID or username - Filter by action (GET, POST, PUT, DELETE) - Filter by resource type (/api/sessions, /api/users, etc.) - Filter by date range (start_date, end_date) - Filter by IP address (security investigations) - Filter by status code (200, 401, 500, etc.)

EXPORT FORMATS: - JSON: Machine-readable, full details - CSV: Human-readable, spreadsheet-compatible - Both formats include all relevant fields for compliance

USE CASES: - Security incident investigation - Compliance audits and reporting - User activity analysis - System change tracking - Failed access attempt detection

API Endpoints: - GET /api/v1/admin/audit - List audit logs (with filters) - GET /api/v1/admin/audit/:id - Get specific audit log entry - GET /api/v1/admin/audit/export - Export audit logs to CSV/JSON

Thread Safety: - Database operations are thread-safe - Read-only queries, no state modification

Dependencies: - Database: PostgreSQL audit_log table - Middleware: Audit logging middleware (captures all requests)

Example Usage:

handler := NewAuditHandler(database)
handler.RegisterRoutes(router.Group("/api/v1/admin"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements batch operations for bulk resource management.

BATCH OPERATION FEATURES: - Bulk session operations (terminate, hibernate, wake, delete) - Bulk snapshot operations (create, delete) - Bulk template operations (install, delete) - Asynchronous job execution with progress tracking - Job status monitoring and cancellation

OPERATION TYPES: - terminate: Stop multiple running sessions - hibernate: Put multiple sessions into hibernated state - wake: Resume multiple hibernated sessions - delete: Remove multiple sessions/snapshots/templates - update: Bulk update tags or resource limits

BATCH JOB LIFECYCLE: 1. Job creation: Create batch_operations record 2. Async execution: Process items in background goroutine 3. Progress tracking: Update processed/success/failure counts 4. Completion: Mark job as completed or failed 5. Cleanup: Jobs can be cancelled or deleted

JOB STATUS TRACKING: - Total items to process - Processed items count - Success count - Failure count - Errors array for failed items - Created/completed timestamps

ASYNC EXECUTION: - All batch operations run asynchronously - Immediate job ID returned to client - Client polls job status endpoint for progress - WebSocket notifications for real-time updates

ERROR HANDLING: - Partial failures: Continue processing remaining items - Error collection: Record all errors for debugging - Job status reflects overall success/failure

API Endpoints: - POST /api/v1/batch/sessions/terminate - Terminate multiple sessions - POST /api/v1/batch/sessions/hibernate - Hibernate multiple sessions - POST /api/v1/batch/sessions/wake - Wake multiple sessions - POST /api/v1/batch/sessions/delete - Delete multiple sessions - POST /api/v1/batch/sessions/update-tags - Update session tags - POST /api/v1/batch/sessions/update-resources - Update resource limits - POST /api/v1/batch/snapshots/delete - Delete multiple snapshots - POST /api/v1/batch/snapshots/create - Create multiple snapshots - POST /api/v1/batch/templates/install - Install multiple templates - POST /api/v1/batch/templates/delete - Delete multiple templates - GET /api/v1/batch/jobs - List batch jobs - GET /api/v1/batch/jobs/:id - Get batch job status - DELETE /api/v1/batch/jobs/:id - Cancel batch job

Thread Safety: - All database operations are thread-safe via connection pooling - Goroutines for async execution are properly managed

Dependencies: - Database: batch_operations, sessions, snapshots, templates tables - External Services: None

Example Usage:

handler := NewBatchHandler(database)
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements template catalog browsing, ratings, and statistics.

CATALOG FEATURES: - Template discovery with advanced search and filtering - Featured, trending, and popular template lists - User ratings and reviews system - View and install tracking for analytics

SEARCH AND FILTERING: - Full-text search across template names and descriptions - Filter by category, tags, app type - Sort by popularity, rating, recency, or install count - Pagination support with customizable page size

RATINGS AND REVIEWS: - Add, update, and delete template ratings - Star ratings (1-5 scale) - User comments and reviews - Average rating calculation - Rating count tracking

STATISTICS: - View count tracking (catalog impressions) - Install count tracking (template usage) - Trending calculation based on recent activity - Popular templates based on install count

API Endpoints: - GET /api/v1/catalog/templates - List templates with filters and search - GET /api/v1/catalog/templates/:id - Get template details - GET /api/v1/catalog/templates/featured - List featured templates - GET /api/v1/catalog/templates/trending - List trending templates - GET /api/v1/catalog/templates/popular - List popular templates - POST /api/v1/catalog/templates/:id/ratings - Add rating/review - GET /api/v1/catalog/templates/:id/ratings - Get template ratings - PUT /api/v1/catalog/templates/:id/ratings/:ratingId - Update rating - DELETE /api/v1/catalog/templates/:id/ratings/:ratingId - Delete rating - POST /api/v1/catalog/templates/:id/view - Record template view - POST /api/v1/catalog/templates/:id/install - Record template install

Thread Safety: - All database operations are thread-safe via connection pooling

Dependencies: - Database: catalog_templates, repositories, template_ratings tables - External Services: Repository sync for template metadata

Example Usage:

handler := NewCatalogHandler(database)
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers - collaboration.go ¶

This file implements real-time collaboration features for StreamSpace sessions.

Collaboration System Overview ¶

The collaboration system enables multiple users to work together in a single session with features like chat, annotations, cursor tracking, and screen sharing. This transforms StreamSpace from single-user isolated sessions into a collaborative platform for remote teamwork.

Use Cases ¶

**Pair Programming**:

• Developer A creates session with VS Code
• Developer B joins as collaborator with control permissions
• Both can see cursor positions and type code
• Chat for quick questions without switching context

**Teaching/Training**:

• Instructor creates session with training application
• Students join as viewers (read-only)
• Instructor uses annotations to highlight important areas
• Follow mode keeps students in sync with instructor's view

**Support/Troubleshooting**:

• User creates session with problematic application
• Support agent joins with control permissions
• Agent diagnoses issue while user watches
• Chat for real-time communication

**Design Review**:

• Designer creates session with design tool
• Team joins as participants
• Annotations for feedback directly on designs
• Hand-raise feature for structured Q&A

Architecture ¶

Collaboration combines WebSocket (real-time) + database (persistence):

┌────────────────────────────────────────────────────────┐
│                  Collaboration Session                 │
│  - Owner creates session                               │
│  - Participants join via invite/link                   │
│  - Real-time sync via WebSocket                        │
│  - State persisted to database                         │
└──────────────┬─────────────────────────────────────────┘
               │
       ┌───────┴───────┬─────────────┬─────────────┐
       ▼               ▼             ▼             ▼
   Owner          Presenter     Participant    Viewer
 (Full access)  (Can control)  (Can chat)   (Read-only)

**WebSocket Integration**:

• Cursor movements broadcast to all participants
• Chat messages delivered in real-time
• Annotations synced across all viewers
• Presence updates (user joined/left)

**Database Persistence**:

• Collaboration sessions stored in collaboration_sessions table
• Participants tracked in collaboration_participants table
• Chat history in collaboration_messages table
• Annotations in collaboration_annotations table

Permission Model ¶

Collaboration uses a role-based permission system:

**Owner Role** (session creator):

• Full control over session
• Can change settings
• Can promote/demote participants
• Can end collaboration
• Cannot be removed

**Presenter Role** (co-host):

• Can control the session
• Can annotate and chat
• Can invite others
• Others can follow their view
• Can be demoted by owner

**Participant Role** (active user):

• Can chat and annotate
• Can view cursor positions
• Cannot control session
• Limited to max participants count

**Viewer Role** (read-only):

• Can only view session
• Cannot interact or chat
• Unlimited viewers allowed
• Useful for webinars/demos

Permissions are granular:

• can_control: Mouse/keyboard input
• can_annotate: Draw on screen
• can_chat: Send messages
• can_invite: Add participants
• can_manage: Change settings
• can_record: Start recording

Real-Time Features ¶

**Cursor Tracking**:

• Each user's cursor shown with their color and label
• Position updated every 50ms (throttled)
• Cursors fade after 5s of inactivity
• Can be disabled in settings

**Chat System**:

• Text messages with timestamps
• System messages (user joined, settings changed)
• Reactions (emoji responses to messages)
• Message history persisted
• Can be disabled by owner

**Annotations**:

• Drawing tools: line, arrow, rectangle, circle, freehand
• Text annotations
• Color and thickness customization
• Persistent vs temporary (expires after 30s)
• Can be cleared by owner/presenter

**Follow Mode**:

• Follow presenter: Viewers automatically pan/zoom with presenter
• Follow owner: Alternative mode for presentations
• Can be toggled on/off by participants
• Prevents viewer viewport drift

Concurrency Handling ¶

Multiple users interacting simultaneously requires careful synchronization:

1. **Optimistic Locking**: Annotations use version numbers
2. **Event Ordering**: WebSocket messages timestamped for consistency
3. **Conflict Resolution**: Last-write-wins for cursor positions
4. **Rate Limiting**: Max 100 events/sec per user (prevent spam)

Example conflict scenario:

• User A and User B both create annotation at same time
• Both annotations stored with timestamps
• UI renders both (no conflict)
• If same annotation ID, newer timestamp wins

Performance Characteristics ¶

Performance metrics (tested with 50 concurrent collaborators):

• **Cursor latency**: <50ms from movement to display on other screens
• **Chat latency**: <100ms from send to delivery
• **Annotation sync**: <200ms for complex drawings
• **Memory per session**: ~5 MB (includes cursor positions, annotations)
• **Database queries**: ~10 queries/sec for active 10-user session

Scaling limits:

• **Recommended max**: 10 active participants (can_control)
• **Tested max**: 50 viewers (read-only)
• **Bottleneck**: WebSocket broadcast bandwidth

Security Considerations ¶

Collaboration introduces new attack vectors:

1. **Invitation System**: Only owner can invite (no public join)
2. **Approval Mode**: Owner approves join requests (optional)
3. **Permission Enforcement**: Server validates all actions
4. **Input Sanitization**: Chat messages and annotations sanitized
5. **Rate Limiting**: Prevent spam/DoS via excessive cursors/annotations

Prevented attacks:

• **Unauthorized join**: JWT + session ownership verified
• **Privilege escalation**: Roles cannot be self-promoted
• **XSS in chat**: All messages HTML-escaped
• **DoS via annotations**: Max 100 annotations per user

Database Schema ¶

**collaboration_sessions**:

• id, session_id, owner_id, settings, status, created_at, ended_at

**collaboration_participants**:

• id, collaboration_id, user_id, role, permissions, joined_at, last_seen_at

**collaboration_messages**:

• id, collaboration_id, user_id, message, message_type, created_at

**collaboration_annotations**:

• id, collaboration_id, user_id, type, points, is_persistent, created_at

**collaboration_cursors** (in-memory only, not persisted):

• user_id, x, y, timestamp, color

Known Limitations ¶

1. **Single instance**: No cross-server collaboration (yet)
2. **No video/audio**: Text chat only (no voice calling)
3. **No screen regions**: Can't restrict viewer to specific area
4. **No undo/redo**: Annotations permanent until deleted
5. **No file sharing**: Chat is text-only

Future enhancements:

• WebRTC for audio/video calling
• Multi-server collaboration via Redis
• Recording collaboration sessions
• Annotation history with undo/redo
• File sharing in chat
• Breakout rooms for sub-groups

Example Usage ¶

**Creating a collaboration session**:

POST /api/sessions/{sessionId}/collaboration
{
    "settings": {
        "follow_mode": "follow_presenter",
        "max_participants": 10,
        "require_approval": true,
        "show_cursor_labels": true
    }
}

**Joining a collaboration session**:

POST /api/collaboration/{collabId}/join
{
    "role": "participant"
}

**Sending chat message**:

POST /api/collaboration/{collabId}/chat
{
    "message": "Hello team!"
}

**Creating annotation**:

POST /api/collaboration/{collabId}/annotations
{
    "type": "arrow",
    "points": [{"x": 100, "y": 100}, {"x": 200, "y": 200}],
    "color": "#FF0000",
    "is_persistent": true
}

Package handlers provides HTTP handlers for the StreamSpace API. This file implements system configuration management for platform settings.

SYSTEM CONFIGURATION: - CRUD operations for platform-wide settings - Category-based organization (Ingress, Storage, Resources, Features, Session, Security, Compliance) - Type-aware validation (string, boolean, number, duration, enum, array) - Configuration testing before applying changes - Change history tracking

CONFIGURATION CATEGORIES: 1. Ingress: domain, TLS settings 2. Storage: storage class, default sizes, allowed classes 3. Resources: default CPU/memory limits, max limits 4. Features: feature toggles (metrics, hibernation, recordings) 5. Session: idle timeout, max duration, allowed images 6. Security: MFA required, SAML/OIDC enabled, IP whitelist 7. Compliance: frameworks enabled, retention days, archiving

USE CASES: - Platform deployment configuration - Feature flag management - Resource limit enforcement - Security policy configuration - Compliance settings management

API Endpoints: - GET /api/v1/admin/config - List all settings (optional category filter) - GET /api/v1/admin/config/:key - Get specific setting - PUT /api/v1/admin/config/:key - Update setting with validation - POST /api/v1/admin/config/bulk - Bulk update multiple settings

Thread Safety: - Database operations are thread-safe - Validation happens before update

Dependencies: - Database: PostgreSQL configuration table

Example Usage:

handler := NewConfigurationHandler(database)
handler.RegisterRoutes(router.Group("/api/v1/admin"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements console access and file management for sessions.

CONSOLE FEATURES: - Interactive terminal access to sessions via WebSocket - File manager for browsing session filesystems - File operations (create, delete, rename, copy, move, upload, download) - Multi-shell support (bash, sh, zsh) - Terminal resize and configuration

TERMINAL SESSIONS: - WebSocket-based terminal connections - Configurable rows and columns - Shell type selection (bash, sh, zsh) - Activity tracking and idle timeout - Terminal status monitoring

FILE MANAGEMENT: - Directory browsing with file metadata - File/directory creation and deletion - File rename, copy, and move operations - File upload and download - Permissions, ownership, and size information - MIME type detection - Symlink target resolution

FILE OPERATIONS: - Create: Create new files or directories - Delete: Remove files or directories - Rename: Rename files or directories - Copy: Duplicate files or directories - Move: Move files between locations - Upload: Upload files to session - Download: Download files from session

SECURITY: - Access control via session ownership or sharing - User authentication required - Path validation to prevent directory traversal - Permission checks for file operations

API Endpoints: - POST /api/v1/sessions/:sessionId/console - Create console session - GET /api/v1/console/:consoleId - Get console session details - DELETE /api/v1/console/:consoleId - Disconnect console session - GET /api/v1/console/:consoleId/files - List files in directory - POST /api/v1/console/:consoleId/files - Create file/directory - DELETE /api/v1/console/:consoleId/files - Delete file/directory - PUT /api/v1/console/:consoleId/files/rename - Rename file/directory - POST /api/v1/console/:consoleId/files/copy - Copy file/directory - POST /api/v1/console/:consoleId/files/move - Move file/directory - POST /api/v1/console/:consoleId/files/upload - Upload files - GET /api/v1/console/:consoleId/files/download - Download files

Thread Safety: - All database operations are thread-safe via connection pooling - File operations are isolated per session

Dependencies: - Database: console_sessions, sessions, session_shares tables - External Services: Session container filesystem access

Example Usage:

// Create console handler (integrated in main handler)
handler.RegisterConsoleRoutes(router.Group("/api/v1"))

Package handlers defines constants for HTTP handlers.

This file centralizes all "magic numbers" and timeout values to: - Make configuration changes easier (single source of truth) - Improve code readability (named constants vs. bare numbers) - Document the reasoning behind specific values - Enable easy tuning for different environments

SECURITY FIX (2025-11-14): Extracted all magic numbers to named constants as part of code quality improvements. This makes it easier to understand security-critical values like rate limits, timeouts, and buffer sizes.

Categories: - MFA: Multi-factor authentication limits and timing - WebSocket: Connection parameters and buffer sizes - Webhook: Retry logic and timeouts - Session: Verification and expiry times

Package handlers provides HTTP handlers for the StreamSpace API. This file implements dashboard statistics and resource usage queries.

DASHBOARD FEATURES: - Platform-wide statistics (users, sessions, templates, connections) - Resource usage tracking (CPU, memory, storage quotas) - Recent activity metrics (last 24 hours) - Real-time data from Kubernetes and database

PLATFORM STATISTICS: - Total and active user counts - Session counts by state (running, hibernated, total) - Template count from Kubernetes CRDs - Active connection count - 24-hour activity metrics

RESOURCE USAGE: - Quota utilization per user or platform-wide - CPU usage (millicores) - Memory usage (bytes/GB) - Storage usage (bytes/GB) - Session count against quotas

DATA SOURCES: - Database: User, session, connection tables - Kubernetes: Template CRDs, resource quotas - Hybrid queries for comprehensive metrics

API Endpoints: - GET /api/v1/dashboard/platform-stats - Overall platform statistics - GET /api/v1/dashboard/resource-usage - Resource usage metrics

Thread Safety: - All database operations are thread-safe via connection pooling - Kubernetes client operations are thread-safe

Dependencies: - Database: users, sessions, connections tables - Kubernetes: Template CRDs, namespace resources - External Services: None

Example Usage:

handler := NewDashboardHandler(database, k8sClient)
// Routes registered in main API router

Package handlers provides HTTP handlers for the StreamSpace API. This file implements API documentation endpoints serving OpenAPI/Swagger specification and interactive documentation UI.

ENDPOINTS: - GET /api/docs - Swagger UI (interactive documentation) - GET /api/docs/ - Swagger UI (with trailing slash) - GET /api/openapi.yaml - OpenAPI 3.0 specification (YAML) - GET /api/openapi.json - OpenAPI 3.0 specification (JSON)

FEATURES: - Embedded Swagger UI via CDN (no local assets required) - OpenAPI 3.0 compliant specification - YAML and JSON format support - No authentication required (public documentation)

Package handlers provides HTTP handlers for the StreamSpace API. This file implements group management and group-level resource operations.

GROUP MANAGEMENT: - Group CRUD operations (list, create, read, update, delete) - Group filtering by type or parent group (supports hierarchical groups) - Group member management (add, remove, update roles) - Member enrichment with user information

GROUP MEMBERSHIP: - Add users to groups with specific roles - Remove users from groups - Update member roles within groups - List all members with enriched user details - User existence validation before adding to groups

GROUP QUOTAS: - Shared resource quotas for group members - Group-level limits for sessions, CPU, memory, storage - Quota retrieval and modification

API Endpoints: - GET /api/v1/groups - List all groups with optional filters - POST /api/v1/groups - Create new group - GET /api/v1/groups/:id - Get group by ID - PATCH /api/v1/groups/:id - Update group information - DELETE /api/v1/groups/:id - Delete group - GET /api/v1/groups/:id/members - List group members - POST /api/v1/groups/:id/members - Add user to group - DELETE /api/v1/groups/:id/members/:userId - Remove user from group - PATCH /api/v1/groups/:id/members/:userId - Update member role - GET /api/v1/groups/:id/quota - Get group quota - PUT /api/v1/groups/:id/quota - Set group quota

Security: - Password hashes removed from user objects in member lists - User existence validated before membership operations

Thread Safety: - All database operations are thread-safe via connection pooling

Dependencies: - Database: groups, group_members, group_quotas, users tables - External Services: None

Example Usage:

handler := NewGroupHandler(groupDB, userDB)
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements enterprise integration features including webhooks and external API integrations.

Security Features: - Webhook HMAC signature validation (prevents spoofing) - SSRF protection for webhook URLs (prevents internal network access) - Input validation for all integration configurations - Secret management (webhooks secrets never exposed in GET responses) - Authorization enumeration prevention (consistent error responses)

CRITICAL SECURITY FIXES (2025-11-14): 1. SSRF Protection: validateWebhookURL prevents webhooks from targeting:

• Private IP ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)

• Loopback addresses (127.0.0.0/8)

• Link-local addresses (169.254.0.0/16)

• Cloud metadata endpoints (169.254.169.254)

• Internal hostnames (metadata.google.internal, localhost, etc.)

  2. Secret Protection: Webhook secrets use json:"-" tags and separate response structs to ensure secrets are only shown during creation, never in GET endpoints.

  3. Authorization Enumeration Fixes: UpdateWebhook, DeleteWebhook, TestWebhook, and TestIntegration all return consistent "not found" errors for both non-existent resources AND unauthorized access (prevents attacker enumeration).

  4. Input Validation: Comprehensive validation for all webhook and integration fields including URL format, name length, event counts, retry configuration, etc.

Webhook Delivery: - Automatic retries with exponential backoff - HMAC-SHA256 signature in X-Webhook-Signature header - 10-second timeout per delivery attempt - Real-time delivery status updates via WebSocket

Integrations: - External API connections (Slack, Discord, PagerDuty, etc.) - OAuth 2.0 token management - API key storage and rotation - Connection health monitoring

Package handlers provides HTTP handlers for the StreamSpace API. This file implements license management for platform licensing and feature enforcement.

LICENSE MANAGEMENT: - License activation and validation - Feature toggling based on tier (Community, Pro, Enterprise) - Resource limit enforcement (users, sessions, nodes) - Usage tracking and trending - License expiration monitoring

LICENSE TIERS: - Community (Free): 10 users, 20 sessions, 3 nodes, basic auth only - Pro: 100 users, 200 sessions, 10 nodes, SAML/OIDC/MFA/recordings - Enterprise: Unlimited users/sessions/nodes, all features + SLA

API Endpoints: - GET /api/v1/admin/license - Get current license details - POST /api/v1/admin/license/activate - Activate new license key - PUT /api/v1/admin/license/update - Update/renew license - GET /api/v1/admin/license/usage - Current usage vs. limits - POST /api/v1/admin/license/validate - Validate license key - GET /api/v1/admin/license/history - Usage history

Thread Safety: - Database operations are thread-safe - License checks cached for performance

Dependencies: - Database: PostgreSQL licenses and license_usage tables

Example Usage:

handler := NewLicenseHandler(database)
handler.RegisterRoutes(router.Group("/api/v1/admin"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements load balancing policies and node distribution strategies for sessions.

LOAD BALANCING FEATURES: - Multiple load balancing strategies (round robin, least loaded, resource-based, geographic, weighted) - Node health monitoring and status tracking - Resource-based scheduling (CPU, memory thresholds) - Session affinity (sticky sessions) - Node selector and taints support - Geographic distribution preferences - Weighted node distribution

LOAD BALANCING STRATEGIES: - round_robin: Distribute sessions evenly across nodes in rotation - least_loaded: Schedule on node with fewest active sessions - resource_based: Schedule based on available CPU/memory resources - geographic: Prefer nodes in specific regions/zones - weighted: Distribute based on configured node weights

NODE HEALTH MONITORING: - Periodic health checks with configurable intervals - Failure and pass thresholds before status changes - Node readiness tracking from Kubernetes - Resource utilization monitoring - Health status: healthy, unhealthy, unknown

RESOURCE THRESHOLDS: - Maximum CPU percentage before avoiding node - Maximum memory percentage before avoiding node - Maximum concurrent sessions per node - Minimum free CPU cores required - Minimum free memory required

SESSION AFFINITY: - Sticky sessions to maintain user experience - Session-to-node mapping persistence - Reconnection to same node

API Endpoints: - GET /api/v1/loadbalancing/policies - List load balancing policies - POST /api/v1/loadbalancing/policies - Create load balancing policy - GET /api/v1/loadbalancing/policies/:id - Get policy details - PUT /api/v1/loadbalancing/policies/:id - Update policy - DELETE /api/v1/loadbalancing/policies/:id - Delete policy - GET /api/v1/loadbalancing/nodes - List cluster nodes with status - GET /api/v1/loadbalancing/nodes/:name - Get node details - GET /api/v1/loadbalancing/nodes/:name/sessions - Get sessions on node - POST /api/v1/loadbalancing/select-node - Select best node for session

Thread Safety: - All database operations are thread-safe via connection pooling - Kubernetes client operations are thread-safe

Dependencies: - Database: load_balancing_policies table - Kubernetes: Node metrics, resource status - External Services: Kubernetes metrics server

Example Usage:

// Create load balancing handler (integrated in main handler)
handler.RegisterLoadBalancingRoutes(router.Group("/api/v1"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements monitoring, metrics, health checks, and alerting endpoints.

MONITORING FEATURES: - Prometheus-compatible metrics export - Custom application metrics (sessions, users, resources) - Health check endpoints (liveness, readiness) - Performance metrics (response times, throughput) - System resource metrics (CPU, memory, goroutines) - Alert management (create, acknowledge, resolve)

METRICS EXPORT: - Prometheus format (/monitoring/metrics/prometheus) - Session metrics (total, running, hibernated) - User metrics (total, active) - Resource metrics (CPU, memory, storage usage) - Performance metrics (response time percentiles)

HEALTH CHECKS: - Basic health: /monitoring/health (200 if API is responding) - Detailed health: Database, storage, Kubernetes connectivity - Database health: Connection pool status, query latency - Storage health: NFS mount status, disk space

SYSTEM METRICS: - Go runtime stats (goroutines, memory, GC) - Build information (version, git commit, build time) - Uptime and request counts - Resource usage trends

ALERTING: - Create, read, update, delete alerts - Acknowledge and resolve workflows - Alert severity levels (info, warning, error, critical) - Alert filtering and querying

API Endpoints: - GET /api/v1/monitoring/metrics/prometheus - Prometheus metrics - GET /api/v1/monitoring/metrics/sessions - Session metrics - GET /api/v1/monitoring/metrics/resources - Resource metrics - GET /api/v1/monitoring/metrics/users - User metrics - GET /api/v1/monitoring/metrics/performance - Performance metrics - GET /api/v1/monitoring/health - Basic health check - GET /api/v1/monitoring/health/detailed - Detailed health check - GET /api/v1/monitoring/health/database - Database health - GET /api/v1/monitoring/health/storage - Storage health - GET /api/v1/monitoring/system/info - System information - GET /api/v1/monitoring/system/stats - System statistics - GET /api/v1/monitoring/alerts - List alerts - POST /api/v1/monitoring/alerts - Create alert - GET /api/v1/monitoring/alerts/:id - Get alert - PUT /api/v1/monitoring/alerts/:id - Update alert - DELETE /api/v1/monitoring/alerts/:id - Delete alert - POST /api/v1/monitoring/alerts/:id/acknowledge - Acknowledge alert - POST /api/v1/monitoring/alerts/:id/resolve - Resolve alert

Thread Safety: - All database operations are thread-safe via connection pooling - Runtime metrics are thread-safe

Dependencies: - Database: sessions, users, alerts tables - External Services: Prometheus scraping (optional)

Example Usage:

handler := NewMonitoringHandler(database)
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers provides HTTP handlers for the StreamSpace API. This file contains DEPRECATED stub handlers for node management.

⚠️ DEPRECATED: Node management has been moved to the streamspace-node-manager plugin.

MIGRATION GUIDE:

The node management functionality has been extracted into a plugin for better modularity. To restore node management functionality:

1. Install the streamspace-node-manager plugin:

• Via Admin UI: Admin → Plugins → Browse → streamspace-node-manager → Install
• Via CLI: kubectl apply -f https://plugins.streamspace.io/node-manager/install.yaml

2. API endpoints will be available at:

• /api/plugins/streamspace-node-manager/nodes (list)
• /api/plugins/streamspace-node-manager/nodes/:name (get)
• /api/plugins/streamspace-node-manager/nodes/:name/labels (add/remove)
• /api/plugins/streamspace-node-manager/nodes/:name/taints (add/remove)
• /api/plugins/streamspace-node-manager/nodes/:name/cordon (cordon)
• /api/plugins/streamspace-node-manager/nodes/:name/uncordon (uncordon)
• /api/plugins/streamspace-node-manager/nodes/:name/drain (drain)
• /api/plugins/streamspace-node-manager/nodes/stats (cluster stats)

3. The plugin provides enhanced features:

• Auto-scaling integration
• Advanced health monitoring
• Node selection strategies
• Metrics collection (requires metrics-server)
• Alert integration
• Configurable health checks

WHY WAS THIS MOVED TO A PLUGIN?

- Reduced core complexity: Node management is advanced functionality not needed by all users - Optional dependency: Single-node deployments don't need cluster management - Enhanced features: Plugin can provide more advanced capabilities - Modular architecture: Easier to maintain and extend independently - Performance: Core stays lean for basic deployments

BACKWARDS COMPATIBILITY:

These stub handlers remain in core to provide clear migration messages to existing users. They will be removed in v2.0.0.

Package handlers provides HTTP handlers for the StreamSpace API. This file implements notification delivery and management across multiple channels.

NOTIFICATION FEATURES: - In-app notification management (create, read, delete) - Email notifications via SMTP - Webhook notifications with HMAC signatures - Multiple notification types (session events, quotas, teams, alerts) - Priority levels (low, normal, high, urgent) - Read/unread tracking - Notification preferences per user

NOTIFICATION TYPES: - session.created: New session launched - session.idle: Session idle timeout warning - session.shared: Session shared with user - quota.warning: Approaching quota limits (80% threshold) - quota.exceeded: Quota limits exceeded - team.invitation: Invited to join team - system.alert: System-wide alerts

NOTIFICATION CHANNELS: - In-app: Stored in database, retrieved via API - Email: Sent via SMTP with HTML templates - Webhook: HTTP POST to user-configured URLs - Integration: Slack, Teams, Discord (via integrations handler)

PRIORITY LEVELS: - low: Non-urgent informational messages - normal: Standard notifications - high: Important notifications requiring attention - urgent: Critical notifications requiring immediate action

IN-APP NOTIFICATIONS: - Persistent storage in database - Unread count tracking - Mark as read individually or in bulk - Delete individually or clear all - Action URLs for quick navigation - Pagination support

EMAIL NOTIFICATIONS: - HTML template rendering - SMTP configuration (host, port, auth) - Configurable from/reply-to addresses - Environment variable configuration - Test email endpoint for debugging

WEBHOOK NOTIFICATIONS: - HMAC-SHA256 signature for verification - JSON payload with notification data - User-configured webhook URLs - Test webhook endpoint for debugging

API Endpoints: - GET /api/v1/notifications - List user notifications - GET /api/v1/notifications/unread - Get unread notifications - GET /api/v1/notifications/count - Get unread count - POST /api/v1/notifications/:id/read - Mark as read - POST /api/v1/notifications/read-all - Mark all as read - DELETE /api/v1/notifications/:id - Delete notification - DELETE /api/v1/notifications/clear-all - Clear all notifications - POST /api/v1/notifications/send - Send notification (admin) - GET /api/v1/notifications/preferences - Get notification preferences - PUT /api/v1/notifications/preferences - Update notification preferences - POST /api/v1/notifications/test/email - Test email delivery - POST /api/v1/notifications/test/webhook - Test webhook delivery

Thread Safety: - All database operations are thread-safe via connection pooling - SMTP client is created per-request

Dependencies: - Database: notifications, user_preferences tables - External Services: SMTP server for email delivery

Example Usage:

handler := NewNotificationsHandler(database)
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers provides HTTP request handlers for the StreamSpace API.

The plugin_marketplace.go file implements HTTP handlers for the plugin marketplace, which provides a higher-level API that combines catalog management, installation, and runtime lifecycle management.

Marketplace vs Catalog:

Catalog (plugins.go):
  - Database-driven plugin catalog (catalog_plugins table)
  - Install by ID, manage by ID
  - Tracks ratings, statistics, metadata
  - More suitable for production UI with detailed plugin info

Marketplace (plugin_marketplace.go):
  - Runtime-driven plugin marketplace (PluginMarketplace + RuntimeV2)
  - Install by name, manage by name
  - Immediate load/unload (affects runtime state)
  - Catalog sync from external repositories
  - More suitable for programmatic API access

API Endpoint Structure:

Marketplace Catalog:
  GET    /api/plugins/marketplace/catalog      - List available plugins
  POST   /api/plugins/marketplace/sync         - Force catalog sync
  GET    /api/plugins/marketplace/catalog/:name - Get plugin details

Plugin Installation (immediate load/unload):
  POST   /api/plugins/marketplace/install/:name   - Install + load plugin
  DELETE /api/plugins/marketplace/uninstall/:name - Unload + uninstall plugin
  POST   /api/plugins/marketplace/enable/:name    - Enable plugin
  POST   /api/plugins/marketplace/disable/:name   - Unload + disable plugin

Installed Plugins (runtime queries):
  GET    /api/plugins/marketplace/installed       - List loaded plugins
  GET    /api/plugins/marketplace/installed/:name - Get loaded plugin
  PUT    /api/plugins/marketplace/installed/:name/config - Update config

Design Decisions:

1. Immediate Effect: Install/uninstall/enable/disable affect runtime immediately - plugins.go: Changes database only, requires restart/reload - marketplace.go: Changes database AND runtime state

2. Plugin Identification: Uses plugin name instead of database ID - plugins.go: Uses database ID (/api/plugins/123) - marketplace.go: Uses plugin name (/api/plugins/marketplace/install/slack-notifications)

3. Catalog Sync: External repository synchronization - POST /api/plugins/marketplace/sync fetches latest plugins from repository - Populates catalog_plugins and catalog_repositories tables

Example Usage Flow:

1. Sync catalog from external repository: POST /api/plugins/marketplace/sync (Updates catalog_plugins from https://plugins.streamspace.io)

2. Browse available plugins: GET /api/plugins/marketplace/catalog

3. Install and load plugin immediately: POST /api/plugins/marketplace/install/slack-notifications Body: {"config": {"webhook_url": "..."}} (Plugin installed to database AND loaded into runtime)

4. Disable plugin (unloads from runtime): POST /api/plugins/marketplace/disable/slack-notifications (Plugin unloaded AND marked disabled in database)

Package handlers provides HTTP request handlers for the StreamSpace API.

The plugins.go file implements HTTP handlers for plugin management, including catalog browsing, installation, configuration, and lifecycle management.

API Endpoint Structure:

Plugin Catalog (browse/install):
  GET    /api/plugins/catalog           - Browse available plugins
  GET    /api/plugins/catalog/:id       - Get catalog plugin details
  POST   /api/plugins/catalog/:id/rate  - Rate a plugin (1-5 stars)
  POST   /api/plugins/catalog/:id/install - Install plugin from catalog

Installed Plugins (CRUD):
  GET    /api/plugins                   - List installed plugins
  GET    /api/plugins/:id               - Get installed plugin details
  PATCH  /api/plugins/:id               - Update plugin config
  DELETE /api/plugins/:id               - Uninstall plugin
  POST   /api/plugins/:id/enable        - Enable plugin
  POST   /api/plugins/:id/disable       - Disable plugin

Database Tables:

catalog_plugins:
  - Plugins available for installation
  - Includes metadata (name, version, description, icon, tags)
  - Tracks install count, ratings, view count

installed_plugins:
  - Plugins currently installed
  - References catalog_plugins via catalog_plugin_id
  - Includes enabled status and configuration

plugin_ratings:
  - User ratings for catalog plugins (1-5 stars + review)
  - One rating per user per plugin (upsert on conflict)

plugin_stats:
  - Plugin usage statistics (views, installs, last accessed)
  - Updated asynchronously (non-blocking)

Design Patterns:

1. Async stats updates: View/install counts updated in goroutines
2. Graceful errors: Individual row parsing errors don't fail entire query
3. SQL injection prevention: Parameterized queries with $1, $2, etc.
4. User context: user_id extracted from auth middleware via c.GetString()

Example Usage Flow:

1. User browses catalog: GET /api/plugins/catalog?category=analytics&sort=popular

2. User views plugin details: GET /api/plugins/catalog/42 (View count incremented async)

3. User installs plugin: POST /api/plugins/catalog/42/install Body: {"config": {"api_key": "..."}} (Plugin added to installed_plugins, install count incremented)

4. User enables/disables plugin: POST /api/plugins/123/enable (Plugin enabled in database, runtime loads it on next restart/reload)

Package handlers provides HTTP handlers for the StreamSpace API. This file implements user preference management and customization settings.

PREFERENCE FEATURES: - User-specific preference storage (JSON-based) - UI preferences (theme, layout, language, timezone) - Notification preferences (enabled channels, frequency) - Default session settings (resources, templates) - Favorite templates management - Recent session tracking

PREFERENCE CATEGORIES:

1. UI Preferences:

• Theme (light, dark, auto)
• Layout preferences (sidebar, density)
• Language and locale
• Timezone for timestamps
• Default view modes

2. Notification Preferences:

• Email notifications enabled/disabled
• In-app notifications enabled/disabled
• Webhook notifications
• Notification types to receive
• Notification frequency/batching

3. Default Session Settings:

• Default template selection
• Default resource allocations (CPU, memory)
• Default idle timeout
• Default hibernation settings
• Auto-start preferences

4. Favorites:

• Favorite template list
• Quick access templates
• Template ordering

5. Recent Sessions:

• Recently accessed sessions
• Session history limit
• Timestamp tracking

PREFERENCE STORAGE: - JSON-based flexible schema - Per-user preference isolation - Default preferences for new users - Merge strategy for partial updates

API Endpoints: - GET /api/v1/preferences - Get all user preferences - PUT /api/v1/preferences - Update all preferences - DELETE /api/v1/preferences - Reset to defaults - GET /api/v1/preferences/ui - Get UI preferences - PUT /api/v1/preferences/ui - Update UI preferences - GET /api/v1/preferences/notifications - Get notification preferences - PUT /api/v1/preferences/notifications - Update notification preferences - GET /api/v1/preferences/defaults - Get default session settings - PUT /api/v1/preferences/defaults - Update default session settings - GET /api/v1/preferences/favorites - Get favorite templates - POST /api/v1/preferences/favorites/:templateName - Add favorite - DELETE /api/v1/preferences/favorites/:templateName - Remove favorite - GET /api/v1/preferences/recent - Get recent sessions

Thread Safety: - All database operations are thread-safe via connection pooling

Dependencies: - Database: user_preferences table - External Services: None

Example Usage:

handler := NewPreferencesHandler(database)
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements resource quota management and enforcement.

RESOURCE QUOTA SYSTEM OVERVIEW:

The quota system prevents resource exhaustion and ensures fair usage by limiting: - Number of concurrent sessions per user or team - Total CPU allocation (measured in millicores, e.g., 1000m = 1 CPU core) - Total memory allocation (measured in megabytes) - Total storage usage (measured in gigabytes)

QUOTA HIERARCHY:

StreamSpace supports three levels of quotas, applied in this order:

1. Default Quotas (global):

• Applies to all users unless overridden
• Configurable by platform admins
• Example: 10 sessions, 4 cores, 8GB RAM, 100GB storage per user

2. User-Specific Quotas:

• Overrides defaults for specific users
• Allows customization for power users or restricted accounts
• Example: Premium user gets 50 sessions, 20 cores, 40GB RAM

3. Team/Group Quotas:

• Shared quota pool for all team members
• Prevents one team from monopolizing resources
• Example: Engineering team gets 200 sessions, 100 cores

QUOTA ENFORCEMENT:

Quotas are enforced at multiple points: - Session creation: CheckQuota endpoint verifies before creating session - Session startup: Controller checks quotas before scheduling pods - API responses: Quota status shown in user dashboards - Violations logged: Audit trail of quota violations for compliance

USAGE CALCULATION:

Resource usage is calculated in real-time from: - Active sessions: Sessions in "running", "starting", or "pending" states - Resource requests: CPU and memory from session specs (not actual usage) - Storage: Sum of snapshot sizes plus persistent home directories

Note: Quotas are based on REQUESTED resources (reservations), not actual usage. This ensures predictable capacity planning. If a session requests 2GB RAM but only uses 500MB, it still counts as 2GB toward the quota.

QUOTA STATUS LEVELS:

- "ok": Usage below 80% of quota (green) - "warning": Usage between 80-100% of quota (yellow) - "exceeded": Usage above 100% of quota (red, blocks new sessions)

EXAMPLE QUOTA LIFECYCLE:

1. User has quota: 10 sessions, 10000m CPU, 20480 MB memory 2. User creates 8 sessions using 8000m CPU, 16384 MB memory 3. Status: "ok" (80% of session quota, 80% of resources) 4. User creates 2 more sessions using 2000m CPU, 4096 MB memory 5. Status: "warning" (100% of session quota) 6. User tries to create 11th session 7. System blocks request with "quota exceeded" error

TEAM QUOTAS VS USER QUOTAS:

Team quotas are SHARED across all members: - Team of 10 users with team quota of 50 sessions - Each user can create sessions up to the team limit - If 5 users create 10 sessions each = 50 total (team quota reached) - Remaining 5 users cannot create any sessions until others terminate

User quotas are INDIVIDUAL limits: - Even within a team, each user has their own session limit - User quota prevents one team member from using all team resources

STORAGE QUOTA DETAILS:

Storage quota includes: - Session snapshots: Saved states of sessions for resume/backup - Persistent home directories: User's /home directory across sessions - Template storage: Custom container images (future feature)

Storage usage is calculated as: - Sum of completed snapshot sizes (in-progress snapshots not counted) - Estimated persistent home size (10GB default, actual size if available)

Package handlers provides HTTP handlers for the StreamSpace API. This file implements session scheduling and calendar integration features.

SCHEDULING SYSTEM OVERVIEW:

The scheduling system allows users to create sessions that start automatically at specific times or on recurring schedules. This is useful for: - Regular team meetings or training sessions - Pre-warming environments before work hours - Demo environments that start/stop on a schedule - Resource optimization by scheduling sessions during off-peak hours

SUPPORTED SCHEDULE TYPES:

1. One-Time (once): Session starts at a specific date/time, runs once

• Example: Demo session on Friday at 2 PM
• Requires: start_time field

2. Daily (daily): Session starts every day at a specific time

• Example: Development environment ready at 9 AM every weekday
• Requires: time_of_day field (HH:MM format)

3. Weekly (weekly): Session starts on specific days of the week

• Example: Training sessions every Monday and Wednesday at 10 AM
• Requires: days_of_week array (0=Sunday, 6=Saturday), time_of_day

4. Monthly (monthly): Session starts on a specific day of each month

• Example: Monthly report review on the 1st at 9 AM
• Requires: day_of_month (1-31), time_of_day

5. Cron Expression (cron): Advanced scheduling using cron syntax

• Example: "0 9 * * 1-5" for weekdays at 9 AM
• Requires: cron_expr field
• Uses standard cron format: minute hour day month weekday

CONFLICT DETECTION:

The system prevents scheduling conflicts by checking if proposed schedules would overlap with existing sessions. This prevents: - Resource quota violations (too many concurrent sessions) - Node capacity issues - User confusion from overlapping sessions

CALENDAR INTEGRATION:

Sessions can be automatically synced to external calendars: - Google Calendar (via Google Calendar API) - Microsoft Outlook (via Microsoft Graph API) - iCal export for other calendar applications

This allows users to see their scheduled sessions alongside other events and get calendar notifications/reminders.

PRE-WARMING AND AUTO-TERMINATION:

• Pre-warming: Start session N minutes before scheduled time Useful for sessions with slow startup (large container images)

• Auto-termination: Automatically stop session N minutes after start Prevents runaway sessions and saves resources

TIMEZONE HANDLING:

All schedules are stored with timezone information. The system converts between timezones when calculating next run times to ensure schedules work correctly for users in different locations.

Package handlers provides HTTP handlers for the StreamSpace API. This file implements advanced search, filtering, and saved search functionality.

SEARCH FEATURES: - Universal search across templates, sessions, users - Full-text search with relevance scoring - Advanced filtering (category, tags, app type) - Auto-complete suggestions - Saved search queries - Search history tracking

SEARCH TYPES: - Universal: Search across all resource types - Templates: Search template catalog - Sessions: Search user sessions - Suggestions: Auto-complete for search input - Advanced: Multi-filter complex queries

SEARCH RESULTS: - Type-specific results (template, session, user) - Relevance scoring - Result metadata (category, tags, icons) - Pagination support

FILTERING: - Categories: Filter by template/session category - Tags: Filter by tags - App Types: Filter by application type - Multiple filters combined with AND logic

SAVED SEARCHES: - Save frequently used search queries - Named searches for quick access - Execute saved searches - Update and delete saved searches - User-specific saved searches

SEARCH HISTORY: - Track user search queries - Timestamp tracking - Result count tracking - History limits per user

API Endpoints: - GET /api/v1/search - Universal search - GET /api/v1/search/templates - Template-specific search - GET /api/v1/search/sessions - Session search - GET /api/v1/search/suggest - Auto-complete suggestions - GET /api/v1/search/advanced - Advanced multi-filter search - GET /api/v1/search/filters/categories - List all categories - GET /api/v1/search/filters/tags - List popular tags - GET /api/v1/search/filters/app-types - List app types - GET /api/v1/search/saved - List saved searches - POST /api/v1/search/saved - Create saved search - GET /api/v1/search/saved/:id - Get saved search - PUT /api/v1/search/saved/:id - Update saved search - DELETE /api/v1/search/saved/:id - Delete saved search - POST /api/v1/search/saved/:id/execute - Execute saved search - GET /api/v1/search/history - Get search history

Thread Safety: - All database operations are thread-safe via connection pooling

Dependencies: - Database: catalog_templates, sessions, users, saved_searches, search_history tables - External Services: None

Example Usage:

handler := NewSearchHandler(database)
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements enterprise security features including:

Security Features: - Multi-Factor Authentication (TOTP, SMS*, Email*) *Note: SMS/Email under development - IP Whitelisting for access control - MFA backup codes for account recovery - Rate limiting on MFA verification (5 attempts/minute) - Database transactions for data consistency - Secret protection (never expose secrets in API responses) - Input validation for all security-sensitive operations

Security Fixes Applied (2025-11-14): 1. Disabled incomplete SMS/Email MFA to prevent authentication bypass 2. Added rate limiting to MFA verification (prevents brute force) 3. Wrapped MFA setup in database transactions (ensures consistency) 4. Protected secrets with json:"-" tags (never returned in GET responses) 5. Fixed authorization enumeration in DeleteIPWhitelist 6. Added comprehensive input validation 7. Proper error handling for JSON unmarshal operations

Thread Safety: - All database operations are thread-safe via connection pooling - Rate limiting uses thread-safe in-memory storage with mutex - No shared mutable state between handlers

Package handlers provides HTTP request handlers for the StreamSpace API.

This file implements the Selkies/HTTP proxy handler for HTTP-based streaming protocols.

HTTP Streaming Traffic Flow (v2.0):

UI Client → Control Plane HTTP Proxy → Session Service → Pod (Selkies Web Interface)

The Selkies proxy:

1. Receives HTTP/WebSocket requests from UI clients
2. Verifies user has access to the session
3. Proxies HTTP/WebSocket traffic directly to session Service (in-cluster)
4. Session Service routes to pod's Selkies web interface (port 3000, 6901, etc.)

Architecture:

• Control plane runs IN the Kubernetes cluster
• Can access ClusterIP services via Kubernetes DNS
• Uses Go's httputil.ReverseProxy for HTTP and WebSocket proxying

Supported Protocols:

• Selkies: LinuxServer images (port 3000, path /websockify)
• Kasm: Kasm Workspaces images (port 6901, path /websockify)
• Guacamole: Apache Guacamole (port 8080, path /guacamole)

Security:

• Requires valid JWT token
• Verifies user has access to the session
• Proxies only to authorized session pods

Example:

UI connects to: http://control-plane/api/v1/http/:sessionId/
Proxy forwards to: http://sessionId.streamspace.svc.cluster.local:3000/

Package handlers provides HTTP handlers for the StreamSpace API. This file implements session activity logging and audit trail functionality.

SESSION ACTIVITY FEATURES: - Comprehensive session event logging - Activity timeline and audit trail - Event categorization (lifecycle, connection, state, configuration, access, error) - User action tracking with IP addresses and user agents - Activity statistics and analytics - Activity export for compliance

EVENT CATEGORIES: - lifecycle: Session creation, startup, termination, deletion - connection: User connections, disconnections, heartbeats - state: State changes (running, hibernated, stopped) - configuration: Resource updates, config changes, tag updates - access: Permission grants, denials, sharing events - error: Error occurrences and exceptions

EVENT TYPES: - session.created, session.started, session.stopped, session.hibernated - session.woken, session.terminated, session.deleted - user.connected, user.disconnected, user.heartbeat - state.changed, resources.updated, config.updated, tags.updated - access.granted, access.denied, share.created, share.revoked - error.occurred

ACTIVITY LOGGING: - Automatic event logging for all session operations - Manual event logging via API - Metadata capture (user ID, IP address, user agent) - Timestamp tracking with millisecond precision

ACTIVITY QUERIES: - List session activity timeline - Filter by event type or category - Date range filtering - Pagination support - Export to CSV/JSON for compliance

ACTIVITY STATISTICS: - Event count by type - Activity heatmap data - User activity patterns - Session usage analytics

API Endpoints: - POST /api/v1/sessions/:id/activity/log - Log activity event - GET /api/v1/sessions/:id/activity - Get session activity timeline - GET /api/v1/sessions/:id/activity/stats - Get activity statistics - GET /api/v1/sessions/:id/activity/export - Export activity data

Thread Safety: - All database operations are thread-safe via connection pooling

Dependencies: - Database: session_activity_events table - External Services: None

Example Usage:

handler := NewSessionActivityHandler(database)
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements custom session template management and presets.

SESSION TEMPLATE FEATURES: - User-defined session configuration templates - Template CRUD operations (create, read, update, delete) - Template visibility (private, team, public) - Template cloning and versioning - Template sharing within teams - Create templates from existing sessions - Usage tracking and analytics

TEMPLATE VISIBILITY: - private: Only visible to template owner - team: Visible to team members - public: Visible to all users (requires approval)

TEMPLATE STRUCTURE: - Based on catalog template (base template reference) - Custom configuration overrides - Resource allocations (CPU, memory) - Environment variables - Tags and categorization - Version tracking

TEMPLATE OPERATIONS: - Create: Define new template from scratch or from session - Clone: Duplicate existing template - Use: Launch session from template - Publish/Unpublish: Make template public or private - Share: Share with specific users or teams

TEMPLATE SHARING: - Share templates with users or teams - Permission levels (view, use, edit) - Revoke shares - Track who has access

TEMPLATE VERSIONING: - Version history tracking - Restore previous versions - Version comparison - Change logs

QUICK ACTIONS: - Create template from running session - Set as default template for user - Clone template with modifications

API Endpoints: - GET /api/v1/session-templates - List session templates - POST /api/v1/session-templates - Create session template - GET /api/v1/session-templates/:id - Get template details - PUT /api/v1/session-templates/:id - Update template - DELETE /api/v1/session-templates/:id - Delete template - POST /api/v1/session-templates/:id/clone - Clone template - POST /api/v1/session-templates/:id/use - Launch session from template - POST /api/v1/session-templates/:id/publish - Make template public - POST /api/v1/session-templates/:id/unpublish - Make template private - GET /api/v1/session-templates/:id/shares - List template shares - POST /api/v1/session-templates/:id/share - Share template - DELETE /api/v1/session-templates/:id/shares/:shareId - Revoke share - GET /api/v1/session-templates/:id/versions - List template versions - POST /api/v1/session-templates/:id/versions - Create version - POST /api/v1/session-templates/:id/versions/:version/restore - Restore version - POST /api/v1/session-templates/from-session/:sessionId - Create from session

Thread Safety: - All database operations are thread-safe via connection pooling

Dependencies: - Database: session_templates, template_shares, template_versions tables - External Services: None

Example Usage:

handler := NewSessionTemplatesHandler(database)
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements the first-run setup wizard for admin user onboarding.

Purpose: - Provides a secure setup wizard for initial admin password configuration - Enables account recovery when admin password is lost or not set - Automatically disables after admin account is configured - Works as fallback when Helm secret or environment variable not available

Security Features: - Only accessible when admin account has no password set - Password strength validation (minimum 12 characters) - Password confirmation to prevent typos - Email validation for admin contact - Single-use wizard (auto-disables after setup) - Atomic database transaction - Input sanitization and validation

Integration: - Part of multi-layered admin onboarding strategy - Priority 3 fallback after Helm secret and environment variable - Works with database migration admin user creation - Compatible with all authentication modes (local, SAML, OIDC)

Thread Safety: - All database operations are thread-safe via connection pooling - No shared mutable state between requests

Package handlers provides HTTP handlers for the StreamSpace API. This file implements session sharing and collaboration features.

SESSION SHARING FEATURES: - Direct user-to-user session sharing with permission levels - Shareable invitation links with expiration and usage limits - Share revocation and ownership transfer - Collaborator tracking and activity monitoring

PERMISSION LEVELS: - view: Read-only access to view the session - collaborate: Can interact but has limited control - control: Full control equivalent to owner

SHARING METHODS:

1. Direct Shares:

• Share with specific users by user ID
• Owner-only operation
• Requires user existence validation
• Supports expiration timestamps
• Generates unique share tokens

2. Invitation Links:

• Generate shareable invitation tokens
• Configurable max uses and expiration
• Anyone with link can accept (until exhausted/expired)
• Tracks usage count

OWNERSHIP TRANSFER: - Transfer session ownership to another user - Requires current owner authorization - Validates new owner exists

COLLABORATOR MANAGEMENT: - Track active collaborators in sessions - Update activity timestamps - Remove collaborators - Permission inheritance from shares

API Endpoints: - POST /api/v1/sessions/:id/share - Create direct share with user - GET /api/v1/sessions/:id/shares - List all shares for session - DELETE /api/v1/sessions/:id/shares/:shareId - Revoke a share - POST /api/v1/sessions/:id/transfer - Transfer ownership - POST /api/v1/sessions/:id/invitations - Create invitation link - GET /api/v1/sessions/:id/invitations - List invitations - DELETE /api/v1/invitations/:token - Revoke invitation - POST /api/v1/invitations/:token/accept - Accept invitation - GET /api/v1/sessions/:id/collaborators - List active collaborators - POST /api/v1/sessions/:id/collaborators/:userId/activity - Update activity - DELETE /api/v1/sessions/:id/collaborators/:userId - Remove collaborator - GET /api/v1/shared-sessions - List sessions shared with user

Security: - Owner-only operations for sharing and transfer - User existence validation - Expiration and usage limit enforcement - Authorization checks for all operations

Thread Safety: - All database operations are thread-safe via connection pooling - Atomic upsert operations for collaborators and shares

Dependencies: - Database: sessions, session_shares, session_share_invitations, session_collaborators, users tables - External Services: None

Example Usage:

handler := NewSharingHandler(database)
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements team-based Role-Based Access Control (RBAC) operations.

TEAM RBAC FEATURES: - Team permissions and role management - User permission queries within teams - Team session access control - Permission checking for authorization

TEAM PERMISSIONS: - Role-based permissions (owner, admin, member, viewer, etc.) - Permission inheritance from team roles - User-specific permission queries - Permission validation for resource access

TEAM SESSIONS: - List sessions belonging to a specific team - Permission-based access control (requires team.sessions.view) - Team member authorization

API Endpoints: - GET /api/v1/teams/:teamId/permissions - Get all team role permissions - GET /api/v1/teams/:teamId/role-info - Get available team roles - GET /api/v1/teams/:teamId/my-permissions - Get current user's permissions - GET /api/v1/teams/:teamId/check-permission/:permission - Check specific permission - GET /api/v1/teams/:teamId/sessions - List team sessions (requires permission) - GET /api/v1/teams/my-teams - Get current user's team memberships

Security: - Authentication required for all endpoints - Permission-based authorization for sensitive operations - Safe type assertions to prevent panics

Thread Safety: - All database operations are thread-safe via connection pooling

Dependencies: - Database: teams, team_members, team_role_permissions, sessions tables - Middleware: TeamRBAC for permission checks - External Services: None

Example Usage:

handler := NewTeamHandler(database)
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers provides HTTP handlers for the StreamSpace API. This file implements template versioning, testing, and inheritance management.

TEMPLATE VERSIONING FEATURES: - Semantic versioning (major.minor.patch) - Version lifecycle (draft, testing, stable, deprecated) - Version testing and validation - Template inheritance (parent-child relationships) - Version comparison and diff - Rollback to previous versions

VERSION LIFECYCLE: - draft: Work in progress, not ready for use - testing: Undergoing validation tests - stable: Production-ready, recommended for use - deprecated: Old version, migration recommended

VERSION MANAGEMENT: - Create new versions with semantic versioning - Set default version for template - Publish versions for public use - Deprecate outdated versions - Track version metadata (changelog, test results)

TEMPLATE TESTING: - Automated template validation - Test types: startup, smoke, functional, performance - Test status tracking: pending, running, passed, failed - Test results with duration and error messages - Test execution history

TEMPLATE INHERITANCE: - Parent-child template relationships - Field inheritance and overrides - Inherited field tracking - Override visualization - Template family trees

VERSION COMPARISON: - Compare configurations between versions - Highlight differences - Migration guides between versions

API Endpoints: - POST /api/v1/templates/:id/versions - Create template version - GET /api/v1/templates/:id/versions - List template versions - GET /api/v1/templates/:id/versions/:version - Get version details - PUT /api/v1/templates/:id/versions/:version - Update version - DELETE /api/v1/templates/:id/versions/:version - Delete version - POST /api/v1/templates/:id/versions/:version/publish - Publish version - POST /api/v1/templates/:id/versions/:version/deprecate - Deprecate version - POST /api/v1/templates/:id/versions/:version/test - Run version tests - GET /api/v1/templates/:id/versions/:version/tests - Get test results - GET /api/v1/templates/:id/inheritance - Get template inheritance tree - POST /api/v1/templates/:id/inherit-from - Set parent template

Thread Safety: - All database operations are thread-safe via connection pooling

Dependencies: - Database: template_versions, template_tests, template_inheritance tables - External Services: Test execution infrastructure

Example Usage:

// Create version handler (integrated in main handler)
handler.RegisterTemplateVersioningRoutes(router.Group("/api/v1"))

Package handlers provides HTTP handlers for the StreamSpace API. This file defines common response types used across all handler files.

COMMON TYPES: - ErrorResponse: Standardized error response format - SuccessResponse: Standardized success message format

These types provide consistency across all API endpoints for error handling and success messaging. All handlers in this package use these types to ensure uniform API response structures.

Thread Safety: - These are simple data structures with no shared state

Dependencies: - None (pure data types)

Package handlers provides HTTP handlers for the StreamSpace API. This file implements user management and user-level resource quota operations.

USER MANAGEMENT: - User CRUD operations (list, create, read, update, delete) - User profile management (/me endpoints for current user) - User filtering by role, provider, or active status - Password hash sanitization (never exposed in responses)

QUOTA MANAGEMENT: - Per-user resource quotas (sessions, CPU, memory, storage) - Quota retrieval for current user and specific users - Admin quota management (list all, set, delete/reset) - Username-based quota operations for admin convenience

USER ASSOCIATIONS: - User sessions (redirects to /sessions?user=id) - User group memberships

API Endpoints: - GET /api/v1/users - List all users with optional filters - POST /api/v1/users - Create new user account - GET /api/v1/users/me - Get current authenticated user - GET /api/v1/users/me/quota - Get current user's quota - GET /api/v1/users/:id - Get user by ID - PATCH /api/v1/users/:id - Update user information - DELETE /api/v1/users/:id - Delete user account - GET /api/v1/users/:id/sessions - Get user's sessions - GET /api/v1/users/:id/quota - Get user's resource quota - PUT /api/v1/users/:id/quota - Set user's resource quota - GET /api/v1/users/:id/groups - Get user's group memberships - GET /api/v1/admin/quotas - List all user quotas (admin) - GET /api/v1/admin/quotas/:username - Get quota by username (admin) - PUT /api/v1/admin/quotas - Set quota by username (admin) - DELETE /api/v1/admin/quotas/:username - Reset quota to defaults (admin)

Security: - Password hashes are sanitized before returning user objects - Safe type assertions prevent panics - Authentication required via middleware for protected endpoints

Thread Safety: - All database operations are thread-safe via connection pooling

Dependencies: - Database: users, user_quotas, user_groups tables - External Services: None

Example Usage:

handler := NewUserHandler(userDB, groupDB)
handler.RegisterRoutes(router.Group("/api/v1"))

Package handlers - websocket.go ¶

This file implements the WebSocket handler for real-time updates in StreamSpace.

Real-Time Communication Architecture ¶

The WebSocket system enables bidirectional communication between the server and connected clients for instant updates about sessions, notifications, metrics, and alerts. This eliminates the need for polling and provides a better UX.

Architecture pattern: **Hub-and-Spoke** (centralized message routing)

┌─────────────────────────────────────────────────────────────┐
│                      WebSocket Hub                          │
│  - Maintains registry of connected clients                 │
│  - Routes broadcast messages to matching clients           │
│  - Handles client registration/unregistration              │
│  - Filters messages based on subscriptions                 │
└──────────────┬──────────────────────────────────────────────┘
               │
       ┌───────┴──────┬─────────────┬─────────────┬──────────┐
       ▼              ▼             ▼             ▼          ▼
   Client 1      Client 2      Client 3      Client 4   Client N
   (User A)      (User B)      (User A)      (Admin)    (User C)
   [Filters:     [Filters:     [Filters:     [Filters:  [Filters:
    UserID=A]     UserID=B]     UserID=A]     All]       UserID=C]

Message Flow ¶

**Outbound (Server → Clients)**:

1. API handler emits event (e.g., session.created)
2. Event serialized to BroadcastMessage
3. Message sent to hub's broadcast channel
4. Hub filters and routes to matching clients
5. Clients receive message via WebSocket

**Inbound (Clients → Server)**:

1. Client sends message via WebSocket
2. Message parsed (subscription updates, heartbeats)
3. Client filters updated accordingly
4. Future: Plugin event triggers, RPC calls

Subscription Filtering ¶

Clients can subscribe to specific event types to reduce bandwidth:

• **Session IDs**: Only updates for specific sessions
• **User ID**: Only updates for this user's resources
• **Team ID**: Only updates for team resources
• **Event Types**: Only specific events (created, updated, deleted)

Example filter: User viewing "my sessions" page subscribes to:

{
    "userId": "user-123",
    "eventTypes": ["session.created", "session.updated", "session.deleted"]
}

This ensures they only receive their own session updates, not all platform events.

Connection Lifecycle ¶

WebSocket connection lifecycle:

1. **Handshake**: HTTP upgrade request with auth token
2. **Validation**: Origin check, auth verification
3. **Registration**: Client added to hub's sessions map
4. **Active**: Bidirectional communication (read/write pumps)
5. **Heartbeat**: Periodic pings to detect dead connections
6. **Unregistration**: Client removed on disconnect/error
7. **Cleanup**: Goroutines stopped, channels closed

Concurrency Model ¶

The hub uses the **Actor pattern** with channels for synchronization:

• **Hub goroutine**: Single goroutine processes all registration/broadcast
• **Read pump per client**: Goroutine reads messages from WebSocket
• **Write pump per client**: Goroutine writes messages to WebSocket
• **Channel-based**: No mutexes in pumps, only in hub

Why this pattern?

• Simplifies concurrent access to sessions map
• Prevents race conditions in WebSocket writes
• Enables efficient broadcast to thousands of clients
• Matches Gorilla WebSocket best practices

Performance Characteristics ¶

Performance metrics (measured with 1000 concurrent connections):

• **Message latency**: <10ms from broadcast to client receive (p99)
• **Throughput**: 10,000+ messages/sec per hub instance
• **Memory per client**: ~100 KB (goroutines + buffers)
• **CPU overhead**: ~5% for 1000 clients with 100 msg/sec

Scaling limits:

• **Single instance**: ~10,000 concurrent connections (tested)
• **Bottleneck**: Network bandwidth and file descriptors
• **Horizontal scaling**: Use Redis pub/sub to sync multiple instances

Message Types ¶

The platform emits these event types:

**Session Events**:

• session.created: New session requested
• session.started: Session pod running
• session.updated: Session metadata changed
• session.stopped: Session stopped by user
• session.hibernated: Auto-hibernation triggered
• session.woken: Session resumed from hibernation
• session.deleted: Session permanently removed

**Notification Events**:

• notification.created: New notification for user
• notification.read: Notification marked as read

**Metric Events**:

• metrics.updated: Real-time resource usage updates

**Alert Events**:

• alert.triggered: Platform alert fired
• alert.resolved: Alert condition cleared

Security Considerations ¶

WebSocket security measures:

1. **Origin validation**: Blocks CSRF by checking Origin header
2. **Authentication**: JWT token required in initial handshake
3. **Authorization**: Filters ensure users only see their own data
4. **Rate limiting**: Future: Limit messages per client per second
5. **Message validation**: Inbound messages validated before processing

Vulnerabilities prevented:

• **CSRF**: Origin check prevents cross-site WebSocket hijacking
• **Data leakage**: Filters prevent users seeing other users' data
• **DoS**: Connection limits prevent resource exhaustion

Error Handling ¶

The hub is resilient to client failures:

• **Write errors**: Client disconnected, removed from hub
• **Read errors**: Connection closed, cleanup triggered
• **Broadcast overflow**: Slow clients dropped (non-blocking)
• **Hub errors**: Logged but hub continues (fail gracefully)

Why drop slow clients?

• Prevents one slow client from blocking the entire hub
• Clients can reconnect and resync state
• Better UX for fast clients (no global slowdown)

Known Limitations ¶

1. **Single instance**: No cross-instance message routing (yet)
2. **No persistence**: Messages not stored (missed if offline)
3. **No compression**: WebSocket compression not enabled
4. **No reconnection**: Clients must implement reconnect logic
5. **No backpressure**: Fast sender can overflow slow receivers

Future enhancements:

• Redis pub/sub for multi-instance deployments
• Message persistence for offline clients
• WebSocket compression for bandwidth optimization
• Automatic reconnection with exponential backoff
• Per-client rate limiting and backpressure

Example Usage ¶

**Client (JavaScript)**:

const ws = new WebSocket('wss://api.streamspace.io/ws/sessions');

// Send auth token after connection
ws.onopen = () => {
    ws.send(JSON.stringify({
        type: 'subscribe',
        filters: {
            userId: 'user-123',
            eventTypes: ['session.created', 'session.updated']
        }
    }));
};

// Handle messages
ws.onmessage = (event) => {
    const message = JSON.parse(event.data);
    console.log('Event:', message.event, 'Data:', message.data);
};

**Server (API handler)**:

// Broadcast session update to all connected clients
wsHandler.Broadcast(&BroadcastMessage{
    Type:      "update",
    Event:     "session.created",
    SessionID: session.ID,
    UserID:    session.UserID,
    Data:      sessionData,
    Timestamp: time.Now(),
})

Package handlers provides HTTP and WebSocket handlers for the StreamSpace API. This file implements enterprise WebSocket functionality for real-time updates.

Security Features: - Origin validation to prevent Cross-Site WebSocket Hijacking (CSWSH) - Race condition protection with proper mutex usage - User authentication required for all connections - Graceful disconnect handling

Architecture: - Hub-and-spoke model: Central hub broadcasts to all clients - Each client has dedicated read/write goroutines - Buffered channels prevent blocking - Automatic cleanup of disconnected clients