Bedrock.Service.Foreman (bedrock v0.5.2)

Wait until the foreman signals that it (and all of it's workers) are reporting that they are healthy, or the timeout happens... whichever comes first.

Types

health()

@type health() ::
  :ok | {:failed_to_start, :at_least_one_failed_to_start} | :unknown | :starting

ref()

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

Functions

all(foreman, opts \\ [])

@spec all(foreman :: ref(), opts :: [{:timeout, timeout()}]) ::
  {:ok, [Bedrock.Service.Worker.ref()]}
  | {:error, :unavailable | :timeout | :unknown}

Return a list of running workers.

config_key()

@spec config_key() :: atom()

get_all_running_services(foreman, opts \\ [])

@spec get_all_running_services(foreman :: ref(), opts :: [{:timeout, timeout()}]) ::
  {:ok,
   [{service_id :: String.t(), kind :: :log | :materializer, name :: atom()}]}
  | {:error, :unavailable | :timeout | :unknown}

Return a list of all running services with information needed for coordinator registration.

Each service is returned as a compact tuple of {service_id, kind, name} where:

service_id is the real service identifier from the worker's manifest
kind is :log or :materializer
name is the OTP name atom for the worker

The coordinator will expand this to full service info using node(from) and the provided service_id.

materializer_workers(foreman, opts \\ [])

@spec materializer_workers(foreman :: ref(), opts :: [{:timeout, timeout()}]) ::
  {:ok, [Bedrock.Service.Worker.ref()]}
  | {:error, :unavailable | :timeout | :unknown}

Return a list of running materializer workers only.

new_worker(foreman, id, kind, opts \\ [])

@spec new_worker(
  foreman :: ref(),
  id :: Bedrock.Service.Worker.id(),
  kind :: :log | :materializer,
  opts :: [{:timeout, timeout()}]
) :: {:ok, Bedrock.Service.Worker.ref()} | {:error, :timeout}

Create a new worker.

remove_worker(foreman, worker_id, opts \\ [])

@spec remove_worker(
  foreman :: ref(),
  Bedrock.Service.Worker.id(),
  opts :: [{:timeout, timeout()}]
) ::
  :ok
  | {:error, :worker_not_found}
  | {:error, {:failed_to_remove_directory, File.posix(), Path.t()}}
  | {:error, :unavailable | :timeout | :unknown}

Remove a worker and clean up its resources.

This will:

Terminate the worker process
Remove it from the supervisor
Clean up its working directory
Remove it from foreman state

remove_workers(foreman, worker_ids, opts \\ [])

@spec remove_workers(
  foreman_ref :: ref(),
  worker_ids :: [Bedrock.Service.Worker.id()],
  opts :: [{:timeout, timeout()}]
) ::
  %{required(Bedrock.Service.Worker.id()) => :ok | {:error, term()}}
  | {:error, :unavailable | :timeout | :unknown}

Remove multiple workers in a single batch operation.

This is more efficient than calling remove_worker/3 multiple times as it processes all workers in one foreman call.

Returns a map of results where successful removals are :ok and failures include the error reason.

report_health(foreman, worker_id, health)

@spec report_health(
  foreman :: ref(),
  Bedrock.Service.Worker.id(),
  Bedrock.Service.Worker.health()
) :: :ok

Called by a worker to report it's health to the foreman.

start_link(opts)

wait_for_healthy(foreman, opts \\ [])

@spec wait_for_healthy(foreman :: ref(), opts :: [{:timeout, timeout()}]) ::
  :ok | {:error, :unavailable | :timeout | :unknown}

Wait until the foreman signals that it (and all of it's workers) are reporting that they are healthy, or the timeout happens... whichever comes first.