puppet 7.9.0-universal-darwin → 7.12.1-universal-darwin

data/lib/puppet/defaults.rb

@@ -3,7 +3,7 @@ require_relative '../puppet/util/platform'
 module Puppet
 
   def self.default_diffargs
-    if (Facter.value(:kernel) == "AIX" && Facter.value(:kernelmajversion) == "5300")
+    if (Puppet.runtime[:facter].value(:kernel) == "AIX" && Puppet.runtime[:facter].value(:kernelmajversion) == "5300")
       ""
     else
       "-u"
@@ -199,7 +199,7 @@ module Puppet
 
         The strictness level is for both language semantics and runtime
         evaluation validation. In addition to controlling the behavior with
-        this master switch some individual warnings may also be controlled
+        this primary server switch some individual warnings may also be controlled
         by the disable_warnings setting.
 
         No new validations will be added to a micro (x.y.z) release,
@@ -243,7 +243,7 @@ module Puppet
           internal Ruby stack trace interleaved with Puppet function frames.",
         :hook     => proc do |value|
           # Enable or disable Facter's trace option too
-          Facter.trace(value) if Facter.respond_to? :trace
+          Puppet.runtime[:facter].trace(value)
         end
     },
     :puppet_trace => {
@@ -268,7 +268,7 @@ module Puppet
       :default    => true,
       :type       => :boolean,
       :desc       => "Whether to compile a [static catalog](https://puppet.com/docs/puppet/latest/static_catalogs.html#enabling-or-disabling-static-catalogs),
-        which occurs only on a Puppet Server master when the `code-id-command` and
+        which occurs only on Puppet Server when the `code-id-command` and
         `code-content-command` settings are configured in its `puppetserver.conf` file.",
     },
     :settings_catalog => {
@@ -391,13 +391,13 @@ module Puppet
         :default  => "production",
         :desc     => "The environment in which Puppet is running. For clients,
           such as `puppet agent`, this determines the environment itself, which
-          Puppet uses to find modules and much more. For servers, such as `puppet master`,
+          Puppet uses to find modules and much more. For servers, such as `puppet server`,
           this provides the default environment for nodes that Puppet knows nothing about.
 
           When defining an environment in the `[agent]` section, this refers to the
-          environment that the agent requests from the master. The environment doesn't
+          environment that the agent requests from the primary server. The environment doesn't
           have to exist on the local filesystem because the agent fetches it from the
-          master. This definition is used when running `puppet agent`.
+          primary server. This definition is used when running `puppet agent`.
 
           When defined in the `[user]` section, the environment refers to the path that
           Puppet uses to search for code and modules related to its execution. This
@@ -761,6 +761,12 @@ Valid values are 0 (never cache) and 15 (15 second minimum wait time).
       :owner    => "service",
       :group    => "service",
       :desc    => "The directory where catalog previews per node are generated."
+    },
+    :location_trusted => {
+      :default => false,
+      :type     => :boolean,
+      :desc    => "This will allow sending the name + password and the cookie header to all hosts that puppet may redirect to.
+        This may or may not introduce a security breach if puppet redirects you to a site to which you'll send your authentication info and cookies."
     }
   )
 
@@ -791,7 +797,7 @@ Valid values are 0 (never cache) and 15 (15 second minimum wait time).
     :certname => {
       :default => lambda { Puppet::Settings.default_certname.downcase },
       :desc => "The name to use when handling certificates. When a node
-        requests a certificate from the CA puppet master, it uses the value of the
+        requests a certificate from the CA Puppet Server, it uses the value of the
         `certname` setting as its requested Subject CN.
 
         This is the name used when managing a node's permissions in
@@ -854,7 +860,7 @@ EOT
       :desc => <<EOT
 An optional file containing custom attributes to add to certificate signing
 requests (CSRs). You should ensure that this file does not exist on your CA
-puppet master; if it does, unwanted certificate extensions may leak into
+Puppet Server; if it does, unwanted certificate extensions may leak into
 certificates created with the `puppetserver ca generate` command.
 
 If present, this file must be a YAML hash containing a `custom_attributes` key
@@ -1143,7 +1149,7 @@ EOT
       :default => "$confdir/autosign.conf",
       :type => :autosign,
       :desc => "Whether (and how) to autosign certificate requests. This setting
-        is only relevant on a puppet master acting as a certificate authority (CA).
+        is only relevant on a Puppet Server acting as a certificate authority (CA).
 
         Valid values are true (autosigns all certificate requests; not recommended),
         false (disables autosigning certificates), or the absolute path to a file.
@@ -1154,7 +1160,7 @@ EOT
         file, it will be treated as a policy executable; otherwise, it will be
         treated as a config file.
 
-        If a custom policy executable is configured, the CA puppet master will run it
+        If a custom policy executable is configured, the CA Puppet Server will run it
         every time it receives a CSR. The executable will be passed the subject CN of the
         request _as a command line argument,_ and the contents of the CSR in PEM format
         _on stdin._ It should exit with a status of 0 if the cert should be autosigned
@@ -1241,7 +1247,7 @@ EOT
     :manifest => {
       :default    => nil,
       :type       => :file_or_directory,
-      :desc       => "The entry-point manifest for puppet master. This can be one file
+      :desc       => "The entry-point manifest for the primary server. This can be one file
         or a directory of manifests to be evaluated in alphabetical order. Puppet manages
         this path as a directory if one exists or if the path ends with a / or \\.
 
@@ -1421,8 +1427,8 @@ EOT
         their names should be comma-separated, with whitespace allowed. (For example,
         `reports = http, store`.)
 
-        This setting is relevant to puppet master and puppet apply. The puppet
-        master will call these report handlers with the reports it receives from
+        This setting is relevant to puppet server and puppet apply. The primary Puppet
+        server will call these report handlers with the reports it receives from
         agent nodes, and puppet apply will call them with its own report. (In
         all cases, the node applying the catalog must have `report = true`.)
 
@@ -1474,14 +1480,14 @@ EOT
     :node_name_value => {
       :default => "$certname",
       :desc => "The explicit value used for the node name for all requests the agent
-        makes to the master. WARNING: This setting is mutually exclusive with
+        makes to the primary server. WARNING: This setting is mutually exclusive with
         node_name_fact.  Changing this setting also requires changes to
         Puppet Server's default [auth.conf](https://puppet.com/docs/puppetserver/latest/config_file_auth.html)."
     },
     :node_name_fact => {
       :default => "",
       :desc => "The fact name used to determine the node name used for all requests the agent
-        makes to the master. WARNING: This setting is mutually exclusive with
+        makes to the primary server. WARNING: This setting is mutually exclusive with
         node_name_value.  Changing this setting also requires changes to
         Puppet Server's default [auth.conf](https://puppet.com/docs/puppetserver/latest/config_file_auth.html).",
       :hook => proc do |value|
@@ -1494,8 +1500,8 @@ EOT
       :default => "$statedir/state.yaml",
       :type => :file,
       :mode => "0640",
-      :desc => "Where puppet agent and puppet master store state associated
-        with the running configuration.  In the case of puppet master,
+      :desc => "Where Puppet agent and Puppet Server store state associated
+        with the running configuration.  In the case of Puppet Server,
         this file reflects the state discovered through interacting
         with clients."
     },
@@ -1532,6 +1538,12 @@ EOT
       :mode => "0750",
       :desc => "The directory in which serialized data is stored on the client."
     },
+    :write_catalog_summary => {
+      :default => true,
+      :type => :boolean,
+      :desc => "Whether to write the `classfile` and `resourcefile` after applying
+        the catalog. It is enabled by default, except when running `puppet apply`.",
+    },
     :classfile => {
       :default => "$statedir/classes.txt",
       :type => :file,
@@ -1558,11 +1570,11 @@ EOT
         the POSIX syslog service and the Windows Event Log are unavailable. (Currently,
         no supported operating systems match that description.)
 
-        Despite the name, both puppet agent and puppet master will use this file
+        Despite the name, both puppet agent and puppet server will use this file
         as the fallback logging destination.
 
         For control over logging destinations, see the `--logdest` command line
-        option in the manual pages for puppet master, puppet agent, and puppet
+        option in the manual pages for puppet server, puppet agent, and puppet
         apply. You can see man pages by running `puppet <SUBCOMMAND> --help`,
         or read them online at https://puppet.com/docs/puppet/latest/man/."
     },
@@ -1576,12 +1588,12 @@ EOT
     },
     :server => {
       :default => "puppet",
-      :desc => "The puppet master server to which the puppet agent should connect.",
+      :desc => "The primary Puppet server to which the Puppet agent should connect.",
     },
     :server_list => {
       :default => [],
       :type => :server_list,
-      :desc => "The list of Puppet master servers to which the Puppet agent should connect,
+      :desc => "The list of primary Puppet servers to which the Puppet agent should connect,
         in the order that they will be tried. Each value should be a fully qualified domain name, followed by an optional ':' and port number. If a port is omitted, Puppet uses masterport for that host.",
     },
     :use_srv_records => {
@@ -1596,7 +1608,7 @@ EOT
     :http_extra_headers => {
       :default => [],
       :type => :http_extra_headers,
-      :desc => "The list of extra headers that will be sent with http requests to the master.
+      :desc => "The list of extra headers that will be sent with http requests to the primary server.
       The header definition consists of a name and a value separated by a colon."
     },
     :ignoreschedules => {
@@ -1622,7 +1634,7 @@ EOT
         like it does when running normally. However, if a resource attribute is not in
         the desired state (as declared in the catalog), Puppet will take no
         action, and will instead report the changes it _would_ have made. These
-        simulated changes will appear in the report sent to the puppet master, or
+        simulated changes will appear in the report sent to the primary Puppet server, or
         be shown on the console if running puppet agent or puppet apply in the
         foreground. The simulated changes will not send refresh events to any
         subscribing or notified resources, although Puppet will log that a refresh
@@ -1689,13 +1701,38 @@ EOT
         new configurations, where you want to fix the broken configuration
         rather than reverting to a known-good one.",
     },
+    :fact_name_length_soft_limit => {
+      :default    => 2560,
+      :type       => :integer,
+      :desc       => "The soft limit for the length of a fact name.",
+    },
+    :fact_value_length_soft_limit => {
+      :default    => 4096,
+      :type       => :integer,
+      :desc       => "The soft limit for the length of a fact value.",
+    },
+    :top_level_facts_soft_limit => {
+      :default    => 512,
+      :type       => :integer,
+      :desc       => "The soft limit for the number of top level facts.",
+    },
+    :number_of_facts_soft_limit => {
+      :default    => 2048,
+      :type       => :integer,
+      :desc       => "The soft limit for the total number of facts.",
+    },
+    :payload_soft_limit => {
+      :default    => 16 * 1024 * 1024,
+      :type       => :integer,
+      :desc       => "The soft limit for the size of the payload.",
+    },
     :use_cached_catalog => {
       :default    => false,
       :type       => :boolean,
       :desc       => "Whether to only use the cached catalog rather than compiling a new catalog
         on every run.  Puppet can be run with this enabled by default and then selectively
         disabled when a recompile is desired. Because a Puppet agent using cached catalogs
-        does not contact the master for a new catalog, it also does not upload facts at
+        does not contact the primary server for a new catalog, it also does not upload facts at
         the beginning of the Puppet run.",
     },
     :ignoremissingtypes => {
@@ -1703,7 +1740,7 @@ EOT
       :type       => :boolean,
       :desc       => "Skip searching for classes and definitions that were missing during a
         prior compilation. The list of missing objects is maintained per-environment and
-        persists until the environment is cleared or the master is restarted.",
+        persists until the environment is cleared or the primary server is restarted.",
     },
     :splaylimit => {
       :default    => "$runinterval",
@@ -1733,7 +1770,7 @@ EOT
         If you restart an agent's puppet service with `splay` enabled, it
         recalculates its splay period and delays its first agent run after
         restarting for this new period. If you simultaneously restart a group of
-        puppet agents with `splay` enabled, their checkins to your puppet masters
+        puppet agents with `splay` enabled, their checkins to your primary servers
         can be distributed more evenly.",
     },
     :clientbucketdir => {
@@ -1832,7 +1869,7 @@ EOT
 
       When starting for the first time, puppet agent will submit a certificate
       signing request (CSR) to the server named in the `ca_server` setting
-      (usually the puppet master); this may be autosigned, or may need to be
+      (usually the primary Puppet server); this may be autosigned, or may need to be
       approved by a human, depending on the CA server's configuration.
 
       Puppet agent cannot apply configurations until its approved certificate is
@@ -1946,7 +1983,7 @@ EOT
       :call_hook => :on_initialize_and_write, # Call our hook with the default value, so we always get the value added to facter.
       :hook => proc do |value|
         paths = value.split(File::PATH_SEPARATOR)
-        Facter.search(*paths)
+        Puppet.runtime[:facter].search(*paths)
       end
     }
   )

data/lib/puppet/environments.rb

@@ -48,6 +48,13 @@ module Puppet::Environments
         root.instance_variable_set(:@rich_data, nil)
       end
     end
+
+    # The base implementation is a noop, because `get` returns a new environment
+    # each time.
+    #
+    # @see Puppet::Environments::Cached#guard
+    def guard(name); end
+    def unguard(name); end
   end
 
   # @!macro [new] loader_search_paths
@@ -188,7 +195,7 @@ module Puppet::Environments
 
     def self.real_path(dir)
       if Puppet::FileSystem.symlink?(dir) && Puppet[:versioned_environment_dirs]
-        dir = Puppet::FileSystem.expand_path(Puppet::FileSystem.readlink(dir))
+        dir = Pathname.new Puppet::FileSystem.expand_path(Puppet::FileSystem.readlink(dir))
       end
       return dir
     end
@@ -241,7 +248,7 @@ module Puppet::Environments
 
     def validated_directory(envdir)
       env_name = Puppet::FileSystem.basename_string(envdir)
-      envdir = Puppet::Environments::Directories.real_path(envdir)
+      envdir = Puppet::Environments::Directories.real_path(envdir).to_s
       if Puppet::FileSystem.directory?(envdir) && Puppet::Node::Environment.valid_name?(env_name)
         envdir
       else
@@ -330,21 +337,13 @@ module Puppet::Environments
     end
 
     def self.cache_expiration_service=(service)
-      @cache_expiration_service = service
+      @cache_expiration_service_singleton = service
     end
 
     def self.cache_expiration_service
-      @cache_expiration_service || DefaultCacheExpirationService.new
+      @cache_expiration_service_singleton || DefaultCacheExpirationService.new
     end
 
-    # Returns the end of time (the next Mesoamerican Long Count cycle-end after 2012 (5125+2012) = 7137
-    def self.end_of_time
-      Time.gm(7137)
-    end
-
-    END_OF_TIME = end_of_time
-    START_OF_TIME = Time.gm(1)
-
     def initialize(loader)
       @loader = loader
       @cache_expiration_service = Puppet::Environments::Cached.cache_expiration_service
@@ -356,7 +355,7 @@ module Puppet::Environments
       # Evict all that have expired, in the same way as `get`
       clear_all_expired
 
-      # Evict all that was removed from diks
+      # Evict all that was removed from disk
       cached_envs = @cache.keys.map!(&:to_sym)
       loader_envs = @loader.list.map!(&:name)
       removed_envs = cached_envs - loader_envs
@@ -385,27 +384,35 @@ module Puppet::Environments
 
     # @!macro loader_get
     def get(name)
+      entry = get_entry(name)
+      entry ? entry.value : nil
+    end
+
+    # Get a cache entry for an envionment. It returns nil if the
+    # environment doesn't exist.
+    def get_entry(name, check_expired = true)
       # Aggressively evict all that has expired
       # This strategy favors smaller memory footprint over environment
       # retrieval time.
-      clear_all_expired
-      result = @cache[name]
-      if result
-        Puppet.debug {"Found in cache '#{name}' #{result.label}"}
+      clear_all_expired if check_expired
+      name = name.to_sym
+      entry = @cache[name]
+      if entry
+        Puppet.debug {"Found in cache #{name.inspect} #{entry.label}"}
         # found in cache
-        result.touch
-        return result.value
-      elsif (result = @loader.get(name))
+        entry.touch
+      elsif (env = @loader.get(name))
         # environment loaded, cache it
-        cache_entry = entry(result)
-        add_entry(name, cache_entry)
-        result
+        entry = entry(env)
+        add_entry(name, entry)
       end
+      entry
     end
+    private :get_entry
 
     # Adds a cache entry to the cache
     def add_entry(name, cache_entry)
-      Puppet.debug {"Caching environment '#{name}' #{cache_entry.label}"}
+      Puppet.debug {"Caching environment #{name.inspect} #{cache_entry.label}"}
       @cache[name] = cache_entry
       @cache_expiration_service.created(cache_entry.value)
     end
@@ -413,7 +420,7 @@ module Puppet::Environments
 
     def clear_entry(name, entry)
       @cache.delete(name)
-      Puppet.debug {"Evicting cache entry for environment '#{name}'"}
+      Puppet.debug {"Evicting cache entry for environment #{name.inspect}"}
       @cache_expiration_service.evicted(name.to_sym)
       Puppet::GettextConfig.delete_text_domain(name)
       Puppet.settings.clear_environment_settings(name)
@@ -423,6 +430,7 @@ module Puppet::Environments
     # Clears the cache of the environment with the given name.
     # (The intention is that this could be used from a MANUAL cache eviction command (TBD)
     def clear(name)
+      name = name.to_sym
       entry = @cache[name]
       clear_entry(name, entry) if entry
     end
@@ -443,19 +451,21 @@ module Puppet::Environments
     # Clears all environments that have expired, either by exceeding their time to live, or
     # through an explicit eviction determined by the cache expiration service.
     #
-    def clear_all_expired()
+    def clear_all_expired
       t = Time.now
 
       @cache.each_pair do |name, entry|
         clear_if_expired(name, entry, t)
       end
     end
+    private :clear_all_expired
 
     # Clear an environment if it is expired, either by exceeding its time to live, or
     # through an explicit eviction determined by the cache expiration service.
     #
     def clear_if_expired(name, entry, t = Time.now)
       return unless entry
+      return if entry.guarded?
 
       if entry.expired?(t) || @cache_expiration_service.expired?(name.to_sym)
         clear_entry(name, entry)
@@ -472,10 +482,25 @@ module Puppet::Environments
     #
     # @!macro loader_get_conf
     def get_conf(name)
+      name = name.to_sym
       clear_if_expired(name, @cache[name])
       @loader.get_conf(name)
     end
 
+    # Guard an environment so it can't be evicted while it's in use. The method
+    # may be called multiple times, provided it is unguarded the same number of
+    # times. If you call this method, you must call `unguard` in an ensure block.
+    def guard(name)
+      entry = get_entry(name, false)
+      entry.guard if entry
+    end
+
+    # Unguard an environment.
+    def unguard(name)
+      entry = get_entry(name, false)
+      entry.unguard if entry
+    end
+
     # Creates a suitable cache entry given the time to live for one environment
     #
     def entry(env)
@@ -501,6 +526,7 @@ module Puppet::Environments
 
       def initialize(value)
         @value = value
+        @guards = 0
       end
 
       def touch
@@ -513,6 +539,20 @@ module Puppet::Environments
       def label
         ""
       end
+
+      # These are not protected with a lock, because all of the Cached
+      # methods are protected.
+      def guarded?
+        @guards > 0
+      end
+
+      def guard
+        @guards += 1
+      end
+
+      def unguard
+        @guards -= 1
+      end
     end
 
     # Always evicting entry

data/lib/puppet/facter_impl.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+#
+# @api private
+# Default Facter implementation that delegates to Facter API
+#
+
+module Puppet
+  class FacterImpl
+    def initialize
+      require 'facter'
+
+      setup_logging
+    end
+
+    def value(fact_name)
+      ::Facter.value(fact_name)
+    end
+
+    def add(name, &block)
+      ::Facter.add(name, &block)
+    end
+
+    def to_hash
+      ::Facter.to_hash
+    end
+
+    def clear
+      ::Facter.clear
+    end
+
+    def reset
+      ::Facter.reset
+    end
+
+    def resolve(options)
+      ::Facter.resolve(options)
+    end
+
+    def search_external(dirs)
+      ::Facter.search_external(dirs)
+    end
+
+    def search(*dirs)
+      ::Facter.search(*dirs)
+    end
+
+    def trace(value)
+      ::Facter.trace(value) if ::Facter.respond_to? :trace
+    end
+
+    def debugging(value)
+      ::Facter.debugging(value) if ::Facter.respond_to?(:debugging)
+    end
+
+    def load_external?
+      ::Facter.respond_to?(:load_external)
+    end
+
+    def load_external(value)
+      ::Facter.load_external(value) if self.load_external?
+    end
+
+    private
+
+    def setup_logging
+      return unless ::Facter.respond_to? :on_message
+
+      ::Facter.on_message do |level, message|
+        case level
+        when :trace, :debug
+          level = :debug
+        when :info
+          # Same as Puppet
+        when :warn
+          level = :warning
+        when :error
+          level = :err
+        when :fatal
+          level = :crit
+        else
+          next
+        end
+
+        Puppet::Util::Log.create(
+          {
+            :level => level,
+            :source => 'Facter',
+            :message => message
+          }
+        )
+        nil
+      end
+    end
+  end
+end

data/lib/puppet/file_serving/configuration/parser.rb

@@ -78,6 +78,8 @@ class Puppet::FileServing::Configuration::Parser
       mount = Mount::Modules.new(name)
     when "plugins"
       mount = Mount::Plugins.new(name)
+    when "scripts"
+      mount = Mount::Scripts.new(name)
     when "tasks"
       mount = Mount::Tasks.new(name)
     when "locales"

data/lib/puppet/file_serving/configuration.rb

@@ -6,6 +6,7 @@ require_relative '../../puppet/file_serving/mount/modules'
 require_relative '../../puppet/file_serving/mount/plugins'
 require_relative '../../puppet/file_serving/mount/locales'
 require_relative '../../puppet/file_serving/mount/pluginfacts'
+require_relative '../../puppet/file_serving/mount/scripts'
 require_relative '../../puppet/file_serving/mount/tasks'
 
 class Puppet::FileServing::Configuration
@@ -83,6 +84,7 @@ class Puppet::FileServing::Configuration
     @mounts["plugins"] ||= Mount::Plugins.new("plugins")
     @mounts["locales"] ||= Mount::Locales.new("locales")
     @mounts["pluginfacts"] ||= Mount::PluginFacts.new("pluginfacts")
+    @mounts["scripts"] ||= Mount::Scripts.new("scripts")
     @mounts["tasks"] ||= Mount::Tasks.new("tasks")
   end
 

data/lib/puppet/file_serving/mount/file.rb

@@ -3,12 +3,12 @@ require_relative '../../../puppet/file_serving/mount'
 class Puppet::FileServing::Mount::File < Puppet::FileServing::Mount
   def self.localmap
     @localmap ||= {
-      "h" => Facter.value("hostname"),
+      "h" => Puppet.runtime[:facter].value("hostname"),
       "H" => [
-               Facter.value("hostname"),
-               Facter.value("domain")
+               Puppet.runtime[:facter].value("hostname"),
+               Puppet.runtime[:facter].value("domain")
              ].join("."),
-      "d" => Facter.value("domain")
+      "d" => Puppet.runtime[:facter].value("domain")
     }
   end
 

data/lib/puppet/file_serving/mount/scripts.rb

@@ -0,0 +1,24 @@
+require 'puppet/file_serving/mount'
+
+class Puppet::FileServing::Mount::Scripts < Puppet::FileServing::Mount
+  # Return an instance of the appropriate class.
+  def find(path, request)
+    raise _("No module specified") if path.to_s.empty?
+    module_name, relative_path = path.split("/", 2)
+    mod = request.environment.module(module_name)
+    return nil unless mod
+
+    mod.script(relative_path)
+  end
+
+  def search(path, request)
+    result = find(path, request)
+    if result
+      [result]
+    end
+  end
+
+  def valid?
+    true
+  end
+end

data/lib/puppet/file_system/file_impl.rb

@@ -84,7 +84,9 @@ class Puppet::FileSystem::FileImpl
   end
 
   def read_preserve_line_endings(path)
-    read(path, encoding: "bom|#{Encoding.default_external.name}")
+    default_encoding = Encoding.default_external.name
+    encoding = default_encoding.downcase.start_with?('utf-') ? "bom|#{default_encoding}" : default_encoding
+    read(path, encoding: encoding)
   end
 
   def binread(path)

data/lib/puppet/file_system.rb

@@ -345,7 +345,8 @@ module Puppet::FileSystem
   # value ~ will be expanded to something like /Users/Foo
   #
   # This method exists primarlily to resolve a Ruby deficiency where
-  # File.expand_path doesn't handle ~ in each segment on a Windows path
+  # File.expand_path doesn't convert short paths to long paths, which is
+  # important when resolving the path to load.
   #
   # @param path [Object] a path handle produced by {#pathname}
   # @return [String] a string representation of the path