add: basic vhost endpoints

Author: rhblind

.gitignore

@@ -20,7 +20,7 @@ erl_crash.dump
 *.ez
 
 # Ignore package tarball (built via "mix hex.build").
-ex_rabbitmqadmin-*.tar
+ex_rabbitmq_admin-*.tar
 
 # Temporary files, for example, from tests.
 /tmp/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Intility AS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,21 +1,31 @@
 # ExRabbitMQAdmin
 
-**TODO: Add description**
+Simple client library for the RabbitMQ [HTTP API](https://www.rabbitmq.com/management.html#http-api),
+built on [Tesla](https://github.com/elixir-tesla/tesla).
 
 ## Installation
 
 If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `ex_rabbitmqadmin` to your list of dependencies in `mix.exs`:
+by adding `ex_rabbitmq_admin` to your list of dependencies in `mix.exs`:
 
 ```elixir
 def deps do
   [
-    {:ex_rabbitmqadmin, "~> 0.1.0"}
+    {:ex_rabbitmq_admin, "~> 0.1.0"}
   ]
 end
 ```
 
 Documentation can be generated with [ExDoc](https://github.com/elixir-lang/ex_doc)
 and published on [HexDocs](https://hexdocs.pm). Once published, the docs can
-be found at <https://hexdocs.pm/ex_rabbitmqadmin>.
+be found at <https://hexdocs.pm/ex_rabbitmq_admin>.
 
+## Contribution
+
+The RabbitMQ HTTP API is available [here](https://rawcdn.githack.com/rabbitmq/rabbitmq-server/v3.11.2/deps/rabbitmq_management/priv/www/api/index.html).
+
+### Running the test suite
+
+```shell
+$ MIX_ENV=test mix coveralls
+```

config/config.exs

@@ -6,7 +6,7 @@ case config_env() do
 
     config :tesla, adapter: {Tesla.Adapter.Hackney, [recv_timeout: 30_000]}
 
-    config :ex_rabbitmqadmin, ExRabbitMQAdmin.Client,
+    config :ex_rabbitmq_admin, ExRabbitMQAdmin.Client,
       base_url: System.get_env("RABBITMQ_HTTP_BASE_URL", "http://localhost:5672"),
       username: "guest",
       password: "guest"

lib/ex_rabbitmq_admin.ex

@@ -0,0 +1,29 @@
+defmodule ExRabbitMQAdmin do
+  @moduledoc """
+  Default module for the RabbitMQ admin client.
+
+  ### Configuration
+
+  Some options, such as e.g. `base_url` are read from the config.
+
+      # config.ex
+      config :ex_rabbitmq_admin, ExRabbitMQAdmin,
+        base_url: "https://rabbitmq.example.com:15672",
+        username: "guest",
+        password: "guest"
+
+
+  ### Examples
+
+  * Create a client, add basic auth by reading default values from config and
+    list all virtual hosts running in the RabbitMQ cluster.
+
+        iex> ExRabbitMQAdmin.client()
+             |> ExRabbitMQAdmin.add_basic_auth_middleware()
+             |> ExRabbitMQAdmin.VHost.list_vhosts()
+        {:ok, %Tesla.Env{status: 200, body: [...]}}
+  """
+
+  use ExRabbitMQAdmin.Client,
+    otp_app: :ex_rabbitmq_admin
+end

lib/ex_rabbitmq_admin/client.ex

@@ -0,0 +1,93 @@
+defmodule ExRabbitMQAdmin.Client do
+  @moduledoc """
+  Macro for creating RabbitMQ HTTP API client.
+
+  ### Configuration
+
+  Some options, such as e.g. `base_url` are read from the config. For each module that
+  uses this macro, add an entry to your `config.exs` as:
+
+      # config.ex
+      config :my_app, MyApp.RabbitClient,
+        base_url: "https://rabbitmq.example.com:15672",
+        username: "guest",
+        password: "guest"
+
+  #### Parameters
+
+  * `otp_app` - Namespace used to look up configuration values such as `base_url` and others.
+
+
+  ### Example
+
+      defmodule MyApp.RabbitClient do
+        use ExRabbitMQAdmin.Client, otp_app: :my_app
+      end
+
+  """
+  defmacro __using__(opts) do
+    {:ok, otp_app} = Keyword.fetch(opts, :otp_app)
+
+    quote location: :keep do
+      @spec client(opts :: Keyword.t()) :: Tesla.Client.t()
+      def client, do: Application.get_env(unquote(otp_app), __MODULE__) |> client()
+
+      def client(opts) do
+        middleware = [
+          {Tesla.Middleware.BaseUrl, client_option(opts, :base_url)},
+          {Tesla.Middleware.Logger, filter_headers: ["authorization"]},
+          {Tesla.Middleware.JSON, engine: Jason}
+        ]
+
+        Tesla.client(middleware)
+      end
+
+      @spec bearer_auth_middleware(client :: Tesla.Client.t(), opts :: Keyword.t()) :: [
+              {Tesla.Middleware.BearerAuth, Keyword.t()}
+            ]
+      def bearer_auth_middleware(client, opts) when is_list(opts) do
+        [
+          {Tesla.Middleware.BearerAuth, token: client_option(opts, :token)}
+          | Tesla.Client.middleware(client)
+        ]
+      end
+
+      def add_bearer_auth_middleware(client, opts),
+        do: bearer_auth_middleware(client, opts) |> Tesla.client()
+
+      @spec basic_auth_middleware(client :: Tesla.Client.t(), opts :: Keyword.t()) ::
+              [{Tesla.Middleware.BasicAuth, Keyword.t()}]
+      def basic_auth_middleware(client, opts) when is_list(opts) do
+        [
+          {Tesla.Middleware.BasicAuth,
+           username: client_option(opts, :username), password: client_option(opts, :password)}
+          | Tesla.Client.middleware(client)
+        ]
+      end
+
+      def basic_auth_middleware(client) do
+        [
+          {Tesla.Middleware.BasicAuth,
+           username: client_option(:username), password: client_option(:password)}
+          | Tesla.Client.middleware(client)
+        ]
+      end
+
+      @spec add_basic_auth_middleware(client :: Tesla.Client.t(), opts :: Keyword.t()) ::
+              Tesla.Client.t()
+      def add_basic_auth_middleware(client, opts) when is_list(opts),
+        do: basic_auth_middleware(client, opts) |> Tesla.client()
+
+      def add_basic_auth_middleware(client), do: basic_auth_middleware(client) |> Tesla.client()
+
+      @spec client_option(opts :: Keyword.t(), atom()) :: any()
+      defp client_option(key) when is_atom(key),
+        do: Application.get_env(unquote(otp_app), __MODULE__) |> client_option(key)
+
+      defp client_option(opts, :base_url), do: Keyword.get(opts, :base_url, "")
+      defp client_option(opts, :username), do: Keyword.get(opts, :username, "")
+      defp client_option(opts, :password), do: Keyword.get(opts, :password, "")
+      defp client_option(opts, :token), do: Keyword.get(opts, :token, "")
+    end
+  end
+end

lib/ex_rabbitmq_admin/vhost.ex

@@ -0,0 +1,129 @@
+defmodule ExRabbitMQAdmin.VHost do
+  @moduledoc """
+  This module contains functions for interacting with RabbitMQ VHosts.
+  """
+
+  @doc """
+  List all virtual hosts running on the RabbitMQ cluster.
+  """
+  @spec list_vhosts(client :: Tesla.Client.t()) :: {:ok, Tesla.Env.t()}
+  def list_vhosts(client), do: client |> Tesla.get("/api/vhosts")
+
+  @doc """
+  List all open open connections in a specific virtual host.
+  Optionally pass pagination parameters to filter connections.
+
+  ### Params
+
+    * `name` - type: `binary`, required: `true`
+    * `params` - type: `map`, reqiured: `false`
+
+        * `page` - type: `non_neg_integer`, required: `false`
+        * `page_size` - type: `non_neg_integer`, required: `false`
+        * `use_regex` - type: `boolean`, required: `false`
+
+        ```
+        %{
+          "page" => 1,
+          "page_size" => 100,
+          "use_regex" => true
+        }
+
+        ```
+  """
+  @spec list_vhost_connections(client :: Tesla.Client.t(), name :: String.t(), params :: map()) ::
+          {:ok, Tesla.Env.t()}
+  def list_vhost_connections(client, name, params \\ %{}) do
+    client |> Tesla.get("/api/vhosts/#{name}/connections", params)
+  end
+
+  @doc """
+  List all open channels for a specific virtual host.
+  Optionally pass pagination parameters to filter channels.
+
+  ### Params
+
+    * `name` - type: `binary`, required: `true`
+    * `params` - type: `map`, reqiured: `false`
+
+        * `page` - type: `non_neg_integer`, required: `false`
+        * `page_size` - type: `non_neg_integer`, required: `false`
+        * `use_regex` - type: `boolean`, required: `false`
+
+        ```
+        %{
+          "page" => 1,
+          "page_size" => 100,
+          "use_regex" => true
+        }
+
+        ```
+  """
+  @spec list_vhost_channels(client :: Tesla.Client.t(), name :: String.t(), params :: map()) ::
+          {:ok, Tesla.Env.t()}
+  def list_vhost_channels(client, name, params \\ %{}) do
+    client |> Tesla.get("/api/vhosts/#{name}/channels", params)
+  end
+
+  @doc """
+  List all permissions for a specific virtual host.
+  """
+  @spec list_vhost_permissions(client :: Tesla.Client.t(), name :: String.t()) ::
+          {:ok, Tesla.Env.t()}
+  def list_vhost_permissions(client, name) do
+    client |> Tesla.get("/api/vhosts/#{name}/permissions")
+  end
+
+  @doc """
+  List all topic permissions for a specific virtual host.
+  """
+  @spec list_vhost_topic_permissions(client :: Tesla.Client.t(), name :: String.t()) ::
+          {:ok, Tesla.Env.t()}
+  def list_vhost_topic_permissions(client, name) do
+    client |> Tesla.get("/api/vhosts/#{name}/topic-permissions")
+  end
+
+  @doc """
+  Get an individual virtual host by name.
+  """
+  @spec get_vhost(client :: Telsa.Client.t(), name :: String.t()) :: {:ok, Tesla.Env.t()}
+  def get_vhost(client, name) when is_binary(name), do: client |> Tesla.get("/api/vhosts/#{name}")
+
+  @doc """
+  Create a new virtual host with given name.
+
+  ### Params
+
+    * `params` - type: `map`
+
+      * `name` - type: `binary`, required: `true`
+      * `description` - type: `binary`, required: `false`
+      * `tags` - type: `binary`, required: `false`. Comma-separated list of tags to be set on the virtual host
+
+      ```
+      %{
+        "name" => "accounting",
+        "description" => "this vhost is for accounting messages",
+        "tags" => "finance,production"
+      }
+      ```
+  """
+  @spec put_vhost(client :: Telsa.Client.t(), params :: map) :: {:ok, Tesla.Env.t()}
+  def put_vhost(client, %{"name" => name} = params),
+    do: client |> Tesla.put("/api/vhosts/#{name}", params)
+
+  @doc """
+  Delete a specific virtual host by name.
+  """
+  @spec delete_vhost(client :: Tesla.Client.t(), name :: String.t()) :: {:ok, Tesla.Env.t()}
+  def delete_vhost(client, name), do: client |> Tesla.delete("/api/vhosts/#{name}")
+
+  @doc """
+  Start a specific virtual host on given node.
+  """
+  @spec start_vhost(client :: Tesla.Client.t(), name :: String.t(), node :: String.t()) ::
+          {:ok, Tesla.Env.t()}
+  def start_vhost(client, name, node) do
+    client |> Tesla.post("/api/vhosts/#{name}/start/#{node}")
+  end
+end