Mesh

Capability-based distributed process management for Elixir.

Mesh distributes GenServer processes across BEAM nodes using shard-based routing and capabilities. Processes are lazily activated on-demand and automatically placed on the correct node based on their ID and capability type.

What is Mesh?

Mesh solves the distributed process placement problem. Instead of manually managing where processes run, you define capabilities (like :game, :chat, :payment) and let Mesh handle the routing using shards distributed across your cluster.

Key characteristics:

• Deterministic placement: Same ID always routes to same node
• Lazy activation: Processes created on first invocation
• Zero coordination: No distributed locks or consensus
• High throughput: 16,000+ process creations/s, 30,000+ requests/s
• Library design: You control your supervision tree

Use cases: game servers with regional routing, multi-tenant systems with workload isolation, microservice patterns where different node types handle different request types.

Core Concepts

Capabilities

Capabilities are labels that define what types of processes a node can handle. Think of them as tags that describe a node's responsibility in your cluster.

For example:

• :game - This node handles game-related processes
• :chat - This node handles chat/messaging processes
• :payment - This node handles payment processing

Nodes register the capabilities they support, and Mesh automatically routes process requests to nodes with matching capabilities. This enables workload isolation and specialized node types.

Mesh.register_capabilities([:game, :chat])

Mesh uses shards to distribute processes across nodes:

process_id → shard → owner_node

Same ID always maps to the same shard. Shards are automatically distributed across nodes supporting the required capability. When cluster topology changes (nodes joining/leaving), shards are rebalanced accordingly.

NOTE: The default shard strategy (EventualConsistency) uses eventual consistency for process placement. Shards are used purely for routing decisions - they do not provide state guarantees or transactions. Each process manages its own state independently. During network partitions, the same process ID may temporarily exist on multiple nodes until the system converges. When topology changes occur (nodes joining/leaving), rebalancing stops conflicting processes so they can be migrated to the correct node on their next invocation. You can implement custom shard strategies with different consistency guarantees - see Configuration.

Processes are created lazily on first invocation. When you call a non-existent process, Mesh:

1. Determines target node via shard routing
2. Starts the process on that node
3. Caches the PID for fast subsequent lookups
4. Forwards the message and returns the response

This eliminates manual lifecycle management.

Quick Start

Add to mix.exs:

def deps do
  [
    {:mesh, "~> 0.1"},
    {:libcluster, "~> 3.3"}
  ]
end

Start Mesh in your application:

defmodule MyApp.Application do
  use Application

  def start(_type, _args) do
    topologies = [
      gossip: [
        strategy: Cluster.Strategy.Gossip,
        config: [port: 45892, if_addr: "0.0.0.0"]
      ]
    ]

    children = [
      {Mesh.Supervisor, topologies: topologies}
    ]

    Supervisor.start_link(children, strategy: :one_for_one)
  end
end

Define a GenServer:

defmodule MyApp.Counter do
  use GenServer

  def start_link(process_id) do
    GenServer.start_link(__MODULE__, process_id)
  end

  def init(process_id) do
    {:ok, %{id: process_id, count: 0}}
  end

  def handle_call({:actor_call, _payload}, _from, state) do
    new_count = state.count + 1
    {:reply, {:ok, new_count}, %{state | count: new_count}}
  end
end

Register capabilities and invoke:

Mesh.register_capabilities([:counter])

{:ok, pid, result} = Mesh.call(%Mesh.Request{
  module: MyApp.Counter,
  id: "counter_1",
  payload: %{},
  capability: :counter
})

API

Mesh.call/1 - Synchronous invocation

{:ok, pid, response} = Mesh.call(%Mesh.Request{
  module: MyApp.Counter,
  id: "counter_1",
  payload: %{action: :increment},
  capability: :counter
})

Mesh.cast/1 - Fire-and-forget invocation

:ok = Mesh.cast(%Mesh.Request{
  module: MyApp.Counter,
  id: "counter_1",
  payload: %{action: :reset},
  capability: :counter
})

Mesh.register_capabilities/1 - Register supported capabilities

Mesh.register_capabilities([:game, :chat, :payment])

Cluster Setup

Single-node development:

iex -S mix
iex> Mesh.register_capabilities([:game, :chat])

Multi-node with Gossip:

# Terminal 1
iex --sname game@localhost --cookie mesh -S mix
iex> Mesh.register_capabilities([:game])

# Terminal 2
iex --sname chat@localhost --cookie mesh -S mix
iex> Mesh.register_capabilities([:chat])

Kubernetes deployment:

config :libcluster,
  topologies: [
    k8s: [
      strategy: Cluster.Strategy.Kubernetes.DNS,
      config: [
        service: "mesh-headless",
        application_name: "mesh"
      ]
    ]
  ]

Performance

Run benchmarks:

mix run scripts/benchmark_singlenode.exs
elixir --name bench@127.0.0.1 --cookie mesh -S mix run scripts/benchmark_multinode.exs

Documentation

• Quickstart Guide - Get started in 5 minutes
• Configuration - Configure shard strategies and distribution
• Clustering - Multi-node setup
• Sharding - Process distribution internals
• Implementing Processes - Building stateful actors

Development

Using Make:

make help          # Show all commands
make all           # Install, compile, test
make dev           # Start IEx session
make test          # Run tests
make benchmark     # Run single-node benchmark