# 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