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

docs: update

Browse Source
This commit is contained in:
0x1d
2025-10-19 14:05:00 +02:00
parent d166b0b634
commit 56e54e0b31
3 changed files with 13 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
README.md
View File

@@ -42,19 +42,19 @@ Zero-configuration web interface for monitoring and managing SPORE embedded syst
- **API**: SPORE Embedded System API - **API**: SPORE Embedded System API
- **Design**: Glassmorphism, CSS Grid, Flexbox - **Design**: Glassmorphism, CSS Grid, Flexbox
## UDP Auto Discovery ## UDP Heartbeat Discovery
The backend now includes automatic UDP discovery for SPORE nodes on the network. This eliminates the need for hardcoded IP addresses and provides a self-healing, scalable solution for managing SPORE clusters. The backend now includes automatic UDP heartbeat-based discovery for SPORE nodes on the network. This eliminates the need for hardcoded IP addresses and provides a self-healing, scalable solution for managing SPORE clusters.
### 🚀 How It Works ### 🚀 How It Works
1. **UDP Server**: The backend listens on port 4210 for UDP messages 1. **UDP Server**: The backend listens on port 4210 for UDP messages
2. **Heartbeat Message**: Nodes send `CLUSTER_HEARTBEAT` messages to broadcast address `255.255.255.255:4210` 2. **Heartbeat Message**: Nodes send `CLUSTER_HEARTBEAT` messages to broadcast address `255.255.255.255:4210`
3. **Auto Configuration**: When a discovery message is received, the source IP is automatically used to configure the SporeApiClient 3. **Auto Configuration**: When a heartbeat message is received, the source IP is automatically used to configure the SporeApiClient
4. **Dynamic Updates**: The system automatically switches to the most recently seen node as the primary connection 4. **Dynamic Updates**: The system automatically switches to the most recently seen node as the primary connection
5. **Health Monitoring**: Continuous monitoring of node availability with automatic failover 5. **Health Monitoring**: Continuous monitoring of node availability with automatic failover
### 📡 Discovery Protocol ### 📡 Heartbeat Protocol
- **Port**: 4210 (configurable via `UDP_PORT` constant) - **Port**: 4210 (configurable via `UDP_PORT` constant)
- **Message**: `CLUSTER_HEARTBEAT` (configurable via `HEARTBEAT_MESSAGE` constant) - **Message**: `CLUSTER_HEARTBEAT` (configurable via `HEARTBEAT_MESSAGE` constant)
@@ -71,7 +71,7 @@ npm start
# The server will automatically: # The server will automatically:
# - Start HTTP server on port 3001 # - Start HTTP server on port 3001
# - Start UDP discovery server on port 4210 # - Start UDP heartbeat server on port 4210
# - Wait for CLUSTER_HEARTBEAT messages # - Wait for CLUSTER_HEARTBEAT messages
``` ```

14
docs/DISCOVERY.md
View File

@@ -8,12 +8,12 @@ The backend has been successfully updated to implement UDP auto discovery, elimi
### 1. UDP Discovery Server ### 1. UDP Discovery Server
- **Port**: 4210 (configurable via `UDP_PORT` constant) - **Port**: 4210 (configurable via `UDP_PORT` constant)
- **Message**: `CLUSTER_DISCOVERY` (configurable via `DISCOVERY_MESSAGE` constant) - **Message**: `CLUSTER_HEARTBEAT` (configurable via `HEARTBEAT_MESSAGE` constant)
- **Protocol**: UDP broadcast listening - **Protocol**: UDP broadcast listening
- **Auto-binding**: Automatically binds to the specified port on startup - **Auto-binding**: Automatically binds to the specified port on startup
### 2. Dynamic Node Management ### 2. Dynamic Node Management
- **Automatic Discovery**: Nodes are discovered when they send `CLUSTER_DISCOVERY` messages - **Automatic Discovery**: Nodes are discovered when they send `CLUSTER_HEARTBEAT` messages
- **Primary Node Selection**: The most recently seen node becomes the primary connection - **Primary Node Selection**: The most recently seen node becomes the primary connection
- **Stale Node Cleanup**: Nodes not seen for 5+ minutes are automatically removed - **Stale Node Cleanup**: Nodes not seen for 5+ minutes are automatically removed
- **Health Monitoring**: Continuous monitoring of node availability - **Health Monitoring**: Continuous monitoring of node availability
@@ -45,14 +45,14 @@ The backend has been successfully updated to implement UDP auto discovery, elimi
``` ```
1. Backend starts and binds UDP server to port 4210 1. Backend starts and binds UDP server to port 4210
2. HTTP server starts on port 3001 2. HTTP server starts on port 3001
3. System waits for CLUSTER_DISCOVERY messages 3. System waits for CLUSTER_HEARTBEAT messages
4. When messages arrive, nodes are automatically discovered 4. When messages arrive, nodes are automatically discovered
5. SporeApiClient is configured with the first discovered node 5. SporeApiClient is configured with the first discovered node
``` ```
### 2. Discovery Process ### 2. Discovery Process
``` ```
1. Node sends "CLUSTER_DISCOVERY" to 255.255.255.255:4210 1. Node sends "CLUSTER_HEARTBEAT:hostname" to 255.255.255.255:4210
2. Backend receives message and extracts source IP 2. Backend receives message and extracts source IP
3. Node is added to discovered nodes list 3. Node is added to discovered nodes list
4. If no primary node exists, this becomes the primary 4. If no primary node exists, this becomes the primary
@@ -71,11 +71,11 @@ The backend has been successfully updated to implement UDP auto discovery, elimi
### Environment Variables ### Environment Variables
- `PORT`: HTTP server port (default: 3001) - `PORT`: HTTP server port (default: 3001)
- `UDP_PORT`: UDP discovery port (default: 4210) - `UDP_PORT`: UDP heartbeat port (default: 4210)
### Constants (in index.js) ### Constants (in index.js)
- `UDP_PORT`: Discovery port (currently 4210) - `UDP_PORT`: Heartbeat port (currently 4210)
- `DISCOVERY_MESSAGE`: Expected message (currently "CLUSTER_DISCOVERY") - `HEARTBEAT_MESSAGE`: Expected message (currently "CLUSTER_HEARTBEAT")
- Stale timeout: 5 minutes (configurable in `cleanupStaleNodes()`) - Stale timeout: 5 minutes (configurable in `cleanupStaleNodes()`)
- Health check interval: 5 seconds (configurable in `setInterval`) - Health check interval: 5 seconds (configurable in `setInterval`)

2
index.js
View File

@@ -596,7 +596,7 @@ app.get('/api/node/status', async (req, res) => {
if (discoveredNodes.size === 0) { if (discoveredNodes.size === 0) {
return res.status(503).json({ return res.status(503).json({
error: 'Service unavailable', error: 'Service unavailable',
message: 'No SPORE nodes discovered yet. Waiting for CLUSTER_DISCOVERY messages...', message: 'No SPORE nodes discovered yet. Waiting for CLUSTER_HEARTBEAT messages...',
discoveredNodes: Array.from(discoveredNodes.keys()) discoveredNodes: Array.from(discoveredNodes.keys())
}); });
} }