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

go mod tidy
go build

Usage

./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:

# 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:

{
  "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:

# 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 - MQTT message forwarding and integration
Rollout Process - Firmware rollout orchestration
Testing Tools - 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