145 lines
4.3 KiB
Markdown
145 lines
4.3 KiB
Markdown
# SPORE Gateway
|
|
|
|
A gateway service providing UDP-based node discovery, cluster management, and HTTP API endpoints for SPORE devices.
|
|
|
|
## Features
|
|
|
|
- **UDP Node Discovery**: Listens for heartbeat messages from SPORE nodes on port 4210
|
|
- **Cluster Management**: Tracks node status, manages primary node selection, and handles failover
|
|
- **HTTP API Server**: Provides REST endpoints for cluster information, node management, and proxy calls
|
|
- **WebSocket Server**: Real-time cluster updates via WebSocket connections
|
|
- **Failover Logic**: Automatic switching between SPORE nodes when primary fails
|
|
- **Proxy Functionality**: Generic proxy calls to SPORE node capabilities
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
go mod tidy
|
|
go build
|
|
```
|
|
|
|
## Usage
|
|
|
|
```bash
|
|
./spore-gateway [options]
|
|
|
|
Options:
|
|
-port string
|
|
HTTP server port (default "3001")
|
|
-udp-port string
|
|
UDP discovery port (default "4210")
|
|
-mqtt string
|
|
Enable MQTT integration with server URL (e.g., tcp://localhost:1883)
|
|
-log-level string
|
|
Log level (debug, info, warn, error) (default "info")
|
|
```
|
|
|
|
### MQTT Integration
|
|
|
|
The gateway can integrate with an MQTT broker to subscribe to all MQTT topics and forward messages to connected WebSocket clients.
|
|
|
|
To enable MQTT integration:
|
|
|
|
```bash
|
|
# Basic usage
|
|
./spore-gateway -mqtt tcp://localhost:1883
|
|
|
|
# With authentication (using environment variables)
|
|
MQTT_USER=username MQTT_PASSWORD=password ./spore-gateway -mqtt tcp://broker.example.com:1883
|
|
```
|
|
|
|
When enabled, the gateway will:
|
|
- Connect to the specified MQTT broker
|
|
- Subscribe to all topics (`#`)
|
|
- Forward all received messages to connected WebSocket clients with the format:
|
|
```json
|
|
{
|
|
"topic": "sensor/temperature",
|
|
"data": "{\"value\": 23.5}",
|
|
"timestamp": "2024-01-15T10:30:00Z"
|
|
}
|
|
```
|
|
|
|
Environment variables:
|
|
- `MQTT_USER`: Username for MQTT broker authentication (optional)
|
|
- `MQTT_PASSWORD`: Password for MQTT broker authentication (optional)
|
|
|
|
## Integration
|
|
|
|
The spore-gateway works together with the SPORE UI frontend:
|
|
|
|
- **spore-gateway**: Runs on port 3001, handles UDP discovery, API endpoints, and WebSocket connections
|
|
- **spore-ui**: Runs on port 3000, serves the frontend interface and connects to spore-gateway for all backend functionality
|
|
|
|
Start spore-gateway first, then start the frontend:
|
|
```bash
|
|
# Terminal 1 - Start backend
|
|
./spore-gateway
|
|
|
|
# Terminal 2 - Start frontend
|
|
cd ../spore-ui && npm start
|
|
```
|
|
|
|
Access the UI at: `http://localhost:3000`
|
|
|
|
## API Endpoints
|
|
|
|
### Discovery
|
|
- `GET /api/discovery/nodes` - Get discovered nodes and cluster status
|
|
- `POST /api/discovery/refresh` - Refresh cluster state
|
|
- `POST /api/discovery/random-primary` - Select random primary node
|
|
- `POST /api/discovery/primary/{ip}` - Set specific node as primary
|
|
|
|
### Cluster
|
|
- `GET /api/cluster/members` - Get cluster member information
|
|
- `POST /api/cluster/refresh` - Trigger cluster refresh
|
|
|
|
### Tasks
|
|
- `GET /api/tasks/status` - Get task status (optionally for specific node)
|
|
|
|
### Nodes
|
|
- `GET /api/node/status` - Get system status
|
|
- `GET /api/node/status/{ip}` - Get system status for specific node
|
|
- `GET /api/node/endpoints` - Get available API endpoints
|
|
- `POST /api/node/update` - Upload firmware to node
|
|
|
|
### Proxy
|
|
- `POST /api/proxy-call` - Make generic proxy call to SPORE node
|
|
|
|
### Testing
|
|
- `POST /api/test/websocket` - Test WebSocket broadcasting
|
|
|
|
### Health
|
|
- `GET /api/health` - Health check endpoint
|
|
|
|
## WebSocket
|
|
|
|
Connect to `/ws` for real-time cluster updates.
|
|
|
|
## Development
|
|
|
|
The application follows the same patterns as the original Node.js spore-ui server but is implemented in Go with:
|
|
|
|
- Structured logging using logrus
|
|
- Graceful shutdown handling
|
|
- Concurrent-safe node management
|
|
- HTTP middleware for CORS and logging
|
|
- WebSocket support for real-time updates
|
|
|
|
## Documentation
|
|
|
|
See the `docs/` directory for detailed documentation:
|
|
- [MQTT Integration](./docs/MQTT.md) - MQTT message forwarding and integration
|
|
- [Rollout Process](./docs/Rollout.md) - Firmware rollout orchestration
|
|
- [Testing Tools](./hack/README.md) - Local MQTT broker and testing scripts
|
|
|
|
## Architecture
|
|
|
|
- `main.go` - Application entry point
|
|
- `internal/discovery/` - UDP-based node discovery
|
|
- `internal/server/` - HTTP API server
|
|
- `internal/websocket/` - WebSocket server for real-time updates
|
|
- `internal/mqtt/` - MQTT client and message forwarding
|
|
- `pkg/client/` - SPORE API client
|
|
- `pkg/config/` - Configuration management
|