PreferredWithFallbackRoutingStrategy

Overview

The PreferredWithFallbackRoutingStrategy attempts to use a designated preferred gateway first, and only falls back to an alternative routing strategy if the preferred gateway fails or is unavailable. This strategy is ideal for applications with dedicated infrastructure or specific gateway requirements.

Routing Strategy Comparison

← Swipe to see more →

Strategy	Best For	Use Case	Predictability	Infrastructure Control
Preferred + Fallback	Dedicated infrastructure	CDN with origin fallback, enterprise gateways	High	Maximum
Fastest Ping	Real-time applications	Performance-critical apps, gaming	Medium	Low
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

← Swipe to see more →

Configuration

Basic Usage

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

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

With Default Fallback

// Uses FastestPingRoutingStrategy as default fallback
const strategy = new PreferredWithFallbackRoutingStrategy({
  preferredGateway: 'https://my-primary-gateway.com',
})

Parameters

Parameter	Type	Default	Description
`preferredGateway`	`string`	required	URL of the preferred gateway
`fallbackStrategy`	`RoutingStrategy`	`FastestPingRoutingStrategy()`	Strategy to use when preferred gateway fails
`logger`	`Logger`	`defaultLogger`	Optional logger instance

How It Works

Health Check: Performs a HEAD request to the preferred gateway with a 1000ms timeout
Success: If the preferred gateway responds with a successful status, it's used
Failure: If the preferred gateway fails or times out, the fallback strategy is used
Logging: All attempts and failures are logged for monitoring

Integration with Wayfinder

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

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

Multiple Fallback Levels

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

// Create nested fallback strategies
const tertiaryFallback = new RandomRoutingStrategy()

const secondaryFallback = new PreferredWithFallbackRoutingStrategy({
  preferredGateway: 'https://secondary-gateway.com',
  fallbackStrategy: tertiaryFallback,
})

const primaryStrategy = new PreferredWithFallbackRoutingStrategy({
  preferredGateway: 'https://primary-gateway.com',
  fallbackStrategy: secondaryFallback,
})

Different Fallback Strategies

import {
  PreferredWithFallbackRoutingStrategy,
  RoundRobinRoutingStrategy,
  StaticRoutingStrategy,
  RandomRoutingStrategy,
} from '@ar.io/wayfinder-core'

// With Round Robin fallback (requires predefined gateways)
const roundRobinFallback = new RoundRobinRoutingStrategy({
  gateways: [
    new URL('https://gateway1.com'),
    new URL('https://gateway2.com'),
    new URL('https://gateway3.com'),
  ],
})

const strategy1 = new PreferredWithFallbackRoutingStrategy({
  preferredGateway: 'https://my-gateway.com',
  fallbackStrategy: roundRobinFallback,
})

// With Static fallback (uses first available gateway)
const staticFallback = new StaticRoutingStrategy()

const strategy2 = new PreferredWithFallbackRoutingStrategy({
  preferredGateway: 'https://my-gateway.com',
  fallbackStrategy: staticFallback,
})

// With Random fallback
const randomFallback = new RandomRoutingStrategy()

const strategy3 = new PreferredWithFallbackRoutingStrategy({
  preferredGateway: 'https://my-gateway.com',
  fallbackStrategy: randomFallback,
})

Use Cases

AR.IO Gateway with Fallback

Perfect for applications using a preferred AR.IO gateway that need to fall back to other gateways when unavailable.

const gatewayStrategy = new PreferredWithFallbackRoutingStrategy({
  preferredGateway: 'https://myapp.ar-io.dev', // Your preferred AR.IO gateway
  fallbackStrategy: new FastestPingRoutingStrategy({ timeoutMs: 500 }), // Other AR.IO gateways
})

Enterprise Gateway with Public Fallback

Ideal for enterprise applications with dedicated gateways that need public gateway fallback.

const enterpriseStrategy = new PreferredWithFallbackRoutingStrategy({
  preferredGateway: 'https://enterprise-gateway.company.com',
  fallbackStrategy: new PreferredWithFallbackRoutingStrategy({
    preferredGateway: 'https://arweave.net',
    fallbackStrategy: new FastestPingRoutingStrategy({ timeoutMs: 500 }),
  }),
})

High Availability Setup

For mission-critical applications requiring multiple levels of redundancy.

const haStrategy = new PreferredWithFallbackRoutingStrategy({
  preferredGateway: 'https://primary-production-gateway.com',
  fallbackStrategy: new PreferredWithFallbackRoutingStrategy({
    preferredGateway: 'https://secondary-production-gateway.com',
    fallbackStrategy: new RoundRobinRoutingStrategy({
      gateways: [
        new URL('https://backup1.com'),
        new URL('https://backup2.com'),
        new URL('https://backup3.com'),
      ],
    }),
  }),
})

Best Practices

Choose Appropriate Fallback Strategies: Use strategies that complement your preferred gateway
Monitor Gateway Performance: Track preferred gateway uptime and performance through logs
Set Reasonable Timeouts in Fallback: Configure fallback strategies with appropriate timeouts
Use Nested Fallbacks: Create multiple levels of fallback for high availability
Handle Subdomain Routing: The strategy supports subdomain-based routing automatically

The PreferredWithFallbackRoutingStrategy is ideal for applications with dedicated infrastructure that need predictable routing behavior with reliable fallback options.