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. On a failed check it asks the wrapped strategy again, excluding the gateways that failed | 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 or has already failed the request | 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 '/'
});PingRoutingStrategy
Wraps another strategy and health-checks the gateway it picked. If the check
fails, it asks the wrapped strategy again and passes every gateway that failed
so far as exclude. RandomRoutingStrategy and RoundRobinRoutingStrategy
then pick a different gateway when one is left, and
FastestPingRoutingStrategy picks a different one when another answers its
ping; a wrapped StaticRoutingStrategy returns its one gateway each time. 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. When Wayfinder retries a request because the preferred gateway returned a 5xx or a network error, the preferred gateway is excluded and the retry goes to the 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, or returns a gateway in the
excludelist (one that already failed this request), moves to the next strategy - If every strategy that did not throw returned an excluded gateway, returns the first of those
- 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?