openbolt 5.0.0.rc1

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

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require_relative '../../../bolt/util'
+
+module Bolt
+  class PAL
+    class YamlPlan
+      class Step
+        attr_reader :body
+
+        STEP_KEYS = %w[
+          command
+          download
+          eval
+          message
+          verbose
+          plan
+          resources
+          script
+          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 StepError.new("No valid action detected", step_body['name'], step_number)
+          when 1
+            type = type_keys.first
+          else
+            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}")
+          step_class.validate(step_body, step_number)
+          step_class.new(step_body)
+        end
+
+        def initialize(body)
+          @body = body
+        end
+
+        # Transpiles the step into the plan language
+        #
+        def transpile
+          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)
+          validate_step_keys(body, step_number)
+
+          begin
+            body.each { |k, v| validate_puppet_code(k, v) }
+          rescue Bolt::Error => e
+            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 = body['parameters'].keys
+                                           .select { |key| key.start_with?('_') }
+                                           .map { |key| key.sub(/^_/, '') }
+
+            if (dups = body.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 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 StepError.new(error_message, body['name'], step_number)
+            end
+          end
+        end
+
+        def self.validate_step_keys(body, step_number)
+          step_type = name.split('::').last.downcase
+
+          # For validated step action, ensure only valid keys
+          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)"
+            raise StepError.new(error_message, body['name'], step_number)
+          end
+
+          # Ensure all required keys are present
+          missing_keys = required_keys - body.keys
+
+          if missing_keys.any?
+            error_message = "The #{step_type.inspect} step requires: #{missing_keys.to_a.inspect} key(s)"
+            raise StepError.new(error_message, body['name'], step_number)
+          end
+        end
+
+        # Recursively ensure all puppet code can be parsed
+        def self.validate_puppet_code(step_key, value)
+          case value
+          when Array
+            value.map { |element| validate_puppet_code(step_key, element) }
+          when Hash
+            value.each_with_object({}) do |(k, v), o|
+              key = k.is_a?(Bolt::PAL::YamlPlan::EvaluableString) ? k.value : k
+              o[key] = validate_puppet_code(key, v)
+            end
+            # CodeLiterals can be parsed directly
+          when Bolt::PAL::YamlPlan::CodeLiteral
+            parse_code_string(value.value)
+            # BareString is parsed directly if it starts with '$'
+          when Bolt::PAL::YamlPlan::BareString
+            if value.value.start_with?('$')
+              parse_code_string(value.value)
+            else
+              parse_code_string(value.value, true)
+            end
+          when Bolt::PAL::YamlPlan::EvaluableString
+            # Must quote parsed strings to evaluate them
+            parse_code_string(value.value, true)
+          end
+        rescue Puppet::Error => e
+          raise Bolt::Error.new("Error parsing #{step_key.inspect}: #{e.basic_message}", "bolt/invalid-plan")
+        end
+
+        # Parses the an evaluable string, optionally quote it before parsing
+        def self.parse_code_string(code, quote = false)
+          if quote
+            quoted = Puppet::Pops::Parser::EvaluatingParser.quote(code)
+            Puppet::Pops::Parser::EvaluatingParser.new.parse_string(quoted)
+          else
+            Puppet::Pops::Parser::EvaluatingParser.new.parse_string(code)
+          end
+        end
+      end
+    end
+  end
+end
+
+require_relative 'step/command'
+require_relative 'step/eval'
+require_relative 'step/plan'
+require_relative 'step/resources'
+require_relative 'step/script'
+require_relative 'step/task'
+require_relative 'step/upload'
+require_relative 'step/download'
+require_relative 'step/message'
+require_relative 'step/verbose'

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

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative '../../../bolt/error'
+require_relative '../../../bolt/pal/yaml_plan/loader'
+require_relative '../../../bolt/util'
+
+module Bolt
+  class PAL
+    class YamlPlan
+      class Transpiler
+        class ConvertError < Bolt::Error
+          def initialize(msg, plan_path)
+            super(msg, 'bolt/convert-error', { "plan_path" => plan_path })
+          end
+        end
+
+        def transpile(plan_path)
+          @plan_path = plan_path
+          @modulename = Bolt::Util.module_name(@plan_path)
+          @filename = @plan_path.split(File::SEPARATOR)[-1]
+          validate_path
+
+          plan_object = parse_plan
+          param_descriptions = plan_object.parameters.map do |param|
+            str = String.new("# @param #{param.name}")
+            str << " #{param.description}" if param.description
+            str
+          end.join("\n")
+
+          plan_string = String.new('')
+          plan_string << "# #{plan_object.description}\n" if plan_object.description
+          plan_string << "# WARNING: This is an autogenerated plan. It might not behave as expected.\n"
+          plan_string << "# @api #{plan_object.private ? 'private' : 'public'}\n" unless plan_object.private.nil?
+          plan_string << "#{param_descriptions}\n" unless param_descriptions.empty?
+
+          plan_string << "plan #{plan_object.name}("
+          # Parameters are Bolt::PAL::YamlPlan::Parameter
+          plan_object.parameters&.each_with_index do |param, i|
+            plan_string << param.transpile
+
+            # If it's the last parameter add a newline and no comma
+            last = i + 1 == plan_object.parameters.length ? "\n" : ","
+            # This encodes strangely if we << directly to plan_string
+            plan_string << last
+          end
+          plan_string << ") {\n"
+
+          plan_object.steps&.each do |step|
+            plan_string << step.transpile
+          end
+
+          plan_string << "\n  return #{Bolt::Util.to_code(plan_object.return)}\n" if plan_object.return
+          plan_string << "}"
+          # We always print the plan, even if there's an error
+          puts plan_string
+          validate_plan(plan_string)
+          plan_string
+        end
+
+        def parse_plan
+          begin
+            file_contents = File.read(@plan_path)
+          rescue Errno::ENOENT
+            msg = "Could not read yaml plan file: #{@plan_path}"
+            raise Bolt::FileError.new(msg, @plan_path)
+          end
+
+          begin
+            Bolt::PAL::YamlPlan::Loader.from_string(@modulename, file_contents, @plan_path)
+          rescue Puppet::PreformattedError, StandardError => e
+            raise PALError.from_preformatted_error(e)
+          end
+        end
+
+        def validate_path
+          unless File.extname(@filename) == ".yaml"
+            raise ConvertError.new("You can only convert plans written in yaml", @plan_path)
+          end
+        end
+
+        def validate_plan(plan)
+          Puppet::Pops::Parser::EvaluatingParser.new.parse_string(plan)
+        rescue Puppet::Error => e
+          $stderr.puts "The converted puppet plan contains invalid puppet code: #{e.message}"
+          exit 1
+        end
+      end
+    end
+  end
+end

data/lib/bolt/pal/yaml_plan.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require_relative 'yaml_plan/parameter'
+require_relative 'yaml_plan/step'
+
+module Bolt
+  class PAL
+    class YamlPlan
+      PLAN_KEYS = Set['parameters', 'private', 'steps', 'return', 'version', 'description']
+      VAR_NAME_PATTERN = /\A[a-z_][a-z0-9_]*\z/.freeze
+
+      attr_reader :name, :parameters, :private, :steps, :return, :description
+
+      def initialize(name, plan)
+        # Top-level plan keys aren't allowed to be Puppet code, so force them
+        # all to strings.
+        plan = Bolt::Util.walk_keys(plan) { |key| stringify(key) }
+        @name = name.freeze
+        @description = stringify(plan['description']) if plan['description']
+
+        params_hash = stringify(plan.fetch('parameters', {}))
+        # Ensure params is a hash
+        unless params_hash.is_a?(Hash)
+          raise Bolt::Error.new("Plan parameters must be a Hash", "bolt/invalid-plan")
+        end
+
+        # Munge parameters into an array of Parameter objects, which is what
+        # the Puppet API expects
+        @parameters = params_hash.map do |param, definition|
+          Parameter.new(param, definition)
+        end.freeze
+
+        @private = plan['private']
+        unless @private.nil? || @private.is_a?(TrueClass) || @private.is_a?(FalseClass)
+          msg = "Plan #{@name} key 'private' must be a boolean, received: #{@private.inspect}"
+          raise Bolt::Error.new(msg, "bolt/invalid-plan")
+        end
+
+        # Validate top level plan keys
+        top_level_keys = plan.keys.to_set
+        unless PLAN_KEYS.superset?(top_level_keys)
+          invalid_keys = top_level_keys - PLAN_KEYS
+          raise Bolt::Error.new("Plan contains illegal key(s) #{invalid_keys.to_a.inspect}",
+                                "bolt/invalid-plan")
+        end
+
+        unless plan['steps'].is_a?(Array)
+          raise Bolt::Error.new("Plan must specify an array of steps", "bolt/invalid-plan")
+        end
+
+        used_names = Set.new(@parameters.map(&:name))
+
+        @steps = plan['steps'].each_with_index.map do |step, index|
+          unless step.is_a?(Hash)
+            raise Bolt::Error.new(
+              "Parse error in step number #{index + 1}: Plan step must be an object with valid step keys.",
+              'bolt/invalid-plan'
+            )
+          end
+
+          # Step keys also aren't allowed to be code and neither is the value of "name"
+          stringified_step = Bolt::Util.walk_keys(step) { |key| stringify(key) }
+          stringified_step['name'] = stringify(stringified_step['name']) if stringified_step.key?('name')
+
+          step = Step.create(stringified_step, index + 1)
+          duplicate_check(used_names, stringified_step['name'], index + 1)
+          used_names << stringified_step['name'] if stringified_step['name']
+          step
+        end.freeze
+        @return = plan['return']
+      end
+
+      def duplicate_check(used_names, name, step_number)
+        if used_names.include?(name)
+          error_message = "Duplicate step name or parameter detected: #{name.inspect}"
+          raise Step::StepError.new(error_message, name, step_number)
+        end
+      end
+
+      def body
+        self
+      end
+
+      def return_type
+        Puppet::Pops::Types::TypeParser.singleton.parse('Boltlib::PlanResult')
+      end
+
+      # Turn all "potential" strings in the object into actual strings.
+      # Because we interpret bare strings as potential Puppet code, even in
+      # places where Puppet code isn't allowed (like some hash keys), we need
+      # to be able to force them back into regular strings, as if we had
+      # parsed them normally.
+      def stringify(value)
+        case value
+        when Array
+          value.map { |element| stringify(element) }
+        when Hash
+          value.each_with_object({}) do |(k, v), o|
+            o[stringify(k)] = stringify(v)
+          end
+        when EvaluableString
+          value.value
+        else
+          value
+        end
+      end
+
+      # This class wraps a value parsed from YAML which may be Puppet code.
+      # That includes double-quoted strings and string literals, each of which
+      # subclasses this parent class in order to implement its own evaluation
+      # logic.
+      class EvaluableString
+        attr_reader :file, :line, :value
+
+        def initialize(value, file = nil, line = nil)
+          @value = value
+          @file  = file
+          @line  = line
+        end
+
+        def ==(other)
+          self.class == other.class && @value == other.value
+        end
+      end
+
+      # This class represents a double-quoted YAML string, which is interpreted
+      # as though it were a double-quoted Puppet string (with associated
+      # variable interpolations)
+      class DoubleQuotedString < EvaluableString
+        def evaluate(scope, evaluator)
+          # "inspect" allows us to get back a double-quoted string literal with
+          # special characters escaped. This is based on the assumption that
+          # YAML, Ruby and Puppet all support similar escape sequences.
+          parse_result = evaluator.parse_string(@value.inspect)
+
+          scope.with_local_scope({}) do
+            evaluator.evaluate(scope, parse_result)
+          end
+        end
+      end
+
+      # This represents a literal snippet of Puppet code
+      class CodeLiteral < EvaluableString
+        def evaluate(scope, evaluator)
+          parse_result = evaluator.parse_string(@value)
+
+          scope.with_local_scope({}) do
+            evaluator.evaluate(scope, parse_result)
+          end
+        end
+      end
+
+      # This class stores a bare YAML string, which is fuzzily interpreted as
+      # either Puppet code or a literal string, depending on whether it starts
+      # with a variable reference.
+      class BareString < EvaluableString
+        def evaluate(scope, evaluator)
+          if @value.start_with?('$')
+            # Try to parse the string as Puppet code. If it's invalid code,
+            # return the original string.
+            parse_result = evaluator.parse_string(@value)
+            scope.with_local_scope({}) do
+              evaluator.evaluate(scope, parse_result)
+            end
+          else
+            @value
+          end
+        end
+      end
+    end
+  end
+end