Skip to content

Priority Routing

Saturn uses a priority-based system to select the best available service when multiple backends are on the network.

How priority works

Each service registers with a numeric priority. Lower numbers = higher priority (priority 1 beats priority 10, which beats priority 50).

When a client needs a service:

  1. Discovers all available services via mDNS
  2. Filters by health status
  3. Sorts by priority (ascending)
  4. Routes to the lowest-priority-number healthy service

GPU Server priority: 1 Cloud Primary priority: 10 Cloud Fallback priority: 50 Client active failover 1 failover 2

The client always routes to the GPU Server (priority 1). If it goes down, traffic shifts to Cloud Primary (priority 10). If that also fails, Cloud Fallback (priority 50) handles requests.

Health monitoring

Saturn polls /v1/health on each service every 20 seconds. A service is marked unhealthy after a failed health check and excluded from routing until it passes again.

The health check cycle:

  1. Send GET to /v1/health on the service
  2. Expect a 200 response within the timeout
  3. Mark healthy or unhealthy accordingly
  4. Repeat every 20 seconds

Automatic failover

When the primary (lowest priority number) service goes down:

  1. Health check detects the failure within 20 seconds
  2. Next-lowest-priority healthy service becomes active
  3. Traffic routes to the new active service immediately
  4. When the primary recovers and passes a health check, routing switches back automatically

No manual intervention required. Recovery is automatic.

Auto recovery

When a failed service comes back online, Saturn detects it on the next health poll. The service re-enters the pool at its configured priority. If its priority is lower (more preferred) than the current active service, it takes over immediately.

Priority conflict resolution

When a new server starts, it checks existing priorities on the network via mDNS discovery. If another service already has the same priority, the new service auto-increments to the next available value.

For example: if you start a service with priority = 10 and another service already has priority 10, your service registers as priority 11.

Range Use
1--9 Local GPU servers, fastest/cheapest resources
10--29 Primary cloud services
30--49 Secondary cloud services
50--89 Backup services
90--99 Fallback and error handlers