openbolt 5.0.0.rc1

data/lib/bolt/plugin/module.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require_relative '../../bolt/task/run'
+
+module Bolt
+  class Plugin
+    class Module
+      class InvalidPluginData < Bolt::Plugin::PluginError
+        def initialize(msg, plugin)
+          msg = "Invalid Plugin Data for #{plugin}: #{msg}"
+          super(msg, 'bolt/invalid-plugin-data')
+        end
+      end
+
+      # mod should not be nil
+      def self.load(mod, opts)
+        if mod.plugin?
+          opts[:mod] = mod
+          plugin = Bolt::Plugin::Module.new(**opts)
+          plugin.setup
+          plugin
+        else
+          raise PluginError::Unknown, mod.name
+        end
+      end
+
+      attr_reader :config, :hook_map
+
+      def initialize(mod:, context:, config:, **_opts)
+        @module = mod
+        @config = config
+        @context = context
+      end
+
+      # This method interacts with the module on disk so it's separate from initialize
+      def setup
+        @data = load_data
+        @hook_map = find_hooks(@data['hooks'] || {})
+
+        if @data['config']
+          msg = <<~MSG.chomp
+            Found unsupported key 'config' in bolt_plugin.json. Config for a plugin is inferred
+            from task parameters, with config values passed as parameters.
+          MSG
+          raise InvalidPluginData.new(msg, name)
+        end
+
+        # Validate againsts the intersection of all task schemas.
+        @config_schema = process_schema(extract_task_parameter_schema)
+
+        validate_config(@config, @config_schema)
+      end
+
+      def name
+        @module.name
+      end
+
+      def hooks
+        (@hook_map.keys + [:validate_resolve_reference]).uniq
+      end
+
+      def load_data
+        JSON.parse(File.read(@module.plugin_data_file))
+      rescue JSON::ParserError => e
+        raise InvalidPluginData.new(e.message, name)
+      end
+
+      def process_schema(schema)
+        raise InvalidPluginData.new('config specification is not an object', name) unless schema.is_a?(Hash)
+        schema.each do |key, val|
+          unless key =~ /\A[a-z][a-z0-9_]*\z/
+            raise InvalidPluginData.new("config specification key, '#{key}',  is not allowed", name)
+          end
+
+          unless val.is_a?(Hash) && (val['type'] || '').is_a?(String)
+            raise InvalidPluginData.new("config specification #{val.to_json} is not allowed", name)
+          end
+
+          type_string = val['type'] || 'Any'
+          begin
+            val['pcore_type'] = Puppet::Pops::Types::TypeParser.singleton.parse(type_string)
+            if val['pcore_type'].is_a? Puppet::Pops::Types::PTypeReferenceType
+              raise InvalidPluginData.new("Could not find type '#{type_string}' for #{key}", name)
+            end
+          rescue Puppet::ParseError
+            raise InvalidPluginData.new("Could not parse type '#{type_string}' for #{key}", name)
+          end
+        end
+
+        schema
+      end
+
+      def validate_config(config, config_schema)
+        config.each_key do |key|
+          msg = "Config for #{name} plugin contains unexpected key #{key}"
+          raise Bolt::ValidationError, msg unless config_schema.include?(key)
+        end
+
+        config_schema.each do |key, spec|
+          val = config[key]
+
+          unless spec['pcore_type'].instance?(val)
+            raise Bolt::ValidationError, "#{name} plugin expects a #{spec['type']} for key #{key}, got: #{val}"
+          end
+          val.nil?
+        end
+        nil
+      end
+
+      def find_hooks(hook_data)
+        raise InvalidPluginData.new("'hooks' must be a hash", name) unless hook_data.is_a?(Hash)
+
+        hooks = {}
+        # Load hooks specified in the config
+        hook_data.each do |hook_name, hook_spec|
+          unless hook_spec.is_a?(Hash) && hook_spec['task'].is_a?(String)
+            msg = "Unexpected hook specification #{hook_spec.to_json} in #{@name} for hook #{hook_name}"
+            raise InvalidPluginData.new(msg, name)
+          end
+
+          begin
+            task = @context.get_validated_task(hook_spec['task'])
+          rescue Bolt::Error => e
+            msg = if e.kind == 'bolt/unknown-task'
+                    "Plugin #{name} specified an unkown task '#{hook_spec['task']}' for a hook"
+                  else
+                    "Plugin #{name} could not load task '#{hook_spec['task']}': #{e.message}"
+                  end
+            raise InvalidPluginData.new(msg, name)
+          end
+
+          hooks[hook_name.to_sym] = { 'task' => task }
+        end
+
+        # Check for tasks for any hooks not already defined
+        (Set.new(KNOWN_HOOKS.map) - hooks.keys).each do |hook_name|
+          task_name = "#{name}::#{hook_name}"
+          begin
+            task = @context.get_validated_task(task_name)
+          rescue Bolt::Error => e
+            raise e unless e.kind == 'bolt/unknown-task'
+          end
+          hooks[hook_name] = { 'task' => task } if task
+        end
+
+        Bolt::Util.symbolize_top_level_keys(hooks)
+      end
+
+      def validate_params(task, params)
+        @context.validate_params(task.name, params)
+      end
+
+      def process_params(task, opts)
+        # opts are passed directly from inventory but all of the _ options are
+        # handled previously. That may not always be the case so filter them
+        # out now.
+        meta, params = opts.partition { |key, _val| key.start_with?('_') }.map(&:to_h)
+
+        # Reject parameters from config that are not accepted by the task and
+        # merge in parameter defaults
+        params = if task.parameters
+                   task.parameter_defaults
+                       .merge(config.slice(*task.parameters.keys))
+                       .merge(params)
+                 else
+                   config.merge(params)
+                 end
+
+        validate_params(task, params)
+
+        meta['_boltdir'] = @context.boltdir.to_s
+
+        [params, meta]
+      end
+
+      def extract_task_parameter_schema
+        # Get the intersection of expected types (using Set)
+        type_set = @hook_map.each_with_object({}) do |(_hook, task), acc|
+          next unless (schema = task['task'].metadata['parameters'])
+          schema.each do |param, scheme|
+            next unless scheme['type'].is_a?(String)
+            scheme['type'] = Set.new([scheme['type']])
+            if acc.dig(param, 'type').is_a?(Set)
+              scheme['type'].merge(acc[param]['type'])
+            end
+          end
+          acc.merge!(schema)
+        end
+        # Convert Set to string
+        type_set.each do |_param, schema|
+          next unless schema['type']
+          schema['type'] = if schema['type'].size > 1
+                             "Optional[Variant[#{schema['type'].to_a.join(', ')}]]"
+                           else
+                             "Optional[#{schema['type'].to_a.first}]"
+                           end
+        end
+      end
+
+      def run_task(task, opts)
+        opts = opts.reject { |key, _val| key.start_with?('_') }
+        params, metaparams = process_params(task, opts)
+        params = params.merge(metaparams)
+
+        # There are no executor options to pass now.
+        options = { catch_errors: true }
+
+        result = @context.run_local_task(task,
+                                         params,
+                                         options).first
+
+        raise Bolt::Error.new(result.error_hash['msg'], result.error_hash['kind']) unless result.ok
+        result.value
+      end
+
+      def run_hook(hook_name, opts, value = true)
+        hook = @hook_map[hook_name]
+        # This shouldn't happen if the Plugin api is used
+        raise PluginError::UnsupportedHook.new(name, hook_name) unless hook
+        result = run_task(hook['task'], opts)
+
+        if value
+          unless result.include?('value')
+            msg = "Plugin #{name} result did not include a value, got #{result}"
+            raise Bolt::Plugin::PluginError::ExecutionError.new(msg, name, hook_name)
+          end
+
+          result['value']
+        end
+      end
+
+      def validate_resolve_reference(opts)
+        task = @hook_map[:resolve_reference]['task']
+        params, _metaparams = process_params(task, opts)
+
+        if task
+          validate_params(task, params)
+        end
+
+        if @hook_map.include?(:validate_resolve_reference)
+          run_hook(:validate_resolve_reference, opts, false)
+        end
+      end
+
+      # These are all the same but are defined explicitly for clarity
+      def resolve_reference(opts)
+        run_hook(__method__, opts)
+      end
+
+      def secret_encrypt(opts)
+        run_hook(__method__, opts)
+      end
+
+      def secret_decrypt(opts)
+        run_hook(__method__, opts)
+      end
+
+      def secret_createkeys(opts = {})
+        run_hook(__method__, opts)
+      end
+
+      def puppet_library(opts, target, apply_prep)
+        task = @hook_map[:puppet_library]['task']
+
+        params, meta_params = process_params(task, opts)
+
+        options = {}
+        options[:run_as] = meta_params['_run_as'] if meta_params['_run_as']
+
+        proc do
+          apply_prep.run_task([target], task, params, options).first
+        end
+      end
+    end
+  end
+end

data/lib/bolt/plugin/prompt.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Bolt
+  class Plugin
+    class Prompt
+      def initialize(*_args); end
+
+      def name
+        'prompt'
+      end
+
+      def hooks
+        hook_descriptions.keys
+      end
+
+      def hook_descriptions
+        {
+          resolve_reference: 'Prompt the user for a sensitive value.',
+          validate_resolve_reference: nil
+        }
+      end
+
+      def validate_resolve_reference(opts)
+        raise Bolt::ValidationError, "Prompt requires a 'message'" unless opts['message']
+      end
+
+      def resolve_reference(opts)
+        $stderr.print("#{opts['message']}: ")
+        value = $stdin.noecho(&:gets).to_s.chomp
+        $stderr.puts
+
+        value
+      end
+    end
+  end
+end

data/lib/bolt/plugin/puppet_connect_data.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Bolt
+  class Plugin
+    class PuppetConnectData
+      INPUT_DATA_VAR = 'PUPPET_CONNECT_INPUT_DATA'
+
+      def initialize(context:, **_opts)
+        if ENV.key?(INPUT_DATA_VAR)
+          # The user provided input data that they will copy-paste into the Puppet Connect UI
+          # for inventory syncing. This environment variable will likely be set when invoking a
+          # general "test Puppet Connect input data" command. That command tests that parsing
+          # the inventory with the given input data results in connectable targets. Part of
+          # that requires validating that the input data contains all of the referenced keys,
+          # which is what this plugin will do in validate_resolve_reference.
+          @input_data_path = ENV[INPUT_DATA_VAR]
+          data_path = @input_data_path
+        else
+          # The user is using this plugin during a regular Bolt invocation, so fetch the (minimal)
+          # required data from the default location. This data should typically be non-autoloadable
+          # secrets like WinRM passwords.
+          #
+          # Note that any unspecified keys will be resolved to nil.
+          data_path = File.join(context.boltdir, 'puppet_connect_data.yaml')
+        end
+
+        @data = Bolt::Util.read_optional_yaml_hash(
+          data_path,
+          File.basename(data_path)
+        )
+
+        if @input_data_path
+          # Validate that the data does not contain any plugin-reference
+          # values
+          @data.each do |key, toplevel_value|
+            # Use walk_vals to check for nested plugin references
+            Bolt::Util.walk_vals(toplevel_value) do |current_value|
+              if current_value.is_a?(Hash) && current_value.key?('_plugin')
+                raise invalid_input_data_err("the #{key} key's value contains a plugin reference")
+              end
+              current_value
+            end
+          end
+        end
+      end
+
+      def name
+        'puppet_connect_data'
+      end
+
+      def hooks
+        hook_descriptions.keys
+      end
+
+      def hook_descriptions
+        {
+          resolve_reference: nil,
+          validate_resolve_reference: nil
+        }
+      end
+
+      def resolve_reference(opts)
+        key = opts['key']
+        @data[key]
+      end
+
+      def validate_resolve_reference(opts)
+        unless opts['key']
+          raise Bolt::ValidationError,
+                "puppet_connect_data plugin requires that 'key' be specified"
+        end
+        if @input_data_path && !@data.key?(opts['key'])
+          # Input data for Puppet Connect was provided and opts['key'] does not have a
+          # value specified. Raise an error for this case.
+          raise invalid_input_data_err("a value for the #{opts['key']} key is not specified")
+        end
+      end
+
+      def invalid_input_data_err(msg)
+        Bolt::ValidationError.new("invalid input data #{@input_data_path}: #{msg}")
+      end
+    end
+  end
+end

data/lib/bolt/plugin/puppetdb.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module Bolt
+  class Plugin
+    class Puppetdb
+      class FactLookupError < Bolt::Error
+        def initialize(fact, err = nil)
+          m = String.new("Fact lookup '#{fact}' contains an invalid factname")
+          m << ": #{err}" unless err.nil?
+          super(m, 'bolt.plugin/fact-lookup-error')
+        end
+      end
+
+      TEMPLATE_OPTS = %w[alias config facts features name uri vars].freeze
+      PLUGIN_OPTS = %w[_plugin _cache query target_mapping instance].freeze
+
+      attr_reader :puppetdb_client
+
+      def initialize(config:, context:)
+        @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
+
+      def name
+        'puppetdb'
+      end
+
+      def hooks
+        hook_descriptions.keys
+      end
+
+      def hook_descriptions
+        {
+          resolve_reference: 'Query PuppetDB for a group of targets.'
+        }
+      end
+
+      def warn_missing_fact(certname, fact)
+        Bolt::Logger.warn("puppetdb_missing_fact", "Could not find fact #{fact} for node #{certname}")
+      end
+
+      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']
+          fact_path
+        else
+          raise FactLookupError.new(raw_fact, "fact lookups must start with 'facts.'")
+        end
+      end
+
+      def resolve_reference(opts)
+        targets = @puppetdb_client.query_certnames(opts['query'], opts['instance'])
+        facts = []
+
+        template = opts.delete('target_mapping') || {}
+
+        keys = Set.new(TEMPLATE_OPTS) & opts.keys
+        unless keys.empty?
+          raise Bolt::ValidationError, "PuppetDB plugin expects keys #{keys.to_a} to be set under 'target_mapping'"
+        end
+
+        keys = Set.new(opts.keys) - PLUGIN_OPTS
+        unless keys.empty?
+          raise Bolt::ValidationError, "Unknown keys in PuppetDB plugin: #{keys.to_a}"
+        end
+
+        Bolt::Util.walk_vals(template) do |value|
+          # This is done in parts instead of in place so that we only need to
+          # make one puppetDB query. Don't gather certname since we already
+          # have that and it's not a fact.
+          if value.is_a?(String) && value != 'certname'
+            facts << fact_path(value)
+          end
+          value
+        end
+
+        facts.uniq!
+        # Returns {'mycertname' => [{'path' => ['nested', 'fact'], 'value' => val'}], ... }
+        fact_values = @puppetdb_client.fact_values(targets, facts, opts['instance'])
+
+        targets.map do |certname|
+          target_data = fact_values[certname]
+          target = resolve_facts(template, certname, target_data) || {}
+          target['uri'] = certname unless target['uri'] || target['name']
+
+          target
+        end
+      end
+
+      def resolve_facts(config, certname, target_data)
+        Bolt::Util.walk_vals(config) do |value|
+          case value
+          when String
+            if value == 'certname'
+              certname
+            else
+              data = target_data&.detect { |d| d['path'] == fact_path(value) }
+              warn_missing_fact(certname, value) if data.nil?
+              # If there's no fact data this will be nil
+              data&.fetch('value', nil)
+            end
+          when Array, Hash
+            value
+          else
+            raise FactLookupError.new(value, "fact lookups must be a string")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/bolt/plugin/task.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Bolt
+  class Plugin
+    class Task
+      def hooks
+        hook_descriptions.keys
+      end
+
+      def hook_descriptions
+        {
+          puppet_library: 'Run a task to install the Puppet agent package.',
+          resolve_reference: 'Run a task as a plugin.',
+          validate_resolve_reference: nil
+        }
+      end
+
+      def name
+        'task'
+      end
+
+      attr_accessor :pal, :executor, :inventory
+
+      def initialize(context:, **_opts)
+        @context = context
+      end
+
+      def run_task(opts)
+        params = opts['parameters'] || {}
+        options = { catch_errors: true }
+
+        raise Bolt::ValidationError, "Task plugin requires that the 'task' is specified" unless opts['task']
+        task = @context.get_validated_task(opts['task'], params)
+
+        result = @context.run_local_task(task, params, options).first
+
+        raise Bolt::Error.new(result.error_hash['msg'], result.error_hash['kind']) if result.error_hash
+        result
+      end
+
+      def validate_options(opts)
+        raise Bolt::ValidationError, "Task plugin requires that the 'task' is specified" unless opts['task']
+        @context.get_validated_task(opts['task'], opts['parameters'] || {})
+      end
+      alias validate_resolve_reference validate_options
+
+      def resolve_reference(opts)
+        result = run_task(opts)
+
+        unless result.value.include?('value')
+          raise Bolt::ValidationError, "Task result did not return 'value': #{result.value}"
+        end
+
+        result['value']
+      end
+
+      def puppet_library(opts, target, apply_prep)
+        params = opts['parameters'] || {}
+        run_opts = {}
+        run_opts[:run_as] = opts['_run_as'] if opts['_run_as']
+        begin
+          task = @context.get_validated_task(opts['task'], params)
+        rescue Bolt::Error => e
+          raise Bolt::Plugin::PluginError::ExecutionError.new(e.message, name, 'puppet_library')
+        end
+        proc do
+          apply_prep.run_task([target], task, params, run_opts).first
+        end
+      end
+    end
+  end
+end