EasyRpc.NodeSelector (EasyRpc v0.9.0)

Copy Markdown View Source

Node selection strategies for distributed RPC calls.

Supports both static node lists and dynamic node discovery through MFA (Module, Function, Arguments).

Selection Strategies

  • :random - Randomly picks a node on each call.
  • :round_robin - Circular distribution, tracked per-process.
  • :hash - Consistent hashing on function arguments.
                 Same args always route to the same node.

Sticky Nodes

When sticky_node: true, a process sticks to the first node it selects for all subsequent calls (stored in the process dictionary).

Node Configuration

  • Static list: nodes: [:node1@host, :node2@host]
  • Dynamic MFA: nodes: {MyModule, :get_nodes, []}

Examples

selector = NodeSelector.new([:n1@host, :n2@host], :my_id, :random)

selector = NodeSelector.new(
  {ClusterHelper, :get_nodes, [:backend]},
  :backend_selector,
  :round_robin,
  true
)

node = NodeSelector.select_node(selector, ["user_123"])
#=> :n1@host

Summary

Types

node_list()
nodes_config()
nodes_mfa()
selector_id()
strategy()
t()

Functions

clear_sticky_node(arg1)

Clears the sticky node for the current process.

load_config!(app_name, config_name)

Loads a NodeSelector from application config.

new(nodes_or_mfa, id, strategy \\ :random, sticky_node \\ false)

Creates and validates a new NodeSelector. Raises EasyRpc.Error if any option is invalid.

reset_round_robin(node_selector)

Resets the round-robin counter for the current process.

select_node(selector, data)

Selects a node using the configured strategy.

update_id(selector, id)

Updates the selector's :id field.

Types

node_list()

@type node_list() :: [node()]

nodes_config()

@type nodes_config() :: node_list() | nodes_mfa()

nodes_mfa()

@type nodes_mfa() :: {module :: atom(), function :: atom(), args :: list()}

selector_id()

@type selector_id() :: term()

strategy()

@type strategy() :: :random | :round_robin | :hash

t()

@type t() :: %EasyRpc.NodeSelector{
  id: selector_id(),
  nodes_or_mfa: nodes_config(),
  sticky_node: boolean(),
  strategy: strategy()
}

Functions

clear_sticky_node(arg1)

@spec clear_sticky_node(t()) :: :ok

Clears the sticky node for the current process.

load_config!(app_name, config_name)

@spec load_config!(app :: atom(), config_name :: atom()) :: t()

Loads a NodeSelector from application config.

Expected format:

config :my_app, :remote_nodes,
  nodes: [:node1@host, :node2@host],
  select_mode: :round_robin,
  sticky_node: false

Raises EasyRpc.Error if config is missing or invalid.

new(nodes_or_mfa, id, strategy \\ :random, sticky_node \\ false)

@spec new(nodes_config(), selector_id(), strategy(), boolean()) :: t()

Creates and validates a new NodeSelector. Raises EasyRpc.Error if any option is invalid.

reset_round_robin(node_selector)

@spec reset_round_robin(t()) :: :ok

Resets the round-robin counter for the current process.

select_node(selector, data)

@spec select_node(t(), data :: term()) :: node()

Selects a node using the configured strategy.

  • Respects sticky-node state stored in the process dictionary.
  • data is only used by the :hash strategy.

Raises EasyRpc.Error when no nodes are available.

update_id(selector, id)

@spec update_id(t(), selector_id()) :: t()

Updates the selector's :id field.