feat: adds random balancer

Signed-off-by: Dennis Zhuang <killme2008@gmail.com>

Author: killme2008

CHANGELOG.md

@@ -10,10 +10,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Multi-endpoint support via `GreptimeClientOptions.Endpoints` (`IList<string>`).
-  Supplying more than one endpoint enables client-side round-robin load
-  balancing with automatic failover across endpoints. Single-element lists
-  behave as the previous single-node case. Backed by
-  `Grpc.Net.Client.Balancer`.
+  Supplying more than one endpoint enables client-side load balancing with
+  automatic failover across endpoints. Single-element lists behave as the
+  previous single-node case. Backed by `Grpc.Net.Client.Balancer`.
+- `GreptimeClientOptions.LoadBalancing` (`LoadBalancingStrategy`) selects the
+  multi-endpoint balancing policy. Supported: `Random` (default — picks a
+  ready endpoint uniformly at random per call, avoiding the herding pattern
+  that round-robin can produce when many short-lived clients start at the
+  same time) and `RoundRobin`.
 
 ### Changed
 
@@ -22,6 +26,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   end-of-support, and `Grpc.Net.Client.Balancer` (required for the new
   multi-endpoint client-side load balancer) is only shipped in the package's
   `net8.0+` build, not its `netstandard2.1` build.
+  Users on `net6.0` / `net7.0` should pin to the `0.1.x` line, which keeps
+  those TFMs supported.
 
 ### Deprecated
 

README.md

@@ -5,7 +5,7 @@
 [![NuGet Downloads](https://img.shields.io/nuget/dt/GreptimeDB.Ingester.svg)](https://www.nuget.org/packages/GreptimeDB.Ingester)
 [![NuGet Grpc](https://img.shields.io/nuget/v/GreptimeDB.Ingester.Grpc.svg)](https://www.nuget.org/packages/GreptimeDB.Ingester.Grpc)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
-![.NET](https://img.shields.io/badge/.NET-6.0%20%7C%207.0%20%7C%208.0%20%7C%209.0%20%7C%2010.0-purple)
+![.NET](https://img.shields.io/badge/.NET-8.0%20%7C%209.0%20%7C%2010.0-purple)
 
 .NET SDK for writing data to [GreptimeDB](https://github.com/GreptimeTeam/greptimedb).
 
@@ -19,6 +19,13 @@
 dotnet add package GreptimeDB.Ingester
 ```
 
+> **.NET 6.0 / 7.0 users:** the latest version requires .NET 8.0 or newer.
+> Stay on the `0.1.x` line for net6.0 / net7.0 support:
+>
+> ```bash
+> dotnet add package GreptimeDB.Ingester --version 0.1.*
+> ```
+
 ## Quick Start
 
 ```csharp
@@ -76,11 +83,53 @@ var client = new GreptimeClient(new GreptimeClientOptions
 });
 ```
 
+## Multiple Endpoints
+
+Pass more than one endpoint to enable client-side load balancing and failover
+across a GreptimeDB cluster:
+
+```csharp
+var client = new GreptimeClient(new GreptimeClientOptions
+{
+    Endpoints = new List<string>
+    {
+        "http://node-a:4001",
+        "http://node-b:4001",
+        "http://node-c:4001",
+    },
+    Database = "public",
+});
+```
+
+A single-element list takes the direct-channel fast path (no balancer); two
+or more endpoints route through `Grpc.Net.Client.Balancer` with the configured
+strategy. All endpoints must share the same scheme (all `http` or all `https`)
+and must be plain `host:port` URIs without a path/query/fragment.
+
+### Load-balancing strategy
+
+`LoadBalancing` selects the policy used in the multi-endpoint case:
+
+```csharp
+new GreptimeClientOptions
+{
+    Endpoints = new List<string> { "http://node-a:4001", "http://node-b:4001" },
+    LoadBalancing = LoadBalancingStrategy.Random,     // default
+    // LoadBalancing = LoadBalancingStrategy.RoundRobin,
+};
+```
+
+- `Random` (default) — pick a ready endpoint uniformly at random per call.
+  Avoids the herding pattern that round-robin can produce when many
+  short-lived clients start simultaneously.
+- `RoundRobin` — cycle through ready endpoints in order.
+
 ## Features
 
 - **Unary Write** - Simple single-request writes via gRPC
 - **Streaming Write** - High-throughput streaming via gRPC for multiple tables
 - **Bulk Write** - Maximum throughput via Apache Arrow Flight
+- Multi-endpoint client-side load balancing (random / round-robin) with failover
 - Type coercion between .NET and GreptimeDB types
 - Health check
 - DI integration

src/GreptimeDB.Ingester/Client/GreptimeClient.cs

@@ -40,7 +40,7 @@ public GreptimeClient(GreptimeClientOptions options, ILoggerFactory? loggerFacto
         _logger = _loggerFactory.CreateLogger<GreptimeClient>();
 
         var endpoints = options.ResolveEndpoints();
-        (_channel, _channelServices) = BuildChannel(endpoints);
+        (_channel, _channelServices) = BuildChannel(endpoints, options.LoadBalancing);
         _client = new GreptimeDatabase.GreptimeDatabaseClient(_channel);
         _healthClient = new HealthCheck.HealthCheckClient(_channel);
         _flightClient = new Lazy<FlightClient>(() => new FlightClient(_channel));
@@ -358,7 +358,9 @@ private CallOptions CreateCallOptions(CancellationToken cancellationToken)
             cancellationToken: cancellationToken);
     }
 
-    private static (GrpcChannel Channel, ServiceProvider? Services) BuildChannel(IReadOnlyList<string> endpoints)
+    private static (GrpcChannel Channel, ServiceProvider? Services) BuildChannel(
+        IReadOnlyList<string> endpoints,
+        LoadBalancingStrategy strategy)
     {
         // Single endpoint: skip the balancer entirely. This preserves the original
         // direct-channel behavior, including default TLS authority/SNI handling for
@@ -380,14 +382,25 @@ private static (GrpcChannel Channel, ServiceProvider? Services) BuildChannel(IRe
 
         var services = new ServiceCollection();
         services.AddSingleton<ResolverFactory>(new StaticResolverFactory(addresses));
+        if (strategy == LoadBalancingStrategy.Random)
+        {
+            services.AddSingleton<LoadBalancerFactory>(RandomBalancerFactory.Instance);
+        }
         var serviceProvider = services.BuildServiceProvider();
 
+        LoadBalancingConfig lbConfig = strategy switch
+        {
+            LoadBalancingStrategy.Random => new RandomConfig(),
+            LoadBalancingStrategy.RoundRobin => new RoundRobinConfig(),
+            _ => throw new ArgumentOutOfRangeException(nameof(strategy), strategy, "Unsupported load-balancing strategy."),
+        };
+
         var channelOptions = new GrpcChannelOptions
         {
             ServiceProvider = serviceProvider,
             ServiceConfig = new ServiceConfig
             {
-                LoadBalancingConfigs = { new RoundRobinConfig() }
+                LoadBalancingConfigs = { lbConfig }
             },
             Credentials = scheme == Uri.UriSchemeHttps
                 ? ChannelCredentials.SecureSsl

src/GreptimeDB.Ingester/Client/GreptimeClientOptions.cs

@@ -43,6 +43,14 @@ public sealed class GreptimeClientOptions
     /// </summary>
     public TimeSpan WriteTimeout { get; set; } = TimeSpan.FromSeconds(30);
 
+    /// <summary>
+    /// Gets or sets the load-balancing strategy used when multiple
+    /// <see cref="Endpoints"/> are configured. Ignored for the single-endpoint
+    /// case, which always uses a direct channel. Defaults to
+    /// <see cref="LoadBalancingStrategy.Random"/>.
+    /// </summary>
+    public LoadBalancingStrategy LoadBalancing { get; set; } = LoadBalancingStrategy.Random;
+
     /// <summary>
     /// Returns the effective endpoint list: trimmed, non-whitespace entries of
     /// <see cref="Endpoints"/> when the caller populated that list. Falls back
@@ -77,11 +85,15 @@ public void Validate()
         var endpoints = ResolveEndpoints();
         if (endpoints.Count == 0)
         {
-            var allWhitespace = Endpoints != null && Endpoints.Count > 0;
+            if (Endpoints != null && Endpoints.Count > 0)
+            {
+                throw new ArgumentException(
+                    "Endpoints was set but contained no non-whitespace entries.",
+                    nameof(Endpoints));
+            }
+
             throw new ArgumentException(
-                allWhitespace
-                    ? "Endpoints was set but contained no non-whitespace entries."
-                    : "At least one endpoint is required (set Endpoints).",
+                "At least one endpoint is required. Set Endpoints; the deprecated Endpoint property is empty or whitespace.",
                 nameof(Endpoints));
         }
 
@@ -102,6 +114,15 @@ public void Validate()
                     nameof(Endpoints));
             }
 
+            // Reject path/query/fragment: the multi-endpoint balancer uses host:port only
+            // (BalancerAddress), so a path would silently diverge from the single-endpoint case.
+            if (uri.AbsolutePath is not ("" or "/") || !string.IsNullOrEmpty(uri.Query) || !string.IsNullOrEmpty(uri.Fragment))
+            {
+                throw new ArgumentException(
+                    $"Endpoint '{endpoint}' must be a host:port URI without a path, query, or fragment.",
+                    nameof(Endpoints));
+            }
+
             firstScheme ??= uri.Scheme;
             if (!string.Equals(uri.Scheme, firstScheme, StringComparison.Ordinal))
             {
@@ -130,6 +151,25 @@ public void Validate()
     }
 }
 
+/// <summary>
+/// Client-side load-balancing strategy used when multiple endpoints are
+/// configured.
+/// </summary>
+public enum LoadBalancingStrategy
+{
+    /// <summary>
+    /// Pick a ready endpoint uniformly at random for each call. Default.
+    /// Avoids the lock-step herding pattern that round-robin can produce when
+    /// many short-lived clients start at the same time.
+    /// </summary>
+    Random = 0,
+
+    /// <summary>
+    /// Cycle through ready endpoints in order.
+    /// </summary>
+    RoundRobin = 1,
+}
+
 /// <summary>
 /// Authentication options for GreptimeDB.
 /// </summary>

src/GreptimeDB.Ingester/Client/RandomBalancer.cs

@@ -0,0 +1,58 @@
+using Grpc.Net.Client.Balancer;
+using Grpc.Net.Client.Configuration;
+using Microsoft.Extensions.Logging;
+
+namespace GreptimeDB.Ingester.Client;
+
+/// <summary>
+/// <see cref="LoadBalancerFactory"/> for the <c>random</c> policy: each pick selects
+/// uniformly at random from the ready subchannels. Spreads load with no shared state
+/// or coordination, which avoids the lock-step herding pattern that round-robin can
+/// produce when many short-lived clients start at the same time.
+/// </summary>
+internal sealed class RandomBalancerFactory : LoadBalancerFactory
+{
+    public static readonly RandomBalancerFactory Instance = new();
+
+    public override string Name => RandomConfig.Name;
+
+    public override LoadBalancer Create(LoadBalancerOptions options)
+    {
+        return new RandomBalancer(options.Controller, options.LoggerFactory);
+    }
+}
+
+internal sealed class RandomConfig : LoadBalancingConfig
+{
+    public const string Name = "random";
+
+    public RandomConfig() : base(Name) { }
+}
+
+internal sealed class RandomBalancer : SubchannelsLoadBalancer
+{
+    public RandomBalancer(IChannelControlHelper controller, ILoggerFactory loggerFactory)
+        : base(controller, loggerFactory) { }
+
+    protected override SubchannelPicker CreatePicker(IReadOnlyList<Subchannel> readySubchannels)
+    {
+        return new RandomPicker(readySubchannels);
+    }
+}
+
+internal sealed class RandomPicker : SubchannelPicker
+{
+    private readonly IReadOnlyList<Subchannel> _subchannels;
+
+    public RandomPicker(IReadOnlyList<Subchannel> subchannels)
+    {
+        _subchannels = subchannels;
+    }
+
+    public override PickResult Pick(PickContext context)
+    {
+        // Random.Shared is thread-safe; pickers are invoked concurrently from many RPCs.
+        var index = Random.Shared.Next(_subchannels.Count);
+        return PickResult.ForSubchannel(_subchannels[index]);
+    }
+}

tests/GreptimeDB.Ingester.Tests/GreptimeClientOptionsTests.cs

@@ -16,6 +16,12 @@ public void Validate_DefaultOptions_Passes()
         act.Should().NotThrow();
     }
 
+    [Fact]
+    public void LoadBalancing_DefaultsToRandom()
+    {
+        new GreptimeClientOptions().LoadBalancing.Should().Be(LoadBalancingStrategy.Random);
+    }
+
     [Fact]
     public void Validate_SingleEndpoint_Passes()
     {
@@ -141,6 +147,41 @@ public void Validate_EndpointsAllWhitespace_ThrowsAndDoesNotFallBack()
         act.Should().Throw<ArgumentException>().WithMessage("*no non-whitespace*");
     }
 
+    [Theory]
+    [InlineData(LoadBalancingStrategy.Random)]
+    [InlineData(LoadBalancingStrategy.RoundRobin)]
+    public void Constructor_MultiEndpoint_AcceptsAllStrategies(LoadBalancingStrategy strategy)
+    {
+        var options = new GreptimeClientOptions
+        {
+            Endpoints = new List<string> { "http://host-a:4001", "http://host-b:4001" },
+            LoadBalancing = strategy,
+        };
+
+        var act = () =>
+        {
+            using var client = new GreptimeClient(options);
+        };
+
+        act.Should().NotThrow();
+    }
+
+    [Theory]
+    [InlineData("http://host:4001/v1")]
+    [InlineData("http://host:4001/?foo=1")]
+    [InlineData("http://host:4001/#frag")]
+    public void Validate_EndpointWithPathQueryOrFragment_Throws(string endpoint)
+    {
+        var options = new GreptimeClientOptions
+        {
+            Endpoints = new List<string> { endpoint }
+        };
+
+        var act = () => options.Validate();
+
+        act.Should().Throw<ArgumentException>().WithMessage("*without a path, query, or fragment*");
+    }
+
     [Fact]
     public void ResolveEndpoints_FiltersWhitespaceAndTrims()
     {