toxiproxy_ex.ex

defmodule ToxiproxyEx do
  alias ToxiproxyEx.{Proxy, Client, Toxic, ToxicCollection}

  @external_resource "README.md"
  @moduledoc "README.md"
             |> File.read!()
             |> String.split("<!-- MDOC !-->")
             |> Enum.fetch!(1)

  @typedoc """
  A proxy that intercepts traffic to and from an upstream server.
  """
  @opaque proxy :: Proxy.t()

  @typedoc """
  A collection of proxies.
  """
  @opaque toxic_collection :: ToxicCollection.t()

  @typedoc """
  A hostname or IP address including a port number, e.g. `localhost:4539`.
  """
  @type host_with_port :: String.t()

  @typedoc """
  A map containing fields required to setup a proxy. Designed to be used with `ToxiproxyEx.populate!/1`.
  """
  @type proxy_map :: %{
          required(:name) => String.t(),
          required(:upstream) => host_with_port(),
          optional(:listen) => host_with_port(),
          optional(:enabled) => true | false
        }

  @doc """
  Creates a proxy on the toxiproxy server.

  Raises `ToxiproxyEx.ServerError` if the creation fails.

  ## Examples

  Create a new proxy:
      iex> ToxiproxyEx.create!(upstream: "localhost:3306", name: "test_mysql_master")

  Create a new proxy that listens on a specific port:
      iex> ToxiproxyEx.create!(upstream: "localhost:3306", listen: "localhost:5555", name: "test_mysql_master")

  Create a new proxy that is disabled by default:
      iex> ToxiproxyEx.create!(upstream: "localhost:3306", name: "test_mysql_master", enabled: false)
  """
  @spec create!(
          upstream: host_with_port(),
          name: String.t() | atom(),
          listen: host_with_port() | nil,
          enabled: true | false | nil
        ) :: proxy()
  defdelegate create!(options), to: Proxy, as: :create

  @doc """
  Deletes one or multiple proxies on the toxiproxy server.

  Raises `ToxiproxyEx.ServerError` if the deletion fails.

  ## Examples

  Destroy a single proxy:
      iex> ToxiproxyEx.create!(upstream: "localhost:3456", name: :test_mysql_master)
      iex> proxy = ToxiproxyEx.get!(:test_mysql_master)
      iex> ToxiproxyEx.destroy!(proxy)
      :ok

  Destroy all proxies:
      iex> ToxiproxyEx.create!(upstream: "localhost:3456", name: :test_mysql_master)
      iex> proxies = ToxiproxyEx.all!()
      iex> ToxiproxyEx.destroy!(proxies)
      :ok
  """

  @spec destroy!(proxy() | toxic_collection()) :: :ok
  def destroy!(%Proxy{} = proxy) do
    destroy!(ToxicCollection.new(proxy))
  end

  def destroy!(%ToxicCollection{proxies: proxies}) do
    Enum.each(proxies, &Proxy.destroy/1)
  end

  @doc """
  Retrieves a proxy from the toxiproxy server.

  Raises `ToxiproxyEx.ServerError` if the proxy could not be retrieved.
  Raises `ArgumentError` if the proxy does not exist.

  ## Examples

  Retrievs a proxy:
      iex> ToxiproxyEx.create!(upstream: "localhost:3306", name: "test_mysql_master")
      iex> ToxiproxyEx.get!(:test_mysql_master)
  """
  @spec get!(atom() | String.t()) :: proxy()
  def get!(name) when is_atom(name) or is_binary(name) do
    name = to_string(name)

    case Enum.find(all!().proxies, &(&1.name == name)) do
      nil -> raise ArgumentError, message: "Unknown proxy with name '#{name}'"
      proxy -> proxy
    end
  end

  @doc """
  Retrieves a list of proxies from the toxiproxy server where the name matches the specificed regex.

  Raises `ToxiproxyEx.ServerError` if the list of proxies could not be retrieved.
  Raises `ArgumentError` if no proxy matching the specified regex does exist.

  ## Examples

  Retrievs a proxy:
      iex> ToxiproxyEx.create!(upstream: "localhost:3306", name: "test_mysql_master")
      iex> ToxiproxyEx.create!(upstream: "localhost:3307", name: "test_mysql_follower")
      iex> ToxiproxyEx.create!(upstream: "localhost:3308", name: "test_redis_master")
      iex> ToxiproxyEx.grep!(~r/master/)
  """
  @spec grep!(Regex.t()) :: toxic_collection()
  def grep!(%Regex{} = pattern) do
    case Enum.filter(all!().proxies, &String.match?(&1.name, pattern)) do
      proxies = [_h | _t] -> ToxicCollection.new(proxies)
      [] -> raise ArgumentError, message: "No proxies found for regex '#{pattern}'"
    end
  end

  @doc """
  Retrieves a list of all proxies from the toxiproxy server.

  Raises `ToxiproxyEx.ServerError` if the list of proxies could not be retrieved.

  ## Examples

  Retrievs a proxy:
      iex> ToxiproxyEx.create!(upstream: "localhost:3306", name: "test_mysql_master")
      iex> ToxiproxyEx.create!(upstream: "localhost:3307", name: "test_redis_master")
      iex> ToxiproxyEx.all!()
  """
  @spec all!() :: toxic_collection()
  def all!() do
    Client.request!(:get, "/proxies")
    |> Enum.map(&parse_proxy/1)
    |> ToxicCollection.new()
  end

  defp parse_proxy(
         {_proxy_name,
          %{
            "upstream" => upstream,
            "listen" => listen,
            "name" => name,
            "enabled" => enabled
          }}
       ) do
    %Proxy{upstream: upstream, listen: listen, name: name, enabled: enabled}
  end

  @doc """
  Adds an upstream toxic to the proxy or list of proxies that will be enabled when passed to `ToxiproxyEx.apply!/2`.

  ## Examples

  Add an upstream toxic to a proxy:
      iex> proxy = ToxiproxyEx.create!(upstream: "localhost:3306", name: "test_mysql_master")
      iex> proxies = ToxiproxyEx.upstream(proxy, :latency, latency: 1000)
      iex> ToxiproxyEx.apply!(proxies, fn ->
      ...>  # Do some testing
      ...>  nil
      ...> end)

  Add an upstream toxic to a list of proxies:
      iex> ToxiproxyEx.create!(upstream: "localhost:3306", name: "test_mysql_master")
      iex> ToxiproxyEx.create!(upstream: "localhost:3307", name: "test_mysql_follower")
      iex> proxies = ToxiproxyEx.all!()
      iex> proxies = ToxiproxyEx.upstream(proxies, :latency, latency: 1000)
      iex> ToxiproxyEx.apply!(proxies, fn ->
      ...>  # Do some testing
      ...>  nil
      ...> end)
  """
  @spec upstream(proxy() | toxic_collection(), atom(), []) :: toxic_collection()
  def upstream(proxy_or_collection, type, attrs \\ [])

  def upstream(proxy = %Proxy{}, type, attrs) do
    upstream(ToxicCollection.new(proxy), type, attrs)
  end

  def upstream(%ToxicCollection{proxies: proxies, toxics: toxics}, type, attrs) do
    name = Keyword.get(attrs, :name)
    toxicity = Keyword.get(attrs, :toxicity)

    attrs =
      attrs
      |> Keyword.delete(:name)
      |> Keyword.delete(:toxicity)

    new_toxics =
      Enum.map(proxies, fn proxy ->
        Toxic.new(
          name: name,
          type: type,
          proxy_name: proxy.name,
          stream: :upstream,
          toxicity: toxicity,
          attributes: attrs
        )
      end)

    %ToxicCollection{proxies: proxies, toxics: toxics ++ new_toxics}
  end

  @doc """
  Alias for `ToxiproxyEx.downstream/3`.
  """
  @spec toxic(proxy() | toxic_collection(), atom(), []) :: toxic_collection()
  def toxic(proxy_or_collection, type, attrs \\ []) do
    downstream(proxy_or_collection, type, attrs)
  end

  @doc """
  Alias for `ToxiproxyEx.downstream/3`.
  """
  @spec toxicate(proxy() | toxic_collection(), atom(), []) :: toxic_collection()
  def toxicate(proxy_or_collection, type, attrs \\ []) do
    downstream(proxy_or_collection, type, attrs)
  end

  @doc """
  Adds an downstream toxic to the proxy or list of proxies that will be enabled when passed to `ToxiproxyEx.apply!/2`.

  ## Examples

  Add an downstream toxic to a proxy:
      iex> proxy = ToxiproxyEx.create!(upstream: "localhost:3306", name: "test_mysql_master")
      iex> proxies = ToxiproxyEx.downstream(proxy, :latency, latency: 1000)
      iex> ToxiproxyEx.apply!(proxies, fn ->
      ...>  # Do some testing
      ...>  nil
      ...> end)

  Add an downstream toxic to a list of proxies:
      iex> ToxiproxyEx.create!(upstream: "localhost:3306", name: "test_mysql_master")
      iex> ToxiproxyEx.create!(upstream: "localhost:3307", name: "test_mysql_follower")
      iex> proxies = ToxiproxyEx.all!()
      iex> proxies = ToxiproxyEx.downstream(proxies, :latency, latency: 1000)
      iex> ToxiproxyEx.apply!(proxies, fn ->
      ...>  # Do some testing
      ...>  nil
      ...> end)
  """
  @spec downstream(proxy() | toxic_collection(), atom(), []) :: toxic_collection()
  def downstream(proxy_or_collection, type, attrs \\ [])

  def downstream(proxy = %Proxy{}, type, attrs) do
    downstream(ToxicCollection.new(proxy), type, attrs)
  end

  def downstream(%ToxicCollection{proxies: proxies, toxics: toxics}, type, attrs) do
    name = Keyword.get(attrs, :name)
    toxicity = Keyword.get(attrs, :toxicity)

    attrs =
      attrs
      |> Keyword.delete(:name)
      |> Keyword.delete(:toxicity)

    new_toxics =
      Enum.map(proxies, fn proxy ->
        Toxic.new(
          name: name,
          type: type,
          proxy_name: proxy.name,
          stream: :downstream,
          toxicity: toxicity,
          attributes: attrs
        )
      end)

    %ToxicCollection{proxies: proxies, toxics: toxics ++ new_toxics}
  end

  @doc """
  Applies all toxics previously defined on the list of proxies during the duration of the given function.

  Raises `ToxiproxyEx.ServerError` if the toxics could not be enabled and disabled again on the server.

  ## Examples

  Add toxics and apply them toxic to a single proxy:
      iex> proxy = ToxiproxyEx.create!(upstream: "localhost:3306", name: "test_mysql_master")
      iex> proxies = ToxiproxyEx.downstream(proxy, :slow_close, delay: 100)
      iex> proxies = ToxiproxyEx.downstream(proxies, :latency, jitter: 300)
      iex> ToxiproxyEx.apply!(proxies, fn ->
      ...>  # All calls to mysql master are now slow at responding and closing.
      ...>  nil
      ...> end)

  Add toxics and apply them toxic to a list of proxies:
      iex> ToxiproxyEx.create!(upstream: "localhost:3306", name: "test_mysql_master")
      iex> ToxiproxyEx.create!(upstream: "localhost:3306", name: "test_mysql_follower")
      iex> proxies = ToxiproxyEx.all!()
      iex> proxies = ToxiproxyEx.downstream(proxies, :slow_close, delay: 100)
      iex> proxies = ToxiproxyEx.downstream(proxies, :latency, jitter: 300)
      iex> ToxiproxyEx.apply!(proxies, fn ->
      ...>  # All calls to mysql master and follower are now slow at responding and closing.
      ...>  nil
      ...> end)
  """
  @spec apply!(toxic_collection(), (-> result)) :: result when result: var
  def apply!(%ToxicCollection{toxics: toxics}, fun) when is_function(fun, 0) do
    toxics
    |> Enum.group_by(fn %Toxic{} = toxic -> {toxic.name, toxic.proxy_name} end)
    |> Enum.each(fn
      {_name_and_proxy_name, [toxic, _other_toxic | _rest]} ->
        raise ArgumentError, """
        there are multiple toxics with the name #{inspect(toxic.name)} for proxy \
        #{inspect(toxic.proxy_name)}, please override the default name (<type>_<direction>)\
        """

      {_name_and_proxy_name, [_toxic]} ->
        :ok
    end)

    # We probably don't care about the updated toxics here but we still use
    # rather than the one passed into the function.
    toxics = Enum.map(toxics, &Toxic.create/1)

    try do
      fun.()
    after
      Enum.each(toxics, &Toxic.destroy/1)
    end
  end

  @doc """
  Takes down the proxy or the list of proxies during the duration of the given function.

  Raises `ToxiproxyEx.ServerError` if the proxy or list of proxies could not have been disabled and enabled again on the server.

  ## Examples

  Take down a single proxy:
      iex> proxy = ToxiproxyEx.create!(upstream: "localhost:3306", name: "test_mysql_master")
      iex> ToxiproxyEx.down!(proxy, fn ->
      ...>  # Takes mysql master down.
      ...>  nil
      ...> end)

  Take down a list of proxies:
      iex> ToxiproxyEx.create!(upstream: "localhost:3306", name: "test_mysql_master")
      iex> ToxiproxyEx.create!(upstream: "localhost:3306", name: "test_mysql_follower")
      iex> proxies = ToxiproxyEx.all!()
      iex> ToxiproxyEx.down!(proxies, fn ->
      ...>  # Takes mysql master and follower down.
      ...>  nil
      ...> end)
  """
  @spec down!(toxic_collection() | proxy(), (-> result)) :: result when result: var
  def down!(proxy_or_collection, fun)

  def down!(proxy = %Proxy{}, fun) do
    down!(ToxicCollection.new(proxy), fun)
  end

  def down!(%ToxicCollection{proxies: proxies}, fun) when is_function(fun, 0) do
    Enum.each(proxies, &Proxy.disable/1)

    try do
      fun.()
    after
      Enum.each(proxies, &Proxy.enable/1)
    end
  end

  @doc """
  Re-enables are proxies and disables all toxics on toxiproxy.

  Raises `ToxiproxyEx.ServerError` if the server could not have been reset.

  ## Examples

  Reset toxiproxy:
      iex> ToxiproxyEx.reset!()
      :ok
  """
  @spec reset!() :: :ok
  def reset!() do
    Client.request!(:post, "/reset", %{})
    :ok
  end

  @doc """
  Gets the version of the running toxiproxy server.

  Raises `ToxiproxyEx.ServerError` if the version could not have been fetched from the server.

  ## Examples

  Get running toxiproxy version:
      iex> ToxiproxyEx.version!()
      "2.1.2"
  """
  @spec version!() :: String.t()
  def version!() do
    case Client.request!(:get, "/version") do
      %{"version" => version} -> version
      version -> version
    end
  end

  @doc """
  Creates proxies based on the passed data.
  This is usefull to quickly create multiple proxies based on hardcoded value or values read from external sources such as a config file.

  Nonexisting proxies will be created and existing ones will be updated to match the passed data.

  Raises `ToxiproxyEx.ServerError` if the proxies could not have been created on the server.

  ## Examples

  Creating proxies:
      iex> ToxiproxyEx.populate!([
      ...>  %{name: "test_mysql_master", upstream: "localhost:5765"},
      ...>  %{name: "test_mysql_follower", upstream: "localhost:5766", enabled: false}
      ...> ])
  """
  @spec populate!([proxy_map()]) :: toxic_collection()
  def populate!(proxies) when is_list(proxies) do
    Enum.map(proxies, fn proxy_attrs ->
      name = Map.get(proxy_attrs, :name)
      upstream = Map.get(proxy_attrs, :upstream)
      listen = Map.get(proxy_attrs, :upstream)

      existing = Enum.find(all!().proxies, &(&1.name == name))

      if existing do
        if existing.upstream == upstream && existing.listen == listen do
          existing
        else
          destroy!(existing)

          Keyword.new(proxy_attrs)
          |> create!()
        end
      else
        Keyword.new(proxy_attrs)
        |> create!()
      end
    end)
    |> ToxicCollection.new()
  end
end