Chronicle.Connections.LoadBalancer (cratis_chronicle v2.1.3)

Copy Markdown View Source

Selects a Chronicle server address to connect to from a resolved candidate list.

Chronicle.Connections.Connection re-resolves its configured (or DNS SRV-resolved, via Chronicle.Connections.DnsResolver) addresses on every connect/reconnect attempt and asks select/4 to pick one, according to the connection string's loadBalancer strategy:

  • :least_connections (the default) — probes every candidate's GET /connections/count HTTP endpoint on the Chronicle kernel and picks the address reporting the fewest active connections, breaking ties randomly. Before every probe attempt (not just the first), a random jitter of up to jitter_max_ms (0-250ms, defaulting to 250ms; 0 disables it) is slept, so a fleet of clients reconnecting at the same moment doesn't stampede every candidate host simultaneously - this mirrors the reference .NET client. The winner is then best-effort informed via POST /connections/reserve, so other clients racing to connect at the same time see an up-to-date count. If every probe fails (e.g. none of the candidates expose the endpoint), selection falls back to :random rather than failing the connection attempt outright. The actual HTTP calls live in Chronicle.Connections.LoadBalancer.HttpProbe.
  • :round_robin — cycles through the candidates in order. The starting point is a random offset chosen once per Connection process (not index 0), so a fleet of clients doesn't all dial the first host first.
  • :random — picks uniformly at random on every attempt.

Testing

The HTTP probe used by :least_connections is injectable via the :probe_fun option on Chronicle.Connections.Connection, mirroring the :connect_fun/:disconnect_fun seam already used to fake the gRPC channel.

Summary

Types

probe_action()
probe_fun()

Functions

default_probe(action, address, connection_string)

Default :probe_fun implementation, delegating to Chronicle.Connections.LoadBalancer.HttpProbe.

select(addresses, connection_string, round_robin_counter, probe_fun, jitter_max_ms \\ 250)

Selects one address from addresses according to connection_string.load_balancer.

Types

probe_action()

@type probe_action() :: :count | :reserve

probe_fun()

@type probe_fun() :: (probe_action(),
                Chronicle.Connections.ConnectionString.ServerAddress.t(),
                Chronicle.Connections.ConnectionString.t() ->
                  {:ok, term()} | {:error, term()})

Functions

default_probe(action, address, connection_string)

@spec default_probe(
  probe_action(),
  Chronicle.Connections.ConnectionString.ServerAddress.t(),
  Chronicle.Connections.ConnectionString.t()
) :: {:ok, term()} | {:error, term()}

Default :probe_fun implementation, delegating to Chronicle.Connections.LoadBalancer.HttpProbe.

select(addresses, connection_string, round_robin_counter, probe_fun, jitter_max_ms \\ 250)

@spec select(
  [Chronicle.Connections.ConnectionString.ServerAddress.t()],
  Chronicle.Connections.ConnectionString.t(),
  integer(),
  probe_fun(),
  non_neg_integer()
) ::
  {:ok, Chronicle.Connections.ConnectionString.ServerAddress.t()}
  | {:error, :no_addresses}

Selects one address from addresses according to connection_string.load_balancer.

round_robin_counter is an ever-incrementing integer owned by the calling Connection process — this module holds no state of its own, since the counter (and any future strategy state) belongs to the one Connection GenServer it is scoped to.

jitter_max_ms bounds the random delay :least_connections sleeps before every probe attempt; it defaults to 250ms and 0 disables it entirely. Ignored by :round_robin and :random.

Returns {:error, :no_addresses} when addresses is empty.