RustMinerSystem

Documentation

WebSocket, Error Handling, and Compatibility

RustMinerSystem real-time Stratum WebSocket frames, subscriptions, error states, compatibility, and unused endpoint definitions.

WebSocket, Error Handling, and Compatibility

WebSocket URL

Real-time worker Stratum data uses:

ws://host:port/{safe-route}/api/ws
wss://host:port/{safe-route}/api/ws

HTTPS pages must use wss://. Safe-route construction matches the HTTP API.

Subscribe and heartbeat

Subscribe to a worker group:

{
  "type": "subscribe",
  "group_id": "<worker gid>"
}

The frontend sends a heartbeat every 10 seconds:

{
  "type": "ping"
}

The server can return the string pong, { "type": "pong" }, or pong inside body.

Unsubscribe and close:

{
  "type": "unsubscribe",
  "group_id": "<worker gid>"
}

{
  "type": "close"
}

Messages can be strings, JSON objects, or { type, body } envelopes. A worker identifier may be named workerID, workerId, worker_id, sid, or id.

HTTP error handling

Condition Recommended behavior
No HTTP response Treat as network failure, restart, or CORS failure; retry with bounded backoff.
401 / 403 Verify X-ACCESS-TOKEN and generate a fresh token from the current Key.
404 Check whether the running backend supports the endpoint.
5xx Log a request ID, path, and redacted error; never retry forever.
HTTP 200 with business failure Inspect PoolNode status, error, and operation-specific values.

Web-port, safe-route, TLS, and certificate changes can restart services and drop the current request. Confirm state through the new URL before deciding the change failed.

Defined but not called by the current frontend

Path Status
/api/port/{id}/workers Legacy worker list; current code uses /api/port/{id}/g/workers.
/api/sysinfo Legacy system information; current code uses /api/sys/base/info.
/api/pump/t Defined getter for pump timing, currently unused.
/api/pump/t/{pump_t} Defined setter for pump timing, currently unused.
/api/poolnode/rewards p_get_fee_log is an unused alias; the same path is used by the reward-list call.

Do not infer HTTP method, permission, or response contracts for unused paths solely from frontend constants. This edition does not treat them as stable until a target instance confirms their actual response.

Compatibility guidance

  • Call /api/local/version at startup and enable optional features by version.
  • Parse new response fields permissively and never depend on object field order.
  • GET, POST, and DELETE on the same path are distinct operations.
  • Read currency, protocol, and status enums from /api/currency/config or current responses.
  • Manage the API Key, Access Token, Observer token, and fleet API separately.

Compatible response parsing

  1. Check HTTP status and Content-Type, while accepting scalar JSON and plain text.
  2. If an object contains both status and data, parse it as a PoolNode envelope and read error when status !== 0.
  3. For ordinary errors, prefer message, then error, then a redacted raw body.
  4. Accept [] as a successful empty list.
  5. Preserve null chart values and trust returned page, size, pages, and total.
  6. If a port, TLS, certificate, or route switch drops the request, verify with a read-only call at the new address before retrying the write.

Diagnostic logs may keep method, path template, HTTP status, and business status, but must remove API, Observer, and fleet tokens, wallets, certificate keys, and complete revenue data.