Routing Strategies

Wayfinder supports multiple routing strategies to select target gateways for your requests.

Strategy	Description	Use Case
`RandomRoutingStrategy`	Selects a random gateway from a list	Good for load balancing and resilience
`StaticRoutingStrategy`	Always uses a single gateway	When you need to use a specific gateway
`RoundRobinRoutingStrategy`	Selects gateways in round-robin order	Good for load balancing and resilience
`FastestPingRoutingStrategy`	Selects the fastest gateway based on ping time	Good for performance and latency
`PingRoutingStrategy`	Wraps another strategy and health-checks its choice, retrying with a different gateway on failure	Filtering out unresponsive gateways. Used by default by `new Wayfinder()`
`PreferredWithFallbackRoutingStrategy`	Uses a preferred gateway, with a fallback strategy if the preferred gateway is not available	Good for performance and resilience. Ideal for builders who run their own gateways.
`SimpleCacheRoutingStrategy`	Caches the gateway chosen by another strategy for a TTL	Avoids re-running selection on every request
`CompositeRoutingStrategy`	Chains multiple routing strategies together, trying each sequentially until one succeeds	Good for complex fallback scenarios and maximum resilience

RandomRoutingStrategy

Selects a random gateway from a list of gateways.

import { RandomRoutingStrategy } from '@ar.io/wayfinder-core';

const strategy = new RandomRoutingStrategy({
  gatewaysProvider: myGatewaysProvider,
});

FastestPingRoutingStrategy

Selects the fastest gateway based on ping time. This strategy pings all available gateways and selects the one with the lowest latency.

import { FastestPingRoutingStrategy } from '@ar.io/wayfinder-core';

const strategy = new FastestPingRoutingStrategy({
  timeoutMs: 1000,
  gatewaysProvider: myGatewaysProvider,
  probePath: '/', // optional, defaults to '/'
});

Wraps another strategy, health-checks the gateway it picked, and retries with a different one if the check fails. This is the default strategy used by new Wayfinder() (wrapping a RandomRoutingStrategy).

import { PingRoutingStrategy, RandomRoutingStrategy } from '@ar.io/wayfinder-core';

const strategy = new PingRoutingStrategy({
  routingStrategy: new RandomRoutingStrategy({ gatewaysProvider: myGatewaysProvider }),
  retries: 5, // optional
  timeoutMs: 1000, // optional
  probePath: '/', // optional
});

What gets probed. Both ping strategies send a HEAD to probePath on the gateway's own host — not to the sandboxed URL of the request being routed. Probing the content URL makes the gateway resolve the data before it can answer, so a short timeout ends up measuring "is this object already cached here" rather than "is this gateway up". Against the live network with a 1s budget, a HEAD of the gateway root succeeded for ~85% of peers versus ~23% for the sandboxed content URL — and the difference is latency rather than breakage, since the sandboxed URL reaches ~78% once given 10s. Set probePath to /ar-io/healthcheck, or to any path you prefer, to override.

PreferredWithFallbackRoutingStrategy

Uses a preferred gateway, with a fallback strategy if the preferred gateway is not available. This is useful for builders who run their own gateways and want to use their own gateway as the preferred gateway, but also want to have a fallback strategy in case their gateway is not available.

This strategy is built using CompositeRoutingStrategy internally. It first attempts to ping the preferred gateway (using PingRoutingStrategy with StaticRoutingStrategy), and if that fails, it falls back to the specified fallback strategy.

import { PreferredWithFallbackRoutingStrategy, FastestPingRoutingStrategy } from '@ar.io/wayfinder-core';

const strategy = new PreferredWithFallbackRoutingStrategy({
  preferredGateway: 'https://my-gateway.com',
  fallbackStrategy: new FastestPingRoutingStrategy({ timeoutMs: 500 }),
});

CompositeRoutingStrategy

The CompositeRoutingStrategy allows you to chain multiple routing strategies together, providing maximum resilience by trying each strategy in sequence until one succeeds. This is ideal for complex fallback scenarios where you want to combine different routing approaches.

How it works:

Tries each strategy in the order they're provided
If a strategy successfully returns a gateway, that gateway is used (remaining strategies are skipped)
If a strategy throws an error, moves to the next strategy
If all strategies fail, throws an error

Common use cases:

Performance + Resilience: Try fastest ping first, fallback to random if ping fails
Preferred + Network: Use your own gateway first, fallback to AR.IO network selection
Multi-tier Fallback: Try premium gateways, then standard gateways, then any available gateway

import { 
  createWayfinderClient,
  CompositeRoutingStrategy, 
  FastestPingRoutingStrategy, 
  RandomRoutingStrategy,
  StaticRoutingStrategy,
  NetworkGatewaysProvider,
} from '@ar.io/wayfinder-core';
import { ARIO } from '@ar.io/sdk';
import { createSolanaRpc } from '@solana/kit';

const ario = ARIO.init({
  rpc: createSolanaRpc('https://api.mainnet-beta.solana.com'),
});

// Example 1: Performance-first with resilience fallback
const performanceWayfinder = createWayfinderClient({
  routingStrategy: new CompositeRoutingStrategy({
    strategies: [
      // Try fastest ping first (high performance, but may fail if all gateways are slow)
      new FastestPingRoutingStrategy({
        timeoutMs: 500,
        gatewaysProvider: new NetworkGatewaysProvider({
          ario,
          sortBy: 'operatorStake',
          limit: 10,
        }),
      }),
      // Fallback to random selection (guaranteed to work if gateways exist)
      new RandomRoutingStrategy({
        gatewaysProvider: new NetworkGatewaysProvider({
          ario,
          sortBy: 'operatorStake', 
          limit: 20, // Use more gateways for fallback
        }),
      }),
    ],
  }),
});

// Example 2: Preferred gateway with multi-tier fallback
const preferredWayfinder = createWayfinderClient({
  routingStrategy: new CompositeRoutingStrategy({
    strategies: [
      // First, try your preferred gateway
      new StaticRoutingStrategy({ 
        gateway: 'https://my-preferred-gateway.com' 
      }),
      // If that fails, try fastest ping from top-tier gateways
      new FastestPingRoutingStrategy({
        timeoutMs: 1000,
        gatewaysProvider: new NetworkGatewaysProvider({
          ario,
          sortBy: 'operatorStake',
          limit: 5, // Only top 5 gateways
        }),
      }),
      // Final fallback: any random gateway from a larger pool
      new RandomRoutingStrategy({
        gatewaysProvider: new NetworkGatewaysProvider({
          ario,
          limit: 50, // Larger pool for maximum availability
        }),
      }),
    ],
  }),
});

How is this guide?

Routing Strategies

RandomRoutingStrategy

FastestPingRoutingStrategy

PingRoutingStrategy

PreferredWithFallbackRoutingStrategy

CompositeRoutingStrategy

On this page