bolt 3.8.0 → 3.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f4c856f3322c88dabb51efe39bc7373d96e33f6274785188900e8fbb5488436
-  data.tar.gz: 5e5da3f150093febfc2b6d7e343e9995ea33b044fb4941ed9229944e4735aa72
+  metadata.gz: fa1075046a81e0596ff3f0483dc7b7a5913a073dd6e998f66c70687049531e74
+  data.tar.gz: 9cdb2d3503e1bd2d84fa7c0fc846e3f4d2293780f648d9d07d549fd50d2b1a51
 SHA512:
-  metadata.gz: 8f88f29b98a7bab28a4bbae5e860bb4c94fca20dd994241b71f2e5327934a92db1370c77fdb03d5f9a033e626b726e379e3eec510f0316b67b0807aa86920b67
-  data.tar.gz: 8cf9a3bbfde78b7930089a7ada109e03bba5439ea8ef3049d3fa58bc589914881969be783fe667ef5c238613e126c7f79d7dd0db30fcd2f5d9147999086d1df7
+  metadata.gz: 4b2f636ec7f5f038b69cd5c4f82e9fd93e59521035e15fa678cef67501a4e00287e29f40ce1672d2f5db0fa4972cbc26d9763f62480612e30ebcfae404d12a1f
+  data.tar.gz: f87b3966ea10cf5a5fe46937e9a47b73d4553924bff00ee578f6c659a70fe82864e2cc78b76a685dfb9e3d4a4e5a3fb7bea136730bf6b5160454e665f4f02ea8

data/bolt-modules/boltlib/lib/puppet/datatypes/future.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# The [`background()` plan function](plan_functions.md#background) returns a
+# `Future` object, which can be passed to the [`wait()` plan
+# function](plan_functions.md#wait) to block on the result of the backgrounded
+# code block.
+#
+# @!method state
+#   Either 'running' if the Future is still executing, 'done' if the Future
+#   finished successfully, or 'error' if the Future finished with an error.
+#
+Puppet::DataTypes.create_type('Future') do
+  interface <<-PUPPET
+    attributes => {},
+    functions => {
+      state => Callable[[], Enum['running', 'done', 'error']],
+    }
+  PUPPET
+
+  load_file('bolt/plan_future')
+
+  # Needed for Puppet to recognize Bolt::Result as a Puppet object when deserializing
+  Bolt::PlanFuture.include(Puppet::Pops::Types::PuppetObject)
+  implementation_class Bolt::PlanFuture
+end

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

@@ -16,6 +16,7 @@ Puppet::Functions.create_function(:apply_prep) do
   # @param targets A pattern or array of patterns identifying a set of targets.
   # @param options Options hash.
   # @option options [Array] _required_modules An array of modules to sync to the target.
+  # @option options [String] _run_as User to run as using privilege escalation.
   # @return [nil]
   # @example Prepare targets by name.
   #   apply_prep('target1,target2')
@@ -71,7 +72,8 @@ Puppet::Functions.create_function(:apply_prep) do
         .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'apply_prep')
     end
 
-    options = options.transform_keys { |k| k.sub(/^_/, '').to_sym }
+    # Unfreeze this
+    options = options.slice(*%w[_run_as _required_modules])
 
     applicator = Puppet.lookup(:apply_executor)
 
@@ -79,14 +81,14 @@ Puppet::Functions.create_function(:apply_prep) do
 
     targets = inventory.get_targets(target_spec)
 
-    required_modules = options[:required_modules].nil? ? nil : Array(options[:required_modules])
-    if required_modules&.any?
+    required_modules = options.delete('_required_modules').to_a
+    if required_modules.any?
       Puppet.debug("Syncing only required modules: #{required_modules.join(',')}.")
     end
 
     # Gather facts, including custom facts
     plugins = applicator.build_plugin_tarball do |mod|
-      next unless required_modules.nil? || required_modules.include?(mod.name)
+      next unless required_modules.empty? || required_modules.include?(mod.name)
       search_dirs = []
       search_dirs << mod.plugins if mod.plugins?
       search_dirs << mod.pluginfacts if mod.pluginfacts?
@@ -107,8 +109,9 @@ Puppet::Functions.create_function(:apply_prep) do
             opts = t.plugin_hooks&.fetch('puppet_library').dup
             plugin_name = opts.delete('plugin')
             hook = inventory.plugins.get_hook(plugin_name, :puppet_library)
+            # Give plan function options precedence over inventory options
             { 'target' => t,
-              'hook_proc' => hook.call(opts, t, self) }
+              'hook_proc' => hook.call(opts.merge(options), t, self) }
           rescue StandardError => e
             Bolt::Result.from_exception(t, e)
           end
@@ -132,7 +135,7 @@ Puppet::Functions.create_function(:apply_prep) do
 
         task = applicator.custom_facts_task
         arguments = { 'plugins' => Puppet::Pops::Types::PSensitiveType::Sensitive.new(plugins) }
-        results = executor.run_task(targets, task, arguments)
+        results = run_task(targets, task, arguments, options)
 
         # TODO: Standardize RunFailure type with error above
         raise Bolt::RunFailure.new(results, 'run_task', task.name) unless results.ok?

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

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Starts a block of code in parallel with the main plan without blocking.
+# Returns a Future object.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:background, Puppet::Functions::InternalFunction) do
+  # Starts a block of code in parallel with the main plan without blocking.
+  # Returns a Future object.
+  # @param name An optional name for legible logs.
+  # @param block The code block to run in the background.
+  # @return A Bolt Future object
+  # @example Start a long-running process
+  #   background() || {
+  #     run_task('superlong::task', $targets)
+  #   }
+  #   run_command("echo 'Continue immediately'", $targets)
+  dispatch :background do
+    scope_param
+    optional_param 'String[1]', :name
+    block_param 'Callable[0, 0]', :block
+    return_type 'Future'
+  end
+
+  def background(scope, name = nil, &block)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'background')
+    end
+
+    executor = Puppet.lookup(:bolt_executor)
+    executor.report_function_call(self.class.name)
+
+    executor.create_future(scope: scope, name: name) do |newscope|
+      # Catch 'return' calls inside the block
+      result = catch(:return) do
+        # 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, {}, 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
+end

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

@@ -112,17 +112,13 @@ Puppet::Functions.create_function(:download_file, Puppet::Functions::InternalFun
       call_function('debug', "Simulating file download of '#{source}' - no targets given - no action taken")
       Bolt::ResultSet.new([])
     else
-      r = if executor.in_parallel
-            require 'concurrent'
-            require 'fiber'
-            future = Concurrent::Future.execute do
-              executor.download_file(targets, source, destination, options, Puppet::Pops::PuppetStack.top_of_stack)
+      file_line = Puppet::Pops::PuppetStack.top_of_stack
+      r = if executor.in_parallel?
+            executor.run_in_thread do
+              executor.download_file(targets, source, destination, options, file_line)
             end
-
-            Fiber.yield('unfinished') while future.incomplete?
-            future.value || future.reason
           else
-            executor.download_file(targets, source, destination, options, Puppet::Pops::PuppetStack.top_of_stack)
+            executor.download_file(targets, source, destination, options, file_line)
           end
 
       if !r.ok && !options[:catch_errors]

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

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'bolt/yarn'
-
 # Map a code block onto an array, where each array element executes in parallel.
 # This function is experimental.
 #
@@ -35,21 +33,38 @@ Puppet::Functions.create_function(:parallelize, Puppet::Functions::InternalFunct
     executor = Puppet.lookup(:bolt_executor)
     executor.report_function_call(self.class.name)
 
-    skein = data.each_with_index.map do |object, index|
-      executor.create_yarn(scope, block, object, index)
-    end
+    futures = data.map do |object|
+      executor.create_future(scope: scope) 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
 
-    result = executor.round_robin(skein)
+        # 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)
 
-    failed_indices = result.each_index.select do |i|
-      result[i].is_a?(Bolt::Error)
-    end
+        # 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
 
-    # TODO: Inner catch errors block?
-    if failed_indices.any?
-      raise Bolt::ParallelFailure.new(result, failed_indices)
+        result
+      rescue Puppet::PreformattedError => e
+        if e.cause.is_a?(Bolt::Error)
+          e.cause
+        else
+          raise e
+        end
+      end
     end
 
-    result
+    # We may eventually want parallelize to accept a timeout
+    executor.wait(futures)
   end
 end

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

@@ -87,23 +87,13 @@ Puppet::Functions.create_function(:run_command) do
       call_function('debug', "Simulating run_command('#{command}') - no targets given - no action taken")
       Bolt::ResultSet.new([])
     else
-      r = if executor.in_parallel
-            require 'concurrent'
-            require 'fiber'
-            future = Concurrent::Future.execute do
-              executor.run_command(targets,
-                                   command,
-                                   options,
-                                   Puppet::Pops::PuppetStack.top_of_stack)
+      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
-
-            Fiber.yield('unfinished') while future.incomplete?
-            future.value || future.reason
           else
-            executor.run_command(targets,
-                                 command,
-                                 options,
-                                 Puppet::Pops::PuppetStack.top_of_stack)
+            executor.run_command(targets, command, options, file_line)
           end
 
       if !r.ok && !options[:catch_errors]

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

@@ -130,25 +130,13 @@ Puppet::Functions.create_function(:run_script, Puppet::Functions::InternalFuncti
     if targets.empty?
       Bolt::ResultSet.new([])
     else
-      r = if executor.in_parallel
-            require 'concurrent'
-            require 'fiber'
-            future = Concurrent::Future.execute do
-              executor.run_script(targets,
-                                  found,
-                                  arguments,
-                                  options,
-                                  Puppet::Pops::PuppetStack.top_of_stack)
+      file_line = Puppet::Pops::PuppetStack.top_of_stack
+      r = if executor.in_parallel?
+            executor.run_in_thread do
+              executor.run_script(targets, found, arguments, options, file_line)
             end
-
-            Fiber.yield('unfinished') while future.incomplete?
-            future.value || future.reason
           else
-            executor.run_script(targets,
-                                found,
-                                arguments,
-                                options,
-                                Puppet::Pops::PuppetStack.top_of_stack)
+            executor.run_script(targets, found, arguments, options, file_line)
           end
 
       if !r.ok && !options[:catch_errors]

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

@@ -130,28 +130,19 @@ Puppet::Functions.create_function(:run_task) do
       end
     end
 
+    # Report whether the task was run in noop mode.
+    executor.report_noop_mode(executor.noop || options[:noop])
+
     if targets.empty?
       Bolt::ResultSet.new([])
     else
-      result = if executor.in_parallel
-                 require 'concurrent'
-                 require 'fiber'
-                 future = Concurrent::Future.execute do
-                   executor.run_task(targets,
-                                     task,
-                                     params,
-                                     options,
-                                     Puppet::Pops::PuppetStack.top_of_stack)
+      file_line = Puppet::Pops::PuppetStack.top_of_stack
+      result = if executor.in_parallel?
+                 executor.run_in_thread do
+                   executor.run_task(targets, task, params, options, file_line)
                  end
-
-                 Fiber.yield('unfinished') while future.incomplete?
-                 future.value || future.reason
                else
-                 executor.run_task(targets,
-                                   task,
-                                   params,
-                                   options,
-                                   Puppet::Pops::PuppetStack.top_of_stack)
+                 executor.run_task(targets, task, params, options, file_line)
                end
 
       if !result.ok && !options[:catch_errors]

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

@@ -175,28 +175,21 @@ Puppet::Functions.create_function(:run_task_with) do
       end
     end
 
+    # Report whether the task was run in noop mode.
+    executor.report_noop_mode(executor.noop || options[:noop])
+
     if targets.empty?
       Bolt::ResultSet.new([])
     else
       # Combine the results from the task run with any failing results that were
       # generated earlier when creating the target mapping
-      task_result = if executor.in_parallel
-                      require 'concurrent'
-                      require 'fiber'
-                      future = Concurrent::Future.execute do
-                        executor.run_task_with(target_mapping,
-                                               task,
-                                               options,
-                                               Puppet::Pops::PuppetStack.top_of_stack)
+      file_line = Puppet::Pops::PuppetStack.top_of_stack
+      task_result = if executor.in_parallel?
+                      executor.run_in_thread do
+                        executor.run_task_with(target_mapping, task, options, file_line)
                       end
-
-                      Fiber.yield('unfinished') while future.incomplete?
-                      future.value || future.reason
                     else
-                      executor.run_task_with(target_mapping,
-                                             task,
-                                             options,
-                                             Puppet::Pops::PuppetStack.top_of_stack)
+                      executor.run_task_with(target_mapping, task, options, file_line)
                     end
       result = Bolt::ResultSet.new(task_result.results + error_set)
 

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

@@ -87,25 +87,13 @@ Puppet::Functions.create_function(:upload_file, Puppet::Functions::InternalFunct
       call_function('debug', "Simulating file upload of '#{found}' - no targets given - no action taken")
       Bolt::ResultSet.new([])
     else
-      r = if executor.in_parallel
-            require 'concurrent'
-            require 'fiber'
-            future = Concurrent::Future.execute do
-              executor.upload_file(targets,
-                                   found,
-                                   destination,
-                                   options,
-                                   Puppet::Pops::PuppetStack.top_of_stack)
+      file_line = Puppet::Pops::PuppetStack.top_of_stack
+      r = if executor.in_parallel?
+            executor.run_in_thread do
+              executor.upload_file(targets, found, destination, options, file_line)
             end
-
-            Fiber.yield('unfinished') while future.incomplete?
-            future.value || future.reason
           else
-            executor.upload_file(targets,
-                                 found,
-                                 destination,
-                                 options,
-                                 Puppet::Pops::PuppetStack.top_of_stack)
+            executor.upload_file(targets, found, destination, options, file_line)
           end
       if !r.ok && !options[:catch_errors]
         raise Bolt::RunFailure.new(r, 'upload_file', source)

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

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require 'bolt/logger'
+require 'bolt/target'
+
+# Wait for a Future or array of Futures to finish and return results,
+# optionally with a timeout.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:wait, Puppet::Functions::InternalFunction) do
+  # Wait for Future(s) to finish
+  # @param futures A Bolt Future object or array of Bolt Futures to wait on.
+  # @param options A hash of additional options.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @return A Result or Results from the Futures
+  # @example Upload a large file in the background, then wait until it's loaded
+  #   $futures = background() || {
+  #     upload_file("./very_large_file", "/opt/jfrog/artifactory/var/etc/artifactory", $targets)
+  #   }
+  #   # Run an unrelated task
+  #   run_task("deploy", $targets)
+  #   # Wait for the file upload to finish
+  #   $results = wait($futures)
+  dispatch :wait do
+    param 'Variant[Future, Array[Future]]', :futures
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'Array[Boltlib::PlanResult]'
+  end
+
+  # Wait for Future(s) to finish with timeout
+  # @param futures A Bolt Future object or array of Bolt Futures to wait on.
+  # @param timeout How long to wait for Futures to finish before raising a Timeout error.
+  # @param options A hash of additional options.
+  # @option options [Boolean] _catch_errors Whether to catch raised errors.
+  # @return A Result or Results from the Futures
+  # @example Upload a large file in the background with a 30 second timeout.
+  #   $futures = background() || {
+  #     upload_file("./very_large_file", "/opt/jfrog/artifactory/var/etc/artifactory", $targets)
+  #   }
+  #   # Run an unrelated task
+  #   run_task("deploy", $targets)
+  #   # Wait for the file upload to finish
+  #   $results = wait($futures, 30)
+  #
+  # @example Upload a large file in the background with a 30 second timeout, catching any errors.
+  #   $futures = background() || {
+  #     upload_file("./very_large_file", "/opt/jfrog/artifactory/var/etc/artifactory", $targets)
+  #   }
+  #   # Run an unrelated task
+  #   run_task("deploy", $targets)
+  #   # Wait for the file upload to finish
+  #   $results = wait($futures, 30, '_catch_errors' => true)
+  dispatch :wait_with_timeout do
+    param 'Variant[Future, Array[Future]]', :futures
+    param 'Variant[Integer[0], Float[0.0]]', :timeout
+    optional_param 'Hash[String[1], Any]', :options
+    return_type 'Array[Boltlib::PlanResult]'
+  end
+
+  def wait(futures, options = {})
+    inner_wait(futures, nil, options)
+  end
+
+  def wait_with_timeout(futures, timeout, options = {})
+    inner_wait(futures, timeout, options)
+  end
+
+  def inner_wait(futures, timeout = nil, options = {})
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'wait')
+    end
+
+    valid, unknown = options.partition { |k, _v| %w[_catch_errors].include?(k) }.map(&:to_h)
+    if unknown.any?
+      file, line = Puppet::Pops::PuppetStack.top_of_stack
+      msg = "The wait() function call in #{file}#L#{line} received unknown options "\
+        "#{unknown.keys}. Removing unknown options and continuing..."
+      Bolt::Logger.warn("plan_function_options", msg)
+    end
+
+    valid = valid.transform_keys { |k| k.sub(/^_/, '').to_sym }
+    valid[:timeout] = timeout if timeout
+
+    executor = Puppet.lookup(:bolt_executor)
+    executor.report_function_call(self.class.name)
+
+    futures = Array(futures)
+    executor.wait(futures, **valid)
+  end
+end