Add Choria transport (phases 1 and 2 of 5)

Implements phases 1 and 2 of the Choria transport, enabling OpenBolt to
run tasks, commands, and scripts on nodes via Choria's NATS pub/sub
messaging as an alternative to SSH and WinRM.

Phase 1 (bolt_tasks agent): Downloads task files to targets from an
OpenVox/Puppet Server and executes them using the bolt_tasks Choria agent.

Phase 2 (shell agent): Executes commands, scripts, and tasks through the
Choria shell agent. This allows running tasks not available on an
OpenVox/Puppet server.

Everything is implemented as asynchronously as possible, aligning with
Choria's model, and is built to run at scale across many thousands of
nodes at once.

See docs in a later commit for details on the phases of this project as
well as user-facing and developer documentation.

Author: nmburgan

.rubocop.yml

@@ -22,4 +22,16 @@ Layout/LineLength:
   Max: 150
 
 Style/FetchEnvVar:
+  Enabled: false
+
+Naming/BlockForwarding:
+  Enabled: false
+
+Naming/PredicatePrefix:
+  Enabled: false
+
+Lint/NoReturnInBeginEndBlocks:
+  Enabled: false
+
+Style/MultilineTernaryOperator:
   Enabled: false

lib/bolt/bolt_option_parser.rb

@@ -168,7 +168,7 @@ def get_help_text(subcommand, action = nil)
       when 'task'
         case action
         when 'run'
-          { flags: ACTION_OPTS + %w[params tmpdir noop],
+          { flags: ACTION_OPTS + %w[params tmpdir noop choria-agent],
             banner: TASK_RUN_HELP }
         when 'show'
           { flags: OPTIONS[:global] + OPTIONS[:global_config_setters] + %w[filter format],
@@ -1095,6 +1095,11 @@ def initialize(options)
       define('--tmpdir DIR', 'The directory to upload and execute temporary files on the target.') do |tmpdir|
         @options[:tmpdir] = tmpdir
       end
+      define('--choria-agent AGENT', %w[bolt_tasks shell],
+             "Which Choria agent to use for task execution (bolt_tasks, shell).",
+             "Defaults to 'bolt_tasks'. Set to 'shell' for tasks not on the Puppet Server.") do |agent|
+        @options[:'choria-agent'] = agent
+      end
 
       separator "\n#{self.class.colorize(:cyan, 'Module options')}"
       define('--[no-]resolve',

lib/bolt/config/options.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative '../../bolt/config/transport/choria'
 require_relative '../../bolt/config/transport/docker'
 require_relative '../../bolt/config/transport/jail'
 require_relative '../../bolt/config/transport/local'
@@ -15,6 +16,7 @@ module Options
       # Transport config classes. Used to load default transport config which
       # gets passed along to the inventory.
       TRANSPORT_CONFIG = {
+        'choria' => Bolt::Config::Transport::Choria,
         'docker' => Bolt::Config::Transport::Docker,
         'jail'   => Bolt::Config::Transport::Jail,
         'local'  => Bolt::Config::Transport::Local,
@@ -551,6 +553,12 @@ module Options
           _example: "winrm",
           _default: "ssh"
         },
+        "choria" => {
+          description: "A map of configuration options for the choria transport.",
+          type: Hash,
+          _plugin: true,
+          _example: { "config-file" => "/etc/choria/client.conf" }
+        },
         "docker" => {
           description: "A map of configuration options for the docker transport.",
           type: Hash,

lib/bolt/config/transport/choria.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative '../../../bolt/error'
+require_relative '../../../bolt/config/transport/base'
+
+module Bolt
+  class Config
+    module Transport
+      class Choria < Base
+        OPTIONS = %w[
+          choria-agent
+          cleanup
+          collective
+          command-timeout
+          config-file
+          host
+          interpreters
+          nats-connection-timeout
+          nats-servers
+          puppet-environment
+          rpc-timeout
+          ssl-ca
+          ssl-cert
+          ssl-key
+          task-timeout
+          tmpdir
+        ].sort.freeze
+
+        DEFAULTS = {
+          'cleanup' => true,
+          'command-timeout' => 60,
+          'nats-connection-timeout' => 30,
+          'puppet-environment' => 'production',
+          'rpc-timeout' => 30,
+          'task-timeout' => 300,
+          'tmpdir' => '/tmp'
+        }.freeze
+
+        VALID_AGENTS = %w[bolt_tasks shell].freeze
+
+        private def validate
+          super
+
+          if @config['choria-agent'] && !VALID_AGENTS.include?(@config['choria-agent'])
+            raise Bolt::ValidationError,
+                  "choria-agent must be one of #{VALID_AGENTS.join(', ')}, got '#{@config['choria-agent']}'"
+          end
+
+          if @config['tmpdir'] && !absolute_path?(@config['tmpdir'])
+            raise Bolt::ValidationError,
+                  "Choria tmpdir must be an absolute path, got '#{@config['tmpdir']}'"
+          end
+
+          ssl_keys = %w[ssl-ca ssl-cert ssl-key]
+          provided_ssl = ssl_keys.select { |k| @config[k] }
+          if provided_ssl.any? && provided_ssl.length < ssl_keys.length
+            missing = ssl_keys - provided_ssl
+            raise Bolt::ValidationError,
+                  "When overriding Choria SSL settings, all three options must be provided " \
+                  "(ssl-ca, ssl-cert, ssl-key). Missing: #{missing.join(', ')}"
+          end
+
+          @config['interpreters'] = normalize_interpreters(@config['interpreters']) if @config['interpreters']
+        end
+
+        # Accept both POSIX absolute paths (/tmp) and Windows absolute paths (C:\temp).
+        def absolute_path?(path)
+          path.start_with?('/') || path.match?(Bolt::Transport::Choria::WINDOWS_PATH_REGEX)
+        end
+      end
+    end
+  end
+end

lib/bolt/config/transport/options.rb

@@ -51,6 +51,56 @@ module Options
             _default: true,
             _example: false
           },
+          "choria-agent" => {
+            type: String,
+            description: "Which Choria agent to use for task execution. Defaults to 'bolt_tasks' " \
+                         "(downloads task files from a Puppet Server). Set to 'shell' for tasks " \
+                         "not available on the Puppet Server.",
+            _plugin: true,
+            _example: "shell"
+          },
+          "collective" => {
+            type: String,
+            description: "The Choria collective to target. Overrides the main_collective from the Choria " \
+                         "client configuration file.",
+            _plugin: true,
+            _example: "production"
+          },
+          "command-timeout" => {
+            type: Integer,
+            description: "How long to wait in seconds for commands and scripts to complete when using the " \
+                         "Choria transport.",
+            minimum: 1,
+            _plugin: true,
+            _default: 60,
+            _example: 120
+          },
+          "config-file" => {
+            type: String,
+            description: "The path to the Choria or MCollective client configuration file.",
+            _plugin: true,
+            _example: "/etc/choria/client.conf"
+          },
+          "nats-connection-timeout" => {
+            type: Integer,
+            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.",
+            minimum: 1,
+            _plugin: true,
+            _default: 30,
+            _example: 60
+          },
+          "rpc-timeout" => {
+            type: Integer,
+            description: "How long to wait in seconds for nodes to respond to an RPC request. " \
+                         "Used for lightweight operations like agent discovery, shell.start, and " \
+                         "shell.list polling. Distinct from command-timeout and task-timeout which " \
+                         "govern the overall duration of commands and tasks.",
+            minimum: 1,
+            _plugin: true,
+            _default: 30,
+            _example: 60
+          },
           "connect-timeout" => {
             type: Integer,
             description: "How long to wait in seconds when establishing connections. Set this value higher if you " \
@@ -225,6 +275,16 @@ module Options
             _plugin: true,
             _example: %w[defaults hmac-md5]
           },
+          "nats-servers" => {
+            type: [String, Array],
+            description: "One or more NATS server addresses for the Choria transport. Overrides the middleware " \
+                         "hosts from the Choria client configuration file. Can be a single string or an array.",
+            items: {
+              type: String
+            },
+            _plugin: true,
+            _example: ["nats://broker1:4222", "nats://broker2:4222"]
+          },
           "native-ssh" => {
             type: [TrueClass, FalseClass],
             description: "This enables the native SSH transport, which shells out to SSH instead of using the " \
@@ -267,6 +327,14 @@ module Options
             _plugin: true,
             _example: "jump.example.com"
           },
+          "puppet-environment" => {
+            type: String,
+            description: "The Puppet environment to use when constructing task file URIs for the Choria " \
+                         "bolt_tasks agent.",
+            _plugin: true,
+            _default: "production",
+            _example: "staging"
+          },
           "read-timeout" => {
             type: Integer,
             description: "How long to wait in seconds when making requests to the Orchestrator.",
@@ -343,6 +411,27 @@ module Options
             _plugin: true,
             _example: 445
           },
+          "ssl-ca" => {
+            type: String,
+            description: "The path to the CA certificate for Choria TLS connections. Overrides the CA " \
+                         "from the Choria client configuration file.",
+            _plugin: true,
+            _example: "/etc/choria/ssl/ca.pem"
+          },
+          "ssl-cert" => {
+            type: String,
+            description: "The path to the client certificate for Choria TLS connections. Overrides the " \
+                         "certificate from the Choria client configuration file.",
+            _plugin: true,
+            _example: "/etc/choria/ssl/client.pem"
+          },
+          "ssl-key" => {
+            type: String,
+            description: "The path to the client private key for Choria TLS connections. Overrides the " \
+                         "key from the Choria client configuration file.",
+            _plugin: true,
+            _example: "/etc/choria/ssl/client-key.pem"
+          },
           "ssh-command" => {
             type: [Array, String],
             description: "The command and options to use when SSHing. This option is used when you need support for " \
@@ -393,6 +482,14 @@ module Options
             _default: "production",
             _example: "development"
           },
+          "task-timeout" => {
+            type: Integer,
+            description: "How long to wait in seconds for tasks to complete when using the Choria transport.",
+            minimum: 1,
+            _plugin: true,
+            _default: 300,
+            _example: 300
+          },
           "tmpdir" => {
             type: String,
             description: "The directory to upload and execute temporary files on the target.",

lib/bolt/executor.rb

@@ -13,6 +13,7 @@
 require_relative '../bolt/result'
 require_relative '../bolt/result_set'
 # Load transports
+require_relative '../bolt/transport/choria'
 require_relative '../bolt/transport/docker'
 require_relative '../bolt/transport/jail'
 require_relative '../bolt/transport/local'
@@ -24,6 +25,7 @@
 
 module Bolt
   TRANSPORTS = {
+    choria: Bolt::Transport::Choria,
     docker: Bolt::Transport::Docker,
     jail: Bolt::Transport::Jail,
     local: Bolt::Transport::Local,