RoundRobinRoutingStrategy

Overview

The RoundRobinRoutingStrategy distributes requests evenly across all available gateways in a cyclical manner. Each gateway is selected in turn, ensuring fair load distribution and preventing any single gateway from being overwhelmed.

Routing Strategy Comparison

← Swipe to see more →

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

← Swipe to see more →

How It Works

Initialize Gateway List: Start with an ordered list of available gateways
Track Current Position: Maintain a pointer to the current gateway in the rotation
Select Next Gateway: Choose the next gateway in the sequence
Cycle Through List: Return to the first gateway after reaching the end
Handle Failures: Skip failed gateways and continue rotation

Configuration

Basic Usage

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

const strategy = new RoundRobinRoutingStrategy({
  gateways: [new URL('https://arweave.net'), new URL('https://permagate.io')],
})

With Weighted Rotation

const strategy = new RoundRobinRoutingStrategy({
  gateways: [
    new URL('https://high-capacity-gateway.com'),
    new URL('https://medium-capacity-gateway.com'),
    new URL('https://low-capacity-gateway.com'),
  ],
  weightedRotation: true,
  weights: new Map([
    ['https://high-capacity-gateway.com', 3],
    ['https://medium-capacity-gateway.com', 2],
    ['https://low-capacity-gateway.com', 1],
  ]),
})

Parameters

Parameter	Type	Default	Description
`gateways`	`URL[]`	required	Array of gateway URLs to rotate through
`weightedRotation`	`boolean`	`false`	Use weighted rotation
`weights`	`Map<string, number>`	`new Map()`	Gateway weights for weighted rotation
`shuffleOnStart`	`boolean`	`false`	Randomize initial gateway order
`logger`	`Logger`	`defaultLogger`	Optional logger instance

Integration with Wayfinder

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

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

Use Cases

Even Load Distribution

Perfect for distributing load evenly across multiple known gateways.

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

Capacity-Based Distribution

Ideal for gateways with different capacities using weighted rotation.

const capacityStrategy = new RoundRobinRoutingStrategy({
  gateways: [
    new URL('https://high-capacity.com'),
    new URL('https://medium-capacity.com'),
    new URL('https://low-capacity.com'),
  ],
  weightedRotation: true,
  weights: new Map([
    ['https://high-capacity.com', 5],
    ['https://medium-capacity.com', 3],
    ['https://low-capacity.com', 1],
  ]),
})

Predictable Testing

Useful for testing scenarios where you need predictable gateway selection.

const testStrategy = new RoundRobinRoutingStrategy({
  gateways: [
    new URL('https://test-gateway-1.com'),
    new URL('https://test-gateway-2.com'),
  ],
  shuffleOnStart: false, // Maintain order for predictable testing
})

Best Practices

Define Gateway Order: Carefully consider the order of gateways in your list
Use Weighted Rotation: Apply weights when gateways have different capacities
Monitor Distribution: Track requests to ensure even distribution
Consider Shuffling: Use shuffleOnStart to avoid predictable patterns
Plan for Failures: Combine with health checking for production use

The RoundRobinRoutingStrategy is ideal for applications that need predictable, even distribution of requests across a known set of gateways.