Bedrock.ControlPlane.Director (bedrock v0.5.2)

The director is a singleton within the cluster that orchestrates transaction system lifecycle and epoch-based generation management.

Created by the coordinator election winner, the director is responsible for bringing up the data plane and maintaining the cluster in a writable state. It coordinates recovery after component failures and manages the distributed consensus required for consistent system operation.

Epoch Management

The Director uses epoch-based generation management to prevent split-brain scenarios during recovery. Epochs are managed by the Coordinators as ever-increasing numbers that serve as generation counters. There is only ever one Director instance for a given epoch - it either completes recovery successfully or is relieved by the next Director with a higher epoch.

Services locked with newer epochs take precedence over older ones, and processes from previous epochs terminate themselves when they detect a generation change. This approach eliminates the need for complex coordination protocols while maintaining system consistency during concurrent recovery attempts.

Service Discovery Dependencies

The Director requires a populated service directory and node capabilities to orchestrate recovery effectively. The Coordinator ensures the Director receives complete cluster topology and capability information at startup, providing full knowledge of available cluster resources and the ability to create new services when vacancies must be filled during recovery.

Summary

Types

ref()

running_service_info()

running_service_info_by_id()

Functions

fetch_transaction_system_layout(director, timeout_in_ms \\ 5000)

notify_capabilities_updated(director, node_capabilities)

Notifies the director that node capabilities have been updated. This allows the director to update its capability map and retry stalled recovery if the new capabilities might resolve insufficient_nodes conditions.

notify_services_registered(director, service_infos)

Notifies the director that new services have been registered in the coordinator. This allows the director to update its service directory and retry stalled recovery if the new services might resolve insufficient_nodes conditions.

request_worker_creation(director, node, worker_id, kind, timeout_in_ms \\ 10000)

Requests a foreman on a specific node to create a new worker.

send_ping(director, minimum_read_version)

Sends a 'ping' message to the specified cluster director from the given node. We also include the minimum read version. The director will respond with a 'pong' message if it is alive and the read version is acceptable.

send_pong(director, from_node)

Sends a 'pong' message to the specified cluster director from the given node.

start_link(opts)

Types

ref()

@type ref() :: pid() | atom() | {atom(), node()}

running_service_info()

@type running_service_info() :: %{
  id: String.t(),
  otp_name: atom(),
  kind: :log | :materializer,
  pid: pid()
}

running_service_info_by_id()

@type running_service_info_by_id() :: %{
  required(Bedrock.Service.Worker.id()) => running_service_info()
}

Functions

fetch_transaction_system_layout(director, timeout_in_ms \\ 5000)

@spec fetch_transaction_system_layout(
  director_ref :: ref(),
  timeout_in_ms :: timeout_in_ms()
) ::
  {:ok, Bedrock.ControlPlane.Config.TransactionSystemLayout.t()}
  | {:error, :unavailable | :timeout | :unknown}

notify_capabilities_updated(director, node_capabilities)

@spec notify_capabilities_updated(
  director :: ref(),
  node_capabilities :: %{required(Bedrock.Cluster.capability()) => [node()]}
) :: :ok

Parameters

director: The reference to the cluster director (a GenServer).
node_capabilities: Map of capability -> [nodes] for use by recovery

Returns

:ok: Indicates the notification was successfully sent.

notify_services_registered(director, service_infos)

@spec notify_services_registered(
  director :: ref(),
  service_infos :: [{String.t(), atom(), {atom(), node()}}]
) :: :ok

Parameters

director: The reference to the cluster director (a GenServer).
service_infos: List of service info tuples in format {service_id, kind, {otp_name, node}}

Returns

:ok: Indicates the notification was successfully sent.

request_worker_creation(director, node, worker_id, kind, timeout_in_ms \\ 10000)

@spec request_worker_creation(
  director :: ref(),
  node(),
  Bedrock.Service.Worker.id(),
  :log | :materializer,
  timeout_in_ms()
) ::
  {:ok, running_service_info()}
  | {:error, :worker_creation_failed | :node_unavailable | :timeout}

Requests a foreman on a specific node to create a new worker.

Parameters

director: The reference to the cluster director (a GenServer).
node: The node where the worker should be created.
worker_id: The ID for the new worker.
kind: The type of worker (:log or :storage).
timeout_in_ms: (Optional) The timeout for this request in milliseconds, default is 10000ms.

Returns

{:ok, worker_info}: If the worker was successfully created.
{:error, reason}: If the worker creation failed.

send_ping(director, minimum_read_version)

@spec send_ping(director :: ref(), minimum_read_version :: Bedrock.version()) :: :ok

send_pong(director, from_node)

@spec send_pong(director :: ref(), from_node :: node()) :: :ok

Sends a 'pong' message to the specified cluster director from the given node.

Parameters

director: The reference to the cluster director (a GenServer).
from_node: The node from which the pong is sent.

Returns

:ok: Indicates the message was successfully sent.