openbolt 5.0.0.rc1

data/bolt-modules/boltlib/lib/puppet/functions/get_targets.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Parses common ways of referring to targets and returns an array of Targets.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:get_targets) do
+  # @param names A pattern or array of patterns identifying a set of targets.
+  # @return A list of unique Targets resolved from any target URIs and groups.
+  # @example Resolve a group
+  #   get_targets('group1')
+  # @example Resolve a target URI
+  #   get_targets('winrm://host2:54321')
+  # @example Resolve array of groups and/or target URIs
+  #   get_targets(['host1', 'group1', 'winrm://host2:54321'])
+  # @example Resolve string consisting of a comma-separated list of groups and/or target URIs
+  #   get_targets('host1,group1,winrm://host2:54321')
+  # @example Run on localhost
+  #   get_targets('localhost')
+  dispatch :get_targets do
+    param 'Boltlib::TargetSpec', :names
+    return_type 'Array[Target]'
+  end
+
+  def get_targets(names)
+    inventory = Puppet.lookup(:bolt_inventory)
+    # Bolt executor not expected when invoked from apply block
+    executor = Puppet.lookup(:bolt_executor) { nil }
+    # Send Analytics Report
+    executor&.report_function_call(self.class.name)
+
+    inventory.get_targets(names)
+  end
+end

data/bolt-modules/boltlib/lib/puppet/functions/parallelize.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+# Map a code block onto an array, where each array element executes in parallel.
+# This function is experimental.
+#
+# > **Note:** Not available in apply block.
+Puppet::Functions.create_function(:parallelize, Puppet::Functions::InternalFunction) do
+  # Map a block onto an array, where each array element executes in parallel.
+  # This function is experimental.
+  # @param data The array to apply the block to.
+  # @param block The code block to execute for each array element.
+  # @return [Array] An array of PlanResult objects. Each input from the input
+  #   array returns a corresponding PlanResult object.
+  # @example Execute two tasks on two targets.
+  #   $targets = get_targets(["host1", "host2"])
+  #   $result = parallelize ($targets) |$t| {
+  #     run_task('a', $t)
+  #     run_task('b', $t)
+  #   }
+  dispatch :parallelize do
+    scope_param
+    param 'Array[Any]', :data
+    block_param 'Callable[Any]', :block
+    return_type 'Array[Boltlib::PlanResult]'
+  end
+
+  def parallelize(scope, data, &block)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'parallelize')
+    end
+
+    executor = Puppet.lookup(:bolt_executor)
+    executor.report_function_call(self.class.name)
+
+    futures = data.map do |object|
+      # We're going to immediately wait for these futures, *and* don't want
+      # their results to be returned as part of `wait()`, so use a 'dummy'
+      # value as the plan_id. This could also be nil, though in general we want
+      # to require Futures to have a plan stack so that they don't get lost.
+      executor.create_future(scope: scope, plan_id: 'parallel') do |newscope|
+        # Catch 'return' calls inside the block
+        result = catch(:return) do
+          # Add the object to the block parameters
+          args = { block.parameters[0][1].to_s => object }
+          # Execute the block. Individual plan steps in the block will yield
+          # the Fiber if they haven't finished, so all this needs to do is run
+          # the block.
+          block.closure.call_by_name_with_scope(newscope, args, true)
+        end
+
+        # If we got a return from the block, get its value
+        # Otherwise the result is the last line from the block
+        result = result.value if result.is_a?(Puppet::Pops::Evaluator::Return)
+
+        # Validate the result is a PlanResult
+        unless Puppet::Pops::Types::TypeParser.singleton.parse('Boltlib::PlanResult').instance?(result)
+          raise Bolt::InvalidParallelResult.new(result.to_s, *Puppet::Pops::PuppetStack.top_of_stack)
+        end
+
+        result
+      rescue Puppet::PreformattedError => e
+        if e.cause.is_a?(Bolt::Error)
+          e.cause
+        else
+          raise e
+        end
+      end
+    end
+
+    # We may eventually want parallelize to accept a timeout
+    executor.wait(futures)
+  end
+end

data/bolt-modules/boltlib/lib/puppet/functions/puppetdb_command.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Send a command with a payload to PuppetDB.
+#
+# The `pdb_command` function only supports version 5 of the `replace_facts`
+# command. Other commands might also work, but are not tested or supported
+# by Bolt.
+#
+# See the [commands endpoint](https://puppet.com/docs/puppetdb/latest/api/command/v1/commands.html)
+# documentation for more information about available commands and payload
+# format.
+#
+# _This function is experimental and subject to change._
+#
+# > **Note:** Not available in apply block
+#
+Puppet::Functions.create_function(:puppetdb_command) do
+  # Send a command with a payload to PuppetDB.
+  #
+  # @param command The command to invoke.
+  # @param version The version of the command to invoke.
+  # @param payload The payload to the command.
+  # @return The UUID identifying the response sent by PuppetDB.
+  # @example Replace facts for a target
+  #   $payload = {
+  #     'certname'           => 'localhost',
+  #     'environment'        => 'dev',
+  #     'producer'           => 'bolt',
+  #     'producer_timestamp' => '1970-01-01',
+  #     'values'             => { 'orchestrator' => 'bolt' }
+  #   }
+  #
+  #   puppetdb_command('replace_facts', 5, $payload)
+  dispatch :puppetdb_command do
+    param 'String[1]', :command
+    param 'Integer', :version
+    param 'Hash[Data, Data]', :payload
+    return_type 'String'
+  end
+
+  # Send a command with a payload to a named PuppetDB instance.
+  #
+  # @param command The command to invoke.
+  # @param version The version of the command to invoke.
+  # @param payload The payload to the command.
+  # @param instance The PuppetDB instance to send the command to.
+  # @return The UUID identifying the response sent by PuppetDB.
+  # @example Replace facts for a target using a named PuppetDB instance
+  #   $payload = {
+  #     'certname'           => 'localhost',
+  #     'environment'        => 'dev',
+  #     'producer'           => 'bolt',
+  #     'producer_timestamp' => '1970-01-01',
+  #     'values'             => { 'orchestrator' => 'bolt' }
+  #   }
+  #
+  #   puppetdb_command('replace_facts', 5, $payload, 'instance-1')
+  dispatch :puppetdb_command_with_instance do
+    param 'String[1]', :command
+    param 'Integer', :version
+    param 'Hash[Data, Data]', :payload
+    param 'String', :instance
+    return_type 'String'
+  end
+
+  def puppetdb_command(command, version, payload)
+    puppetdb_command_with_instance(command, version, payload, nil)
+  end
+
+  def puppetdb_command_with_instance(command, version, payload, instance)
+    # Disallow in apply blocks.
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+        action: 'puppetdb_command'
+      )
+    end
+
+    # Send analytics report.
+    Puppet.lookup(:bolt_executor).report_function_call(self.class.name)
+
+    puppetdb_client = Puppet.lookup(:bolt_pdb_client)
+
+    # Error if the PDB client does not implement :send_command
+    unless puppetdb_client.respond_to?(:send_command)
+      raise Bolt::Error.new(
+        "PuppetDB client #{puppetdb_client.class} does not implement :send_command, "\
+        "unable to invoke command.",
+        'bolt/pdb-command'
+      )
+    end
+
+    puppetdb_client.send_command(command, version, payload, instance)
+  end
+end

data/bolt-modules/boltlib/lib/puppet/functions/puppetdb_fact.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Collects facts based on a list of certnames.
+#
+# If a node is not found in PuppetDB, it's included in the returned hash with an empty facts hash.
+# Otherwise, the node is included in the hash with a value that is a hash of its facts.
+Puppet::Functions.create_function(:puppetdb_fact) do
+  # Collect facts from PuppetDB.
+  #
+  # @param certnames Array of certnames.
+  # @return A hash of certname to facts hash for each matched Target.
+  # @example Get facts for nodes
+  #   puppetdb_fact(['app.example.com', 'db.example.com'])
+  dispatch :puppetdb_fact do
+    param 'Array[String]', :certnames
+    return_type 'Hash[String, Data]'
+  end
+
+  # Collects facts from a named PuppetDB instance.
+  #
+  # @param certnames Array of certnames.
+  # @param instance The PuppetDB instance to query.
+  # @return A hash of certname to facts hash for each matched Target.
+  # @example Get facts for nodes from a named PuppetDB instance
+  #   puppetdb_fact(['app.example.com', 'db.example.com'], 'instance-1')
+  dispatch :puppetdb_fact_with_instance do
+    param 'Array[String]', :certnames
+    param 'String', :instance
+    return_type 'Hash[String, Data]'
+  end
+
+  def puppetdb_fact(certnames)
+    puppetdb_fact_with_instance(certnames, nil)
+  end
+
+  def puppetdb_fact_with_instance(certnames, instance)
+    puppetdb_client = Puppet.lookup(:bolt_pdb_client)
+    # Bolt executor not expected when invoked from apply block
+    executor = Puppet.lookup(:bolt_executor) { nil }
+    # Send Analytics Report
+    executor&.report_function_call(self.class.name)
+
+    puppetdb_client.facts_for_node(certnames, instance)
+  end
+end

data/bolt-modules/boltlib/lib/puppet/functions/puppetdb_query.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Makes a query to [puppetdb](https://puppet.com/docs/puppetdb/latest/index.html)
+# using Bolt's PuppetDB client.
+Puppet::Functions.create_function(:puppetdb_query) do
+  # rubocop:disable Layout/LineLength
+  # Make a query to PuppetDB.
+  #
+  # @param query A PQL query.
+  #   Learn more about [Puppet's query language](https://puppet.com/docs/puppetdb/latest/api/query/tutorial-pql.html), PQL.
+  # @return Results of the PuppetDB query.
+  # @example Request certnames for all nodes
+  #   puppetdb_query('nodes[certname] {}')
+  # rubocop:enable Layout/LineLength
+  dispatch :make_query do
+    param 'Variant[String, Array[Data]]', :query
+    return_type 'Array[Data]'
+  end
+
+  # rubocop:disable Layout/LineLength
+  # Make a query to a named PuppetDB instance.
+  #
+  # @param query A PQL query.
+  #   Learn more about [Puppet's query language](https://puppet.com/docs/puppetdb/latest/api/query/tutorial-pql.html), PQL.
+  # @param instance The PuppetDB instance to query.
+  # @return Results of the PuppetDB query.
+  # @example Request certnames for all nodes using a named PuppetDB instance
+  #   puppetdb_query('nodes[certname] {}', 'instance-1')
+  # rubocop:enable Layout/LineLength
+  dispatch :make_query_with_instance do
+    param 'Variant[String, Array[Data]]', :query
+    param 'String', :instance
+    return_type 'Array[Data]'
+  end
+  # The query type could be more specific ASTQuery = Array[Variant[String, ASTQuery]]
+
+  def make_query(query)
+    make_query_with_instance(query, nil)
+  end
+
+  def make_query_with_instance(query, instance)
+    puppetdb_client = Puppet.lookup(:bolt_pdb_client)
+    # Bolt executor not expected when invoked from apply block
+    executor = Puppet.lookup(:bolt_executor) { nil }
+    # Send Analytics Report
+    executor&.report_function_call(self.class.name)
+
+    puppetdb_client.make_query(query, nil, instance)
+  end
+end

data/bolt-modules/boltlib/lib/puppet/functions/remove_from_group.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Removes a target from the specified inventory group.
+#
+# The target is removed from all child groups and all parent groups where the target has
+# not been explicitly defined. A target cannot be removed from the `all` group.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:remove_from_group) do
+  # @param target A pattern identifying a single target.
+  # @param group The name of the group to remove the target from.
+  # @return [nil]
+  # @example Remove Target from group.
+  #   remove_from_group('foo@example.com', 'group1')
+  # @example Remove failing Targets from the rest of a plan
+  #   $result = run_command(uptime, my_group, '_catch_errors' => true)
+  #   $result.error_set.targets.each |$t| { remove_from_group($t, my_group) }
+  #   run_command(next_command, my_group) # does not target the failing nodes.
+  dispatch :remove_from_group do
+    param 'Boltlib::TargetSpec', :target
+    param 'String[1]', :group
+  end
+
+  def remove_from_group(target, group)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+                              action: 'remove_from_group')
+    end
+
+    inventory = Puppet.lookup(:bolt_inventory)
+    executor = Puppet.lookup(:bolt_executor)
+    # Send Analytics Report
+    executor.report_function_call(self.class.name)
+
+    inventory.remove_from_group(inventory.get_targets(target), group)
+  end
+end

data/bolt-modules/boltlib/lib/puppet/functions/resolve_references.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+
+# Evaluates all `_plugin` references in a hash and returns the resolved reference data.
+Puppet::Functions.create_function(:resolve_references) do
+  # Resolve references.
+  # @param references A hash of reference data to resolve.
+  # @return A hash of resolved reference data.
+  # @example Resolve a hash of reference data
+  #   $references = {
+  #     "targets" => [
+  #       "_plugin" => "terraform",
+  #       "dir" => "path/to/terraform/project",
+  #       "resource_type" => "aws_instance.web",
+  #       "uri" => "public_ip"
+  #     ]
+  #   }
+  #
+  #   resolve_references($references)
+  dispatch :resolve_references do
+    param 'Data', :references
+    return_type 'Data'
+  end
+
+  def resolve_references(references)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(
+          Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+          action: 'resolve_references'
+        )
+    end
+
+    executor = Puppet.lookup(:bolt_executor)
+    # Send Analytics Report
+    executor.report_function_call(self.class.name)
+
+    plugins = Puppet.lookup(:bolt_inventory).plugins
+    plugins.resolve_references(references)
+  end
+end

data/bolt-modules/boltlib/lib/puppet/functions/resource.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+# Lookup a resource in the target's data.
+#
+# For more information about resources see [the
+# documentation](https://puppet.com/docs/puppet/latest/lang_resources.html).
+#
+# > **Note:** The `ResourceInstance` data type is under active development and is subject to
+#   change. You can read more about the data type in the [experimental features
+#   documentation](experimental_features.md#resourceinstance-data-type).
+Puppet::Functions.create_function(:resource) do
+  # Lookup a resource in the target's data.
+  # @param target The Target object to add resources to. See {get_targets}.
+  # @param type The type of the resource
+  # @param title The title of the resource
+  # @return The ResourceInstance if found, or Undef
+  # @example Get the openssl package resource
+  #   $target.apply_prep
+  #   $resources = $target.get_resources(Package).first['resources']
+  #   $target.set_resources($resources)
+  #   $openssl = $target.resource('Package', 'openssl')
+  dispatch :resource do
+    param 'Target', :target
+    param 'Type[Resource]', :type
+    param 'String[1]', :title
+    return_type 'Optional[ResourceInstance]'
+  end
+
+  # Lookup a resource in the target's data, referring to resource as a string
+  # @param target The Target object to add resources to. See {get_targets}.
+  # @param type The type of the resource
+  # @param title The title of the resource
+  # @return The ResourceInstance if found, or Undef
+  dispatch :resource_from_string do
+    param 'Target', :target
+    param 'String[1]', :type
+    param 'String[1]', :title
+    return_type 'Optional[ResourceInstance]'
+  end
+
+  def resource(target, type, title)
+    inventory = Puppet.lookup(:bolt_inventory)
+    executor  = Puppet.lookup(:bolt_executor) { nil }
+    # Send Analytics Report
+    executor&.report_function_call(self.class.name)
+
+    inventory.resource(target, type, title)
+  end
+
+  def resource_from_string(target, type, title)
+    resource(target, type, title)
+  end
+end

data/bolt-modules/boltlib/lib/puppet/functions/run_command.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+require 'bolt/error'
+require 'json'
+
+# Runs a command on the given set of targets and returns the result from each command execution.
+# This function does nothing if the list of targets is empty.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:run_command) do
+  # Run a command.
+  # @param command A command to run on target.
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param options A hash of additional options.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @option options [String] _run_as User to run as using privilege escalation.
+  # @option options [Hash[String, Any]] _env_vars Map of environment variables to set
+  # @return A list of results, one entry per target.
+  # @example Run a command on targets
+  #   run_command('hostname', $targets, '_catch_errors' => true)
+  dispatch :run_command do
+    param 'String[1]', :command
+    param 'Boltlib::TargetSpec', :targets
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'ResultSet'
+  end
+
+  # Run a command, logging the provided description.
+  # @param command A command to run on target.
+  # @param targets A pattern identifying zero or more targets. See {get_targets} for accepted patterns.
+  # @param description A description to be output when calling this function.
+  # @param options A hash of additional options.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @option options [String] _run_as User to run as using privilege escalation.
+  # @option options [Hash[String, Any]] _env_vars Map of environment variables to set
+  # @return A list of results, one entry per target.
+  # @example Run a command on targets
+  #   run_command('hostname', $targets, 'Get hostname')
+  dispatch :run_command_with_description do
+    param 'String[1]', :command
+    param 'Boltlib::TargetSpec', :targets
+    param 'String', :description
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'ResultSet'
+  end
+
+  def run_command(command, targets, options = {})
+    run_command_with_description(command, targets, nil, options)
+  end
+
+  def run_command_with_description(command, targets, description = nil, options = {})
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'run_command')
+    end
+
+    options = options.transform_keys { |k| k.sub(/^_/, '').to_sym }
+    options[:description] = description if description
+
+    # Ensure env_vars is a hash and that each hash value is transformed to JSON
+    # so we don't accidentally pass Ruby-style data to the target.
+    if options[:env_vars]
+      unless options[:env_vars].is_a?(Hash)
+        raise Bolt::ValidationError, "Option 'env_vars' must be a hash"
+      end
+
+      if (bad_keys = options[:env_vars].keys.reject { |k| k.is_a?(String) }).any?
+        raise Bolt::ValidationError,
+              "Keys for option 'env_vars' must be strings: #{bad_keys.map(&:inspect).join(', ')}"
+      end
+
+      options[:env_vars] = options[:env_vars].transform_values do |val|
+        [Array, Hash].include?(val.class) ? val.to_json : val
+      end
+    end
+
+    executor = Puppet.lookup(:bolt_executor)
+    inventory = Puppet.lookup(:bolt_inventory)
+
+    # Send Analytics Report
+    executor.report_function_call(self.class.name)
+
+    # Ensure that given targets are all Target instances
+    targets = inventory.get_targets(targets)
+
+    if targets.empty?
+      call_function('debug', "Simulating run_command('#{command}') - no targets given - no action taken")
+      Bolt::ResultSet.new([])
+    else
+      file_line = Puppet::Pops::PuppetStack.top_of_stack
+      r = if executor.in_parallel?
+            executor.run_in_thread do
+              executor.run_command(targets, command, options, file_line)
+            end
+          else
+            executor.run_command(targets, command, options, file_line)
+          end
+
+      if !r.ok && !options[:catch_errors]
+        raise Bolt::RunFailure.new(r, 'run_command', command)
+      end
+
+      r
+    end
+  end
+end