verdi setup: improve validation and help string of broker virtual host (#4408)

The help string of the `--broker-virtual-host` option of `verdi setup`
incorrectly said that forward slashes have to be escaped but this is not
true. The code will escape any characters necessary when constructing
the URL to connect to RabbitMQ. On top of that, slashes would fail the
validation outright, even though these are common in virtual hosts. For
example the virtual host always starts with a leading forward slash, but
our validation would reject it. Also the leading slash will be added by
the code and so does not have to be used in the setup phase. The help
string and the documentation now reflect this.

The exacti naming rules for virtual hosts, imposed by RabbitMQ or other
implemenatations of the AMQP protocol, are not fully clear. But instead
of putting an explicit validation on AiiDA's side and running the risk
that we incorrectly reject valid virtual host names, we simply accept
all strings. In any case, any non-default virtual host will have to be
created through RabbitMQ's control interface, which will perform the
validation itself.

Author: sphuber

aiida/cmdline/params/options/__init__.py

@@ -315,10 +315,10 @@ def decorator(command):
 
 BROKER_VIRTUAL_HOST = OverridableOption(
     '--broker-virtual-host',
-    type=types.HostnameType(),
+    type=click.types.StringParamType(),
     default=BROKER_DEFAULTS.virtual_host,
     show_default=True,
-    help='Name of the virtual host for the message broker. Forward slashes need to be encoded'
+    help='Name of the virtual host for the message broker without leading forward slash.'
 )
 
 REPOSITORY_PATH = OverridableOption(

docs/source/intro/installation.rst

@@ -687,7 +687,7 @@ The following parameters can be configured:
 +--------------+---------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------+
 | Port         | ``--broker-port``         | ``5672``      | The port to which the server listens.                                                                                   |
 +--------------+---------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------+
-| Virtual host | ``--broker-virtual-host`` | ``''``        | Optional virtual host. If defined, needs to start with a forward slash.                                                 |
+| Virtual host | ``--broker-virtual-host`` | ``''``        | Optional virtual host. Should not contain the leading forward slash, this will be added automatically by AiiDA.         |
 +--------------+---------------------------+---------------+-------------------------------------------------------------------------------------------------------------------------+
 
 

docs/source/reference/command_line.rst

@@ -500,8 +500,8 @@ Below is a list with all available subcommands.
 
       --broker-host HOSTNAME          Hostname for the message broker.  [default: 127.0.0.1]
       --broker-port INTEGER           Port for the message broker.  [default: 5672]
-      --broker-virtual-host HOSTNAME  Name of the virtual host for the message broker. Forward
-                                      slashes need to be encoded  [default: ]
+      --broker-virtual-host TEXT      Name of the virtual host for the message broker without
+                                      leading forward slash.  [default: ]
 
       --repository DIRECTORY          Absolute path to the file repository.
       --config FILEORURL              Load option values from configuration file in yaml
@@ -638,8 +638,8 @@ Below is a list with all available subcommands.
                                       required]
 
       --broker-port INTEGER           Port for the message broker.  [default: 5672; required]
-      --broker-virtual-host HOSTNAME  Name of the virtual host for the message broker. Forward
-                                      slashes need to be encoded  [default: ; required]
+      --broker-virtual-host TEXT      Name of the virtual host for the message broker without
+                                      leading forward slash.  [default: ; required]
 
       --repository DIRECTORY          Absolute path to the file repository.
       --config FILEORURL              Load option values from configuration file in yaml