1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
# RabbitMQ CLI Tools
This is a next generation implementation of the [rabbitmqctl](https://www.rabbitmq.com/man/rabbitmqctl.1.man.html) and
other RabbitMQ CLI tools that will ship in RabbitMQ `3.7.0`.
This implementation is still a WIP. For production use, go
with the `rabbitmqctl` distributed with the `rabbitmq-server` repo.
## 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](elixir-lang.org) evaluation
## Supported RabbitMQ Versions
This version of CLI tools targets RabbitMQ master (future `3.7.0`). Some operations (for example, the `list_*` ones)
will not work with earlier server releases.
## Building
### Requirements
Building this project requires Elixir 1.3.1 or greater.
Command line tools depend on [rabbitmq-common](https://github.com/rabbitmq/rabbitmq-common). This library is included as a dependency in the `mix.exs` file, though, so the `mix deps.*` commands in the build process below will pull it in.
### Building Standalone Executables
`rabbitmqctl` is the only executable provided at the moment. To generate a runnable version,
run the following:
```
make
```
## Using
### `rabbitmqctl`
`rabbitmqctl [-n node] [-t timeout] [-q] {command} [command options...]`
See the [rabbitmqctl man page](https://www.rabbitmq.com/man/rabbitmqctl.1.man.html) for a full list of options.
## Testing
Assuming you have:
* installed [Elixir](http://elixir-lang.org/install.html)
* have a local running RabbitMQ node with the `rabbitmq-federation` plugin enabled (for parameter management testing), e.g. `make run-broker PLUGINS='rabbitmq_federation rabbitmq_stomp'` from a server repository clone
you can simply run `mix test` within the project root directory.
NOTE: You may see the following message several times:
```
warning: variable context is unused
```
This is nothing to be alarmed about; we're currently using `setup context` functions in Mix to start a new distributed node and connect it to the RabbitMQ server. It complains because we don't actually use the context dictionary, but it's fine otherwise.
## 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.
* `flags`, which returns command-specific option flags as a list of atoms.
* `banner(args, opts)`, which returns a string to be printed before the command output.
* `switches`, which returns command specific switches.
<br>
For example, to add a new command `rabbitmqctl egg_salad`:
1. Create a new test file `test/egg_salad_command_test.exs`.
2. In your new test file, define a module `RabbitMQ.CLI.Ctl.Commands.EggSaladCommandTest` that
runs tests against command behaviour functions, e.g. `EggSaladCommand.run`, `EggSaladCommand.validate` etc.
3. Create a new source file `test/egg_salad_command.exs`.
4. Implement the all the `RabbitMQ.CLI.CommandBehaviour` functions in the new module.
See `lib/rabbitmq/cli/ctl/commands/status_command.ex` and `test/status_command_test.exs` for simple
examples.
## Copyright and License
The project is [licensed under the MPL](LICENSE-MPL-RabbitMQ), the same license
as RabbitMQ.
(c) Pivotal Software, Inc, 2016-Current.
|
