beam_adapter

BEAM transport adapter using Erlang distribution.

This module provides the reference implementation of TransportAdapter using the BEAM’s built-in Erlang distribution protocol. It is the default adapter used by the distribute/transport facade.

Features

Reliable delivery via Erlang distribution (TCP-based)
Per-node circuit breakers to prevent cascading failures
Automatic retries with exponential backoff
Health monitoring and metrics collection
OTP actor implementation for supervision compatibility

Architecture

The adapter runs as a supervised OTP actor that handles:

Sending messages to local/remote registered processes
Broadcasting to process groups
Managing subscriptions for incoming messages
Tracking per-peer circuit breaker state
Collecting send/receive metrics

Usage

Typically you don’t use this module directly. Instead, use the distribute/transport facade which manages a singleton instance.

For custom configurations:

import distribute/transport/adapter
import distribute/transport/beam_adapter

let opts = adapter.default_options("my_adapter")
let adapter = beam_adapter.new()
let assert Ok(handle) = adapter.start(opts)

Types

Command

opaque </>

Commands handled by the BEAM adapter actor.

This type is opaque to prevent external code from sending arbitrary commands to the actor. Use the TransportAdapter interface instead.

pub opaque type Command

Values

child_spec

</>

pub fn child_spec(
  options: types.AdapterOptions,
) -> supervision.ChildSpecification(types.AdapterHandle)

Create a child specification for OTP supervision.

Use this when adding the adapter to a supervision tree.

Example

import gleam/otp/static_supervisor as supervisor

supervisor.new(supervisor.OneForOne)
|> supervisor.add(beam_adapter.child_spec(opts))
|> supervisor.start()

get_handle

</>

pub fn get_handle(
  name: String,
) -> Result(types.AdapterHandle, Nil)

Get a handle to a running adapter by name.

This function looks up a previously started adapter by its registered name and returns a handle that can be used with the TransportAdapter functions.

The handle is retrieved from the registry where it was stored during adapter startup. This allows the singleton pattern used by distribute/transport to work correctly.

Example

case beam_adapter.get_handle("my_adapter") {
  Ok(handle) -> {
    let adapter = beam_adapter.new()
    adapter.send(handle, "peer", payload, opts)
  }
  Error(Nil) -> io.println("Adapter not running")
}

new

</>

pub fn new() -> adapter.TransportAdapter

Create a new BEAM transport adapter instance.

Returns a TransportAdapter record with function pointers for all adapter operations. This allows the adapter to be used polymorphically with other adapter implementations.

Example

let adapter = beam_adapter.new()
let assert Ok(handle) = adapter.start(options)
adapter.send(handle, "peer", payload, opts)