Routing Strategies

Routing strategies determine how Wayfinder selects which AR.IO gateway to use for each request. Different strategies optimize for different goals like performance, reliability, or load distribution.

Strategy Comparison

← Swipe to see more →

Strategy	Best For	Use Case	Predictability	Infrastructure Control
Fastest Ping	Real-time applications	Performance-critical apps, gaming	Medium	Low
Preferred + Fallback	Dedicated infrastructure	CDN with origin fallback, enterprise gateways	High	Maximum
Round Robin	Load balancing	Even distribution across known gateways	High	High
Random	Simple distribution	Basic load spreading, testing	Low	Medium
Static	Single gateway	Development, specific gateway requirements	Maximum	High
Simple Cache	Performance optimization	Wrapping expensive strategies like FastestPing	Medium	Medium

← Swipe to see more →

Available Strategies

FastestPingRoutingStrategy

Selects the gateway with the lowest latency based on HEAD request ping times. Performs health checks on all available gateways and chooses the fastest responding one.

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

const strategy = new FastestPingRoutingStrategy({
  timeoutMs: 500,
  pingPath: '/ar-io/info',
  cacheResultsMs: 30000,
})

Best for: Real-time applications, interactive user experiences, gaming Trade-offs: Higher initial latency due to ping tests, network overhead

PreferredWithFallbackRoutingStrategy

Tries a preferred gateway first, falls back to another strategy if it fails. Ideal for applications with dedicated infrastructure that need reliable fallback options.

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

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

Best for: Applications with dedicated gateway infrastructure, CDN setups, enterprise environments Trade-offs: Potential single point of failure if preferred gateway is down

RoundRobinRoutingStrategy

Distributes requests evenly across all available gateways in a cyclical manner. Ensures fair load distribution and prevents gateway overload.

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

const strategy = new RoundRobinRoutingStrategy({
  gateways: [
    new URL('https://gateway-1.com'),
    new URL('https://gateway-2.com'),
    new URL('https://gateway-3.com'),
  ],
})

Best for: Load balancing, even gateway utilization, high-traffic applications Trade-offs: May route to slow gateways, doesn't optimize for performance

RandomRoutingStrategy

Randomly selects a gateway from the available options. Provides simple load distribution without maintaining state or complex calculations.

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

const strategy = new RandomRoutingStrategy({
  weightedSelection: true,
  weights: new Map([
    ['https://high-capacity.com', 3],
    ['https://standard-capacity.com', 1],
  ]),
})

Best for: Simple load distribution, avoiding patterns, testing environments Trade-offs: No optimization for performance or reliability, unpredictable behavior

StaticRoutingStrategy

Always returns the same configured gateway, ignoring provided gateway lists. Useful for development, testing, or when you need to force all requests through a specific gateway.

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

const strategy = new StaticRoutingStrategy({
  gateway: 'https://arweave.net',
})

Best for: Development, testing, compliance requirements, dedicated gateway setups Trade-offs: Single point of failure, no load distribution or optimization

SimpleCacheRoutingStrategy

Wraps another routing strategy and caches its results for improved performance. Reduces overhead from expensive operations like network pings.

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

const strategy = new SimpleCacheRoutingStrategy({
  strategy: new FastestPingRoutingStrategy({ timeoutMs: 500 }),
  cacheTimeMs: 30000,
})

Best for: Wrapping expensive strategies, high-traffic applications, performance optimization Trade-offs: May serve stale gateway selections, adds complexity

Custom Strategies

You can implement custom routing strategies by implementing the RoutingStrategy interface:

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

class WeightedRandomStrategy implements RoutingStrategy {
  constructor(private weights: Map<string, number>) {}

  async selectGateway({ gateways }) {
    // Implement weighted random selection logic
    const totalWeight = Array.from(this.weights.values()).reduce(
      (a, b) => a + b,
      0,
    )
    let random = Math.random() * totalWeight

    for (const gateway of gateways) {
      const weight = this.weights.get(gateway.toString()) || 1
      random -= weight
      if (random <= 0) {
        return gateway
      }
    }

    return gateways[0] // Fallback
  }
}

Configuration Examples

Development Configuration

// Prioritize fast iteration and debugging
const wayfinder = new Wayfinder({
  routingSettings: {
    strategy: new StaticRoutingStrategy({
      gateway: 'http://localhost:1984',
    }),
  },
})

Production Configuration

// Prioritize reliability and performance
const wayfinder = new Wayfinder({
  routingSettings: {
    strategy: new PreferredWithFallbackRoutingStrategy({
      preferredGateway: 'https://your-primary-gateway.com',
      fallbackStrategy: new FastestPingRoutingStrategy({ timeoutMs: 500 }),
    }),
  },
})