iot/spore-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
spore-ui/docs/TOPOLOGY_WEBSOCKET_UPDATE.md

11 KiB
Raw Permalink Blame History

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:

    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
  1. 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