# Load Balancing Algorithms in INFINI Gateway: Configuration and Implementation Guide

> Discover INFINI Gateway's weighted round-robin load balancing for reads and writes. Learn how to configure this algorithm using Elasticsearch filter settings for optimal performance.

- Repository: [INFINI Labs/gateway](https://github.com/infinilabs/gateway)
- Tags: how-to-guide
- Published: 2026-03-04

---

**INFINI Gateway currently implements a single weighted round-robin load balancing algorithm for both read and write operations, configured through the `balancer` and `weights` fields in the Elasticsearch filter configuration.**

INFINI Gateway is a high-performance data gateway designed for Elasticsearch and other search engines. Understanding the available **load balancing algorithms in INFINI Gateway** is essential for optimizing traffic distribution across your cluster nodes. This guide examines the specific implementation details, configuration options, and source code structure that control how requests are routed to upstream Elasticsearch instances.

## Supported Load Balancing Algorithms

### Weighted Round-Robin Implementation

According to the source code in the `infinilabs/gateway` repository, INFINI Gateway provides exactly one load balancing algorithm: **weighted round-robin**. This algorithm distributes incoming requests across upstream nodes in a circular fashion, with each node receiving traffic proportional to its assigned weight.

The implementation resides in [`proxy/balancer/balancer.go`](https://github.com/infinilabs/gateway/blob/main/proxy/balancer/balancer.go), where the `NewBalancer` function constructs a balancer instance based on a slice of integer weights. The algorithm implements the `IBalancer` interface, exposing a `Distribute` method that selects the next appropriate upstream node based on the current state and weight distribution.

## How Load Balancing Works in INFINI Gateway

The load balancing mechanism applies uniformly to **both read and write operations**. Whether processing search queries or indexing requests, INFINI Gateway uses the same weighted round-robin selection process to determine which Elasticsearch node handles the request.

The configuration structure defined in [`proxy/output/elastic/config.go`](https://github.com/infinilabs/gateway/blob/main/proxy/output/elastic/config.go) includes a `Balancer` field of type string, which specifies the algorithm name, and a `Weights` map that associates endpoint URLs with integer values. When the Elasticsearch filter initializes, the default value `"weight"` is assigned in [`proxy/output/elastic/elasticsearch.go`](https://github.com/infinilabs/gateway/blob/main/proxy/output/elastic/elasticsearch.go), ensuring the weighted round-robin algorithm is active by default.

## Configuring Load Balancing

### Basic Configuration

To configure load balancing in INFINI Gateway, you modify the filter configuration within your flow definition. The `balancer` key accepts the algorithm type (currently only `"weight"` is supported), while the `weights` map defines traffic distribution ratios.

```yaml
flow:
  - name: default_flow
    filter:
      - elasticsearch:
          elasticsearch: prod
          balancer: weight          # ← balancer type (only "weight" is supported)

          weights:
            http://es-node-1:9200: 3    # ← node receives 3× the traffic of weight‑1 nodes

            http://es-node-2:9200: 1
            http://es-node-3:9200: 1

```

In this configuration, `es-node-1` receives three times the traffic of the other nodes.

### Weight Assignment Logic

The actual construction of the weight array occurs in [`proxy/output/elastic/reverseproxy.go`](https://github.com/infinilabs/gateway/blob/main/proxy/output/elastic/reverseproxy.go). The code iterates through the configured hosts, retrieves the corresponding weight from the configuration map, and defaults to `1` if the weight is omitted or set to a value less than or equal to zero.

```go
// From proxy/output/elastic/reverseproxy.go
ws := []int{}
for _, endpoint := range hosts {
    w, ok := cfg.Weights[endpoint]
    if !ok || w <= 0 {
        w = 1 // default weight
    }
    ws = append(ws, w)
}
p.bla = balancer.NewBalancer(ws) // creates the weighted round-robin balancer

```

## Implementation Details

The load balancing system centers on the `IBalancer` interface defined in the balancer package. The weighted round-robin implementation maintains internal state to track the current position in the rotation and ensures distribution according to the specified weights.

Key source files include:

- [`proxy/balancer/balancer.go`](https://github.com/infinilabs/gateway/blob/main/proxy/balancer/balancer.go): Contains the `NewBalancer` constructor and `Distribute` method implementation
- [`proxy/output/elastic/config.go`](https://github.com/infinilabs/gateway/blob/main/proxy/output/elastic/config.go): Defines the `ProxyConfig` struct with `Balancer` and `Weights` fields
- [`proxy/output/elastic/elasticsearch.go`](https://github.com/infinilabs/gateway/blob/main/proxy/output/elastic/elasticsearch.go): Sets the default balancer type to `"weight"`
- [`proxy/output/elastic/reverseproxy.go`](https://github.com/infinilabs/gateway/blob/main/proxy/output/elastic/reverseproxy.go): Handles runtime construction of the balancer from configuration

## Summary

- INFINI Gateway supports **one load balancing algorithm**: weighted round-robin, implemented in [`proxy/balancer/balancer.go`](https://github.com/infinilabs/gateway/blob/main/proxy/balancer/balancer.go)
- The algorithm applies to **both read and write operations** uniformly
- Configuration occurs through the `balancer` (type: `"weight"`) and `weights` (endpoint-to-integer map) fields in the Elasticsearch filter
- Default weight is `1` for any node where weight is omitted or set to `≤ 0`
- The balancer is constructed at runtime in [`proxy/output/elastic/reverseproxy.go`](https://github.com/infinilabs/gateway/blob/main/proxy/output/elastic/reverseproxy.go) using the `NewBalancer` function

## Frequently Asked Questions

### What load balancing algorithms does INFINI Gateway support?

INFINI Gateway currently supports only the **weighted round-robin** algorithm. According to the source code in [`proxy/balancer/balancer.go`](https://github.com/infinilabs/gateway/blob/main/proxy/balancer/balancer.go), no other algorithms such as random, least-connections, or consistent-hashing are implemented. The `IBalancer` interface is designed to allow future extensions, but only the weighted round-robin implementation exists in the current codebase.

### How do I configure different weights for Elasticsearch nodes?

Configure the `weights` map in your Elasticsearch filter configuration. Each key represents the endpoint URL (e.g., `http://es-node-1:9200`), and the value is an integer weight. Nodes with higher integers receive proportionally more traffic. If you omit a node from the weights map or set its value to `0` or negative, INFINI Gateway automatically assigns it a default weight of `1` as implemented in [`proxy/output/elastic/reverseproxy.go`](https://github.com/infinilabs/gateway/blob/main/proxy/output/elastic/reverseproxy.go).

### Does INFINI Gateway use the same algorithm for reads and writes?

Yes, INFINI Gateway uses the **same weighted round-robin algorithm** for both read and write operations. The balancer selection occurs at the filter level in [`proxy/output/elastic/elasticsearch.go`](https://github.com/infinilabs/gateway/blob/main/proxy/output/elastic/elasticsearch.go), where the `Balancer` field defaults to `"weight"`. There is no separate configuration path for read versus write traffic; all requests passing through the Elasticsearch filter use the same upstream selection logic defined in [`proxy/balancer/balancer.go`](https://github.com/infinilabs/gateway/blob/main/proxy/balancer/balancer.go).

### What happens if I don't specify weights in the configuration?

If you omit the `weights` configuration entirely, or if specific nodes are missing from the weights map, INFINI Gateway treats every upstream node equally. According to the logic in [`proxy/output/elastic/reverseproxy.go`](https://github.com/infinilabs/gateway/blob/main/proxy/output/elastic/reverseproxy.go), when a weight is not found or is less than or equal to zero, the system assigns a default value of `1`. This results in a standard round-robin distribution where each node receives an equal share of traffic regardless of capacity or performance characteristics.