bolt 2.42.0 → 3.3.0

data/lib/bolt/pal/yaml_plan/step.rb

@@ -6,41 +6,56 @@ module Bolt
   class PAL
     class YamlPlan
       class Step
-        attr_reader :name, :type, :body, :targets
-
-        def self.allowed_keys
-          Set['name', 'description', 'target', 'targets']
-        end
+        attr_reader :body
 
         STEP_KEYS = %w[
           command
-          destination
           download
           eval
           message
           plan
           resources
           script
-          source
           task
           upload
         ].freeze
 
+        class StepError < Bolt::Error
+          def initialize(message, name, step_number)
+            identifier = name ? name.inspect : "number #{step_number}"
+            error      = "Parse error in step #{identifier}: \n #{message}"
+
+            super(error, 'bolt/invalid-plan')
+          end
+        end
+
+        # Keys that are allowed for the step
+        #
+        def self.allowed_keys
+          required_keys + option_keys + Set['name', 'description', 'targets']
+        end
+
+        # Keys that translate to metaparameters for the plan step's function call
+        #
+        def self.option_keys
+          Set.new
+        end
+
+        # Keys that are required for the step
+        #
+        def self.required_keys
+          Set.new
+        end
+
         def self.create(step_body, step_number)
           type_keys = (STEP_KEYS & step_body.keys)
           case type_keys.length
           when 0
-            raise step_error("No valid action detected", step_body['name'], step_number)
+            raise StepError.new("No valid action detected", step_body['name'], step_number)
           when 1
             type = type_keys.first
           else
-            if [Set['source', 'destination'], Set['upload', 'destination']].include?(type_keys.to_set)
-              type = 'upload'
-            elsif type_keys.to_set == Set['download', 'destination']
-              type = 'download'
-            else
-              raise step_error("Multiple action keys detected: #{type_keys.inspect}", step_body['name'], step_number)
-            end
+            raise StepError.new("Multiple action keys detected: #{type_keys.inspect}", step_body['name'], step_number)
           end
 
           step_class = const_get("Bolt::PAL::YamlPlan::Step::#{type.capitalize}")
@@ -48,15 +63,49 @@ module Bolt
           step_class.new(step_body)
         end
 
-        def initialize(step_body)
-          @name = step_body['name']
-          @description = step_body['description']
-          @targets = step_body['targets'] || step_body['target']
-          @body = step_body
+        def initialize(body)
+          @body = body
         end
 
+        # Transpiles the step into the plan language
+        #
         def transpile
-          raise NotImplementedError, "Step #{@name} does not supported conversion to Puppet plan language"
+          code = String.new("  ")
+          code << "$#{body['name']} = " if body['name']
+          code << function_call(function, format_args(body))
+          code << "\n"
+        end
+
+        # Evaluates the step
+        #
+        def evaluate(scope, evaluator)
+          evaluated = evaluator.evaluate_code_blocks(scope, body)
+          scope.call_function(function, format_args(evaluated))
+        end
+
+        # Formats a list of args from the provided body
+        #
+        private def format_args(_body)
+          raise NotImplementedError, "Step class #{self.class} does not implement #format_args"
+        end
+
+        # Returns the step's corresponding Puppet language function call
+        #
+        private def function_call(function, args)
+          code_args = args.map { |arg| Bolt::Util.to_code(arg) }
+          "#{function}(#{code_args.join(', ')})"
+        end
+
+        # The function that corresponds to the step
+        #
+        private def function
+          raise NotImplementedError, "Step class #{self.class} does not implement #function"
+        end
+
+        # Returns a hash of options formatted for function calls
+        #
+        private def format_options(body)
+          body.slice(*self.class.option_keys).transform_keys { |key| "_#{key}" }
         end
 
         def self.validate(body, step_number)
@@ -65,19 +114,35 @@ module Bolt
           begin
             body.each { |k, v| validate_puppet_code(k, v) }
           rescue Bolt::Error => e
-            raise step_error(e.msg, body['name'], step_number)
+            raise StepError.new(e.msg, body['name'], step_number)
+          end
+
+          if body.key?('parameters')
+            unless body['parameters'].is_a?(Hash)
+              raise StepError.new("Parameters key must be a hash", body['name'], step_number)
+            end
+
+            metaparams = option_keys.map { |key| "_#{key}" }
+
+            if (dups = body['parameters'].keys & metaparams).any?
+              raise StepError.new(
+                "Cannot specify metaparameters when using top-level keys with same name: #{dups.join(', ')}",
+                body['name'],
+                step_number
+              )
+            end
           end
 
           unless body.fetch('parameters', {}).is_a?(Hash)
             msg = "Parameters key must be a hash"
-            raise step_error(msg, body['name'], step_number)
+            raise StepError.new(msg, body['name'], step_number)
           end
 
           if body.key?('name')
             name = body['name']
             unless name.is_a?(String) && name.match?(Bolt::PAL::YamlPlan::VAR_NAME_PATTERN)
               error_message = "Invalid step name: #{name.inspect}"
-              raise step_error(error_message, body['name'], step_number)
+              raise StepError.new(error_message, body['name'], step_number)
             end
           end
         end
@@ -89,30 +154,15 @@ module Bolt
           illegal_keys = body.keys.to_set - allowed_keys
           if illegal_keys.any?
             error_message = "The #{step_type.inspect} step does not support: #{illegal_keys.to_a.inspect} key(s)"
-            err = step_error(error_message, body['name'], step_number)
-            raise Bolt::Error.new(err, "bolt/invalid-plan")
+            raise StepError.new(error_message, body['name'], step_number)
           end
 
           # Ensure all required keys are present
           missing_keys = required_keys - body.keys
 
-          # Handle cases where steps with a required 'targets' key are using the deprecated
-          # 'target' key instead.
-          # TODO: Remove this when 'target' is removed
-          if body.include?('target')
-            missing_keys -= ['targets']
-          end
-
-          # Handle cases where upload step uses deprecated 'source' key instead of 'upload'
-          # TODO: Remove when 'source' is removed
-          if body.include?('source')
-            missing_keys -= ['upload']
-          end
-
           if missing_keys.any?
             error_message = "The #{step_type.inspect} step requires: #{missing_keys.to_a.inspect} key(s)"
-            err = step_error(error_message, body['name'], step_number)
-            raise Bolt::Error.new(err, "bolt/invalid-plan")
+            raise StepError.new(error_message, body['name'], step_number)
           end
         end
 
@@ -144,12 +194,6 @@ module Bolt
           raise Bolt::Error.new("Error parsing #{step_key.inspect}: #{e.basic_message}", "bolt/invalid-plan")
         end
 
-        def self.step_error(message, name, step_number)
-          identifier = name ? name.inspect : "number #{step_number}"
-          error = "Parse error in step #{identifier}: \n #{message}"
-          Bolt::Error.new(error, 'bolt/invalid-plan')
-        end
-
         # Parses the an evaluable string, optionally quote it before parsing
         def self.parse_code_string(code, quote = false)
           if quote
@@ -159,11 +203,6 @@ module Bolt
             Puppet::Pops::Parser::EvaluatingParser.new.parse_string(code)
           end
         end
-
-        def function_call(function, args)
-          code_args = args.map { |arg| Bolt::Util.to_code(arg) }
-          "#{function}(#{code_args.join(', ')})"
-        end
       end
     end
   end

data/lib/bolt/pal/yaml_plan/step/command.rb

@@ -5,30 +5,30 @@ module Bolt
     class YamlPlan
       class Step
         class Command < Step
-          def self.allowed_keys
-            super + Set['command']
+          def self.option_keys
+            Set['catch_errors', 'env_vars', 'run_as']
           end
 
           def self.required_keys
-            Set['targets']
+            Set['command', 'targets']
           end
 
-          def initialize(step_body)
-            super
-            @command = step_body['command']
-          end
-
-          def transpile
-            code = String.new("  ")
-            code << "$#{@name} = " if @name
+          # Returns an array of arguments to pass to the step's function call
+          #
+          private def format_args(body)
+            opts = format_options(body)
 
-            fn = 'run_command'
-            args = [@command, @targets]
-            args << @description if @description
+            args = [body['command'], body['targets']]
+            args << body['description'] if body['description']
+            args << opts if opts.any?
 
-            code << function_call(fn, args)
+            args
+          end
 
-            code << "\n"
+          # Returns the function corresponding to the step
+          #
+          private def function
+            'run_command'
           end
         end
       end

data/lib/bolt/pal/yaml_plan/step/download.rb

@@ -5,31 +5,30 @@ module Bolt
     class YamlPlan
       class Step
         class Download < Step
-          def self.allowed_keys
-            super + Set['download', 'destination']
+          def self.option_keys
+            Set['catch_errors', 'run_as']
           end
 
           def self.required_keys
             Set['download', 'destination', 'targets']
           end
 
-          def initialize(step_body)
-            super
-            @source = step_body['download']
-            @destination = step_body['destination']
-          end
-
-          def transpile
-            code = String.new("  ")
-            code << "$#{@name} = " if @name
+          # Returns an array of arguments to pass to the step's function call
+          #
+          private def format_args(body)
+            opts = format_options(body)
 
-            fn = 'download_file'
-            args = [@source, @destination, @targets]
-            args << @description if @description
+            args = [body['download'], body['destination'], body['targets']]
+            args << body['description'] if body['description']
+            args << opts if opts.any?
 
-            code << function_call(fn, args)
+            args
+          end
 
-            code << "\n"
+          # Returns the function corresponding to the step
+          #
+          private def function
+            'download_file'
           end
         end
       end

data/lib/bolt/pal/yaml_plan/step/eval.rb

@@ -5,28 +5,28 @@ module Bolt
     class YamlPlan
       class Step
         class Eval < Step
-          def self.allowed_keys
-            super + Set['eval']
-          end
-
           def self.required_keys
-            Set.new
+            Set['eval']
           end
 
-          def initialize(step_body)
-            super
-            @eval = step_body['eval']
+          # Evaluates the step
+          #
+          def evaluate(scope, evaluator)
+            evaluated = evaluator.evaluate_code_blocks(scope, body)
+            evaluated['eval']
           end
 
+          # Transpiles the step into the plan language
+          #
           def transpile
             code = String.new("  ")
-            code << "$#{@name} = " if @name
+            code << "$#{body['name']} = " if body['name']
 
-            code_body = Bolt::Util.to_code(@eval)
+            code_body = Bolt::Util.to_code(body['eval']) || 'undef'
 
             # If we're trying to assign the result of a multi-line eval to a name
             # variable, we need to wrap it in `with()`.
-            if @name && code_body.lines.count > 1
+            if body['name'] && code_body.lines.count > 1
               indented = code_body.gsub(/\n/, "\n    ").chomp("  ")
               code << "with() || {\n    #{indented}}"
             else

data/lib/bolt/pal/yaml_plan/step/message.rb

@@ -13,14 +13,23 @@ module Bolt
             Set['message']
           end
 
-          def initialize(step_body)
-            super
-            @message = step_body['message']
+          # Returns an array of arguments to pass to the step's function call
+          #
+          private def format_args(body)
+            [body['message']]
           end
 
+          # Returns the function corresponding to the step
+          #
+          private def function
+            'out::message'
+          end
+
+          # Transpiles the step into the plan language
+          #
           def transpile
             code = String.new("  ")
-            code << function_call('out::message', [@message])
+            code << function_call(function, format_args(body))
             code << "\n"
           end
         end

data/lib/bolt/pal/yaml_plan/step/plan.rb

@@ -6,30 +6,34 @@ module Bolt
       class Step
         class Plan < Step
           def self.allowed_keys
-            super + Set['plan', 'parameters']
+            super + Set['parameters']
           end
 
-          def self.required_keys
-            Set.new
+          def self.option_keys
+            Set['catch_errors', 'run_as']
           end
 
-          def initialize(step_body)
-            super
-            @plan = step_body['plan']
-            @parameters = step_body.fetch('parameters', {})
+          def self.required_keys
+            Set['plan']
           end
 
-          def transpile
-            code = String.new("  ")
-            code << "$#{@name} = " if @name
+          # Returns an array of arguments to pass to the step's function call
+          #
+          private def format_args(body)
+            opts   = format_options(body)
+            params = (body['parameters'] || {}).merge(opts)
 
-            fn = 'run_plan'
-            args = [@plan]
-            args << @parameters unless @parameters.empty?
+            args = [body['plan']]
+            args << body['targets'] if body['targets']
+            args << params if params.any?
 
-            code << function_call(fn, args)
+            args
+          end
 
-            code << "\n"
+          # Returns the function corresponding to the step
+          #
+          private def function
+            'run_plan'
           end
         end
       end

data/lib/bolt/pal/yaml_plan/step/resources.rb

@@ -5,18 +5,81 @@ module Bolt
     class YamlPlan
       class Step
         class Resources < Step
-          def self.allowed_keys
-            super + Set['resources']
+          def self.option_keys
+            Set['catch_errors', 'description', 'noop', 'run_as']
           end
 
           def self.required_keys
-            Set['targets']
+            Set['resources', 'targets']
           end
 
-          def initialize(step_body)
+          def initialize(body)
             super
-            @resources = step_body['resources']
-            @normalized_resources = normalize_resources(@resources)
+            @body['resources'] = normalize_resources(@body['resources'])
+          end
+
+          # Returns an array of arguments to pass to the apply function call
+          #
+          private def format_args(body)
+            opts = format_options(body)
+
+            args = [body['targets']]
+            args << opts if opts.any?
+
+            args
+          end
+
+          def evaluate(scope, evaluator)
+            evaluated = evaluator.evaluate_code_blocks(scope, body)
+
+            scope.call_function('apply_prep', evaluated['targets'])
+
+            apply_args = format_args(evaluated)
+            manifest   = generate_manifest(evaluated['resources'])
+            apply_manifest(scope, apply_args, manifest)
+          end
+
+          # Generates a manifest from the resources
+          #
+          private def generate_manifest(resources)
+            # inspect returns the Ruby representation of the resource hashes,
+            # which happens to be the same as the Puppet representation
+            puppet_resources = resources.inspect
+
+            # Because the :tasks setting globally controls which mode the parser
+            # is in, we need to make this snippet of non-tasks manifest code
+            # parseable in tasks mode. The way to do that is by putting it in an
+            # apply statement and taking the body.
+            <<~MANIFEST
+            apply('placeholder') {
+              $resources = #{puppet_resources}
+              $resources.each |$res| {
+                Resource[$res['type']] { $res['title']:
+                  * => $res['parameters'],
+                }
+              }
+  
+              # Add relationships if there is more than one resource
+              if $resources.length > 1 {
+                ($resources.length - 1).each |$index| {
+                  $lhs = $resources[$index]
+                  $rhs = $resources[$index+1]
+                  $lhs_resource = Resource[$lhs['type'] , $lhs['title']]
+                  $rhs_resource = Resource[$rhs['type'] , $rhs['title']]
+                  $lhs_resource -> $rhs_resource
+                }
+              }
+            }
+            MANIFEST
+          end
+
+          # Applies the manifest block on the targets
+          #
+          private def apply_manifest(scope, args, manifest)
+            ast = self.class.parse_code_string(manifest)
+            apply_block = ast.body.body
+            applicator = Puppet.lookup(:apply_executor)
+            applicator.apply(args, apply_block, scope)
           end
 
           def self.validate(body, step_number)
@@ -26,26 +89,28 @@ module Bolt
               if resource['type'] || resource['title']
                 if !resource['type']
                   err = "Resource declaration must include type key if title key is set"
-                  raise step_error(err, body['name'], step_number)
+                  raise StepError.new(err, body['name'], step_number)
                 elsif !resource['title']
                   err = "Resource declaration must include title key if type key is set"
-                  raise step_error(err, body['name'], step_number)
+                  raise StepError.new(err, body['name'], step_number)
                 end
               else
                 type_keys = (resource.keys - ['parameters'])
                 if type_keys.empty?
                   err = "Resource declaration is missing a type"
-                  raise step_error(err, body['name'], step_number)
+                  raise StepError.new(err, body['name'], step_number)
                 elsif type_keys.length > 1
                   err = "Resource declaration has ambiguous type: could be #{type_keys.join(' or ')}"
-                  raise step_error(err, body['name'], step_number)
+                  raise StepError.new(err, body['name'], step_number)
                 end
               end
             end
           end
 
+          # Normalizes the resources so they are in a format compatible with apply blocks
           # What if this comes from a code block?
-          def normalize_resources(resources)
+          #
+          private def normalize_resources(resources)
             resources.map do |resource|
               if resource['type'] && resource['title']
                 type = resource['type']
@@ -59,25 +124,21 @@ module Bolt
             end
           end
 
-          def body
-            @body.merge('resources' => @normalized_resources)
-          end
-
           def transpile
             code = StringIO.new
 
             code.print "  "
-            fn = 'apply_prep'
-            args = [@targets]
-            code << function_call(fn, args)
+            code << function_call('apply_prep', [body['targets']])
             code.print "\n"
 
             code.print "  "
-            code.print "$#{@name} = " if @name
+            code.print "$#{body['name']} = " if body['name']
+
+            code << function_call('apply', format_args(body))
 
-            code.puts "apply(#{Bolt::Util.to_code(@targets)}) {"
+            code.print " {\n"
 
-            declarations = @normalized_resources.map do |resource|
+            declarations = body['resources'].map do |resource|
               type = resource['type'].is_a?(EvaluableString) ? resource['type'].value : resource['type']
               title = Bolt::Util.to_code(resource['title'])
               parameters = resource['parameters'].transform_values do |val|