One WebSocket in front of the whole SHiP fleet.

1. Connect

   The client opens one WebSocket to the router. The router selects an upstream and forwards that upstream's ABI, so the client talks to a single SHiP endpoint.

2. Route

   Selection prefers an upstream whose trace range covers the requested block, then the lowest priority tier, then the fewest connections per unit of weight. A get_blocks_request_v1 with fetch_finality_data only goes to a node whose finality range covers that block.

3. Fail over

   When the active upstream closes, errors or goes silent, the client socket stays open. A quiet upstream is pinged and abandoned if nothing comes back within 4 s. The router re-sends the in-flight get_blocks from the next block on another suitable node and replays the client frames buffered during the swap.

4. De-duplicate

   Blocks the client already received are dropped on replay. The client never reconnects and never sees the same block twice.

Single resilient endpointws://router:17000

Hyperion, Atomic and other indexers share one WebSocket instead of each consumer pinning itself to one SHiP node.

Range-aware least-connectionstrace_begin_block … trace_end_block

Prefers an upstream whose trace range covers the requested block, then the least-loaded healthy node. Finality-data requests go only to a node whose finality range covers that block.

Upstream preferencepriority · weight

Among nodes that can serve a request equally well, the router uses the lowest priority tier, then the fewest connections per unit of weight. A high priority makes a node a last resort, and failover still moves off a failed preferred node to a backup that covers the block.

Transparent failoverresume at next block

On upstream loss the router reconnects to another suitable node, resumes get_blocks at the next block, de-duplicates replayed blocks and replays buffered client frames. That includes a node that goes silent without closing the connection, such as a pulled cable or a frozen VM: a quiet upstream is pinged and abandoned after upstream_liveness_timeout_ms (4 s by default).

Stale-upstream deprioritizationupstream_stale = 1

An upstream that stops advancing its chain state is flagged stale and deprioritized when routing. It is not hard-excluded.

Many networks, one processlisteners[] · /ready/<name>

listeners serves each chain on its own port with its own upstream pool, chain_id, connection cap and /ready/<name> check.

chain_id verificationrequire_chain_id

An upstream whose reported chain_id disagrees with the pin or the rest of its pool stays offline. Nodes that omit chain_id, such as FIO and other EOSIO 2.0 builds, stay usable unless require_chain_id is set.

Bounded failover and quarantineblock_failure_quarantine

Repeated unclean drops at the same next block are bounded: the session closes with code 1011 after five. Opt-in block_failure_quarantine skips a corrupted SHiP log range without marking the node offline.

Live dashboard/ui/ · /status · /api/v1

Opt-in fleet view with block ranges, sessions, throughput, failovers and an event log, plus a no-JavaScript status page and a JSON API with a server-sent events stream. Off by default.

Operator controlsdrain · disable · move

With a control token set, drain an upstream for maintenance, disable or enable it, change its priority and weight at runtime, clear its quarantines, or move a single session. A drain uses the normal failover, so clients stay connected.

Prometheus metrics/metrics · server, endpoint, listener

Per-upstream series carry server and endpoint labels, plus listener in multi-listener mode, with gauges for the start and end of each SHiP range.

Upstream wss://wss://host:port

Optional TLS to SHiP nodes, verified with rustls against the OS trust store. A bare host:port stays ws://. The client listener remains plaintext.

Resource safetymax_connections · idle_timeout_ms

Connection cap, handshake and idle timeouts, and a bounded maximum WebSocket message size.

Runs as a servicesystemd · Docker · launchd

Ships systemd units for one process or one process per network, with a raised open-file limit and basic sandboxing. The operations guide also covers the Docker restart policy, launchd on macOS and a service wrapper on Windows.

Graceful shutdownSIGINT · SIGTERM

Handles SIGINT and SIGTERM with a bounded drain and WebSocket close frames to connected clients. Written in Rust on tokio and tokio-tungstenite; ABI checks use pure-Rust rs_abieos, so libclang is not required.

Quick start

1. Write a sample config
   $ fleet-router config init ./config.json CopyCopiedFailed
2. Validate it and test upstream connectivity
   $ fleet-router config test ./config.json CopyCopiedFailed
3. Run the proxy
   $ fleet-router run --config ./config.json CopyCopiedFailed

To keep it running across reboots, install the systemd unit from deploy/. See Run as a service for systemd, Docker, launchd and Windows.

fleet_router_up
fleet_router_upstream_up{endpoint,server}
fleet_router_upstream_stale{endpoint,server}
fleet_router_active_connections{endpoint,server}
fleet_router_upstream_trace_begin_block{endpoint,server}
fleet_router_upstream_chain_state_begin_block{endpoint,server}
fleet_router_upstream_chain_state_end_block{endpoint,server}
fleet_router_upstream_finality_data_begin_block{endpoint,server}
fleet_router_upstream_finality_data_end_block{endpoint,server}
fleet_router_upstream_block_failures_total{endpoint,server}
fleet_router_upstream_quarantined{endpoint,server}
fleet_router_upstream_quarantine_block{endpoint,server}
fleet_router_upstream_operator_disabled{endpoint,server}
fleet_router_upstream_priority{endpoint,server}
fleet_router_upstream_weight{endpoint,server}

Logging is tracing, controlled with RUST_LOG (default info).

"metrics_address": "127.0.0.1",
"metrics_port": 9090,
"dashboard": {
  "enabled": true,
  "control_token_file": "/etc/fleet-router/control.token"
}

The full contract is in the API reference.