Bedrock.ClusterBootstrap.Discovery (bedrock v0.5.2)

Discovers or creates ClusterBootstrap at node startup.

Boot Sequence

Try to read ClusterBootstrap from ObjectStorage
If not found, attempt conditional write (race for first boot)
If write succeeds → become coordinator
If write fails (someone beat us) → re-read and check coordinator list

First Boot

On first boot (no ClusterBootstrap exists), nodes race to write an initial bootstrap using conditional PUT. The winner becomes the sole coordinator of a single-node cluster. Losers re-read and join as workers (or coordinators if the winner included them).

Summary

Types

bootstrap()

discovery_result()

version_token()

Functions

create_initial(coordinator_node)

Creates an initial ClusterBootstrap for first boot.

discover(self_node)

Discovers the cluster bootstrap using configured ObjectStorage.

discover(backend, bootstrap_key, self_node)

Discovers the cluster bootstrap, creating one if this is first boot.

write_bootstrap(backend, bootstrap_key, version_token, bootstrap)

Writes updated bootstrap to object storage with version check.

Types

bootstrap()

@type bootstrap() :: map()

discovery_result()

@type discovery_result() ::
  {:ok, :coordinator, bootstrap(), version_token()}
  | {:ok, :worker, bootstrap(), version_token()}

version_token()

@type version_token() :: String.t() | nil

Functions

create_initial(coordinator_node)

@spec create_initial(node()) :: bootstrap()

Creates an initial ClusterBootstrap for first boot.

The bootstrap has:

A randomly generated cluster_id
epoch set to 1
Empty logs list
The given node as the sole coordinator

discover(self_node)

@spec discover(node()) :: discovery_result()

Discovers the cluster bootstrap using configured ObjectStorage.

Convenience wrapper that reads backend and bootstrap_key from application config. See discover/3 for full documentation.

discover(backend, bootstrap_key, self_node)

@spec discover(Bedrock.ObjectStorage.backend(), String.t(), node()) ::
  discovery_result()

Discovers the cluster bootstrap, creating one if this is first boot.

Returns {:ok, :coordinator, bootstrap} if this node should run as a coordinator, or {:ok, :worker, bootstrap} if this node should run as a worker.

write_bootstrap(backend, bootstrap_key, version_token, bootstrap)

@spec write_bootstrap(
  Bedrock.ObjectStorage.backend(),
  String.t(),
  String.t(),
  bootstrap()
) ::
  :ok | {:error, :version_mismatch | term()}

Writes updated bootstrap to object storage with version check.

Uses conditional write to prevent overwriting a newer bootstrap from a concurrent recovery. Returns :ok on success or {:error, :version_mismatch} if another recovery completed first.