defmodule Combo.PubSub.Adapter do
  @moduledoc """
  The behaviour for implementing a custom `Combo.PubSub` adapter.
  """

  @type adapter_name :: atom()

  @doc """
  Returns the node name as an atom or a binary.
  """
  @callback node_name(adapter_name()) :: Combo.PubSub.node_name()

  @doc """
  Returns a child specification that mounts the processes required for the
  adapter.

  `child_spec` will receive all options given `Combo.PubSub`. Note, however,
  that the `:name` under options is the name of the complete PubSub system.
  The reserved key space to be used by the adapter is under the `:adapter_name`
  key.
  """
  @callback child_spec(keyword()) :: Supervisor.child_spec()

  @doc """
  Broadcasts the given topic, message, and dispatcher to all nodes in the
  cluster (except the current node itself).
  """
  @callback broadcast(
              adapter_name(),
              topic :: Combo.PubSub.topic(),
              message :: Combo.PubSub.message(),
              dispatcher :: Combo.PubSub.dispatcher()
            ) :: :ok | {:error, term()}

  @doc """
  Broadcasts the given topic, message, and dispatcher to given node in the
  cluster (it may point to itself).
  """
  @callback direct_broadcast(
              adapter_name(),
              node_name :: Combo.PubSub.node_name(),
              topic :: Combo.PubSub.topic(),
              message :: Combo.PubSub.message(),
              dispatcher :: Combo.PubSub.dispatcher()
            ) :: :ok | {:error, term()}
end