Implement Project Sandbox Bridge Versioning with User Restart Notifications

[vedranjukic]

Summary

Implement a comprehensive bridge versioning system for project sandboxes similar to the existing MITM proxy sandbox bridge versioning. When users install a new version of the Apex dashboard that includes an updated bridge version, they should be notified to restart their project sandbox to pick up the new bridge version.

Background

Currently, Daytona has bridge versioning implemented for the MITM proxy sandbox (in /apps/daemon/internal/util/version.go), but project sandboxes lack similar version management. This creates potential compatibility issues when dashboard updates include bridge functionality changes that require sandbox restarts.

Requirements

Core Functionality

• Implement bridge version tracking for project sandboxes
• Add version comparison logic to detect mismatches between dashboard and sandbox bridge versions
• Create user notification system for bridge version incompatibilities
• Provide graceful restart flow for updating bridge versions

Bridge Version Management

• Extend existing version utilities (/apps/daemon/internal/util/version.go) for project sandbox bridges
• Add bridge version endpoints similar to existing /version endpoint in toolbox controller
• Implement version negotiation during bridge connection establishment
• Add bridge version headers to WebSocket and HTTP communications

Notification System

• Extend notification gateway (/apps/api/src/notification/gateways/notification.gateway.ts) with new event types:
  • BRIDGE_VERSION_MISMATCH
  • BRIDGE_RESTART_REQUIRED
• Add real-time notifications via existing WebSocket infrastructure
• Create dashboard UI components for version mismatch warnings

Dashboard Integration

• Extend existing WebSocket sync hooks (useSandboxWsSync, useNotificationSocket) for bridge status
• Add version compatibility checking in dashboard providers
• Implement user-friendly restart prompts with progress indicators
• Add banner/modal notifications for required restarts

Version Increment Strategy

• Define bridge version increment triggers:
  • Changes to bridge API endpoints
  • Modifications to WebSocket communication protocols
  • Updates to session management logic
  • Changes to proxy forwarding behavior
• Implement automated version bumping in CI/CD pipeline
• Add version validation in pre-release checks

Technical Implementation

1. Version Framework Extension

Leverage existing patterns from MITM proxy bridge:

• Extend version.go utilities for project-specific version checking
• Add bridge version to WebSocket subprotocol negotiation
• Implement backward compatibility handling similar to existing SDK versioning

2. Bridge Health Monitoring

• Add bridge version endpoints to project sandbox controllers
• Implement periodic version compatibility checks
• Create bridge health status tracking

3. Graceful Restart Flow

• Use existing session management infrastructure for connection draining
• Implement connection migration during bridge updates
• Add restart coordination between dashboard and sandbox components

4. Notification Architecture

Extend existing real-time notification system:

• Add organization-scoped bridge version events
• Implement targeted notifications for affected sandboxes
• Create dashboard state synchronization for version status

Acceptance Criteria

1. Version Detection: System accurately detects bridge version mismatches between dashboard and project sandboxes
2. User Notification: Users receive clear, actionable notifications when bridge restart is required
3. Graceful Restart: Users can restart project sandboxes without data loss or service interruption
4. Version Tracking: Bridge versions are properly incremented when functionality changes require updates
5. Backward Compatibility: System maintains compatibility with existing sandboxes during transition period
6. Dashboard Integration: Version status is displayed in dashboard with appropriate user actions

Related Files

Existing Implementation Reference

• /apps/daemon/internal/util/version.go - Current bridge versioning utilities
• /apps/daemon/pkg/toolbox/controller.go - Version endpoint implementation
• /apps/api/src/notification/gateways/notification.gateway.ts - Notification system
• /apps/dashboard/src/providers/NotificationSocketProvider.tsx - Dashboard notifications

Areas for Enhancement

• /apps/daemon/pkg/toolbox/process/session/session.go - Session version management
• /apps/dashboard/src/hooks/useNotificationSocket.ts - Bridge status hooks
• /apps/api/src/common/middleware/version-header.middleware.ts - Version headers

Priority

High - This feature prevents compatibility issues between dashboard updates and running sandboxes, improving user experience and system reliability.

Labels

• enhancement
• bridge
• versioning
• notifications
• dashboard
• sandbox

---

Definition of Done:

• Bridge versioning system implemented and tested
• User notification flow functional and user-friendly
• Documentation updated with versioning guidelines
• CI/CD pipeline includes version increment automation
• Backward compatibility maintained during rollout