nessie_cluster

Small but mighty: a library for forming Erlang clusters in Gleam via DNS.

This is a port of the Elixir DNSCluster library to Gleam. (Note this project does not have any affiliation with the Elixir library)

Examples

Fly.io

See the example repo for an example Gleam web service with clustering on Fly.io.

Unsupervised

This is NOT recommended. See below for a supervised example.

gleam add nessie_cluster
gleam add gleam_erlang # for sleeping

import gleam/option.{None}
import gleam/erlang/process
import nessie_cluster

pub fn main_simple() {
    let cluster: nessie_cluster.DnsCluster = nessie_cluster.with_query(
      nessie_cluster.new(), 
      nessie_cluster.DnsQuery("api.internal")
    )

    // The process queries DNS periodically, connecting to nodes
    let assert Ok(_subject) = nessie_cluster.start_spec(cluster, None)

    process.sleep_forever()
}

Supervised

It is strongly recommended to start the process under a supervisor, ensuring it is restarted if it crashes.

This example also sources the DNS name from an environment variable.

gleam add nessie_cluster
gleam add gleam_erlang
gleam add gleam_otp

import gleam/option.{None}
import gleam/erlang/os
import gleam/erlang/process
import gleam/otp/supervisor
import nessie_cluster

pub fn main() {
    // Source the DNS name from an env var
    let dns_query = case os.get_env("DISCOVERY_DNS_NAME") {
        // DNS queries will occur periodically for the given DNS name
        Ok(dns_name) -> nessie_cluster.DnsQuery(dns_name)
        // ensures DNS queries never occur, e.g. for local development
        Error(Nil) -> nessie_cluster.Ignore
    }

    let cluster: nessie_cluster.DnsCluster =
        nessie_cluster.with_query(nessie_cluster.new(), dns_query)

    let cluster_worker =
        supervisor.worker(fn(_) { 
            nessie_cluster.start_spec(cluster, None)
        })

    let children = fn(children) {
        children
        |> supervisor.add(cluster_worker)
        // add other children to your supervisor, e.g. a web server ...
    }
  
    let assert Ok(_) = supervisor.start(children)
  
    process.sleep_forever()
}

Further documentation can be found at https://hexdocs.pm/nessie_cluster.

Development

gleam run   # Run the project
gleam test  # Run the tests
gleam shell # Run an Erlang shell