Rename nats-servers to choria-brokers with port defaulting

Rename nats-servers and nats-connection-timeout to match Choria's
user-facing terminology. CLI flags become --choria-brokers and
--choria-broker-timeout. Internal transport config keys use the
bare forms (brokers, broker-timeout) consistent with all other
choria options.

The CLI parser splits comma-separated broker lists into arrays,
matching the --targets pattern. When a broker address omits the
port, default to 4222.

Also replace [x].flatten with Array(x) in client.rb for clarity,
and add CLI parser tests for the new choria flags.

Signed-off-by: nmburgan <13688219+nmburgan@users.noreply.github.com>

Author: nmburgan

documentation/choria-transport.md

@@ -51,7 +51,7 @@ targets:
     config:
       choria:
         collective: production
-        nats-servers:
+        brokers:
           - broker1:4222
           - broker2:4222
 ```
@@ -96,8 +96,8 @@ targets:
 | `host` | | String | (from URI) | Target's Choria identity (FQDN). Overrides the hostname from the URI. |
 | `interpreters` | | Hash | (none) | File extension to interpreter mapping (e.g., `{".rb": "/usr/bin/ruby"}`). |
 | `mcollective-certname` | `--choria-mcollective-certname` | String | (auto) | Override the MCollective certname for Choria client identity. See [Non-root certname](#non-root-certname) below. |
-| `nats-connection-timeout` | `--nats-connection-timeout` | Integer | `30` | Seconds to wait for the TCP connection to the NATS broker. |
-| `nats-servers` | `--nats-servers` | String or Array | (from config file) | NATS broker addresses in `host:port` format (comma-separated for multiple). Do not use the `nats://` prefix. Multiple servers provide failover if a broker is unavailable. Overrides the config file. |
+| `broker-timeout` | `--choria-broker-timeout` | Integer | `30` | Seconds to wait for the TCP connection to a Choria broker. |
+| `brokers` | `--choria-brokers` | String or Array | (auto-discovered) | Choria broker addresses in `host` or `host:port` format (comma-separated for multiple). Port defaults to 4222 if omitted. Do not use the `nats://` prefix. When not provided, the Choria client checks the config file, then SRV records, then falls back to `puppet:4222`. Multiple servers provide failover. |
 | `puppet-environment` | `--choria-puppet-environment` | String | `production` | Puppet environment for bolt_tasks file URIs. |
 | `rpc-timeout` | `--choria-rpc-timeout` | Integer | `30` | Seconds to wait for replies to individual RPC calls. |
 | `ssl-ca` | `--choria-ssl-ca` | String | (from config file) | CA certificate path for TLS. |
@@ -114,14 +114,14 @@ wins. For ad-hoc targets specified via `--targets` that aren't defined in an
 inventory file, CLI flags take full effect.
 
 For options that have corresponding values in the Choria config file
-(`nats-servers`, `ssl-ca`/`ssl-cert`/`ssl-key`, and `collective`), the full
+(`brokers`, `ssl-ca`/`ssl-cert`/`ssl-key`, and `collective`), the full
 precedence from lowest to highest is: Choria config file < CLI flags <
 inventory. All other options use OpenBolt-level defaults and are not affected by
 the Choria config file.
 
 **Timeout hierarchy:** Three levels of timeout control different things:
-- `nats-connection-timeout` (30s): How long to wait for the initial TCP
-  connection to the NATS broker
+- `broker-timeout` (30s): How long to wait for the initial TCP
+  connection to a Choria broker
 - `rpc-timeout` (30s): How long to wait for replies to each individual RPC
   call (discovery, status checks, etc.)
 - `command-timeout` (60s) / `task-timeout` (300s): How long to wait for the

lib/bolt/bolt_option_parser.rb

@@ -16,8 +16,8 @@ class BoltOptionParser < OptionParser
                 choria: %w[choria-config-file choria-mcollective-certname
                            choria-ssl-ca choria-ssl-cert choria-ssl-key
                            choria-collective choria-puppet-environment choria-rpc-timeout
-                           choria-task-timeout choria-command-timeout nats-servers
-                           nats-connection-timeout],
+                           choria-task-timeout choria-command-timeout choria-brokers
+                           choria-broker-timeout],
                 display: %w[format color verbose trace stream],
                 global: %w[help version log-level clear-cache] }.freeze
 
@@ -1149,13 +1149,13 @@ def initialize(options)
              'Seconds to wait for commands and scripts to complete (default: 60).') do |timeout|
         @options[:'command-timeout'] = timeout
       end
-      define('--nats-servers SERVERS',
-             'NATS broker addresses in host:port format (comma-separated for multiple). Do not use the nats:// prefix.') do |servers|
-        @options[:'nats-servers'] = servers
+      define('--choria-brokers BROKERS',
+             'Choria broker addresses in host or host:port format (comma-separated). Port defaults to 4222 if omitted.') do |brokers|
+        @options[:brokers] = brokers.split(',')
       end
-      define('--nats-connection-timeout SECONDS', Integer,
-             'Seconds to wait for the TCP connection to the NATS broker (default: 30).') do |timeout|
-        @options[:'nats-connection-timeout'] = timeout
+      define('--choria-broker-timeout SECONDS', Integer,
+             'Seconds to wait for the TCP connection to a Choria broker (default: 30).') do |timeout|
+        @options[:'broker-timeout'] = timeout
       end
 
       separator "\n#{self.class.colorize(:cyan, 'Module options')}"

lib/bolt/config/transport/choria.rb

@@ -15,8 +15,8 @@ class Choria < Base
           host
           interpreters
           mcollective-certname
-          nats-connection-timeout
-          nats-servers
+          broker-timeout
+          brokers
           puppet-environment
           rpc-timeout
           ssl-ca
@@ -30,7 +30,7 @@ class Choria < Base
         DEFAULTS = {
           'cleanup' => true,
           'command-timeout' => 60,
-          'nats-connection-timeout' => 30,
+          'broker-timeout' => 30,
           'puppet-environment' => 'production',
           'rpc-timeout' => 30,
           'task-timeout' => 300,

lib/bolt/config/transport/options.rb

@@ -81,9 +81,9 @@ module Options
             _plugin: true,
             _example: "/etc/choria/client.conf"
           },
-          "nats-connection-timeout" => {
+          "broker-timeout" => {
             type: Integer,
-            description: "How long to wait in seconds for the initial TCP connection to the NATS broker. " \
+            description: "How long to wait in seconds for the initial TCP connection to a Choria broker. " \
                          "If the connection cannot be made within this time, the operation fails.",
             minimum: 1,
             _plugin: true,
@@ -284,11 +284,12 @@ module Options
             _plugin: true,
             _example: "primary.example.com"
           },
-          "nats-servers" => {
+          "brokers" => {
             type: [String, Array],
-            description: "One or more NATS server addresses in host:port format for the Choria transport. " \
-                         "Do not use the nats:// prefix. Overrides the middleware hosts from the Choria " \
-                         "client configuration file. Can be a single string or an array.",
+            description: "One or more Choria broker addresses in host or host:port format. " \
+                         "Port defaults to 4222 if omitted. Do not use the nats:// prefix. " \
+                         "Overrides the middleware hosts from the Choria client configuration file. " \
+                         "Can be a single string or an array.",
             items: {
               type: String
             },

lib/bolt/transport/choria/client.rb

@@ -73,10 +73,10 @@ def configure_client(target)
             logger.debug { "MCOLLECTIVE_CERTNAME set to #{opts['mcollective-certname']}" }
           end
 
-          if opts['nats-servers']
-            servers = [opts['nats-servers']].flatten
-            config.pluginconf['choria.middleware_hosts'] = servers.join(',')
-            logger.debug { "NATS servers overridden: #{servers.join(', ')}" }
+          if opts['brokers']
+            brokers = Array(opts['brokers']).map { |broker| broker.include?(':') ? broker : "#{broker}:4222" }
+            config.pluginconf['choria.middleware_hosts'] = brokers.join(',')
+            logger.debug { "Choria brokers overridden: #{brokers.join(', ')}" }
           end
 
           if opts['ssl-ca'] && opts['ssl-cert'] && opts['ssl-key']
@@ -117,11 +117,11 @@ def configure_client(target)
       # @param timeout [Numeric] RPC call timeout in seconds
       # @return [MCollective::RPC::Client] Configured client with direct addressing enabled
       def create_rpc_client(agent_name, targets, timeout)
-        targets = [targets].flatten
+        targets = Array(targets)
         options = MCollective::Util.default_options
         options[:timeout] = timeout
         options[:verbose] = false
-        options[:connection_timeout] = targets.first.options['nats-connection-timeout']
+        options[:connection_timeout] = targets.first.options['broker-timeout']
 
         collective = collective_for(targets.first)
         options[:collective] = collective if collective
@@ -169,7 +169,7 @@ def create_rpc_client(agent_name, targets, timeout)
       #     Includes all targets that responded (both :responded and :errors).
       #     Not populated when rpc_failed is true (no individual responses).
       def rpc_request(agent, targets, context)
-        targets = [targets].flatten
+        targets = Array(targets)
         rpc_results = @rpc_mutex.synchronize do
           rpc_timeout = targets.first.options['rpc-timeout']
           client = create_rpc_client(agent, targets, rpc_timeout)

schemas/bolt-defaults.schema.json

@@ -518,90 +518,90 @@
         {
           "type": "object",
           "properties": {
-            "cleanup": {
+            "broker-timeout": {
               "oneOf": [
                 {
-                  "$ref": "#/transport_definitions/cleanup"
+                  "$ref": "#/transport_definitions/broker-timeout"
                 },
                 {
                   "$ref": "#/definitions/_plugin"
                 }
               ]
             },
-            "collective": {
+            "brokers": {
               "oneOf": [
                 {
-                  "$ref": "#/transport_definitions/collective"
+                  "$ref": "#/transport_definitions/brokers"
                 },
                 {
                   "$ref": "#/definitions/_plugin"
                 }
               ]
             },
-            "command-timeout": {
+            "cleanup": {
               "oneOf": [
                 {
-                  "$ref": "#/transport_definitions/command-timeout"
+                  "$ref": "#/transport_definitions/cleanup"
                 },
                 {
                   "$ref": "#/definitions/_plugin"
                 }
               ]
             },
-            "config-file": {
+            "collective": {
               "oneOf": [
                 {
-                  "$ref": "#/transport_definitions/config-file"
+                  "$ref": "#/transport_definitions/collective"
                 },
                 {
                   "$ref": "#/definitions/_plugin"
                 }
               ]
             },
-            "host": {
+            "command-timeout": {
               "oneOf": [
                 {
-                  "$ref": "#/transport_definitions/host"
+                  "$ref": "#/transport_definitions/command-timeout"
                 },
                 {
                   "$ref": "#/definitions/_plugin"
                 }
               ]
             },
-            "interpreters": {
+            "config-file": {
               "oneOf": [
                 {
-                  "$ref": "#/transport_definitions/interpreters"
+                  "$ref": "#/transport_definitions/config-file"
                 },
                 {
                   "$ref": "#/definitions/_plugin"
                 }
               ]
             },
-            "mcollective-certname": {
+            "host": {
               "oneOf": [
                 {
-                  "$ref": "#/transport_definitions/mcollective-certname"
+                  "$ref": "#/transport_definitions/host"
                 },
                 {
                   "$ref": "#/definitions/_plugin"
                 }
               ]
             },
-            "nats-connection-timeout": {
+            "interpreters": {
               "oneOf": [
                 {
-                  "$ref": "#/transport_definitions/nats-connection-timeout"
+                  "$ref": "#/transport_definitions/interpreters"
                 },
                 {
                   "$ref": "#/definitions/_plugin"
                 }
               ]
             },
-            "nats-servers": {
+            "mcollective-certname": {
               "oneOf": [
                 {
-                  "$ref": "#/transport_definitions/nats-servers"
+                  "$ref": "#/transport_definitions/mcollective-certname"
                 },
                 {
                   "$ref": "#/definitions/_plugin"
@@ -1862,8 +1862,8 @@
         }
       ]
     },
-    "nats-connection-timeout": {
-      "description": "How long to wait in seconds for the initial TCP connection to the NATS broker. If the connection cannot be made within this time, the operation fails.",
+    "broker-timeout": {
+      "description": "How long to wait in seconds for the initial TCP connection to a Choria broker. If the connection cannot be made within this time, the operation fails.",
       "oneOf": [
         {
           "type": "integer",
@@ -2166,8 +2166,8 @@
         }
       ]
     },
-    "nats-servers": {
-      "description": "One or more NATS server addresses in host:port format for the Choria transport. Do not use the nats:// prefix. Overrides the middleware hosts from the Choria client configuration file. Can be a single string or an array.",
+    "brokers": {
+      "description": "One or more Choria broker addresses in host or host:port format. Port defaults to 4222 if omitted. Do not use the nats:// prefix. Overrides the middleware hosts from the Choria client configuration file. Can be a single string or an array.",
       "oneOf": [
         {
           "type": [

schemas/bolt-inventory.schema.json

@@ -63,6 +63,42 @@
                 {
                   "type": "object",
                   "properties": {
+                    "broker-timeout": {
+                      "description": "How long to wait in seconds for the initial TCP connection to a Choria broker. If the connection cannot be made within this time, the operation fails.",
+                      "oneOf": [
+                        {
+                          "type": "integer",
+                          "minimum": 1
+                        },
+                        {
+                          "$ref": "#/definitions/_plugin"
+                        }
+                      ]
+                    },
+                    "brokers": {
+                      "description": "One or more Choria broker addresses in host or host:port format. Port defaults to 4222 if omitted. Do not use the nats:// prefix. Overrides the middleware hosts from the Choria client configuration file. Can be a single string or an array.",
+                      "oneOf": [
+                        {
+                          "type": [
+                            "string",
+                            "array"
+                          ],
+                          "items": {
+                            "oneOf": [
+                              {
+                                "type": "string"
+                              },
+                              {
+                                "$ref": "#/definitions/_plugin"
+                              }
+                            ]
+                          }
+                        },
+                        {
+                          "$ref": "#/definitions/_plugin"
+                        }
+                      ]
+                    },
                     "cleanup": {
                       "description": "Whether to clean up temporary files created on targets. When running commands on a target, Bolt might create temporary files. After completing the command, these files are automatically deleted. This value can be set to 'false' if you wish to leave these temporary files on the target.",
                       "oneOf": [
@@ -150,42 +186,6 @@
                         }
                       ]
                     },
-                    "nats-connection-timeout": {
-                      "description": "How long to wait in seconds for the initial TCP connection to the NATS broker. If the connection cannot be made within this time, the operation fails.",
-                      "oneOf": [
-                        {
-                          "type": "integer",
-                          "minimum": 1
-                        },
-                        {
-                          "$ref": "#/definitions/_plugin"
-                        }
-                      ]
-                    },
-                    "nats-servers": {
-                      "description": "One or more NATS server addresses in host:port format for the Choria transport. Do not use the nats:// prefix. Overrides the middleware hosts from the Choria client configuration file. Can be a single string or an array.",
-                      "oneOf": [
-                        {
-                          "type": [
-                            "string",
-                            "array"
-                          ],
-                          "items": {
-                            "oneOf": [
-                              {
-                                "type": "string"
-                              },
-                              {
-                                "$ref": "#/definitions/_plugin"
-                              }
-                            ]
-                          }
-                        },
-                        {
-                          "$ref": "#/definitions/_plugin"
-                        }
-                      ]
-                    },
                     "puppet-environment": {
                       "description": "The Puppet environment to use when constructing task file URIs for the Choria bolt_tasks agent.",
                       "oneOf": [