bolt 3.12.0 → 3.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6b7b8c5255bf4fcfcfe96a63f2dd479a92018a0a5cccd3898d1ad405232ad7ff
-  data.tar.gz: 83cb6eb774b74151c3b6eee76562c0c588da592b3f97a6d744995330cceb7079
+  metadata.gz: 80a2245a2ac92c15284c4d6206f5480c6cf72033b32b773a98303b634f853e54
+  data.tar.gz: 4a6e868eba652ea23cb8530a135e3187fae81296d63df8bf9b54d5c2117df615
 SHA512:
-  metadata.gz: dfddff8a230e8995804f304e79f0de6a2aa04149fae2c9c5ba1412afb073e5aab31e0c922b14935344c65672195f757e5326e7a7dbd7995acb97b98d154adbc8
-  data.tar.gz: f4bc0bfe2f2f12f94c2fe93e0caf2ce6a011b0e25a8d5e933632d6438e86232ec931936d66734bcbba2a955164ef5989f95a271d22aab963d58376d4ed5d6dd3
+  metadata.gz: f7373197cc0401a971ff8e68ed70ef31f90d2087d09a5a0a5178124e40d2aae59546db768480fb5ea65f2b2993d60104abcf137df281863ddaf37c69d58365e5
+  data.tar.gz: 338c72c31cc379aaf45adae5a122a2a2e9fe6dede738aec4b46c21b5102d16a00ee5a494514dd80bc9f4fcd922ee08e62164e64d34987d40ad1d7383ff475363

data/bolt-modules/log/lib/puppet/functions/log/debug.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'bolt/util/format'
+
+# Log a debugging message.
+#
+# Messages logged at this level typically include detailed information about
+# what a plan is doing. For example, you might log a message at the `debug`
+# level that shows what value is returned from a function invocation.
+#
+# See [Logs](logs.md) for more information about Bolt's log levels.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'log::debug') do
+  # Log a debugging message.
+  # @param message The message to log.
+  # @example Log a debugging message
+  #   log::debug("Function frogsay returned: ${result}")
+  dispatch :log_debug do
+    param 'Any', :message
+    return_type 'Undef'
+  end
+
+  def log_debug(message)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+        action: 'log::debug'
+      )
+    end
+
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :log, level: :debug, message: Bolt::Util::Format.stringify(message))
+    end
+
+    nil
+  end
+end

data/bolt-modules/log/lib/puppet/functions/log/error.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'bolt/util/format'
+
+# Log an error message.
+#
+# Messages logged at this level typically indicate that the plan encountered an
+# error that can be recovered from. For example, you might log a message at the
+# `error` level if you want to inform the user an action running on a target
+# failed but that the plan will continue running.
+#
+# See [Logs](logs.md) for more information about Bolt's log levels.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'log::error') do
+  # Log an error message.
+  # @param message The message to log.
+  # @example Log an error message
+  #   log::error("The HTTP request returned an error, continuing the plan: ${result}")
+  dispatch :log_error do
+    param 'Any', :message
+    return_type 'Undef'
+  end
+
+  def log_error(message)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+        action: 'log::error'
+      )
+    end
+
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :log, level: :error, message: Bolt::Util::Format.stringify(message))
+    end
+
+    nil
+  end
+end

data/bolt-modules/log/lib/puppet/functions/log/fatal.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'bolt/util/format'
+
+# Log a fatal message.
+#
+# Messages logged at this level indicate that the plan encountered an error that
+# could not be recovered from. For example, you might log a message at the
+# `fatal` level if a service is unavailable and the plan cannot continue running
+# without it.
+#
+# See [Logs](logs.md) for more information about Bolt's log levels.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'log::fatal') do
+  # Log a fatal message.
+  # @param message The message to log.
+  # @example Log a fatal message
+  #   log::fatal("The service is unavailable, unable to continue running: ${result}")
+  dispatch :log_fatal do
+    param 'Any', :message
+    return_type 'Undef'
+  end
+
+  def log_fatal(message)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+        action: 'log::fatal'
+      )
+    end
+
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :log, level: :fatal, message: Bolt::Util::Format.stringify(message))
+    end
+
+    nil
+  end
+end

data/bolt-modules/log/lib/puppet/functions/log/info.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'bolt/util/format'
+
+# Log an info message.
+#
+# Messages logged at this level typically include high-level information about
+# what a plan is doing. For example, you might log a message at the `info` level
+# that informs users that the plan is reading a file on disk.
+#
+# See [Logs](logs.md) for more information about Bolt's log levels.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'log::info') do
+  # Log an info message.
+  # @param message The message to log.
+  # @example Log an info message
+  #   log::info("Reading network device command file ${file}.")
+  dispatch :log_info do
+    param 'Any', :message
+    return_type 'Undef'
+  end
+
+  def log_info(message)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+        action: 'log::info'
+      )
+    end
+
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :log, level: :info, message: Bolt::Util::Format.stringify(message))
+    end
+
+    nil
+  end
+end

data/bolt-modules/log/lib/puppet/functions/log/trace.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require 'bolt/util/format'
+
+# Log a trace message.
+#
+# Messages logged at this level typically include the most detailed information
+# about what a plan is doing. For example, you might log a message at the `trace`
+# level that describes how a plan is manipulating data.
+#
+# See [Logs](logs.md) for more information about Bolt's log levels.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'log::trace') do
+  # Log a trace message.
+  # @param message The message to log.
+  # @example Log a trace message
+  #   log::trace("Creating Target object with data ${data} from file ${file}")
+  dispatch :log_trace do
+    param 'Any', :message
+    return_type 'Undef'
+  end
+
+  def log_trace(message)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+        action: 'log::trace'
+      )
+    end
+
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :log, level: :trace, message: Bolt::Util::Format.stringify(message))
+    end
+
+    nil
+  end
+end

data/bolt-modules/log/lib/puppet/functions/log/warn.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require 'bolt/util/format'
+
+# Log a warning message.
+#
+# Messages logged at this level typically include messages about deprecated
+# behavior or potentially harmful situations that might affect the plan run.
+# For example, you might log a message at the `warn` level if you are
+# planning to make a breaking change to your plan in a future release and
+# want to notify users.
+#
+# See [Logs](logs.md) for more information about Bolt's log levels.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'log::warn') do
+  # Log a warning message.
+  # @param message The message to log.
+  # @example Log a warning message
+  #   log::warn('This plan will no longer install the package in a future release.')
+  dispatch :log_warn do
+    param 'Any', :message
+    return_type 'Undef'
+  end
+
+  def log_warn(message)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue.from_issue_and_stack(
+        Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING,
+        action: 'log::warn'
+      )
+    end
+
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :log, level: :warn, message: Bolt::Util::Format.stringify(message))
+    end
+
+    nil
+  end
+end

data/bolt-modules/out/lib/puppet/functions/out/message.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'bolt/util/format'
+
 # Output a message for the user.
 #
 # This will print a message to stdout when using the human output format,
@@ -22,55 +24,11 @@ Puppet::Functions.create_function(:'out::message') do
         .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'out::message')
     end
 
-    executor = Puppet.lookup(:bolt_executor)
-    # Send Analytics Report
-    executor.report_function_call(self.class.name)
-
-    executor.publish_event(type: :message, message: stringify(message))
-
-    nil
-  end
-
-  def stringify(message)
-    formatted = format_message(message)
-    if formatted.is_a?(Hash) || formatted.is_a?(Array)
-      ::JSON.pretty_generate(formatted)
-    else
-      formatted
-    end
-  end
-
-  def format_message(message)
-    case message
-    when Array
-      message.map { |item| format_message(item) }
-    when Bolt::ApplyResult
-      format_apply_result(message)
-    when Bolt::Result, Bolt::ResultSet
-      # This is equivalent to to_s, but formattable
-      message.to_data
-    when Bolt::RunFailure
-      formatted_resultset = message.result_set.to_data
-      message.to_h.merge('result_set' => formatted_resultset)
-    when Hash
-      message.each_with_object({}) do |(k, v), h|
-        h[format_message(k)] = format_message(v)
-      end
-    when Integer, Float, NilClass
-      message
-    else
-      message.to_s
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :message, message: Bolt::Util::Format.stringify(message))
     end
-  end
 
-  def format_apply_result(result)
-    logs = result.resource_logs&.map do |log|
-      # Omit low-level info/debug messages
-      next if %w[info debug].include?(log['level'])
-      indent(2, format_log(log))
-    end
-    hash = result.to_data
-    hash['logs'] = logs unless logs.empty?
-    hash
+    nil
   end
 end

data/bolt-modules/out/lib/puppet/functions/out/verbose.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require 'bolt/util/format'
+
+# Output a message for the user when running in verbose mode.
+#
+# This will print a message to stdout when using the human output format,
+# and print to stderr when using the json output format.
+#
+# > **Note:** Not available in apply block
+Puppet::Functions.create_function(:'out::verbose') do
+  # @param message The message to output.
+  # @example Print a message
+  #   out::verbose('Something went wrong')
+  dispatch :output_verbose do
+    param 'Any', :message
+    return_type 'Undef'
+  end
+
+  def output_verbose(message)
+    unless Puppet[:tasks]
+      raise Puppet::ParseErrorWithIssue
+        .from_issue_and_stack(Bolt::PAL::Issues::PLAN_OPERATION_NOT_SUPPORTED_WHEN_COMPILING, action: 'out::verbose')
+    end
+
+    Puppet.lookup(:bolt_executor).tap do |executor|
+      executor.report_function_call(self.class.name)
+      executor.publish_event(type: :verbose, message: Bolt::Util::Format.stringify(message))
+    end
+
+    nil
+  end
+end

data/lib/bolt/bolt_option_parser.rb

@@ -1088,7 +1088,7 @@ module Bolt
       end
       define('--log-level LEVEL',
              "Set the log level for the console. Available options are",
-             "trace, debug, info, warn, error, fatal, any.") do |level|
+             "trace, debug, info, warn, error, fatal.") do |level|
         @options[:log] = { 'console' => { 'level' => level } }
       end
       define('--clear-cache',

data/lib/bolt/cli.rb

@@ -787,8 +787,8 @@ module Bolt
       if %w[human rainbow].include?(options.fetch(:format, 'human'))
         executor.subscribe(outputter)
       else
-        # Only subscribe to out::message events for JSON outputter
-        executor.subscribe(outputter, [:message])
+        # Only subscribe to out module events for JSON outputter
+        executor.subscribe(outputter, %i[message verbose])
       end
 
       executor.subscribe(log_outputter)

data/lib/bolt/config/options.rb

@@ -202,7 +202,7 @@ module Bolt
                 "level" => {
                   description: "The type of information to log.",
                   type: String,
-                  enum: %w[trace debug error info warn fatal any],
+                  enum: %w[trace debug error info warn fatal],
                   _default: "warn"
                 }
               }
@@ -221,7 +221,7 @@ module Bolt
               "level" => {
                 description: "The type of information to log.",
                 type: String,
-                enum: %w[trace debug error info warn fatal any],
+                enum: %w[trace debug error info warn fatal],
                 _default: "warn"
               }
             }

data/lib/bolt/outputter/human.rb

@@ -78,6 +78,8 @@ module Bolt
           @disable_depth += 1
         when :message
           print_message(event[:message])
+        when :verbose
+          print_message(event[:message]) if @verbose
         end
 
         if enabled?

data/lib/bolt/outputter/json.rb

@@ -23,6 +23,8 @@ module Bolt
           print_result(event[:result])
         when :message
           print_message(event[:message])
+        when :verbose
+          print_message(event[:message]) if @verbose
         end
       end
 

data/lib/bolt/outputter/logger.rb

@@ -24,6 +24,8 @@ module Bolt
           log_container_start(event)
         when :container_finish
           log_container_finish(event)
+        when :log
+          log_message(**event)
         end
       end
 
@@ -65,6 +67,10 @@ module Bolt
           @logger.info("Finished: run container '#{result.object}' failed.")
         end
       end
+
+      def log_message(level:, message:, **_kwargs)
+        @logger.send(level, message)
+      end
     end
   end
 end

data/lib/bolt/util/format.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Bolt
+  module Util
+    module Format
+      class << self
+        # Stringifies an object, formatted as valid JSON.
+        #
+        # @param message [Object] The object to stringify.
+        # @return [String] The JSON string.
+        #
+        def stringify(message)
+          formatted = format_message(message)
+          if formatted.is_a?(Hash) || formatted.is_a?(Array)
+            ::JSON.pretty_generate(formatted)
+          else
+            formatted
+          end
+        end
+
+        # Recursively formats an object into a format that can be represented by
+        # JSON.
+        #
+        # @param message [Object] The object to stringify.
+        # @return [Array, Hash, String]
+        #
+        private def format_message(message)
+          case message
+          when Array
+            message.map { |item| format_message(item) }
+          when Bolt::ApplyResult
+            format_apply_result(message)
+          when Bolt::Result, Bolt::ResultSet
+            # This is equivalent to to_s, but formattable
+            message.to_data
+          when Bolt::RunFailure
+            formatted_resultset = message.result_set.to_data
+            message.to_h.merge('result_set' => formatted_resultset)
+          when Hash
+            message.each_with_object({}) do |(k, v), h|
+              h[format_message(k)] = format_message(v)
+            end
+          when Integer, Float, NilClass
+            message
+          else
+            message.to_s
+          end
+        end
+
+        # Formats a Bolt::ApplyResult object.
+        #
+        # @param result [Bolt::ApplyResult] The apply result.
+        # @return [Hash]
+        #
+        private def format_apply_result(result)
+          logs = result.resource_logs&.map do |log|
+            # Omit low-level info/debug messages
+            next if %w[info debug].include?(log['level'])
+            indent(2, format_log(log))
+          end
+          hash = result.to_data
+          hash['logs'] = logs unless logs.empty?
+          hash
+        end
+      end
+    end
+  end
+end

data/lib/bolt/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bolt
-  VERSION = '3.12.0'
+  VERSION = '3.13.0'
 end

data/lib/bolt_server/transport_app.rb

@@ -120,9 +120,20 @@ module BoltServer
 
     def run_task(target, body)
       validate_schema(@schemas["action-run_task"], body)
+
       task_data = body['task']
       task = Bolt::Task::PuppetServer.new(task_data['name'], task_data['metadata'], task_data['files'], @file_cache)
       parameters = body['parameters'] || {}
+      # Wrap parameters marked with '"sensitive": true' in the task metadata with a
+      # Sensitive wrapper type. This way it's not shown in logs.
+      if (param_spec = task.parameters)
+        parameters.each do |k, v|
+          if param_spec[k] && param_spec[k]['sensitive']
+            parameters[k] = Puppet::Pops::Types::PSensitiveType::Sensitive.new(v)
+          end
+        end
+      end
+
       @executor.run_task(target, task, parameters).each do |result|
         value = result.value
         next unless value.is_a?(Hash)

data/lib/bolt_spec/bolt_context.rb

@@ -191,6 +191,15 @@ module BoltSpec
       allow_out_message.expect_call
     end
 
+    def allow_out_verbose
+      executor.stub_out_verbose.add_stub
+    end
+    alias allow_any_out_verbose allow_out_verbose
+
+    def expect_out_verbose
+      allow_out_verbose.expect_call
+    end
+
     # Example helpers to mock other run functions
     # The with_targets method makes sense for all stubs
     # with_params could be reused for options

data/lib/bolt_spec/plans.rb

@@ -98,7 +98,7 @@ module BoltSpec
       Puppet[:tasks] = true
 
       # Ensure logger is initialized with Puppet levels so 'notice' works when running plan specs.
-      Logging.init :trace, :debug, :info, :notice, :warn, :error, :fatal, :any
+      Logging.init :trace, :debug, :info, :notice, :warn, :error, :fatal
     end
 
     # Provided as a class so expectations can be placed on it.

data/lib/bolt_spec/plans/mock_executor.rb

@@ -29,6 +29,7 @@ module BoltSpec
         @modulepath = [modulepath].flatten.map { |path| File.absolute_path(path) }
         MOCKED_ACTIONS.each { |action| instance_variable_set(:"@#{action}_doubles", {}) }
         @stub_out_message = nil
+        @stub_out_verbose = nil
         @transport_features = ['puppet-agent']
         @executor_real = Bolt::Executor.new
         # by default, we want to execute any plan that we come across without error
@@ -187,6 +188,7 @@ module BoltSpec
           end
         end
         @stub_out_message.assert_called('out::message') if @stub_out_message
+        @stub_out_verbose.assert_called('out::verbose') if @stub_out_verbose
       end
 
       MOCKED_ACTIONS.each do |action|
@@ -199,6 +201,10 @@ module BoltSpec
         @stub_out_message ||= ActionDouble.new(:PublishStub)
       end
 
+      def stub_out_verbose
+        @stub_out_verbose ||= ActionDouble.new(:PublishStub)
+      end
+
       def stub_apply
         @allow_apply = true
       end
@@ -220,12 +226,20 @@ module BoltSpec
       end
 
       def publish_event(event)
-        if event[:type] == :message
+        case event[:type]
+        when :message
           unless @stub_out_message
             @error_message = "Unexpected call to 'out::message(#{event[:message]})'"
             raise UnexpectedInvocation, @error_message
           end
           @stub_out_message.process(event[:message])
+
+        when :verbose
+          unless @stub_out_verbose
+            @error_message = "Unexpected call to 'out::verbose(#{event[:message]})'"
+            raise UnexpectedInvocation, @error_message
+          end
+          @stub_out_verbose.process(event[:message])
         end
       end
 

data/lib/bolt_spec/plans/publish_stub.rb

@@ -7,19 +7,19 @@ module BoltSpec
   module Plans
     class PublishStub < ActionStub
       def return
-        raise "return is not implemented for out_message"
+        raise "return is not implemented for out module functions"
       end
 
       def return_for_targets(_data)
-        raise "return_for_targets is not implemented for out_message"
+        raise "return_for_targets is not implemented for out module functions"
       end
 
       def always_return(_data)
-        raise "always_return is not implemented for out_message"
+        raise "always_return is not implemented for out module functions"
       end
 
       def error_with(_data)
-        raise "error_with is not implemented for out_message"
+        raise "error_with is not implemented for out module functions"
       end
 
       def matches(message)

data/resources/bolt_bash_completion.sh

@@ -47,7 +47,7 @@ _bolt_complete() {
     next=$(compgen -f -d "" -- $cur)
   # Handle tab completing enumerable CLI options
   elif [ "$prev" == "--log-level" ]; then
-    next="trace debug info warn error fatal any"
+    next="trace debug info warn error fatal"
   elif [ "$prev" == "--transport" ]; then
     next="docker local lxd pcp podman remote ssh winrm"
   elif [ "$prev" == "--format" ]; then

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bolt
 version: !ruby/object:Gem::Version
-  version: 3.12.0
+  version: 3.13.0
 platform: ruby
 authors:
 - Puppet
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-07-06 00:00:00.000000000 Z
+date: 2021-07-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: addressable
@@ -448,7 +448,14 @@ files:
 - bolt-modules/file/lib/puppet/functions/file/read.rb
 - bolt-modules/file/lib/puppet/functions/file/readable.rb
 - bolt-modules/file/lib/puppet/functions/file/write.rb
+- bolt-modules/log/lib/puppet/functions/log/debug.rb
+- bolt-modules/log/lib/puppet/functions/log/error.rb
+- bolt-modules/log/lib/puppet/functions/log/fatal.rb
+- bolt-modules/log/lib/puppet/functions/log/info.rb
+- bolt-modules/log/lib/puppet/functions/log/trace.rb
+- bolt-modules/log/lib/puppet/functions/log/warn.rb
 - bolt-modules/out/lib/puppet/functions/out/message.rb
+- bolt-modules/out/lib/puppet/functions/out/verbose.rb
 - bolt-modules/prompt/lib/puppet/functions/prompt.rb
 - bolt-modules/prompt/lib/puppet/functions/prompt/menu.rb
 - bolt-modules/system/lib/puppet/functions/system/env.rb
@@ -586,6 +593,7 @@ files:
 - lib/bolt/transport/winrm.rb
 - lib/bolt/transport/winrm/connection.rb
 - lib/bolt/util.rb
+- lib/bolt/util/format.rb
 - lib/bolt/util/puppet_log_level.rb
 - lib/bolt/validator.rb
 - lib/bolt/version.rb