ExMCP.Transport.Beam.LoadBalancer (ex_mcp v0.9.2)

View Source

Load balancer for distributing client connections across MCP service instances.

Provides multiple load balancing strategies optimized for BEAM transport:

  • Round-robin: Cycles through available services
  • Least-connections: Routes to service with fewest active connections
  • Weighted: Distributes based on service weights
  • Health-aware: Excludes unhealthy services from selection

Example Usage

# Start load balancer with round-robin strategy
{:ok, balancer} = LoadBalancer.start_link(%{
  cluster: cluster_pid,
  strategy: :round_robin,
  health_aware: true
})

# Get a service instance
{:ok, service} = LoadBalancer.get_service(balancer, "calculator")

# Update service connection count for least-connections strategy
LoadBalancer.update_connections(balancer, service_id, 5)

Summary

Types

config()
strategy()

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

get_service(balancer, service_name, opts \\ %{})

Gets a service instance using the configured load balancing strategy.

get_stats(balancer)

Gets load balancer statistics.

record_connection(balancer, service_id)

Records that a connection to a service was established.

record_disconnection(balancer, service_id)

Records that a connection to a service was closed.

start_link(config)

Starts a load balancer with the given configuration.

stop(balancer)

Stops the load balancer.

update_connections(balancer, service_id, connection_count)

Updates connection count for a service (used by least-connections strategy).

update_strategy(balancer, strategy)

Updates the load balancing strategy.

Types

config()

@type config() :: %{
  cluster: GenServer.server(),
  strategy: strategy(),
  health_aware: boolean(),
  connection_tracking: boolean(),
  exclude_circuit_broken: boolean()
}

strategy()

@type strategy() :: :round_robin | :least_connections | :weighted | :random

Functions

child_spec(init_arg)

Returns a specification to start this module under a supervisor.

See Supervisor.

get_service(balancer, service_name, opts \\ %{})

@spec get_service(GenServer.server(), String.t(), map()) ::
  {:ok, map()} | {:error, term()}

Gets a service instance using the configured load balancing strategy.

get_stats(balancer)

@spec get_stats(GenServer.server()) :: {:ok, map()}

Gets load balancer statistics.

record_connection(balancer, service_id)

@spec record_connection(GenServer.server(), String.t()) :: :ok

Records that a connection to a service was established.

record_disconnection(balancer, service_id)

@spec record_disconnection(GenServer.server(), String.t()) :: :ok

Records that a connection to a service was closed.

start_link(config)

@spec start_link(config()) :: GenServer.on_start()

Starts a load balancer with the given configuration.

stop(balancer)

@spec stop(GenServer.server()) :: :ok

Stops the load balancer.

update_connections(balancer, service_id, connection_count)

@spec update_connections(GenServer.server(), String.t(), non_neg_integer()) :: :ok

Updates connection count for a service (used by least-connections strategy).

update_strategy(balancer, strategy)

@spec update_strategy(GenServer.server(), strategy()) :: :ok

Updates the load balancing strategy.