RpcLoadBalancer

Copy Markdown View Source

An Elixir library for executing Remote Procedure Calls across distributed BEAM nodes with a built-in load balancer. It wraps Erlang's :erpc module with structured error handling and provides a pluggable node selection layer powered by OTP's :pg process groups.

Features

  • RPC wrappers — call/5 and cast/5 around :erpc with ErrorMessage error tuples
  • Distributed load balancer — automatic node discovery and registration via :pg
  • Seven selection algorithms — Random, Round Robin, Least Connections, Power of Two, Hash Ring, Weighted Round Robin, Call Direct
  • Custom algorithms — implement the SelectionAlgorithm behaviour to add your own
  • Node filtering — restrict which nodes join a balancer with string or regex patterns
  • Connection tracking — atomic counters for connection-aware algorithms
  • Random-node helpers — call_on_random_node/5 and cast_on_random_node/5 for name-based node filtering with built-in retry
  • Graceful draining — in-flight call tracking and connection draining on shutdown
  • Configurable retry — automatic retry with configurable count and sleep when no nodes are available

Installation

Add rpc_load_balancer to your list of dependencies in mix.exs:

def deps do
  [
    {:rpc_load_balancer, "~> 0.1.0"}
  ]
end

Quick Start

{:ok, result} =
  RpcLoadBalancer.call(
    :"worker@host",
    MyModule,
    :some_fun,
    ["arg"],
    timeout: :timer.seconds(5)
  )

{:ok, _pid} = RpcLoadBalancer.start_link(name: :my_balancer)

{:ok, result} =
  RpcLoadBalancer.call(
    :"worker@host",
    MyModule,
    :my_fun,
    [arg],
    load_balancer: :my_balancer
  )

Documentation

This project's documentation follows the Diátaxis framework:

Tutorials

  • Getting Started — learn the library by building a load-balanced RPC setup step by step

How-To Guides

Reference

Explanation