spore-gateway/docs/QUICKSTART_MOCK.md

Mock Gateway Quick Start Guide

Get started with the SPORE Mock Gateway in under 1 minute!

TL;DR

# Build and run
go build -o mock-gateway cmd/mock-gateway/main.go
./mock-gateway

That's it! The mock gateway is now running on http://localhost:3001

What You Get

✅ 5 mock SPORE nodes ready to use
✅ All REST API endpoints working
✅ WebSocket support for real-time updates
✅ Mock firmware registry with sample firmware
✅ Simulated rollouts with progress tracking

Test It

1. Check Health

curl http://localhost:3001/api/health | jq

2. List Nodes

curl http://localhost:3001/api/discovery/nodes | jq

3. Get Cluster Members

curl http://localhost:3001/api/cluster/members | jq

4. List Firmware

curl http://localhost:3001/api/registry/firmware | jq

5. Connect WebSocket

const ws = new WebSocket('ws://localhost:3001/ws');
ws.onmessage = (event) => console.log(JSON.parse(event.data));

Customize It

# More nodes
./mock-gateway -mock-nodes 10

# Different port
./mock-gateway -port 8080

# Debug logging
./mock-gateway -log-level debug

# Faster updates
./mock-gateway -heartbeat-rate 2

# All together
./mock-gateway -port 8080 -mock-nodes 10 -log-level debug -heartbeat-rate 2

Use the Script

# Easy run with default settings
./scripts/run-mock-gateway.sh

# With custom options
./scripts/run-mock-gateway.sh -p 8080 -n 10 -l debug

# See all options
./scripts/run-mock-gateway.sh --help

Connect Your Frontend

Point your frontend to http://localhost:3001 instead of the real gateway. All endpoints work the same way!

// React example
const API_BASE = 'http://localhost:3001';
const WS_URL = 'ws://localhost:3001/ws';

// Fetch nodes
const nodes = await fetch(`${API_BASE}/api/discovery/nodes`).then(r => r.json());

// WebSocket connection
const ws = new WebSocket(WS_URL);

What's Mocked?

✅ Node discovery (5 default nodes: 192.168.1.100-104)
✅ Cluster management
✅ Firmware uploads (90% success rate, 2s delay)
✅ Rollouts (simulated progress: labels → upload → complete)
✅ Task status
✅ System status
✅ Registry operations
✅ WebSocket broadcasts

Example Workflow

# 1. Start mock gateway
./mock-gateway

# 2. In another terminal, test the API
curl http://localhost:3001/api/discovery/nodes | jq '.nodes[0]'

# 3. Start a rollout
curl -X POST http://localhost:3001/api/rollout \
  -H "Content-Type: application/json" \
  -d '{
    "firmware": {"name": "spore-firmware", "version": "1.1.0"},
    "nodes": [
      {"ip": "192.168.1.100", "version": "1.0.0", "labels": {"env": "mock"}},
      {"ip": "192.168.1.101", "version": "1.0.0", "labels": {"env": "mock"}}
    ]
  }' | jq

# 4. Watch WebSocket for progress (in browser console)
const ws = new WebSocket('ws://localhost:3001/ws');
ws.onmessage = e => console.log(JSON.parse(e.data));

Next Steps

• 📖 Read cmd/mock-gateway/README.md for detailed documentation
• 📖 Read MOCK_GATEWAY.md for implementation details
• 🔧 Customize the mock data in internal/mock/data.go
• 🚀 Use it for frontend development, testing, or demos

Troubleshooting

Port already in use?

./mock-gateway -port 8080

Need more/fewer nodes?

./mock-gateway -mock-nodes 3

Want to see what's happening?

./mock-gateway -log-level debug

Build fails?

# Make sure you have Go 1.21 or later
go version

# Update dependencies
go mod download

Questions?

• See MOCK_GATEWAY.md for complete documentation
• See cmd/mock-gateway/README.md for usage details
• Check the real gateway's documentation to understand the API

Happy mocking! 🎭