mirror of
https://github.com/tinyhumansai/openhuman.git
synced 2026-07-30 23:14:37 +00:00
Add daemon lifecycle management system to frontend UI
This implementation integrates the Rust daemon's health monitoring and lifecycle management into the React frontend. Key features include real-time health indicators, automatic start/error recovery, and detailed control panels, enhancing both user experience and operational reliability.
This commit is contained in:
cyrus
@@ -0,0 +1,341 @@
|
||||
# Daemon Lifecycle Management System
|
||||
|
||||
**Status**: ✅ Implemented
|
||||
**Version**: 1.0.0
|
||||
**Date**: February 2026
|
||||
|
||||
## Overview
|
||||
|
||||
The Daemon Lifecycle Management System provides comprehensive frontend integration with the alphahuman Rust daemon, enabling real-time health monitoring, automatic lifecycle management, and user-friendly daemon controls throughout the application.
|
||||
|
||||
## Background
|
||||
|
||||
### Problem Statement
|
||||
|
||||
The alphahuman application runs a sophisticated Rust daemon that manages critical backend services (gateway, channels, heartbeat, scheduler) and emits detailed health information every 5 seconds. However, the frontend previously had:
|
||||
|
||||
- **Poor Visibility**: Daemon controls buried in developer console only
|
||||
- **No Real-Time Monitoring**: Manual status checks with raw JSON output
|
||||
- **No Automatic Management**: No startup detection or error recovery
|
||||
- **Disconnected UX**: Health events from Rust were ignored by frontend
|
||||
- **Manual Recovery**: Users had to manually restart failed services
|
||||
|
||||
### Solution Overview
|
||||
|
||||
This implementation creates a complete bridge between the Rust daemon's health system and the React frontend, providing:
|
||||
|
||||
- Real-time health monitoring with visual indicators
|
||||
- Automatic daemon startup and error recovery
|
||||
- User-friendly health displays in main UI
|
||||
- Enhanced developer tools with live status
|
||||
- Coordinated daemon and socket connection management
|
||||
|
||||
## Architecture
|
||||
|
||||
### System Components
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ React Frontend │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ UI Layer │
|
||||
│ ├── DaemonHealthIndicator (Main UI) │
|
||||
│ ├── DaemonHealthPanel (Detailed View) │
|
||||
│ └── Enhanced TauriCommandsPanel (Dev Tools) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ State Management │
|
||||
│ ├── daemonSlice.ts (Redux) │
|
||||
│ ├── useDaemonHealth.ts (React Hook) │
|
||||
│ └── useDaemonLifecycle.ts (Lifecycle Hook) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Services │
|
||||
│ └── daemonHealthService.ts (Event Processing) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Integration Layer │
|
||||
│ ├── tauriSocket.ts (Event Listening) │
|
||||
│ └── SocketProvider.tsx (Coordinated State) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
Tauri Event Bridge
|
||||
│
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Rust Daemon │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Health System (src-tauri/src/alphahuman/health/mod.rs) │
|
||||
│ ├── Component Health Tracking │
|
||||
│ ├── Health Snapshot Generation │
|
||||
│ └── Event Emission (every 5s) │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Daemon Supervisor (src-tauri/src/alphahuman/daemon/mod.rs) │
|
||||
│ ├── Component Management │
|
||||
│ ├── Automatic Restarts │
|
||||
│ └── Exponential Backoff │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ Components │
|
||||
│ ├── Gateway (API Server) │
|
||||
│ ├── Channels (Communication) │
|
||||
│ ├── Heartbeat (Health Monitor) │
|
||||
│ └── Scheduler (Cron Jobs) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Event Flow
|
||||
|
||||
1. **Health Generation**: Rust daemon generates health snapshots every 5 seconds
|
||||
2. **Event Emission**: Health data emitted via `alphahuman:health` Tauri event
|
||||
3. **Frontend Processing**: `daemonHealthService` receives and parses events
|
||||
4. **State Updates**: Redux state updated with component health information
|
||||
5. **UI Reactivity**: React components automatically re-render with new status
|
||||
6. **User Actions**: Manual controls trigger Tauri commands back to Rust
|
||||
|
||||
## Implementation Details
|
||||
|
||||
### Redux State Management
|
||||
|
||||
**File**: `src/store/daemonSlice.ts`
|
||||
|
||||
```typescript
|
||||
interface DaemonUserState {
|
||||
status: 'starting' | 'running' | 'error' | 'disconnected';
|
||||
healthSnapshot: HealthSnapshot | null;
|
||||
components: {
|
||||
gateway?: ComponentHealth;
|
||||
channels?: ComponentHealth;
|
||||
heartbeat?: ComponentHealth;
|
||||
scheduler?: ComponentHealth;
|
||||
};
|
||||
lastHealthUpdate: string | null;
|
||||
connectionAttempts: number;
|
||||
autoStartEnabled: boolean;
|
||||
isRecovering: boolean;
|
||||
healthTimeoutId: string | null;
|
||||
}
|
||||
```
|
||||
|
||||
**Key Features**:
|
||||
- Per-user daemon state isolation (following existing patterns)
|
||||
- Component-level health tracking with error details
|
||||
- Connection attempt management with exponential backoff
|
||||
- Auto-start preference persistence
|
||||
- Timeout handling for health event detection
|
||||
|
||||
### Health Monitoring Service
|
||||
|
||||
**File**: `src/services/daemonHealthService.ts`
|
||||
|
||||
```typescript
|
||||
export class DaemonHealthService {
|
||||
private healthTimeoutId: NodeJS.Timeout | null = null;
|
||||
private readonly HEALTH_TIMEOUT_MS = 30000; // 30 seconds
|
||||
|
||||
async setupHealthListener(): Promise<UnlistenFn | null>
|
||||
private parseHealthSnapshot(payload: unknown): HealthSnapshot | null
|
||||
private updateReduxFromHealth(snapshot: HealthSnapshot): void
|
||||
startHealthTimeout(): void
|
||||
}
|
||||
```
|
||||
|
||||
**Responsibilities**:
|
||||
- Listen for `alphahuman:health` Tauri events from Rust
|
||||
- Parse and validate health snapshot data
|
||||
- Update Redux state with component health information
|
||||
- Manage 30-second timeout detection for disconnected daemon
|
||||
- Handle cleanup and error recovery
|
||||
|
||||
### UI Components
|
||||
|
||||
#### DaemonHealthIndicator
|
||||
|
||||
**File**: `src/components/daemon/DaemonHealthIndicator.tsx`
|
||||
|
||||
**Purpose**: Compact status indicator for main application UI
|
||||
|
||||
**Visual States**:
|
||||
- 🟢 **Green**: All components running healthy (`status: 'running'`)
|
||||
- 🟡 **Yellow**: Daemon starting or recovering (`status: 'starting'`)
|
||||
- 🔴 **Red**: One or more components in error state (`status: 'error'`)
|
||||
- ⚪ **Gray**: Daemon disconnected or not running (`status: 'disconnected'`)
|
||||
|
||||
**Features**:
|
||||
- Click to open detailed health panel
|
||||
- Tooltip showing component health summary
|
||||
- Responsive sizing (sm/md/lg variants)
|
||||
- Only visible in Tauri environments
|
||||
|
||||
#### DaemonHealthPanel
|
||||
|
||||
**File**: `src/components/daemon/DaemonHealthPanel.tsx`
|
||||
|
||||
**Purpose**: Detailed health breakdown and manual controls
|
||||
|
||||
**Features**:
|
||||
- Component health table with status, last update, restart counts
|
||||
- Manual restart buttons for individual components
|
||||
- Auto-start toggle with persistence
|
||||
- Connection retry controls
|
||||
- Real-time health information display
|
||||
- User-friendly error messages and troubleshooting hints
|
||||
|
||||
### Lifecycle Management
|
||||
|
||||
**File**: `src/hooks/useDaemonLifecycle.ts`
|
||||
|
||||
**Automatic Behaviors**:
|
||||
|
||||
1. **App Startup**:
|
||||
- Detect existing daemon status
|
||||
- Auto-start daemon if enabled and not running
|
||||
- Setup health monitoring listeners
|
||||
|
||||
2. **Error Recovery**:
|
||||
- Exponential backoff retry attempts (1s → 2s → 4s → 8s → 30s max)
|
||||
- Maximum 5 retry attempts before requiring manual intervention
|
||||
- Clear error states on successful recovery
|
||||
|
||||
3. **Background Handling**:
|
||||
- Maintain health monitoring when app backgrounded
|
||||
- Reconnection logic without page refresh
|
||||
- Coordinate with socket connection management
|
||||
|
||||
4. **Cleanup**:
|
||||
- Proper event listener cleanup on unmount
|
||||
- Timeout cancellation to prevent memory leaks
|
||||
- Graceful shutdown coordination
|
||||
|
||||
### Integration Points
|
||||
|
||||
#### Enhanced Service Management
|
||||
|
||||
**File**: `src/components/settings/panels/TauriCommandsPanel.tsx`
|
||||
|
||||
**Improvements to Existing Developer Console**:
|
||||
|
||||
- **Live Status Display**: Real-time daemon status with PID and uptime
|
||||
- **Component Health Grid**: Visual status for all daemon components
|
||||
- **Enhanced Controls**: Smart start/stop buttons with proper loading states
|
||||
- **Auto-Start Toggle**: User preference for automatic daemon startup
|
||||
- **Connection Tracking**: Display retry attempts and recovery status
|
||||
- **Better Error Messages**: User-friendly errors with troubleshooting hints
|
||||
|
||||
**Before vs After**:
|
||||
```typescript
|
||||
// Before: Manual status check
|
||||
<PrimaryButton onClick={() => run(alphahumanServiceStatus, 'serviceStatus')}>
|
||||
Status
|
||||
</PrimaryButton>
|
||||
|
||||
// After: Live status display
|
||||
<div className="flex items-center gap-3">
|
||||
<DaemonHealthIndicator size="md" />
|
||||
<div>
|
||||
<div className="text-white font-medium">Daemon Status: {status}</div>
|
||||
<div className="text-xs text-gray-400">PID: {pid} | Uptime: {uptime}</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
#### Socket Provider Integration
|
||||
|
||||
**File**: `src/providers/SocketProvider.tsx`
|
||||
|
||||
**Coordinated State Management**:
|
||||
- Check daemon health before attempting socket connections
|
||||
- Display daemon-related errors in socket connection status
|
||||
- Coordinate daemon startup with socket connection flows
|
||||
- Provide daemon health context to socket consumers
|
||||
|
||||
#### Main UI Integration
|
||||
|
||||
**File**: `src/components/MiniSidebar.tsx`
|
||||
|
||||
**User-Facing Integration**:
|
||||
- Daemon health indicator in main navigation (Tauri-only)
|
||||
- Click to open detailed health modal
|
||||
- Non-intrusive but easily accessible
|
||||
- Consistent with existing UI patterns
|
||||
|
||||
## User Experience
|
||||
|
||||
### For End Users
|
||||
|
||||
1. **Visible Status**: Daemon health indicator in main UI shows system status at a glance
|
||||
2. **Automatic Operation**: Daemon starts automatically and recovers from errors without user intervention
|
||||
3. **Clear Feedback**: User-friendly messages explain daemon state and provide actionable guidance
|
||||
4. **Quick Access**: Click health indicator to see detailed component status and manual controls
|
||||
|
||||
### For Developers
|
||||
|
||||
1. **Enhanced Console**: Improved service management in settings with live status updates
|
||||
2. **Component Monitoring**: Real-time visibility into all daemon components (gateway, channels, etc.)
|
||||
3. **Debug Information**: Detailed health snapshots, retry attempts, and error history
|
||||
4. **Manual Override**: Full control over daemon lifecycle with proper state management
|
||||
|
||||
### Error Handling
|
||||
|
||||
1. **Graceful Degradation**: System works properly in non-Tauri environments
|
||||
2. **Timeout Management**: 30-second timeout detection with automatic recovery attempts
|
||||
3. **User Guidance**: Clear error messages with troubleshooting suggestions
|
||||
4. **Recovery Actions**: Manual restart options when automatic recovery fails
|
||||
|
||||
## Technical Benefits
|
||||
|
||||
### Performance
|
||||
|
||||
- **Efficient Updates**: Debounced Redux updates prevent excessive re-renders
|
||||
- **Memory Management**: Proper cleanup of timeouts and event listeners
|
||||
- **Background Optimization**: Minimal resource usage when app backgrounded
|
||||
|
||||
### Reliability
|
||||
|
||||
- **Timeout Handling**: Robust detection of daemon disconnection
|
||||
- **Exponential Backoff**: Smart retry logic prevents resource exhaustion
|
||||
- **State Consistency**: Coordinated daemon and socket connection states
|
||||
- **Error Recovery**: Automatic recovery from transient failures
|
||||
|
||||
### Maintainability
|
||||
|
||||
- **TypeScript**: Full type safety throughout the implementation
|
||||
- **Modular Design**: Clear separation between state, services, and UI components
|
||||
- **Existing Patterns**: Follows established Redux and component patterns
|
||||
- **Testing**: Comprehensive error handling and edge case management
|
||||
|
||||
## Configuration
|
||||
|
||||
### Auto-Start Behavior
|
||||
|
||||
Users can control daemon auto-start behavior through:
|
||||
|
||||
1. **UI Toggle**: Available in both health panel and settings console
|
||||
2. **Persistence**: Preference stored in Redux with persistence
|
||||
3. **Default**: Auto-start enabled by default for better UX
|
||||
|
||||
### Health Monitoring
|
||||
|
||||
- **Event Frequency**: Rust daemon emits health every 5 seconds
|
||||
- **Timeout Duration**: 30 seconds without health events = disconnected
|
||||
- **Retry Logic**: Maximum 5 attempts with exponential backoff
|
||||
- **Component Tracking**: Gateway, channels, heartbeat, scheduler components
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### Potential Improvements
|
||||
|
||||
1. **Health History**: Track daemon health over time with charts/graphs
|
||||
2. **Performance Metrics**: CPU/memory usage from daemon components
|
||||
3. **Log Integration**: Show daemon logs directly in health panel
|
||||
4. **Mobile Optimization**: Enhanced mobile-specific daemon management
|
||||
5. **Notification System**: Push notifications for critical daemon events
|
||||
|
||||
### Extensibility
|
||||
|
||||
The architecture supports easy extension for:
|
||||
- Additional daemon components
|
||||
- Custom health check logic
|
||||
- Third-party integrations
|
||||
- Advanced monitoring features
|
||||
|
||||
## Conclusion
|
||||
|
||||
The Daemon Lifecycle Management System provides a complete bridge between the sophisticated Rust daemon infrastructure and the React frontend, delivering excellent user experience while maintaining the technical robustness required for a production application.
|
||||
|
||||
The implementation follows established patterns, provides comprehensive error handling, and creates a foundation for future daemon-related features while ensuring the system remains reliable and user-friendly.
|
||||
Reference in New Issue
Block a user