puppet 6.0.5-x64-mingw32 → 8.8.1-x64-mingw32

data/lib/puppet/application.rb

@@ -1,100 +1,80 @@
+# frozen_string_literal: true
+
 require 'optparse'
-require 'puppet/util/command_line'
-require 'puppet/util/constant_inflector'
-require 'puppet/error'
-require 'puppet/application_support'
+require_relative '../puppet/util/command_line'
+require_relative '../puppet/util/constant_inflector'
+require_relative '../puppet/error'
+require_relative '../puppet/application_support'
 
 module Puppet
-
-# This class handles all the aspects of a Puppet application/executable
-# * setting up options
-# * setting up logs
-# * choosing what to run
-# * representing execution status
-#
-# === Usage
-# An application is a subclass of Puppet::Application.
+# Defines an abstract Puppet application.
 #
-# For legacy compatibility,
-#      Puppet::Application[:example].run
-# is equivalent to
-#      Puppet::Application::Example.new.run
+# # Usage
 #
+# To create a new application extend `Puppet::Application`. Derived applications
+# must implement the `main` method and should implement the `summary` and
+# `help` methods in order to be included in `puppet help`, and should define
+# application-specific options. For example:
 #
+# ```
 # class Puppet::Application::Example < Puppet::Application
 #
-#     def preinit
-#         # perform some pre initialization
-#         @all = false
-#     end
+#   def summary
+#     "My puppet example application"
+#   end
 #
-#     # run_command is called to actually run the specified command
-#     def run_command
-#         send Puppet::Util::CommandLine.new.args.shift
-#     end
+#   def help
+#     <<~HELP
+#     puppet-example(8) -- #{summary}
+#     ...
+#     HELP
+#   end
 #
-#     # option uses metaprogramming to create a method
-#     # and also tells the option parser how to invoke that method
-#     option("--arg ARGUMENT") do |v|
-#         @args << v
-#     end
+#   # define arg with a required option
+#   option("--arg ARGUMENT") do |v|
+#     options[:arg] = v
+#   end
 #
-#     option("--debug", "-d") do |v|
-#         @debug = v
-#     end
+#   # define arg with an optional option
+#   option("--maybe [ARGUMENT]") do |v|
+#     options[:maybe] = v
+#   end
 #
-#     option("--all", "-a:) do |v|
-#         @all = v
-#     end
+#   # define long and short arg
+#   option("--all", "-a")
 #
-#     def handle_unknown(opt,arg)
-#         # last chance to manage an option
-#         ...
-#         # let's say to the framework we finally handle this option
-#         true
-#     end
+#   def initialize(command_line = Puppet::Util::CommandLine.new)
+#     super
+#     @data = {}
+#   end
 #
-#     def read
-#         # read action
-#     end
+#   def main
+#     # call action
+#     send(@command_line.args.shift)
+#   end
 #
-#     def write
-#         # writeaction
-#     end
-#
-# end
+#   def read
+#     # read action
+#   end
 #
-# === Preinit
-# The preinit block is the first code to be called in your application, before option parsing,
-# setup or command execution.
+#   def write
+#     # write action
+#   end
 #
-# === Options
-# Puppet::Application uses +OptionParser+ to manage the application options.
-# Options are defined with the +option+ method to which are passed various
-# arguments, including the long option, the short option, a description...
-# Refer to +OptionParser+ documentation for the exact format.
-# * If the option method is given a block, this one will be called whenever
-# the option is encountered in the command-line argument.
-# * If the option method has no block, a default functionality will be used, that
-# stores the argument (or true/false if the option doesn't require an argument) in
-# the global (to the application) options array.
-# * If a given option was not defined by a the +option+ method, but it exists as a Puppet settings:
-#  * if +unknown+ was used with a block, it will be called with the option name and argument
-#  * if +unknown+ wasn't used, then the option/argument is handed to Puppet.settings.handlearg for
-#    a default behavior
-#
-# --help is managed directly by the Puppet::Application class, but can be overridden.
+# end
+# ```
 #
-# === Setup
-# Applications can use the setup block to perform any initialization.
-# The default +setup+ behaviour is to: read Puppet configuration and manage log level and destination
+# Puppet defines the following application lifecycle methods that are called in
+# the following order:
 #
-# === What and how to run
-# If the +dispatch+ block is defined it is called. This block should return the name of the registered command
-# to be run.
-# If it doesn't exist, it defaults to execute the +main+ command if defined.
+# * {#initialize}
+# * {#initialize_app_defaults}
+# * {#preinit}
+# * {#parse_options}
+# * {#setup}
+# * {#main}
 #
-# === Execution state
+# ## Execution state
 # The class attributes/methods of Puppet::Application serve as a global place to set and query the execution
 # status of the application: stopping, restarting, etc.  The setting of the application status does not directly
 # affect its running status; it's assumed that the various components within the application will consult these
@@ -104,26 +84,32 @@ module Puppet
 #
 # So, if something in your application needs to stop the process, for some reason, you might consider:
 #
+# ```
 #  def stop_me!
-#      # indicate that we're stopping
-#      Puppet::Application.stop!
-#      # ...do stuff...
+#    # indicate that we're stopping
+#    Puppet::Application.stop!
+#    # ...do stuff...
 #  end
+# ```
 #
 # And, if you have some component that involves a long-running process, you might want to consider:
 #
+# ```
 #  def my_long_process(giant_list_to_munge)
-#      giant_list_to_munge.collect do |member|
-#          # bail if we're stopping
-#          return if Puppet::Application.stop_requested?
-#          process_member(member)
-#      end
+#    giant_list_to_munge.collect do |member|
+#      # bail if we're stopping
+#      return if Puppet::Application.stop_requested?
+#      process_member(member)
+#    end
 #  end
+# ```
+# @abstract
+# @api public
 class Application
-  require 'puppet/util'
+  require_relative '../puppet/util'
   include Puppet::Util
 
-  DOCPATTERN = ::File.expand_path(::File.dirname(__FILE__) + "/util/command_line/*" )
+  DOCPATTERN = ::File.expand_path(::File.dirname(__FILE__) + "/util/command_line/*")
   CommandLineArgs = Struct.new(:subcommand_name, :args)
 
   @loader = Puppet::Util::Autoload.new(self, 'puppet/application')
@@ -137,34 +123,42 @@ class Application
       self.run_status = nil
     end
 
+    # Signal that the application should stop.
+    # @api public
     def stop!
       self.run_status = :stop_requested
     end
 
+    # Signal that the application should restart.
+    # @api public
     def restart!
       self.run_status = :restart_requested
     end
 
     # Indicates that Puppet::Application.restart! has been invoked and components should
     # do what is necessary to facilitate a restart.
+    # @api public
     def restart_requested?
       :restart_requested == run_status
     end
 
     # Indicates that Puppet::Application.stop! has been invoked and components should do what is necessary
     # for a clean stop.
+    # @api public
     def stop_requested?
       :stop_requested == run_status
     end
 
     # Indicates that one of stop! or start! was invoked on Puppet::Application, and some kind of process
     # shutdown/short-circuit may be necessary.
+    # @api public
     def interrupted?
       [:restart_requested, :stop_requested].include? run_status
     end
 
     # Indicates that Puppet::Application believes that it's in usual running run_mode (no stop/restart request
     # currently active).
+    # @api public
     def clear?
       run_status.nil?
     end
@@ -176,6 +170,7 @@ class Application
     # Thus, long-running background processes can potentially finish their work before a restart.
     def controlled_run(&block)
       return unless clear?
+
       result = block.call
       Process.kill(:HUP, $PID) if restart_requested?
       result
@@ -183,16 +178,16 @@ class Application
 
     # used to declare code that handle an option
     def option(*options, &block)
-      long = options.find { |opt| opt =~ /^--/ }.gsub(/^--(?:\[no-\])?([^ =]+).*$/, '\1' ).gsub('-','_')
+      long = options.find { |opt| opt =~ /^--/ }.gsub(/^--(?:\[no-\])?([^ =]+).*$/, '\1').tr('-', '_')
       fname = "handle_#{long}".intern
-      if (block_given?)
+      if block_given?
         define_method(fname, &block)
       else
         define_method(fname) do |value|
-          self.options["#{long}".to_sym] = value
+          self.options[long.to_s.to_sym] = value
         end
       end
-      self.option_parser_commands << [options, fname]
+      option_parser_commands << [options, fname]
     end
 
     def banner(banner = nil)
@@ -247,7 +242,7 @@ class Application
       ####  eventually we need to issue a deprecation warning here,
       ####  and then get rid of this stanza in a subsequent release.
       ################################################################
-      if (clazz.nil?)
+      if clazz.nil?
         class_name = application_name.capitalize
         clazz = try_load_class(class_name)
       end
@@ -256,56 +251,74 @@ class Application
       ################################################################
 
       if clazz.nil?
-        raise Puppet::Error.new(_("Unable to load application class '%{class_name}' from file 'puppet/application/%{application_name}.rb'") % { class_name: class_name, application_name: application_name })
+        raise Puppet::Error, _("Unable to load application class '%{class_name}' from file 'puppet/application/%{application_name}.rb'") % { class_name: class_name, application_name: application_name }
       end
 
-      return clazz
+      clazz
     end
 
     # Given the fully qualified name of a class, attempt to get the class instance.
     # @param [String] class_name the fully qualified name of the class to try to load
     # @return [Class] the Class instance, or nil? if it could not be loaded.
     def try_load_class(class_name)
-        return self.const_defined?(class_name) ? const_get(class_name) : nil
+      const_defined?(class_name) ? const_get(class_name) : nil
     end
     private :try_load_class
 
+    # Return an instance of the specified application.
+    #
+    # @param [Symbol] name the lowercase name of the application
+    # @return [Puppet::Application] an instance of the specified name
+    # @raise [Puppet::Error] if the application class was not found.
+    # @raise [LoadError] if there was a problem loading the application file.
+    # @api public
     def [](name)
       find(name).new
     end
 
     # Sets or gets the run_mode name. Sets the run_mode name if a mode_name is
     # passed. Otherwise, gets the run_mode or a default run_mode
-    #
-    def run_mode( mode_name = nil)
+    # @api public
+    def run_mode(mode_name = nil)
       if mode_name
         Puppet.settings.preferred_run_mode = mode_name
       end
 
-      return @run_mode if @run_mode and not mode_name
+      return @run_mode if @run_mode and !mode_name
 
-      require 'puppet/util/run_mode'
-      @run_mode = Puppet::Util::RunMode[ mode_name || Puppet.settings.preferred_run_mode ]
+      require_relative '../puppet/util/run_mode'
+      @run_mode = Puppet::Util::RunMode[mode_name || Puppet.settings.preferred_run_mode]
     end
 
-    # Sets environment_mode name
+    # Sets environment_mode name. When acting as a compiler, the environment mode
+    # should be `:local` since the directory must exist to compile the catalog.
+    # When acting as an agent, the environment mode should be `:remote` since
+    # the Puppet[:environment] setting refers to an environment directoy on a remote
+    # system. The `:not_required` mode is for cases where the application does not
+    # need an environment to run.
+    #
     # @param mode_name [Symbol] The name of the environment mode to run in. May
-    #   be one of :local, :remote, or :not_required. This impacts where the
-    #   application looks for its specified environment. If :not_required or
-    #   :remote are set, the application will not fail if the environment does
+    #   be one of `:local`, `:remote`, or `:not_required`. This impacts where the
+    #   application looks for its specified environment. If `:not_required` or
+    #   `:remote` are set, the application will not fail if the environment does
     #   not exist on the local filesystem.
+    # @api public
     def environment_mode(mode_name)
       raise Puppet::Error, _("Invalid environment mode '%{mode_name}'") % { mode_name: mode_name } unless [:local, :remote, :not_required].include?(mode_name)
+
       @environment_mode = mode_name
     end
 
     # Gets environment_mode name. If none is set with `environment_mode=`,
     # default to :local.
+    # @return [Symbol] The current environment mode
+    # @api public
     def get_environment_mode
       @environment_mode || :local
     end
 
     # This is for testing only
+    # @api public
     def clear_everything_for_tests
       @run_mode = @banner = @run_status = @option_parser_commands = nil
     end
@@ -316,50 +329,78 @@ class Application
   # Every app responds to --version
   # See also `lib/puppet/util/command_line.rb` for some special case early
   # handling of this.
-  option("--version", "-V") do |arg|
-    puts "#{Puppet.version}"
+  option("--version", "-V") do |_arg|
+    puts Puppet.version
     exit(0)
   end
 
   # Every app responds to --help
-  option("--help", "-h") do |v|
+  option("--help", "-h") do |_v|
     puts help
     exit(0)
   end
 
-  def app_defaults()
+  # Initialize the application receiving the {Puppet::Util::CommandLine} object
+  # containing the application name and arguments.
+  #
+  # @param command_line [Puppet::Util::CommandLine] An instance of the command line to create the application with
+  # @api public
+  def initialize(command_line = Puppet::Util::CommandLine.new)
+    @command_line = CommandLineArgs.new(command_line.subcommand_name, command_line.args.dup)
+    @options = {}
+  end
+
+  # Now that the `run_mode` has been resolved, return default settings for the
+  # application. Note these values may be overridden when puppet's configuration
+  # is loaded later.
+  #
+  # @example To override the facts terminus:
+  #   def app_defaults
+  #     super.merge({
+  #       :facts_terminus => 'yaml'
+  #     })
+  #   end
+  #
+  # @return [Hash<String, String>] default application settings
+  # @api public
+  def app_defaults
     Puppet::Settings.app_defaults_for_run_mode(self.class.run_mode).merge(
-        :name => name
+      :name => name
     )
   end
 
-  def initialize_app_defaults()
+  # Initialize application defaults. It's usually not necessary to override this method.
+  # @return [void]
+  # @api public
+  def initialize_app_defaults
     Puppet.settings.initialize_app_defaults(app_defaults)
   end
 
-  # override to execute code before running anything else
+  # The preinit block is the first code to be called in your application, after
+  # `initialize`, but before option parsing, setup or command execution. It is
+  # usually not necessary to override this method.
+  # @return [void]
+  # @api public
   def preinit
   end
 
-  def initialize(command_line = Puppet::Util::CommandLine.new)
-    @command_line = CommandLineArgs.new(command_line.subcommand_name, command_line.args.dup)
-    @options = {}
-  end
-
-  # call in setup of subclass to deprecate an application
+  # Call in setup of subclass to deprecate an application.
+  # @return [void]
+  # @api public
   def deprecate
     @deprecated = true
   end
 
+  # Return true if this application is deprecated.
+  # @api public
   def deprecated?
     @deprecated
   end
 
-  # Execute the application.
-  # @api public
+  # Execute the application. This method should not be overridden.
   # @return [void]
+  # @api public
   def run
-
     # I don't really like the names of these lifecycle phases.  It would be nice to change them to some more meaningful
     # names, and make deprecated aliases.  --cprice 2012-03-16
 
@@ -382,20 +423,36 @@ class Application
     exit_on_fail(_("Could not run"))                                          { run_command }
   end
 
+  # This method must be overridden and perform whatever action is required for
+  # the application. The `command_line` reader contains the actions and
+  # arguments.
+  # @return [void]
+  # @api public
   def main
     raise NotImplementedError, _("No valid command or main")
   end
 
+  # Run the application. By default, it calls {#main}.
+  # @return [void]
+  # @api public
   def run_command
     main
   end
 
+  # Setup the application. It is usually not necessary to override this method.
+  # @return [void]
+  # @api public
   def setup
     setup_logs
   end
 
+  # Setup logging. By default the `console` log destination will only be created
+  # if `debug` or `verbose` is specified on the command line. Override to customize
+  # the logging behavior.
+  # @return [void]
+  # @api public
   def setup_logs
-    handle_logdest_arg(Puppet[:logdest])
+    handle_logdest_arg(Puppet[:logdest]) unless options[:setdest]
 
     unless options[:setdest]
       if options[:debug] || options[:verbose]
@@ -418,14 +475,16 @@ class Application
   end
 
   def handle_logdest_arg(arg)
-    return if options[:setdest] || arg.nil?
+    return if arg.nil?
+
+    logdest = arg.split(',').map!(&:strip)
+    Puppet[:logdest] = arg
 
-    begin
-      Puppet[:logdest] = arg
-      Puppet::Util::Log.newdestination(arg)
+    logdest.each do |dest|
+      Puppet::Util::Log.newdestination(dest)
       options[:setdest] = true
     rescue => detail
-      Puppet.log_exception(detail)
+      Puppet.log_and_raise(detail, _("Could not set logdest to %{dest}.") % { dest: arg })
     end
   end
 
@@ -436,23 +495,41 @@ class Application
   # Output basic information about the runtime environment for debugging
   # purposes.
   #
-  # @api public
-  #
   # @param extra_info [Hash{String => #to_s}] a flat hash of extra information
   #   to log. Intended to be passed to super by subclasses.
   # @return [void]
-  def log_runtime_environment(extra_info=nil)
+  # @api public
+  def log_runtime_environment(extra_info = nil)
     runtime_info = {
       'puppet_version' => Puppet.version,
-      'ruby_version'   => RUBY_VERSION,
-      'run_mode'       => self.class.run_mode.name,
+      'ruby_version' => RUBY_VERSION,
+      'run_mode' => self.class.run_mode.name
     }
+    unless Puppet::Util::Platform.jruby_fips?
+      runtime_info['openssl_version'] = "'#{OpenSSL::OPENSSL_VERSION}'"
+      runtime_info['openssl_fips'] = OpenSSL::OPENSSL_FIPS
+    end
     runtime_info['default_encoding'] = Encoding.default_external
     runtime_info.merge!(extra_info) unless extra_info.nil?
 
-    Puppet.debug 'Runtime environment: ' + runtime_info.map{|k,v| k + '=' + v.to_s}.join(', ')
+    Puppet.debug 'Runtime environment: ' + runtime_info.map { |k, v| k + '=' + v.to_s }.join(', ')
   end
 
+  # Options defined with the `option` method are parsed from settings and the command line.
+  # Refer to {OptionParser} documentation for the exact format. Options are parsed as follows:
+  #
+  # * If the option method is given a block, then it will be called whenever the option is encountered in the command-line argument.
+  # * If the option method has no block, then the default option handler will store the argument in the `options` instance variable.
+  # * If a given option was not defined by an `option` method, but it exists as a Puppet setting:
+  #   * if `unknown` was used with a block, it will be called with the option name and argument.
+  #   * if `unknown` wasn't used, then the option/argument is handed to Puppet.settings.handlearg for
+  #     a default behavior.
+  #  * The `-h` and `--help` options are automatically handled by the command line before creating the application.
+  #
+  # Options specified on the command line override settings. It is usually not
+  # necessary to override this method.
+  # @return [void]
+  # @api public
   def parse_options
     # Create an option parser
     option_parser = OptionParser.new(self.class.banner)
@@ -476,14 +553,14 @@ class Application
     self.class.option_parser_commands.each do |options, fname|
       option_parser.on(*options) do |value|
         # Call the method that "option()" created.
-        self.send(fname, value)
+        send(fname, value)
       end
     end
 
     # Scan command line.  We just hand any exceptions to our upper levels,
     # rather than printing help and exiting, so that we can meaningfully
     # respond with context-sensitive help if we want to. --daniel 2011-04-12
-    option_parser.parse!(self.command_line.args)
+    option_parser.parse!(command_line.args)
   end
 
   def handlearg(opt, val)
@@ -497,9 +574,12 @@ class Application
   end
 
   def name
-    self.class.to_s.sub(/.*::/,"").downcase.to_sym
+    self.class.to_s.sub(/.*::/, "").downcase.to_sym
   end
 
+  # Return the text to display when running `puppet help`.
+  # @return [String] The help to display
+  # @api public
   def help
     _("No help available for puppet %{app_name}") % { app_name: name }
   end
@@ -507,6 +587,8 @@ class Application
   # The description used in top level `puppet help` output
   # If left empty in implementations, we will attempt to extract
   # the summary from the help text itself.
+  # @return [String]
+  # @api public
   def summary
     ""
   end

data/lib/puppet/application_support.rb

@@ -1,13 +1,14 @@
+# frozen_string_literal: true
+
 require 'yaml'
 
-require 'puppet'
-require 'puppet/node/environment'
-require 'puppet/file_system'
-require 'puppet/indirector'
+require_relative '../puppet'
+require_relative '../puppet/node/environment'
+require_relative '../puppet/file_system'
+require_relative '../puppet/indirector'
 
 module Puppet
   module ApplicationSupport
-
     # Pushes a Puppet Context configured with a remote environment for an agent
     # (one that exists at the master end), and a regular environment for other
     # modes. The configuration is overridden with options from the command line
@@ -19,7 +20,7 @@ module Puppet
     # @return [void]
     # @api private
     def self.push_application_context(run_mode, environment_mode = :local)
-      Puppet.push_context(Puppet.base_context(Puppet.settings), "Update for application settings (#{run_mode})")
+      Puppet.push_context_global(Puppet.base_context(Puppet.settings), "Update for application settings (#{run_mode})")
       # This use of configured environment is correct, this is used to establish
       # the defaults for an application that does not override, or where an override
       # has not been made from the command line.
@@ -36,7 +37,7 @@ module Puppet
       configured_environment = configured_environment.override_from_commandline(Puppet.settings)
 
       # Setup a new context using the app's configuration
-      Puppet.push_context({:current_environment => configured_environment},
+      Puppet.push_context({ :current_environment => configured_environment },
                           "Update current environment from application's configuration")
     end
 
@@ -53,6 +54,13 @@ module Puppet
       route_file = Puppet[:route_file]
       if Puppet::FileSystem.exist?(route_file)
         routes = Puppet::Util::Yaml.safe_load_file(route_file, [Symbol])
+        if routes["server"] && routes["master"]
+          Puppet.warning("Route file #{route_file} contains both server and master route settings.")
+        elsif routes["server"] && !routes["master"]
+          routes["master"] = routes["server"]
+        elsif routes["master"] && !routes["server"]
+          routes["server"] = routes["master"]
+        end
         application_routes = routes[application_name]
         Puppet::Indirector.configure_routes(application_routes) if application_routes
       end

data/lib/puppet/coercion.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # Various methods used to coerce values into a canonical form.
 #
 # @api private
@@ -18,9 +20,9 @@ module Puppet::Coercion
     end
 
     case value
-    when true, :true, 'true', :yes, 'yes'
+    when true, :true, 'true', :yes, 'yes' # rubocop:disable Lint/BooleanSymbol
       true
-    when false, :false, 'false', :no, 'no'
+    when false, :false, 'false', :no, 'no' # rubocop:disable Lint/BooleanSymbol
       false
     else
       fail('expected a boolean value')
@@ -35,6 +37,6 @@ module Puppet::Coercion
   # @raise
   # @api private
   def self.boolean_values
-    ['true', 'false', 'yes', 'no']
+    %w[true false yes no]
   end
 end