defmodule Prymn.Agents do
  @moduledoc ~S"""
  Prymn Agents are programs that manage a remote client machine. Prymn backend
  communicates with them using GRPC calls. GRPC connections are started using
  the Prymn.Agents.ConnectionSupervisor and are book-kept using the
  Prymn.Agents.Registry.

  """

  @doc """
  Establishes a dynamically supervised, background connection with the target
  host agent, keeping it alive if it is already started.
  """
  @spec start_connection_or_keep_alive(String.t()) :: :ok
  def start_connection_or_keep_alive(host_address) do
    spec = {Prymn.Agents.Connection, host_address}

    case DynamicSupervisor.start_child(Prymn.Agents.ConnectionSupervisor, spec) do
      {:error, {:already_started, pid}} ->
        :ok = Prymn.Agents.Connection.keep_alive(pid)
        :ok

      {:ok, _pid} ->
        :ok
    end
  end

  @doc """
  Subscribe to the host's Health using Phoenix.PubSub Broadcasted messages are
  in the form of:

    {host_address, %Prymn.Agents.Health{}}

  ## Returns

  This function returns the last health status of the Agent that was saved.
  """
  @spec subscribe_to_health(String.t()) :: Prymn.Agents.Health.t()
  def subscribe_to_health(host_address) do
    Prymn.Agents.Health.subscribe(host_address)
    Prymn.Agents.Health.lookup(host_address)
  end

  @spec get_channel(String.t()) :: GRPC.Channel.t()
  def get_channel(host_address) do
    Prymn.Agents.Connection.get_channel(host_address)
  end
end