bolt 3.21.0 → 3.23.0

data/lib/bolt/pal.rb

@@ -531,7 +531,9 @@ module Bolt
           'description' => description,
           'parameters'  => parameters,
           'module'      => mod,
-          'private'     => private_plan?(plan)
+          'private'     => private_plan?(plan),
+          'summary'     => plan.tag(:summary)&.text,
+          'docstring'   => (plan.docstring unless plan.docstring.empty?)
         }
 
         pp_info.merge!(get_plan_mtime(plan.file)) if with_mtime
@@ -564,7 +566,9 @@ module Bolt
           'description' => plan.description,
           'parameters'  => parameters,
           'module'      => mod,
-          'private'     => !!plan.private
+          'private'     => !!plan.private,
+          'docstring'   => plan.description,
+          'summary'     => nil
         }
 
         yaml_info.merge!(get_plan_mtime(yaml_path)) if with_mtime

data/lib/bolt/plugin/env_var.rb

@@ -1,8 +1,16 @@
 # frozen_string_literal: true
 
+require 'json'
 module Bolt
   class Plugin
     class EnvVar
+      class InvalidPluginData < Bolt::Plugin::PluginError
+        def initialize(msg, plugin)
+          msg = "Invalid Plugin Data for #{plugin}: #{msg}"
+          super(msg, 'bolt/invalid-plugin-data')
+        end
+      end
+
       def initialize(*_args); end
 
       def name
@@ -31,7 +39,15 @@ module Bolt
       end
 
       def resolve_reference(opts)
-        ENV[opts['var']] || opts['default']
+        reference = ENV[opts['var']]
+        if opts['json'] && reference
+          begin
+            reference = JSON.parse(reference)
+          rescue JSON::ParserError => e
+            raise InvalidPluginData.new(e.message, name)
+          end
+        end
+        reference || opts['default']
       end
     end
   end

data/lib/bolt/plugin/puppetdb.rb

@@ -12,13 +12,16 @@ module Bolt
       end
 
       TEMPLATE_OPTS = %w[alias config facts features name uri vars].freeze
-      PLUGIN_OPTS = %w[_plugin _cache query target_mapping].freeze
+      PLUGIN_OPTS = %w[_plugin _cache query target_mapping instance].freeze
 
       attr_reader :puppetdb_client
 
       def initialize(config:, context:)
-        pdb_config = Bolt::PuppetDB::Config.load_config(config, context.boltdir)
-        @puppetdb_client = Bolt::PuppetDB::Client.new(pdb_config)
+        @puppetdb_client = Bolt::PuppetDB::Client.new(default:   config.delete('default'),
+                                                      instances: config.delete('instances') || {},
+                                                      config:    config,
+                                                      project:   context.boltdir)
+
         @logger = Bolt::Logger.logger(self)
       end
 
@@ -42,6 +45,13 @@ module Bolt
 
       def fact_path(raw_fact)
         fact_path = raw_fact.split(".")
+        fact_path = fact_path.map do |segment|
+          # Turn it into an integer if we can
+          Integer(segment)
+        rescue ArgumentError
+          # Otherwise return the value
+          segment
+        end
         if fact_path[0] == 'facts'
           fact_path.drop(1)
         elsif fact_path == ['certname']
@@ -52,7 +62,7 @@ module Bolt
       end
 
       def resolve_reference(opts)
-        targets = @puppetdb_client.query_certnames(opts['query'])
+        targets = @puppetdb_client.query_certnames(opts['query'], opts['instance'])
         facts = []
 
         template = opts.delete('target_mapping') || {}

data/lib/bolt/plugin.rb

@@ -151,7 +151,8 @@ module Bolt
         msg = "Configuration for the PuppetDB plugin must be in the 'puppetdb' config section, not 'plugins'"
         raise Bolt::Error.new(msg, 'bolt/plugin-error')
       end
-      @unresolved_plugin_configs['puppetdb'] = config.puppetdb if config.puppetdb
+      @unresolved_plugin_configs['puppetdb'] = config.puppetdb.merge('default'   => config.default_puppetdb,
+                                                                     'instances' => config.puppetdb_instances)
     end
 
     # Returns a map of configured plugin hooks. Any unresolved plugin references

data/lib/bolt/project.rb

@@ -128,6 +128,10 @@ module Bolt
 
       @data = data.slice(*Bolt::Config::PROJECT_OPTIONS)
 
+      if @data['rerunfile']
+        @rerunfile = File.expand_path(@data['rerunfile'], @path)
+      end
+
       validate if project_file?
     end
 

data/lib/bolt/puppetdb/client.rb

@@ -2,34 +2,90 @@
 
 require 'json'
 require 'logging'
+require_relative '../../bolt/puppetdb/instance'
 
 module Bolt
   module PuppetDB
     class Client
-      attr_reader :config
-
-      def initialize(config)
-        @config = config
-        @bad_urls = []
-        @current_url = nil
+      # @param config [Hash] A map of default PuppetDB configuration.
+      # @param instances [Hash] A map of configuration for named PuppetDB instances.
+      # @param default [String] The name of PuppetDB instance to use as the default.
+      # @param project [String] The path to the Bolt project.
+      #
+      def initialize(config:, instances: {}, default: nil, project: nil)
         @logger = Bolt::Logger.logger(self)
+
+        @instances = instances.transform_values do |instance_config|
+          Bolt::PuppetDB::Instance.new(config: instance_config, project: project)
+        end
+
+        @default_instance = if default
+                              validate_instance(default)
+                              @instances[default]
+                            else
+                              Bolt::PuppetDB::Instance.new(config: config, project: project, load_defaults: true)
+                            end
+      end
+
+      # Checks whether a given named instance is configured, erroring if not.
+      #
+      # @param name [String] The name of the PuppetDB instance.
+      #
+      private def validate_instance(name)
+        unless @instances[name]
+          raise Bolt::PuppetDBError, "PuppetDB instance '#{name}' has not been configured, unable to connect"
+        end
+      end
+
+      # Yields the PuppetDB instance to connect to.
+      #
+      # @param name [String] The name of the PuppetDB instance.
+      # @yield [Bolt::PuppetDB::Instance]
+      #
+      private def with_instance(name = nil)
+        yield instance(name)
       end
 
-      def query_certnames(query)
+      # Selects the PuppetDB instance to connect to. If an instance is not specified,
+      # the default instance is used.
+      #
+      # @param name [String] The name of the PuppetDB instance.
+      # @return [Bolt::PuppetDB::Instance]
+      #
+      def instance(name = nil)
+        if name
+          validate_instance(name)
+          @instances[name]
+        else
+          @default_instance
+        end
+      end
+
+      # Queries certnames from the PuppetDB instance.
+      #
+      # @param query [String] The PDB query.
+      # @param instance [String] The name of the PuppetDB instance.
+      #
+      def query_certnames(query, instance = nil)
         return [] unless query
 
         @logger.debug("Querying certnames")
-        results = make_query(query)
+        results = make_query(query, nil, instance)
 
         if results&.first && !results.first&.key?('certname')
           fields = results.first&.keys
           raise Bolt::PuppetDBError, "Query results did not contain a 'certname' field: got #{fields.join(', ')}"
         end
+
         results&.map { |result| result['certname'] }&.uniq
       end
 
-      # This method expects an array of certnames to get facts for
-      def facts_for_node(certnames)
+      # Retrieve facts from PuppetDB for a list of nodes.
+      #
+      # @param certnames [Array] The list of certnames to retrieve facts for.
+      # @param instance [String] The name of the PuppetDB instance.
+      #
+      def facts_for_node(certnames, instance = nil)
         return {} if certnames.empty? || certnames.nil?
 
         certnames.uniq!
@@ -37,14 +93,20 @@ module Bolt
         name_query.insert(0, "or")
 
         @logger.debug("Querying certnames")
-        result = make_query(name_query, 'inventory')
+        result = make_query(name_query, 'inventory', instance)
 
         result&.each_with_object({}) do |node, coll|
           coll[node['certname']] = node['facts']
         end
       end
 
-      def fact_values(certnames = [], facts = [])
+      # Retrive fact values for a list of nodes.
+      #
+      # @param certnames [Array] The list of certnames to retrieve fact values for.
+      # @param facts [Array] The list of facts to retrive.
+      # @param instance [String] The name of the PuppetDB instance.
+      #
+      def fact_values(certnames = [], facts = [], instance = nil)
         return {} if certnames.empty? || facts.empty?
 
         certnames.uniq!
@@ -57,135 +119,34 @@ module Bolt
         query = ['and', name_query, facts_query]
 
         @logger.debug("Querying certnames")
-        result = make_query(query, 'fact-contents')
+        result = make_query(query, 'fact-contents', instance)
         result.map! { |h| h.delete_if { |k, _v| %w[environment name].include?(k) } }
         result.group_by { |c| c['certname'] }
       end
 
-      def make_query(query, path = nil)
-        body = JSON.generate(query: query)
-        url = "#{uri}/pdb/query/v4"
-        url += "/#{path}" if path
-
-        begin
-          @logger.debug("Sending PuppetDB query to #{url}")
-          response = http_client.post(url, body: body, header: headers)
-        rescue StandardError => e
-          raise Bolt::PuppetDBFailoverError, "Failed to query PuppetDB: #{e}"
-        end
-
-        @logger.debug("Got response code #{response.code} from PuppetDB")
-        if response.code != 200
-          msg = "Failed to query PuppetDB: #{response.body}"
-          if response.code == 400
-            raise Bolt::PuppetDBError, msg
-          else
-            raise Bolt::PuppetDBFailoverError, msg
-          end
-        end
-
-        begin
-          JSON.parse(response.body)
-        rescue JSON::ParserError
-          raise Bolt::PuppetDBError, "Unable to parse response as JSON: #{response.body}"
-        end
-      rescue Bolt::PuppetDBFailoverError => e
-        @logger.error("Request to puppetdb at #{@current_url} failed with #{e}.")
-        reject_url
-        make_query(query, path)
-      end
-
-      # Sends a command to PuppetDB using version 1 of the commands API.
-      # https://puppet.com/docs/puppetdb/latest/api/command/v1/commands.html
+      # Sends a command to PuppetDB using the commands API.
       #
       # @param command [String] The command to invoke.
       # @param version [Integer] The version of the command to invoke.
       # @param payload [Hash] The payload to send with the command.
-      # @return A UUID identifying the submitted command.
-      #
-      def send_command(command, version, payload)
-        command = command.dup.force_encoding('utf-8')
-        body    = JSON.generate(payload)
-
-        # PDB requires the following query parameters to the POST request.
-        # Error early if there's no certname, as PDB does not return a
-        # message indicating it's required.
-        unless payload['certname']
-          raise Bolt::Error.new(
-            "Payload must include 'certname', unable to invoke command.",
-            'bolt/pdb-command'
-          )
-        end
-
-        url = uri.tap do |u|
-          u.path         = 'pdb/cmd/v1'
-          u.query_values = { 'command'  => command,
-                             'version'  => version,
-                             'certname' => payload['certname'] }
-        end
-
-        # Send the command to PDB
-        begin
-          @logger.debug("Sending PuppetDB command '#{command}' to #{url}")
-          response = http_client.post(url.to_s, body: body, header: headers)
-        rescue StandardError => e
-          raise Bolt::PuppetDBFailoverError, "Failed to invoke PuppetDB command: #{e}"
-        end
-
-        @logger.debug("Got response code #{response.code} from PuppetDB")
-        if response.code != 200
-          raise Bolt::PuppetDBError, "Failed to invoke PuppetDB command: #{response.body}"
-        end
-
-        # Return the UUID string from the response body
-        begin
-          JSON.parse(response.body).fetch('uuid', nil)
-        rescue JSON::ParserError
-          raise Bolt::PuppetDBError, "Unable to parse response as JSON: #{response.body}"
+      # @param instance [String] The name of the PuppetDB instance.
+      #
+      def send_command(command, version, payload, instance = nil)
+        with_instance(instance) do |pdb|
+          pdb.send_command(command, version, payload)
         end
-      rescue Bolt::PuppetDBFailoverError => e
-        @logger.error("Request to puppetdb at #{@current_url} failed with #{e}.")
-        reject_url
-        send_command(command, version, payload)
-      end
-
-      def http_client
-        return @http if @http
-        # lazy-load expensive gem code
-        require 'httpclient'
-        @logger.trace("Creating HTTP Client")
-        @http = HTTPClient.new
-        @http.ssl_config.set_client_cert_file(@config.cert, @config.key) if @config.cert
-        @http.ssl_config.add_trust_ca(@config.cacert)
-        @http.connect_timeout = @config.connect_timeout if @config.connect_timeout
-        @http.receive_timeout = @config.read_timeout if @config.read_timeout
-
-        @http
-      end
-
-      def reject_url
-        @bad_urls << @current_url if @current_url
-        @current_url = nil
       end
 
-      def uri
-        require 'addressable/uri'
-
-        @current_url ||= (@config.server_urls - @bad_urls).first
-        unless @current_url
-          msg = "Failed to connect to all PuppetDB server_urls: #{@config.server_urls.to_a.join(', ')}."
-          raise Bolt::PuppetDBError, msg
+      # Sends a query to PuppetDB.
+      #
+      # @param query [String] The query to send to PuppetDB.
+      # @param path [String] The API path to append to the query URL.
+      # @param instance [String] The name of the PuppetDB instance.
+      #
+      def make_query(query, path = nil, instance = nil)
+        with_instance(instance) do |pdb|
+          pdb.make_query(query, path)
         end
-
-        uri = Addressable::URI.parse(@current_url)
-        uri.port ||= 8081
-        uri
-      end
-
-      def headers
-        headers = { 'Content-Type' => 'application/json' }
-        headers['X-Authentication'] = @config.token if @config.token
-        headers
       end
     end
   end

data/lib/bolt/puppetdb/config.rb

@@ -17,11 +17,30 @@ module Bolt
 
       end
 
+      def initialize(config:, project: nil, load_defaults: false)
+        @settings = if load_defaults
+                      self.class.default_config.merge(config)
+                    else
+                      config
+                    end
+
+        expand_paths(project)
+      end
+
+      # Returns the path to the puppetdb.conf file on Windows.
+      #
+      # @return [String]
+      #
       def self.default_windows_config
         File.expand_path(File.join(ENV['ALLUSERSPROFILE'], 'PuppetLabs/client-tools/puppetdb.conf'))
       end
 
-      def self.load_config(options, project_path = nil)
+      # Loads default configuration from the puppetdb.conf file on system. If
+      # the file is not present, defaults to an empty hash.
+      #
+      # @return [Hash]
+      #
+      def self.default_config
         config = {}
         global_path = Bolt::Util.windows? ? default_windows_config : DEFAULT_CONFIG[:global]
 
@@ -37,13 +56,7 @@ module Bolt
           Bolt::Logger.logger(self).error("Could not load puppetdb.conf from #{filepath}: #{e.message}")
         end
 
-        config = config.fetch('puppetdb', {})
-        new(config.merge(options), project_path)
-      end
-
-      def initialize(settings, project_path = nil)
-        @settings = settings
-        expand_paths(project_path)
+        config.fetch('puppetdb', {})
       end
 
       def token

data/lib/bolt/puppetdb/instance.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'logging'
+require_relative '../../bolt/puppetdb/config'
+
+module Bolt
+  module PuppetDB
+    class Instance
+      attr_reader :config
+
+      def initialize(config:, project: nil, load_defaults: false)
+        @config      = Bolt::PuppetDB::Config.new(config: config, project: project, load_defaults: load_defaults)
+        @bad_urls    = []
+        @current_url = nil
+        @logger      = Bolt::Logger.logger(self)
+      end
+
+      def make_query(query, path = nil)
+        body = JSON.generate(query: query)
+        url = "#{uri}/pdb/query/v4"
+        url += "/#{path}" if path
+
+        begin
+          @logger.debug("Sending PuppetDB query to #{url}")
+          response = http_client.post(url, body: body, header: headers)
+        rescue StandardError => e
+          raise Bolt::PuppetDBFailoverError, "Failed to query PuppetDB: #{e}"
+        end
+
+        @logger.debug("Got response code #{response.code} from PuppetDB")
+        if response.code != 200
+          msg = "Failed to query PuppetDB: #{response.body}"
+          if response.code == 400
+            raise Bolt::PuppetDBError, msg
+          else
+            raise Bolt::PuppetDBFailoverError, msg
+          end
+        end
+
+        begin
+          JSON.parse(response.body)
+        rescue JSON::ParserError
+          raise Bolt::PuppetDBError, "Unable to parse response as JSON: #{response.body}"
+        end
+      rescue Bolt::PuppetDBFailoverError => e
+        @logger.error("Request to puppetdb at #{@current_url} failed with #{e}.")
+        reject_url
+        make_query(query, path)
+      end
+
+      # Sends a command to PuppetDB using version 1 of the commands API.
+      # https://puppet.com/docs/puppetdb/latest/api/command/v1/commands.html
+      #
+      # @param command [String] The command to invoke.
+      # @param version [Integer] The version of the command to invoke.
+      # @param payload [Hash] The payload to send with the command.
+      # @return A UUID identifying the submitted command.
+      #
+      def send_command(command, version, payload)
+        command = command.dup.force_encoding('utf-8')
+        body    = JSON.generate(payload)
+
+        # PDB requires the following query parameters to the POST request.
+        # Error early if there's no certname, as PDB does not return a
+        # message indicating it's required.
+        unless payload['certname']
+          raise Bolt::Error.new(
+            "Payload must include 'certname', unable to invoke command.",
+            'bolt/pdb-command'
+          )
+        end
+
+        url = uri.tap do |u|
+          u.path         = 'pdb/cmd/v1'
+          u.query_values = { 'command'  => command,
+                             'version'  => version,
+                             'certname' => payload['certname'] }
+        end
+
+        # Send the command to PDB
+        begin
+          @logger.debug("Sending PuppetDB command '#{command}' to #{url}")
+          response = http_client.post(url.to_s, body: body, header: headers)
+        rescue StandardError => e
+          raise Bolt::PuppetDBFailoverError, "Failed to invoke PuppetDB command: #{e}"
+        end
+
+        @logger.debug("Got response code #{response.code} from PuppetDB")
+        if response.code != 200
+          raise Bolt::PuppetDBError, "Failed to invoke PuppetDB command: #{response.body}"
+        end
+
+        # Return the UUID string from the response body
+        begin
+          JSON.parse(response.body).fetch('uuid', nil)
+        rescue JSON::ParserError
+          raise Bolt::PuppetDBError, "Unable to parse response as JSON: #{response.body}"
+        end
+      rescue Bolt::PuppetDBFailoverError => e
+        @logger.error("Request to puppetdb at #{@current_url} failed with #{e}.")
+        reject_url
+        send_command(command, version, payload)
+      end
+
+      def http_client
+        return @http if @http
+        # lazy-load expensive gem code
+        require 'httpclient'
+        @logger.trace("Creating HTTP Client")
+        @http = HTTPClient.new
+        @http.ssl_config.set_client_cert_file(@config.cert, @config.key) if @config.cert
+        @http.ssl_config.add_trust_ca(@config.cacert)
+        @http.connect_timeout = @config.connect_timeout if @config.connect_timeout
+        @http.receive_timeout = @config.read_timeout if @config.read_timeout
+
+        @http
+      end
+
+      def reject_url
+        @bad_urls << @current_url if @current_url
+        @current_url = nil
+      end
+
+      def uri
+        require 'addressable/uri'
+
+        @current_url ||= (@config.server_urls - @bad_urls).first
+        unless @current_url
+          msg = "Failed to connect to all PuppetDB server_urls: #{@config.server_urls.to_a.join(', ')}."
+          raise Bolt::PuppetDBError, msg
+        end
+
+        uri = Addressable::URI.parse(@current_url)
+        uri.port ||= 8081
+        uri
+      end
+
+      def headers
+        headers = { 'Content-Type' => 'application/json' }
+        headers['X-Authentication'] = @config.token if @config.token
+        headers
+      end
+    end
+  end
+end

data/lib/bolt/result.rb

@@ -128,7 +128,7 @@ module Bolt
 
     def _pcore_init_from_hash(init_hash)
       opts = init_hash.reject { |k, _v| k == 'target' }
-      initialize(init_hash['target'], opts.transform_keys(&:to_sym))
+      initialize(init_hash['target'], **opts.transform_keys(&:to_sym))
     end
 
     def _pcore_init_hash

data/lib/bolt/transport/ssh/exec_connection.rb

@@ -44,11 +44,12 @@ module Bolt
         end
 
         def ssh_opts
+          # NOTE: not all commands we might use here support various `-o` options,
+          # always provide a way to run without them.
           cmd = []
           # BatchMode is SSH's noninteractive option: if key authentication
           # fails it will error out instead of falling back to password prompt
-          batch_mode = @target.transport_config['batch-mode'] ? 'yes' : 'no'
-          cmd += %W[-o BatchMode=#{batch_mode}]
+          cmd += %w[-o BatchMode=yes] if @target.transport_config['batch-mode']
 
           cmd += %W[-o Port=#{@target.port}] if @target.port
 
@@ -68,6 +69,8 @@ module Bolt
           ssh_cmd = Array(ssh_conf)
           ssh_cmd += ssh_opts
           ssh_cmd << userhost
+          # Add option separator before command for wrappers around SSH
+          ssh_cmd << '--'
           ssh_cmd << command
         end
 

data/lib/bolt/util.rb

@@ -344,7 +344,7 @@ module Bolt
 
         if !stat.readable?
           raise Bolt::FileError.new("The #{type} '#{path}' is unreadable", path)
-        elsif !stat.file? && (!allow_dir || !stat.directory?)
+        elsif !allow_dir && stat.directory?
           expected = allow_dir ? 'file or directory' : 'file'
           raise Bolt::FileError.new("The #{type} '#{path}' is not a #{expected}", path)
         elsif stat.directory?

data/lib/bolt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bolt
-  VERSION = '3.21.0'
+  VERSION = '3.23.0'
 end

data/lib/bolt_server/transport_app.rb

@@ -326,6 +326,7 @@ module BoltServer
         cli << "--basemodulepath" << basemodulepath
         Puppet.settings.send(:clear_everything_for_tests)
         Puppet.initialize_settings(cli)
+        Puppet[:versioned_environment_dirs] = true
         yield
       end
     end

data/lib/bolt_spec/plans/action_stubs/download_stub.rb

@@ -41,7 +41,7 @@ module BoltSpec
         @invocation[:options]
       end
 
-      def result_for(_target, _data)
+      def result_for(_target, **_data)
         raise 'Download result cannot be changed'
       end
 

data/lib/bolt_spec/plans/action_stubs/plan_stub.rb

@@ -30,7 +30,7 @@ module BoltSpec
       end
 
       # Allow any data.
-      def result_for(_target, data)
+      def result_for(_target, **data)
         Bolt::PlanResult.new(Bolt::Util.walk_keys(data, &:to_s), 'success')
       end