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.

Login and subscribe

The following is the internal WebSocket handshake currently used by the bundled frontend. It is not a login prerequisite for the external API; login-free WebSocket credential transport still requires backend implementation.

{
  "type": "login",
  "key": "<current internal WebSocket session credential>"
}

Then 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 Clear the expired session and log in again.
423 The current UI requires TOTP; behavior for the login-free external API is still to be defined.
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/_/captcha A sliding-captcha constant exists, but the new frontend has no call site.
/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. Verify Rust backend routes before publishing them.

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 general API credential, Observer token, and fleet API separately.