bolt 2.35.0 → 2.36.0

data/lib/bolt/config/options.rb

@@ -104,6 +104,21 @@ module Bolt
       #                               files and is not used by Bolt to actually set default values.
       OPTIONS = {
         "apply_settings" => {
+          description: "A map of Puppet settings to use when applying Puppet code using the `apply` "\
+                       "plan function or the `bolt apply` command.",
+          type: Hash,
+          properties: {
+            "show_diff" => {
+              description: "Whether to log and report a contextual diff.",
+              type: [TrueClass, FalseClass],
+              _example: true,
+              _default: false
+            }
+          },
+          _plugin: false,
+          _deprecation: "This option will be removed in Bolt 3.0. Use `apply-settings` instead."
+        },
+        "apply-settings" => {
           description: "A map of Puppet settings to use when applying Puppet code using the `apply` "\
                        "plan function or the `bolt apply` command.",
           type: Hash,
@@ -169,6 +184,9 @@ module Bolt
                        "files](inventory_file_v2.md).",
           type: String,
           _plugin: false,
+          _deprecation: "This option will be removed in Bolt 3.0. Use the `--inventoryfile` command-line option "\
+                        "to use a non-default inventory file or move the file contents to `inventory.yaml` in the "\
+                        "project directory.",
           _example: "~/.puppetlabs/bolt/inventory.yaml",
           _default: "project/inventory.yaml"
         },
@@ -183,7 +201,8 @@ module Bolt
           properties: {
             "console" => {
               description: "Configuration for logs output to the console.",
-              type: Hash,
+              type: [String, Hash],
+              enum: ['disable'],
               properties: {
                 "level" => {
                   description: "The type of information to log.",
@@ -276,8 +295,8 @@ module Bolt
         },
         "name" => {
           description: "The name of the Bolt project. When this option is configured, the project is considered a "\
-                       "[Bolt project](experimental_features.md#bolt-projects), allowing Bolt to load content from "\
-                       "the project directory as though it were a module.",
+                       "[Bolt project](projects.md), allowing Bolt to load content from the project directory "\
+                       "as though it were a module.",
           type: String,
           _plugin: false,
           _example: "myproject"
@@ -294,6 +313,16 @@ module Bolt
           _example: ["myproject", "myproject::foo", "myproject::bar", "myproject::deploy::*"]
         },
         "plugin_hooks" => {
+          description: "A map of [plugin hooks](writing_plugins.md#hooks) and which plugins a hook should use. "\
+                       "The only configurable plugin hook is `puppet_library`, which can use two possible plugins: "\
+                       "[`puppet_agent`](https://github.com/puppetlabs/puppetlabs-puppet_agent#puppet_agentinstall) "\
+                       "and [`task`](using_plugins.md#task).",
+          type: Hash,
+          _plugin: true,
+          _example: { "puppet_library" => { "plugin" => "puppet_agent", "version" => "6.15.0", "_run_as" => "root" } },
+          _deprecation: "This option will be removed in Bolt 3.0. Use `plugin-hooks` instead."
+        },
+        "plugin-hooks" => {
           description: "A map of [plugin hooks](writing_plugins.md#hooks) and which plugins a hook should use. "\
                        "The only configurable plugin hook is `puppet_library`, which can use two possible plugins: "\
                        "[`puppet_agent`](https://github.com/puppetlabs/puppetlabs-puppet_agent#puppet_agentinstall) "\
@@ -307,7 +336,11 @@ module Bolt
                        "its value is a map of configuration data. Configurable options are specified by the plugin. "\
                        "Read more about configuring plugins in [Using plugins](using_plugins.md#configuring-plugins).",
           type: Hash,
-          _plugin: true,
+          additionalProperties: {
+            type: Hash,
+            _plugin: true
+          },
+          _plugin: false,
           _example: { "pkcs7" => { "keysize" => 1024 } }
         },
         "puppetdb" => {
@@ -480,6 +513,7 @@ module Bolt
 
       # Options that are available in a bolt.yaml file
       BOLT_OPTIONS = %w[
+        apply-settings
         apply_settings
         color
         compile-concurrency
@@ -489,6 +523,7 @@ module Bolt
         inventoryfile
         log
         modulepath
+        plugin-hooks
         plugin_hooks
         plugins
         puppetdb
@@ -505,6 +540,7 @@ module Bolt
         format
         inventory-config
         log
+        plugin-hooks
         plugin_hooks
         plugins
         puppetdb
@@ -514,6 +550,7 @@ module Bolt
 
       # Options that are available in a bolt-project.yaml file
       BOLT_PROJECT_OPTIONS = %w[
+        apply-settings
         apply_settings
         color
         compile-concurrency
@@ -526,6 +563,7 @@ module Bolt
         modules
         name
         plans
+        plugin-hooks
         plugin_hooks
         plugins
         puppetdb

data/lib/bolt/config/transport/base.rb

@@ -2,6 +2,7 @@
 
 require 'bolt/error'
 require 'bolt/util'
+require 'bolt/config/validator'
 require 'bolt/config/transport/options'
 
 module Bolt
@@ -90,6 +91,14 @@ module Bolt
           self::OPTIONS
         end
 
+        def self.schema
+          {
+            type:       Hash,
+            properties: self::TRANSPORT_OPTIONS.slice(*self::OPTIONS),
+            _plugin:    true
+          }
+        end
+
         private def defaults
           unless defined? self.class::DEFAULTS
             raise NotImplementedError,
@@ -116,25 +125,7 @@ module Bolt
 
         # Validation defaults to just asserting the option types
         private def validate
-          assert_type
-        end
-
-        # Validates that each option is the correct type. Types are loaded from the TRANSPORT_OPTIONS hash.
-        private def assert_type
-          @config.each_pair do |opt, val|
-            types = Array(TRANSPORT_OPTIONS.dig(opt, :type)).compact
-
-            next if val.nil? || types.empty? || types.include?(val.class)
-
-            # Ruby doesn't have a Boolean class, so add it to the types list if TrueClass or FalseClass
-            # are present.
-            if types.include?(TrueClass) || types.include?(FalseClass)
-              types = types - [TrueClass, FalseClass] + ['Boolean']
-            end
-
-            raise Bolt::ValidationError,
-                  "#{opt} must be of type #{types.join(', ')}; received #{val.class} #{val.inspect} "
-          end
+          Bolt::Config::Validator.new.validate(@config.compact, self.class.schema.fetch(:properties))
         end
       end
     end

data/lib/bolt/config/transport/local.rb

@@ -29,13 +29,6 @@ module Bolt
           if @config['interpreters']
             @config['interpreters'] = normalize_interpreters(@config['interpreters'])
           end
-
-          if (run_as_cmd = @config['run-as-command'])
-            unless run_as_cmd.all? { |n| n.is_a?(String) }
-              raise Bolt::ValidationError,
-                    "run-as-command must be an Array of Strings, received #{run_as_cmd.class} #{run_as_cmd.inspect}"
-            end
-          end
         end
       end
     end

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

@@ -73,6 +73,14 @@ module Bolt
           %w[ssh-command native-ssh].concat(OPTIONS)
         end
 
+        def self.schema
+          {
+            type:       Hash,
+            properties: self::TRANSPORT_OPTIONS.slice(*(self::OPTIONS + self::NATIVE_OPTIONS)),
+            _plugin:    true
+          }
+        end
+
         private def filter(unfiltered)
           # Because we filter before merging config together it's impossible to
           # know whether both ssh-command *and* native-ssh will be specified
@@ -87,12 +95,6 @@ module Bolt
           super
 
           if (key_opt = @config['private-key'])
-            unless key_opt.instance_of?(String) || (key_opt.instance_of?(Hash) && key_opt.include?('key-data'))
-              raise Bolt::ValidationError,
-                    "private-key option must be a path to a private key file or a Hash containing the 'key-data', "\
-                    "received #{key_opt.class} #{key_opt}"
-            end
-
             if key_opt.instance_of?(String)
               @config['private-key'] = File.expand_path(key_opt, @project)
 
@@ -114,14 +116,6 @@ module Bolt
                   "Unsupported login-shell #{@config['login-shell']}. Supported shells are #{LOGIN_SHELLS.join(', ')}"
           end
 
-          %w[encryption-algorithms host-key-algorithms kex-algorithms mac-algorithms run-as-command].each do |opt|
-            next unless @config.key?(opt)
-            unless @config[opt].all? { |n| n.is_a?(String) }
-              raise Bolt::ValidationError,
-                    "#{opt} must be an Array of Strings, received #{@config[opt].inspect}"
-            end
-          end
-
           if @config['login-shell'] == 'powershell'
             %w[tty run-as].each do |key|
               if @config[key]

data/lib/bolt/config/validator.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# This class validates config against a schema, raising an error that includes
+# details about any invalid configuration.
+#
+module Bolt
+  class Config
+    class Validator
+      attr_reader :deprecations, :warnings
+
+      def initialize
+        @errors       = []
+        @deprecations = []
+        @warnings     = []
+        @path         = []
+      end
+
+      # This is the entry method for validating data against the schema.
+      # It loops over each key-value pair in the data hash and validates
+      # the value against the relevant schema definition.
+      #
+      def validate(data, schema, location = nil)
+        @location = location
+
+        validate_keys(data.keys, schema.keys)
+
+        data.each_pair do |key, value|
+          next unless schema.key?(key)
+
+          @path.push(key)
+
+          check_deprecated(key, schema[key], location)
+          validate_value(value, schema[key])
+        ensure
+          @path.pop
+        end
+
+        raise_error
+      end
+
+      # Adds a warning if the given option is deprecated.
+      #
+      def check_deprecated(key, definition, location)
+        if definition.key?(:_deprecation)
+          message  = "Option '#{path}' "
+          message += "at #{location} " if location
+          message += "is deprecated. #{definition[:_deprecation]}"
+          @deprecations << { option: key, message: message }
+        end
+      end
+
+      # Raises a ValidationError if there are any errors. All error messages
+      # created during validation are concatenated into a single error
+      # message.
+      #
+      private def raise_error
+        return unless @errors.any?
+
+        message = "Invalid configuration"
+        message += " at #{@location}" if @location
+        message += ":\n"
+        message += @errors.map { |error| "\s\s#{error}" }.join("\n")
+
+        raise Bolt::ValidationError, message
+      end
+
+      # Validate an individual value. This performs validation that is
+      # common to all values, including type validation. After validating
+      # the value's type, the value is passed off to an individual
+      # validation method for the value's type.
+      #
+      private def validate_value(value, definition)
+        return if plugin_reference?(value, definition)
+        return unless valid_type?(value, definition)
+
+        case value
+        when Hash
+          validate_hash(value, definition)
+        when Array
+          validate_array(value, definition)
+        when String
+          validate_string(value, definition)
+        when Numeric
+          validate_number(value, definition)
+        end
+      end
+
+      # Validates a hash value, logging errors for any validations that fail.
+      # This will enumerate each key-value pair in the hash and validate each
+      # value individually.
+      #
+      private def validate_hash(value, definition)
+        properties = definition[:properties] ? definition[:properties].keys : []
+
+        if definition[:properties] && definition[:additionalProperties].nil?
+          validate_keys(value.keys, properties)
+        end
+
+        if definition[:required] && (definition[:required] - value.keys).any?
+          missing = definition[:required] - value.keys
+          @errors << "Value at '#{path}' is missing required keys #{missing.join(', ')}"
+        end
+
+        value.each_pair do |key, val|
+          @path.push(key)
+
+          if properties.include?(key)
+            validate_value(val, definition[:properties][key])
+          elsif definition[:additionalProperties]
+            validate_value(val, definition[:additionalProperties])
+          end
+        ensure
+          @path.pop
+        end
+      end
+
+      # Validates an array value, logging errors for any validations that fail.
+      # This will enumerate the items in the array and validate each item
+      # individually.
+      #
+      private def validate_array(value, definition)
+        if definition[:uniqueItems] && value.size != value.uniq.size
+          @errors << "Value at '#{path}' must not include duplicate elements"
+          return
+        end
+
+        return unless definition.key?(:items)
+
+        value.each_with_index do |item, index|
+          @path.push(index)
+          validate_value(item, definition[:items])
+        ensure
+          @path.pop
+        end
+      end
+
+      # Validates a string value, logging errors for any validations that fail.
+      #
+      private def validate_string(value, definition)
+        if definition.key?(:enum) && !definition[:enum].include?(value)
+          message  = "Value at '#{path}' must be "
+          message += "one of " if definition[:enum].count > 1
+          message += definition[:enum].join(', ')
+          multitype_error(message, value, definition)
+        end
+      end
+
+      # Validates a numeric value, logging errors for any validations that fail.
+      #
+      private def validate_number(value, definition)
+        if definition.key?(:minimum) && value < definition[:minimum]
+          @errors << "Value at '#{path}' must be a minimum of #{definition[:minimum]}"
+        end
+      end
+
+      # Adds warnings for unknown config options.
+      #
+      private def validate_keys(keys, known_keys)
+        (keys - known_keys).each do |key|
+          message  = "Unknown option '#{key}'"
+          message += " at '#{path}'" if @path.any?
+          message += " at #{@location}" if @location
+          message += "."
+          @warnings << message
+        end
+      end
+
+      # Returns true if a value is a plugin reference. This also validates whether
+      # a value can be a plugin reference in the first place. If the value is a
+      # plugin reference but cannot be one according to the schema, then this will
+      # log an error.
+      #
+      private def plugin_reference?(value, definition)
+        if value.is_a?(Hash) && value.key?('_plugin')
+          unless definition[:_plugin]
+            @errors << "Value at '#{path}' is a plugin reference, which is unsupported at "\
+                       "this location"
+          end
+
+          true
+        else
+          false
+        end
+      end
+
+      # Asserts the type for each option against the type specified in the schema
+      # definition. The schema definition can specify multiple valid types, so the
+      # value needs to only match one of the types to be valid. Returns early if
+      # there is no type in the definition (in practice this shouldn't happen, but
+      # this will safeguard against any dev mistakes).
+      #
+      private def valid_type?(value, definition)
+        return unless definition.key?(:type)
+
+        types = Array(definition[:type])
+
+        if types.include?(value.class)
+          true
+        else
+          if types.include?(TrueClass) || types.include?(FalseClass)
+            types = types - [TrueClass, FalseClass] + ['Boolean']
+          end
+
+          @errors << "Value at '#{path}' must be of type #{types.join(' or ')}"
+
+          false
+        end
+      end
+
+      # Adds an error that includes additional helpful information for values
+      # that accept multiple types.
+      #
+      private def multitype_error(message, value, definition)
+        if Array(definition[:type]).count > 1
+          types    = Array(definition[:type]) - [value.class]
+          message += " or must be of type #{types.join(' or ')}"
+        end
+
+        @errors << message
+      end
+
+      # Returns the formatted path for the key.
+      #
+      private def path
+        @path.join('.')
+      end
+    end
+  end
+end