rabbitmq / rabbitmq-cli Goto Github PK

View Code? Open in Web Editor NEW

104.0 33.0 34.0 13.83 MB

Command line tools for RabbitMQ

License: Other

Elixir 97.95% Makefile 2.05%

rabbitmq cli elixir

rabbitmq-cli's Introduction

RabbitMQ CLI Tools

This was migrated to https://github.com/rabbitmq/rabbitmq-server

This repository has been moved to the main unified RabbitMQ "monorepo", including all open issues. You can find the source under /deps/rabbitmq_cli. All issues have been transferred.

Overview

This repository contains RabbitMQ CLI tools (rabbitmqctl and others).

This generation of CLI tools first shipped with RabbitMQ 3.7.0.

Goals

Team RabbitMQ wanted a set of tools that

Was extensible from/with plugins
Supported pluggable output formats (in particular machine-friendly ones)
Had good test coverage
Wasn't as coupled to the server repository
Could be used as a low risk vehicle for Elixir evaluation

Supported RabbitMQ Versions

Long lived branches in this repository track the same branch in RabbitMQ core and related repositories. So master tracks master in rabbitmq-server, v3.7.x tracks branch v3.7.x in rabbitmq-server and so on.

Please use the version of CLI tools that come with the RabbitMQ distribution version installed.

Building

Requirements

Building this project requires

Erlang/OTP 21.3 (or later)
Elixir 1.10.0 (or later).

Command line tools depend on rabbitmq-common. Dependencies are being resolved by erlang.mk

Building Standalone Executables

This repo produces a rabbitmqctl executable which can be used as different tools (rabbitmq-plugins, rabbitmq-diagnostics, rabbitmq-queues, rabbitmq-streams, rabbitmq-upgrade) by copying or symlinking it with different names. Depending on the name, a different set of commands will be loaded and available, including for --help.

To generate the executable, run

make

Usage

`rabbitmqctl`

See rabbitmqctl help and rabbitmqctl man page for details.

`rabbitmq-plugins`

See rabbitmq-plugins help and rabbitmq-plugins man page for details.

`rabbitmq-diagnostics`

See rabbitmq-diagnostics help and rabbitmq-diagnostics man page.

Testing

See CONTRIBUTING.md.

Developing

Adding a New Command

Conventions

RabbitMQ CLI tools use module name conventions to match the command-line actions (commands) to modules. The convention is outlined in the CommandBehaviour module.

Command Module Interface

Each command module must implement the RabbitMQ.CLI.CommandBehaviour behaviour, which includes the following functions:

validate(args, opts), which returns either :ok or a tuple of {:validation_failure, failure_detail} where failure detail is typically one of: :too_many_args, :not_enough_args or {:bad_argument, String.t}.
merge_defaults(args, opts), which is used to return updated arguments and/or options.
run(args, opts), where the actual command is implemented. Here, args is a list of command-specific parameters and opts is a Map containing option flags.
usage, which returns a string describing the command, its arguments and its optional flags.
banner(args, opts), which returns a string to be printed before the command output.

There are also a number of optional callbacks:

switches, which returns command specific switches.
aliases, which returns a list of command aliases (if any).
formatter: what output formatter should be used by default.
usage_additional: extra values appended to the usage output to provide additional command-specific documentation.
scopes: what scopes this command appears in. Scopes associate tools (e.g. rabbitmqctl, rabbitmq-diagnostics, rabbitmq-queues, rabbitmq-streams) with commands.
distribution: control erlang distribution. Can be :cli (default), :none or {:fun, fun}

Tutorial

We have a tutorial that demonstrates how to add a CLI command that deletes a queue.

Examples

See lib/rabbitmq/cli/ctl/commands/status_command.ex and test/status_command_test.exs for minimalistic but not entirely trivial examples.

Copyright and License

The project is licensed under the MPL, the same license as RabbitMQ.

rabbitmq-cli's People

Contributors

Stargazers

Watchers

rabbitmq-cli's Issues

Implement plugin management commands

Implement rabbitmq-plugins commands (in RabbitMQ.CLI.Plugins namespace)

Start rabbitmqctl nodes with unique name

Currently it's not possible to run two rabbitmqctl instances at the same time (e.g. sync_queue and another one to test cancel_sync_queue) because all instances use the same name.

This issue is not as trivial as it may seem and it took a few iterations in the current rabbitmqctl, see rabbitmq/rabbitmq-server#549 for the most recent one.

Create generic error handler

Currently the main module is vulnerable to unusual error returns (e.g. :error_string instead of :error). This could be dealt with via an error parser that checks the output and runs a simple conversion on any returns it doesn't understand: ```{:strange_code, } -> {:error, {:strange_code, }}`. Many commands already follow this format already, so the CLI knows how to handle it.

Introduce a rate control flag to rabbitmqctl (for list_* commands)

Following the implemention of #62, there could be need to introduce some level of control to the rate at which information is returned and displayed when rabbitmqctl list_* commands are executed.

For example during troubleshooting, controlled monitoring and inspection of a node's metadata like queues and bindings in real time, while the node is subject to other factors like queue declarations, publishes, e.t.c.

list_bindings throw FunctionClauseError when no vhost specificed

** (FunctionClauseError) no function clause matching in ListBindingsCommand.banner/2
    (rabbitmqctl) lib/list_bindings_command.ex:66: ListBindingsCommand.banner(["source_name", "source_kind", "destination_name", "destination_kind", "routing_key", "arguments"], %{node: :rabbit@snowman, timeout: :infinity, vhost: "/"})
    (rabbitmqctl) lib/rabbitmqctl.ex:79: RabbitMQCtl.print_banner/3
    (rabbitmqctl) lib/rabbitmqctl.ex:63: anonymous fn/4 in RabbitMQCtl.run_command/2
    (rabbitmqctl) lib/rabbitmqctl.ex:32: RabbitMQCtl.main/1
    (elixir) lib/kernel/cli.ex:76: anonymous fn/3 in Kernel.CLI.exec_fun/2```

Fill in usage details

print_usage is currently just a stub.

Non default vhost is overriden in merge_defaults

merge_defaults in most commands is implemented like Map.merge(opts, default_opts), which always rewrites opts with default_opts making impossible to set custom vhost or other params.

There should be tests for merge_defaults.

Example test:

test "merge_defaults: default vhost is '/'" do
  assert @command.merge_defaults([], %{}) == {[], %{vhost: "/"}}
  assert @command.merge_defaults([], %{vhost: "non_default"}) == {[], %{vhost: "non_default"}}
end

Scale the units displayed in rabbitmqctl status

A lot of the outputs in rabbitmqctl status are currently given in bytes, kilobytes or microseconds. Applying some scaling would make them more human-readable.

Refactor RabbitMQCtl to evaluate command strings

The Elixir.Code module makes it fairly easy to generate and evaluate strings as function calls. If we use this in RabbitMQCtl.main/1, we can just define one module per subcommand (e.g., EnvironmentCommand for rabbitmqctl env) instead of making one handler in main for each subcommand. As long as we're consistent with the structure of these modules, we can do this fairly simply.

Support machine-friendly output formats

Our CLI tools should be able to output multiple formats for both humans and machines consumption.

The simplest use case is the combination with Unix commands, such as cut(1) or awk(1). Lists and tables should formatted with easy integration with those tools in mind.

A more advanced example is what is done with libxo: it is used by standard Unix tools to format XML, JSON or HTML, in addition to the expected human-readable output.

Finally, on Windows, PowerShell offers commands the possibility to exchange "objects", skipping parsing entirely if I understand correctly. I have no idea how it works but it seems powerful.

Runtime error when first command-line argument is an invalid option

./rabbitmqctl --nope foo clear_permissions -q foo 
Error: invalid options for this command.
Given:
    --nope foo clear_permissions -q foo
** (SyntaxError) nofile:1: syntax error before: '.'
    (elixir) lib/code.ex:168: Code.eval_string/3
    (rabbitmqctl) lib/rabbitmqctl.ex:65: RabbitMQCtl.command_usage/1
    (rabbitmqctl) lib/rabbitmqctl.ex:112: RabbitMQCtl.print_standard_messages/2
    (rabbitmqctl) lib/rabbitmqctl.ex:33: RabbitMQCtl.main/1
    (elixir) lib/kernel/cli.ex:76: anonymous fn/3 in Kernel.CLI.exec_fun/2

This should just fail and print an error message.

Rename param option to vhost

Currently the -p option is called param. Since it's only used for vhost name, it shoud be named vhost

Implement eval command

Implement rabbitmqctl broker display commands

Implement the following commands:

list_queues
list_exchanges
list_bindings
list_connections
list_channels
list_consumers

Show usage for selected command

Add option to show usage for specific command only.
Show node and timeout argument usage in specific command usages.

implement report command

Fix flaky list_users spec

The spec for the list_users command intermittently fails with the following message:

  1) test On a successful query, return an array of lists of tuples (ListUsersCommandTest)
     test/list_users_command_test.exs:55
     Expected truthy, got false
     code: Enum.all?(matches_found, fn user -> Enum.find(context[:std_result], fn found -> found == user end) end)
     stacktrace:
       test/list_users_command_test.exs:59: anonymous fn/1 in ListUsersCommandTest.test On a successful query, return an array of lists of tuples/1
       (ex_unit) lib/ex_unit/capture_io.ex:146: ExUnit.CaptureIO.do_capture_io/2
       (ex_unit) lib/ex_unit/capture_io.ex:119: ExUnit.CaptureIO.do_capture_io/3
       test/list_users_command_test.exs:56

..

  2) test sufficiently long timeouts don't interfere with results (ListUsersCommandTest)
     test/list_users_command_test.exs:72
     Expected truthy, got false
     code: Enum.all?(matches_found, fn user -> Enum.find(context[:std_result], fn found -> found == user end) end)
     stacktrace:
       test/list_users_command_test.exs:77: anonymous fn/1 in ListUsersCommandTest.test sufficiently long timeouts don't interfere with results/1
       (ex_unit) lib/ex_unit/capture_io.ex:146: ExUnit.CaptureIO.do_capture_io/2
       (ex_unit) lib/ex_unit/capture_io.ex:119: ExUnit.CaptureIO.do_capture_io/3
       test/list_users_command_test.exs:74

Implement set_cluster_name command

command aliasing via an .ini file

A request from @dumbbell, this would allow us to set command aliases using a configuration file. Useful if we want to hand people some code for debugging purposes, but don't want them to have to use eval.

`rabbitmqctl forget_cluster_mode --offline` is missing lager_config

RABBITMQ_HOME="/path/to/umbrella.git/deps/rabbit/" RABBITMQ_MNESIA_DIR="/var/folders/6v/nzn6gr5d6k31r39x57fddtpm0000gp/T//rabbitmq-test-instances/rabbit/mnesia/rabbit" ./rabbitmqctl forget_cluster_node -n rabbit@mercurio hare@mercurio --offline
"Removing node hare@mercurio from the cluster"
  * Impersonating node: rabbit@mercurio...
 done
  * Mnesia directory: /var/folders/6v/nzn6gr5d6k31r39x57fddtpm0000gp/T/rabbitmq-test-instances/rabbit/mnesia/rabbit...

08:34:49.359 [info]  Application mnesia exited: :stopped
** (UndefinedFunctionError) function :lager_config.get/2 is undefined (module :lager_config is not available)
    :lager_config.get({:rabbit_log_lager_event, :loglevel}, {0, []})
    (rabbit) src/rabbit_mnesia.erl:308: :rabbit_mnesia.forget_cluster_node/2
    (rabbit) src/rabbit_mnesia.erl:333: :rabbit_mnesia.remove_node_offline_node/1
    (rabbitmqctl) lib/rabbitmqctl.ex:95: anonymous fn/4 in RabbitMQCtl.run_command/2
    (rabbitmqctl) lib/rabbitmqctl.ex:49: RabbitMQCtl.main/1
    (elixir) lib/kernel/cli.ex:76: anonymous fn/3 in Kernel.CLI.exec_fun/2

Improve integration testing for rabbitmqctl

We've been having a lot of command modules pass their tests, but crash when you try to run them from a compiled CLI. This means we need more in-depth integration testing.

Ideally the solution here will respect the goal of self-contained command code and testing, but with integration tests there may not be a clean way.

implement wait command

refactor command validation and run workflow

implement close_connection command

MVP for rabbitmqctl status

Fill in the functionality for the rabbitmqctl status command as a way to drive out some program structure.

rabbitmq-cli autocomplete

A request from @hairyhum, this would be a bash-level auto-complete feature for the basic rabbitmqctl commands.

Docker container for testing

AS A RabbitMQ developer
I WANT the CLI tests to run in a Docker container
SO THAT I don't have to install Elixir when I'm not working on the CLI

NOTE: This may be very slow relative to the actual tests. We may ultimately want a flag in there to let you run tests locally if you have Elixir installed.

Command specific error printing.

Some commands have specific error messages returned from run, which is not handled properly by rabbitmqctl module.
This messages should be handled by function in command module. Something like report_error or report_output.

Update README to include new callbacks

README section for adding commands no longer corresponds with command behaviour since #45 have been merged. Needs to be updated.

Parallelized item listing

Now that rabbitmq/rabbitmq-server#683 is merged, we should port the changes to this project.

Implement rotate_logs command

Implement stop_app and start_app commands

From a testing perspective it makes sense to tackle them together.

Namespace all modules under RabbitMQ.CLI

Currently we use module names such as Parser (top-level). This repository is meant to have multiple tools and inevitably a small shared library they will use. We should namespace all modules under RabbitMQ.CLI, e.g. RabbitMQ.CLI.RabbitMQCtl, RabbitMQ.CLI.Distribution, RabbitMQ.CLI.RabbitMQCtl.Parser and so on.

Implement the node_health_check command

Test suite assumes a single vhost

I have 2 vhosts in the RabbitMQ node I run mix test against and it looks like some tests assume there's a single vhost:

  9) test valid user returns a list of permissions (ListUserPermissionsCommandTest)
     test/list_user_permissions_command_test.exs:78
     Assertion with == failed
     code: ListUserPermissionsCommand.list_user_permissions([context[:username]], context[:opts]) == context[:result]
     lhs:  [[vhost: "bunny_testbed", configure: ".*", write: ".*", read: ".*"], [vhost: "/", configure: ".*", write: ".*", read: ".*"]]
     rhs:  [[vhost: "/", configure: ".*", write: ".*", read: ".*"]]
     stacktrace:
       test/list_user_permissions_command_test.exs:79



 10) test long user-defined timeout doesn't interfere with operation (ListUserPermissionsCommandTest)
     test/list_user_permissions_command_test.exs:100
     Assertion with == failed
     code: ListUserPermissionsCommand.list_user_permissions([context[:username]], context[:opts]) == context[:result]
     lhs:  [[vhost: "bunny_testbed", configure: ".*", write: ".*", read: ".*"], [vhost: "/", configure: ".*", write: ".*", read: ".*"]]
     rhs:  [[vhost: "/", configure: ".*", write: ".*", read: ".*"]]
     stacktrace:
       test/list_user_permissions_command_test.exs:101

Implement sync_queue command

Command-specific usage displays

Currently, you get the full usage message whenever you use an invalid command string, even if it's a recognized command with the wrong number of arguments. We already define a usage string in each command module; it shouldn't be too hard to create a more targeted usage message for errors generated by the wrong number of arguments.

Implement reset and force_reset commands

Stable branch bump.

Stable branch is way behind master. Maybe it's time to make it up-to-date and start merging there.
We are going to need separate master soon, since there will be changes in reporting API

clear_permissions command info message is not suppressed by --quiet

The -q flag is does not currently suppress the info message for the clear_permissions command:

./rabbitmqctl clear_permissions sandwich -q
Clearing permissions for user "sandwich" in vhost "/" ...
:ok

Consider starting a node in the background as part of the test suite setup

The CLI tests currently require a RabbitMQ server to be started separately; let's start a server as part of the test suite.

Specify possible switches in command modules

Option switches for parsing command line arguments are provided in parser module.
Commands can be able to add their own command line options, so they should be added to switches when parsing arguments.

Implement stop command

Implement rabbitmqctl parameter management commands