Arrea (Arrea v1.0.0)

Copy Markdown View Source

Fachada principal del orquestador Arrea.

Responsable de:

Arquitectura

┌─────────────────────────────────────────────────────────┐
│                      Arrea                              │
│                    (Fachada)                             │
└─────────────────────────┬───────────────────────────────┘
                         │
┌────────────────────────▼───────────────────────────────┐
│              Arrea.Leader (GenServer)                   │
│         Coordina ejecución, gestiona workers           │
│         Emite eventos {:leader_event, event}           │
└─────────────────────────┬───────────────────────────────┘
                         │
┌────────────────────────▼───────────────────────────────┐
│       Arrea.WorkerSupervisor (DynamicSupervisor)       │
│              Workers efímeros                          │
└─────────────────────────┬───────────────────────────────┘
                         │
┌────────────────────────▼───────────────────────────────┐
│              Arrea.Worker (GenServer)                  │
│              Ejecuta tareas individuales                │
└─────────────────────────────────────────────────────────┘

Arrea.Monitor — Estadísticas del ciclo de vida de workers
Arrea.CircuitBreaker — Tolerancia a fallos

El árbol de supervisión arranca automáticamente al incluir Arrea como dependencia. No es necesario arrancar Arrea.Supervisor manualmente.

Uso rápido

# Ejecución simple
{:ok, result} = Arrea.execute(fn -> :ok end)

# Ejecución paralela
{:ok, results} = Arrea.run([fn -> 1 end, fn -> 2 end], workers: 4)

# Suscripción a eventos del Leader
:ok = Arrea.subscribe()

receive do
  {:leader_event, %{type: :worker_started} = event} ->
    IO.inspect(event)
  {:leader_event, %{type: :finished} = event} ->
    IO.inspect(event)
end

:ok = Arrea.unsubscribe()

Summary

Types

execution_option()

Functions

execute(cmd, opts \\ [])

Ejecuta un comando único de forma síncrona.

max_workers()

Devuelve el número máximo de workers configurados.

run(commands, opts \\ [])

Ejecuta múltiples comandos en paralelo.

stats()

Obtiene las estadísticas actuales del Engine.

subscribe()

Suscribe el proceso actual a los eventos semánticos del Leader.

unsubscribe()

Cancela la suscripción del proceso actual a los eventos del Leader.

Types

execution_option()

@type execution_option() ::
  {:workers, non_neg_integer()}
  | {:timeout, non_neg_integer()}
  | {:retry, boolean()}

Functions

execute(cmd, opts \\ [])

@spec execute(binary() | (-> term()), [execution_option()]) ::
  {:ok, Arrea.Result.t()} | {:error, Arrea.Error.t()}

Ejecuta un comando único de forma síncrona.

Parámetros

  • cmd — Un binary (comando shell) o una función sin argumentos
  • opts — Opciones adicionales:
    • :timeout — Timeout en ms (por defecto 30_000). Timeout real: cancela la ejecución.
    • :retry — Si se debe reintentar en caso de fallo
    • :shell — Shell a usar (máxima prioridad sobre config y entorno)

Retorna

  • {:ok, Arrea.Result.t()} — Éxito con resultado
  • {:error, Arrea.Error.t()} — Error con código y mensaje

Ejemplos

iex> Arrea.execute("echo hello")
{:ok, %Arrea.Result{success: true, data: %{stdout: "hello\n", ...}, failures: []}}

iex> Arrea.execute(fn -> :work end)
{:ok, %Arrea.Result{success: true, data: :work, failures: []}}

max_workers()

@spec max_workers() :: non_neg_integer()

Devuelve el número máximo de workers configurados.

Ejemplo

iex> Arrea.max_workers()
100

run(commands, opts \\ [])

@spec run([binary() | (-> term())], [execution_option()]) ::
  {:ok, Arrea.Result.t()} | {:error, Arrea.Error.t()}

Ejecuta múltiples comandos en paralelo.

Parámetros

  • commands — Lista de binaries o funciones
  • opts — Opciones:
    • :workers — Número máximo de workers paralelos (por defecto max_workers())
    • :timeout — Timeout total en ms

Retorna

  • {:ok, Arrea.Result.t()} — Con batch_id para correlacionar eventos
  • {:error, Arrea.Error.t()} — Si todos fallaron o no hay workers disponibles

Ejemplo

iex> {:ok, result} = Arrea.run([fn -> 1 end, fn -> 2 end, fn -> 3 end], workers: 2)
iex> result.data.batch_id
"batch_..."

stats()

@spec stats() :: {:ok, map()} | {:error, :monitor_unavailable}

Obtiene las estadísticas actuales del Engine.

Las estadísticas las provee Arrea.Monitor, que trackea el ciclo de vida de todos los workers arrancados bajo el Leader.

Ejemplo

iex> {:ok, stats} = Arrea.stats()
iex> Map.keys(stats)
[:active_workers, :completed_tasks, :failed_tasks, :total_workers]

subscribe()

@spec subscribe() :: :ok

Suscribe el proceso actual a los eventos semánticos del Leader.

Los mensajes recibidos tienen la forma {:leader_event, event} donde event es un mapa con al menos la clave :type.

Tipos de evento habituales:

  • %{type: :worker_started, worker_id: id}
  • %{type: :progress, worker_id: id, percent: float, ...}
  • %{type: :finished, worker_id: id}
  • %{type: :error, worker_id: id, reason: term}
  • %{type: :result, worker_id: id, data: term}

Para desuscribirse, llamar a unsubscribe/0.

Ejemplo

:ok = Arrea.subscribe()

receive do
  {:leader_event, %{type: :finished, worker_id: id}} ->
    IO.puts("Worker #{id} terminó")
end

unsubscribe()

@spec unsubscribe() :: :ok

Cancela la suscripción del proceso actual a los eventos del Leader.

Ejemplo

:ok = Arrea.unsubscribe()