distribute - v2.1.0

distribute/cluster

Types

ClusterHealth

</>

Health status of the cluster from this node’s perspective.

pub type ClusterHealth {
  ClusterHealth(
    self_node: String,
    is_distributed: Bool,
    connected_nodes: List(String),
    connected_count: Int,
    reachable_nodes: List(String),
    unreachable_nodes: List(String),
  )
}

Constructors 

  • ClusterHealth(
  self_node: String,
  is_distributed: Bool,
  connected_nodes: List(String),
  connected_count: Int,
  reachable_nodes: List(String),
  unreachable_nodes: List(String),
)

    Arguments

    self_node

    Name of the current node

    is_distributed

    Whether this node is running as a distributed node

    connected_nodes

    List of currently connected node names

    connected_count

    Number of connected nodes

    reachable_nodes

    Nodes that were pinged successfully

    unreachable_nodes

    Nodes that failed to respond to ping

ConnectError

</>

Error type for connection failures.

pub type ConnectError {
  ConnectTimeout
  NodeNotFound
  ConnectNetworkError(String)
  ConnectIgnored
}

Constructors 

  • ConnectTimeout

    Connection timed out.

  • NodeNotFound

    Node not found or unreachable.

  • ConnectNetworkError(String)

    Network connectivity issue.

  • ConnectIgnored

    Connection was ignored (already connected or self).

Dynamic

</>

Opaque value returned by low-level Erlang FFI calls in the cluster_ffi module. This type is intentionally untyped because the underlying Erlang implementation may return atoms, tuples or other runtime values. Callers should treat Dynamic as an implementation detail and prefer the high-level, type-safe wrappers exported from this module (for example start_node/2, connect/1).

pub type Dynamic

StartError

</> 
pub type StartError {
  InvalidNodeName(String)
  AlreadyStarted
  CookieTooLong
  NetworkError(String)
  SystemError(String)
  StartFailed(String)
}

Constructors 

  • InvalidNodeName(String)

    Node name is invalid (must contain ‘@’ and be a valid atom).

  • AlreadyStarted

    Node is already started as a distributed node.

  • CookieTooLong

    Cookie is too long (max 255 characters).

  • NetworkError(String)

    Network-related error (e.g., port binding failure).

  • SystemError(String)

    Permission denied or other system error.

  • StartFailed(String)

    Generic startup failure with detailed reason.

Values

classify_connect_reason

</> 
pub fn classify_connect_reason(reason: String) -> ConnectError

classify_start_reason

</> 
pub fn classify_start_reason(reason: String) -> StartError

Classify error reason into structured StartError

connect

</> 
pub fn connect(node: String) -> Result(Nil, ConnectError)

Connect to another distributed node. Returns Ok(Nil) if connected, Error with reason otherwise.

connect_bool

</> 
pub fn connect_bool(node: String) -> Bool

Deprecated: Use connect() which returns Result instead

Connect to another distributed node (legacy API). Returns True if connected successfully, False otherwise.

connected_count

</> 
pub fn connected_count() -> Int

Get the number of currently connected nodes.

health

</> 
pub fn health() -> Result(ClusterHealth, String)

Check the health of the cluster.

Returns a ClusterHealth record with information about:

  • Current node status
  • Connected nodes
  • Reachability of connected nodes via ping

Example

case cluster.health() {
  Ok(status) -> {
    io.println("Self: " <> status.self_node)
    io.println("Connected: " <> int.to_string(status.connected_count))
  }
  Error(reason) -> io.println("Health check failed: " <> reason)
}

is_distributed

</> 
pub fn is_distributed() -> Bool

Check if this node is running as a distributed node.

Returns True if the node was started with a name (e.g., -name node@host).

is_healthy

</> 
pub fn is_healthy() -> Bool

Quick health check - returns True if node is distributed and has connections.

Use this for simple health endpoints that just need a boolean.

Example

case cluster.is_healthy() {
  True -> "OK"
  False -> "UNHEALTHY"
}

nodes

</> 
pub fn nodes() -> List(String)

Get the list of currently connected nodes.

ping

</> 
pub fn ping(node: String) -> Bool

Ping a remote node to check if it is reachable. Returns True if the node responds with pong, False otherwise.

self_node

</> 
pub fn self_node() -> String

Get the name of the current node.

start_node

</> 
pub fn start_node(
  name: String,
  cookie: String,
) -> Result(Nil, StartError)

Start distributed node with the given name and cookie. Returns Ok(Nil) on success, Error with specific failure reason.

✨ Search Document