openhamclock/dxspider-proxy

DX Spider Telnet Proxy

A microservice that maintains a persistent telnet connection to DX Spider cluster nodes and exposes the spots via a simple HTTP REST API.

Why This Exists

Many cloud hosting platforms (including Railway) don't support outbound telnet connections. This proxy service solves that by:

1. Maintaining a persistent telnet connection to DX Spider
2. Accumulating spots in memory (30-minute retention)
3. Exposing spots via HTTP API that any app can consume

Features

• Auto-reconnect - Automatically reconnects on disconnect
• Multi-node failover - Cycles through multiple DX Spider nodes if one fails
• Keepalive - Sends periodic keepalive to maintain connection
• Spot deduplication - Prevents duplicate spots within 2-minute window
• 30-minute retention - Accumulates spots for richer data
• Mode detection - Automatically detects CW, SSB, FT8, etc. from comments
• CORS enabled - Can be called from any frontend

Environment Variables

Variable	Default	Description
PORT	3001	HTTP server port
CALLSIGN	OPENHAMCLOCK	Callsign used for DX Spider login

API Endpoints

GET /health

Health check endpoint.

{
  "status": "ok",
  "connected": true,
  "currentNode": "DX Spider UK",
  "spotsInMemory": 142,
  "totalSpotsReceived": 1847,
  "lastSpotTime": "2025-01-31T12:34:56.789Z",
  "connectionUptime": "3600s",
  "uptime": "7200s"
}

GET /api/spots

Get accumulated spots with full details.

Query parameters:

• limit (default: 50, max: 200) - Number of spots to return
• since (timestamp) - Only return spots after this timestamp

{
  "spots": [
    {
      "spotter": "W3ABC",
      "freq": "14.025",
      "freqKhz": 14025,
      "call": "JA1XYZ",
      "comment": "CW 599",
      "time": "12:34z",
      "mode": "CW",
      "timestamp": 1706704496789,
      "source": "DX Spider"
    }
  ],
  "total": 142,
  "connected": true,
  "source": "DX Spider UK",
  "timestamp": 1706704500000
}

GET /api/dxcluster/spots

Get spots in simplified format (compatible with OpenHamClock).

Query parameters:

• limit (default: 25, max: 100)

[
  {
    "spotter": "W3ABC",
    "freq": "14.025",
    "call": "JA1XYZ",
    "comment": "CW 599",
    "time": "12:34z",
    "mode": "CW",
    "source": "DX Spider Proxy"
  }
]

GET /api/stats

Get statistics about spots.

{
  "connected": true,
  "currentNode": "DX Spider UK",
  "totalSpots": 142,
  "totalReceived": 1847,
  "lastSpotTime": "2025-01-31T12:34:56.789Z",
  "retentionMinutes": 30,
  "bandCounts": {
    "20m": 45,
    "40m": 32,
    "15m": 28,
    "10m": 20
  },
  "modeCounts": {
    "FT8": 67,
    "CW": 35,
    "SSB": 25
  }
}

GET /api/nodes

List available DX Spider nodes.

{
  "nodes": [
    { "index": 0, "name": "DX Spider UK", "host": "dxspider.co.uk", "port": 7300, "active": true },
    { "index": 1, "name": "W6KK", "host": "w6kk.no-ip.org", "port": 7300, "active": false }
  ],
  "currentIndex": 0
}

POST /api/reconnect

Force reconnection to current node.

POST /api/switch-node

Switch to a different node.

{ "index": 1 }

Deployment

Railway

1. Create a new project in Railway
2. Connect your GitHub repo or upload files
3. Set environment variable: CALLSIGN=YOURCALL
4. Deploy!

The service will automatically start and connect to DX Spider.

Docker

docker build -t dxspider-proxy .
docker run -p 3001:3001 -e CALLSIGN=YOURCALL dxspider-proxy

Local Development

npm install
CALLSIGN=YOURCALL npm start

Using with OpenHamClock

Once deployed, update your OpenHamClock configuration to use this proxy as a DX cluster source:

https://your-proxy-url.railway.app/api/dxcluster/spots

DX Spider Nodes

The proxy cycles through these nodes on failure:

1. dxspider.co.uk:7300 (UK)
2. w6kk.no-ip.org:7300 (California)
3. dxc.nc7j.com:7373 (NC7J)
4. dx.k3lr.com:7300 (K3LR)

License

MIT