iot/spore-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: live topology view through websocket updates

Browse Source
This commit is contained in:
0x1d
2025-10-23 20:36:07 +02:00
parent ce836e7636
commit fa6777a042
4 changed files with 909 additions and 250 deletions
Download Patch File Download Diff File Expand all files Collapse all files

169
docs/FIRMWARE_REGISTRY_INTEGRATION.md Normal file
View File

@@ -0,0 +1,169 @@
# Firmware Registry Integration
This document describes the integration of the SPORE Registry into the SPORE UI, replacing the previous firmware upload functionality with a comprehensive CRUD interface for managing firmware in the registry.
## Overview
The firmware view has been completely redesigned to provide:
- **Registry Management**: Full CRUD operations for firmware in the SPORE Registry
- **Search & Filter**: Search firmware by name, version, or labels
- **Drawer Forms**: Add/edit forms displayed in the existing drawer component
- **Real-time Status**: Registry connection status indicator
- **Download Support**: Direct download of firmware binaries
## Architecture
### Components
1. **FirmwareComponent** (`FirmwareComponent.js`)
- Main component for the firmware registry interface
- Handles CRUD operations and UI interactions
- Manages registry connection status
2. **FirmwareFormComponent** (`FirmwareFormComponent.js`)
- Form component for add/edit operations
- Used within the drawer component
- Handles metadata and file uploads
3. **API Client Extensions** (`api-client.js`)
- New registry API methods added to existing ApiClient
- Auto-detection of registry server URL
- Support for multipart form data uploads
### API Integration
The integration uses the SPORE Registry API endpoints:
- `GET /health` - Health check
- `GET /firmware` - List firmware with optional filtering
- `POST /firmware` - Upload firmware with metadata
- `GET /firmware/{name}/{version}` - Download firmware binary
### Registry Server Configuration
The registry server is expected to run on:
- **Localhost**: `http://localhost:8080`
- **Remote**: `http://{hostname}:8080`
The UI automatically detects the appropriate URL based on the current hostname.
## Features
### Firmware Management
- **Add Firmware**: Upload new firmware with metadata and labels
- **Edit Firmware**: Modify existing firmware (requires new file upload)
- **Download Firmware**: Direct download of firmware binaries
- **Delete Firmware**: Remove firmware from registry (not yet implemented in API)
### Search & Filtering
- **Text Search**: Search by firmware name, version, or label values
- **Real-time Filtering**: Results update as you type
- **Label Display**: Visual display of firmware labels with color coding
### User Interface
- **Card Layout**: Clean card-based layout for firmware entries
- **Action Buttons**: Edit, download, and delete actions for each firmware
- **Status Indicators**: Registry connection status with visual feedback
- **Loading States**: Proper loading indicators during operations
- **Error Handling**: User-friendly error messages and notifications
### Form Interface
- **Drawer Integration**: Forms open in the existing drawer component
- **Metadata Fields**: Name, version, and custom labels
- **File Upload**: Drag-and-drop or click-to-upload file selection
- **Label Management**: Add/remove key-value label pairs
- **Validation**: Client-side validation with helpful error messages
## Usage
### Adding Firmware
1. Click the "Add Firmware" button in the header
2. Fill in the firmware name and version
3. Select a firmware file (.bin or .hex)
4. Add optional labels (key-value pairs)
5. Click "Upload Firmware"
### Editing Firmware
1. Click the edit button on any firmware card
2. Modify the metadata (name and version are read-only)
3. Upload a new firmware file
4. Update labels as needed
5. Click "Update Firmware"
### Downloading Firmware
1. Click the download button on any firmware card
2. The firmware binary will be downloaded automatically
### Searching Firmware
1. Use the search box to filter firmware
2. Search by name, version, or label values
3. Results update in real-time
## Testing
A test suite is provided to verify the registry integration:
```bash
cd spore-ui/test
node registry-integration-test.js
```
The test suite verifies:
- Registry health check
- List firmware functionality
- Upload firmware functionality
- Download firmware functionality
## Configuration
### Registry Server
Ensure the SPORE Registry server is running on port 8080:
```bash
cd spore-registry
go run main.go
```
### UI Configuration
The UI automatically detects the registry server URL. No additional configuration is required.
## Error Handling
The integration includes comprehensive error handling:
- **Connection Errors**: Clear indication when registry is unavailable
- **Upload Errors**: Detailed error messages for upload failures
- **Validation Errors**: Client-side validation with helpful messages
- **Network Errors**: Graceful handling of network timeouts and failures
## Future Enhancements
Planned improvements include:
- **Delete Functionality**: Complete delete operation when API supports it
- **Bulk Operations**: Select multiple firmware for bulk operations
- **Version History**: View and manage firmware version history
- **Deployment Integration**: Deploy firmware directly to nodes from registry
- **Advanced Filtering**: Filter by date, size, or other metadata
## Migration Notes
The previous firmware upload functionality has been completely replaced. The new interface provides:
- Better organization with the registry
- Improved user experience with search and filtering
- Consistent UI patterns with the rest of the application
- Better error handling and user feedback
All existing firmware functionality is now handled through the registry interface.

248
docs/TOPOLOGY_WEBSOCKET_UPDATE.md Normal file
View File

@@ -0,0 +1,248 @@
# Topology Component WebSocket Integration
## Summary
Enhanced the topology graph component to support real-time node additions and removals via WebSocket connections. The topology view now automatically updates when nodes join or leave the cluster without requiring manual refresh. Existing nodes update their properties (status, labels) smoothly in place without being removed and re-added.
## Changes Made
### 1. TopologyViewModel (`spore-ui/public/scripts/view-models.js`)
Added `setupWebSocketListeners()` method to the TopologyViewModel class:
- **Listens to `clusterUpdate` events**: When cluster membership changes, the topology graph is automatically rebuilt with the new node data
- **Listens to `nodeDiscovery` events**: When a new node is discovered or becomes stale, triggers a topology update
- **Listens to connection status**: Automatically refreshes topology when WebSocket reconnects
- **Async graph updates**: Rebuilds graph data asynchronously from WebSocket data to avoid blocking the UI
Enhanced `buildEnhancedGraphData()` method to preserve node state:
- **Position preservation**: Existing nodes retain their x, y coordinates across updates
- **Velocity preservation**: D3 simulation velocity (vx, vy) is maintained for smooth physics
- **Fixed position preservation**: Manually dragged nodes (fx, fy) stay in place
- **New nodes only**: Only newly discovered nodes get random initial positions
- **Result**: Nodes no longer "jump" or get removed/re-added when their properties update
### 2. TopologyGraphComponent (`spore-ui/public/scripts/components/TopologyGraphComponent.js`)
#### Added WebSocket Setup
- Added `setupWebSocketListeners()` method that calls the view model's WebSocket setup during component initialization
- Integrated into the `initialize()` lifecycle method
#### Improved Dynamic Updates (D3.js Enter/Exit Pattern)
Refactored the graph rendering to use D3's data binding patterns for smooth transitions:
- **`updateLinks()`**: Uses enter/exit pattern to add/remove links with fade transitions
- **`updateNodes()`**: Uses enter/exit pattern to add/remove nodes with fade transitions
- New nodes fade in (300ms transition)
- Removed nodes fade out (300ms transition)
- Existing nodes smoothly update their properties
- **`updateLinkLabels()`**: Dynamically updates link latency labels
- **`updateSimulation()`**: Handles D3 force simulation updates
- Creates new simulation on first render
- Updates existing simulation with new node/link data on subsequent renders
- Maintains smooth physics-based layout
- **`addLegend()`**: Fixed to prevent duplicate legend creation
#### Key Improvements
- **Incremental updates**: Instead of recreating the entire graph, only modified nodes/links are added or removed
- **Smooth animations**: 300ms fade transitions for adding/removing elements
- **In-place updates**: Existing nodes update their properties without being removed/re-added
- **Preserved interactions**: Click, hover, and drag interactions work seamlessly with dynamic updates
- **Efficient rendering**: D3's data binding with key functions ensures optimal DOM updates
- **Intelligent simulation**: Uses different alpha values (0.1 for updates, 0.3 for additions/removals) to minimize disruption
- **Drag-aware updates**: WebSocket updates are deferred while dragging and applied after drag completes
- **Uninterrupted dragging**: Drag operations are never interrupted by incoming updates
- **Rearrange button**: Convenient UI control to reset node layout and clear manual positioning
## How It Works
### Data Flow
```
WebSocket Server (spore-ui backend)
↓ (cluster_update / node_discovery events)
WebSocketClient (api-client.js)
↓ (emits clusterUpdate / nodeDiscovery events)
TopologyViewModel.setupWebSocketListeners()
↓ (builds graph data, updates state)
TopologyGraphComponent subscriptions
↓ (renderGraph() called automatically)
├─ If dragging: queue update in pendingUpdate
└─ If not dragging: apply update immediately
D3.js enter/exit pattern
↓ (smooth visual updates)
Updated Topology Graph
```
### Simplified Update Architecture
**Core Principle**: The D3 simulation is the single source of truth for positions.
#### How It Works:
1. **Drag Deferral**:
- `isDragging` flag blocks updates during drag
- Updates queued in `pendingUpdate` and applied after drag ends
- Dragged positions saved in `draggedNodePositions` Map for persistence
2. **Position Merging** (in `updateNodes()`):
- When simulation exists: copy live positions from simulation nodes to new data
- This preserves ongoing animations and velocities
- Then apply dragged positions (if any) as overrides
- Result: Always use most current position state
3. **Smart Simulation Updates** (in `updateSimulation()`):
- **Structural changes** (nodes added/removed): restart with alpha=0.3
- **Property changes** (status, labels): DON'T restart - just update data
- Simulation continues naturally for property-only changes
- No unnecessary disruptions to ongoing animations
This ensures:
- ✅ Simulation is authoritative for positions
- ✅ No position jumping during animations
- ✅ Property updates don't disrupt node movement
- ✅ Dragged positions always respected
- ✅ Simple, clean logic with one source of truth
### WebSocket Events Handled
1. **`clusterUpdate`** (from `cluster_update` message type)
- Payload: `{ members: [...], primaryNode: string, totalNodes: number, timestamp: string }`
- Action: Rebuilds graph with current cluster state
2. **`nodeDiscovery`** (from `node_discovery` message type)
- Payload: `{ action: 'discovered' | 'stale', nodeIp: string, timestamp: string }`
- Action: Triggers topology refresh after 500ms delay
3. **`connected`** (WebSocket connection established)
- Action: Triggers topology refresh after 1000ms delay
4. **`disconnected`** (WebSocket connection lost)
- Action: Logs disconnection (no action taken)
## Benefits
1. **Real-time Updates**: Topology reflects cluster state changes immediately
2. **Smooth Transitions**: Nodes and links fade in/out gracefully
3. **Better UX**: No manual refresh needed
4. **Efficient**: Only updates changed elements, not entire graph
5. **Resilient**: Automatically refreshes on reconnection
6. **Consistent**: Uses same WebSocket infrastructure as ClusterStatusComponent
## Testing
To test the WebSocket integration:
1. **Start the application**:
```bash
cd spore-ui
node index-standalone.js
```
2. **Open the UI** and navigate to the Topology view
3. **Add a node**: Start a new SPORE device on the network
- Watch it appear in the topology graph within seconds
- Node should fade in smoothly
4. **Remove a node**: Stop a SPORE device
- Watch it fade out from the topology graph
- Connected links should also disappear
5. **Status changes**: Change node status (active → inactive → dead)
- Node colors should update automatically
- Status indicators should change
6. **Drag during updates**:
- Start dragging a node
- While dragging, trigger a cluster update (add/remove/change another node)
- Drag should continue smoothly without interruption
- After releasing, the update should be applied immediately
- **Important**: The dragged node should stay at its final position, not revert
7. **Position persistence after drag**:
- Drag a node to a new position and release
- Trigger multiple WebSocket updates (status changes, new nodes, etc.)
- The dragged node should remain in its new position through all updates
- Only when the node is removed should its position be forgotten
8. **Update during animation**:
- Let the graph settle (simulation running, nodes animating to stable positions)
- While nodes are still moving, trigger a WebSocket update (status change)
- **Expected**: Nodes should continue their smooth animation without jumping
- **No flickering**: Positions should not snap back and forth
- Animation should feel continuous and natural
9. **Single node scenario**:
- Start with multiple nodes in the topology
- Remove nodes one by one until only one remains
- **Expected**: Single node stays visible, no "loading" message
- Graph should render correctly with just one node
- Remove the last node
- **Expected**: "No cluster members found" message appears
10. **Rearrange nodes**:
- Drag nodes to custom positions manually
- Click the "Rearrange" button in the top-left corner
- **Expected**: All nodes reset to physics-based positions
- Dragged positions cleared, simulation restarts
- Nodes animate to a clean, evenly distributed layout
11. **WebSocket reconnection**:
- Disconnect from network briefly
- Reconnect
- Topology should refresh automatically
## Technical Notes
### Architecture
- **Single Source of Truth**: D3 simulation manages all position state
- **Key Functions**: D3 data binding uses node IPs as keys to track identity
- **Transition Duration**: 300ms for fade in/out animations
### Position Management (Simplified!)
- **updateNodes()**: Copies live positions from simulation to new data before binding
- **No complex syncing**: Simulation state flows naturally to new data
- **Dragged positions**: Override via `draggedNodePositions` Map (always respected)
### Simulation Behavior
- **Structural changes** (add/remove nodes): Restart with alpha=0.3
- **Property changes** (status, labels): No restart - data updated in-place
- **Drag operations**: Simulation updates blocked entirely
- **Result**: Smooth animations for property updates, controlled restart for structure changes
### Drag Management
- **isDragging flag**: Blocks all updates during drag
- **pendingUpdate**: Queues one update, applied 50ms after drag ends
- **draggedNodePositions Map**: Persists manual positions across all updates
- **Cleanup**: Map entries removed when nodes deleted
### Performance
- **No unnecessary restarts**: Property-only updates don't disrupt simulation
- **Efficient merging**: Position data copied via Map lookup (O(n))
- **Memory efficient**: Only active nodes tracked, old entries cleaned up
- **Smooth animations**: Velocity and momentum preserved across updates
### Edge Cases Handled
- **Single node**: Graph renders correctly with just one node
- **Transient states**: Loading/no-data states don't clear existing SVG
- **Update races**: SVG preserved even if loading state triggered during render
- **Empty to non-empty**: Smooth transition from loading to first node
## Future Enhancements
Possible improvements for future iterations:
1. **Diff-based updates**: Only rebuild graph when node/link structure actually changes
2. **Visual indicators**: Show "new node" or "leaving node" badges temporarily
3. **Connection health**: Real-time latency updates on links without full rebuild
4. **Throttling**: Debounce rapid successive updates
5. **Persistent layout**: Save and restore user-arranged topology layouts
6. **Zoom to node**: Auto-zoom to newly added nodes with animation
## Related Files
- `spore-ui/public/scripts/view-models.js` - TopologyViewModel class
- `spore-ui/public/scripts/components/TopologyGraphComponent.js` - Topology visualization component
- `spore-ui/public/scripts/api-client.js` - WebSocketClient class
- `spore-ui/index-standalone.js` - WebSocket server implementation