Module: Puppet::Util

Extended by:
POSIX, SymbolicFileMode
Included in:
Puppet, Application, Application, Configurer, Confine, Interface, Node::Exec, Parameter, Parameter, Parser::Compiler, Parser::Functions, Parser::Resource, Parser::Resource::Param, Parser::TemplateWrapper, Provider, Provider, Resource::Catalog::Compiler, Transaction, Type, Type, ClassGen, FileParsing, FileParsing::FileRecord, InstanceLoader, Log, Log, ProviderFeatures::ProviderFeature, Reference, Storage
Defined in:
lib/puppet/util/multi_match.rb,
lib/puppet/util.rb,
lib/puppet/util/json.rb,
lib/puppet/util/logging.rb,
lib/puppet/util/platform.rb,
lib/puppet/util/run_mode.rb,
lib/puppet/util/command_line.rb,
lib/puppet/util/execution_stub.rb,
lib/puppet/util/windows/string.rb,
lib/puppet/util/windows/eventlog.rb,
lib/puppet/util/constant_inflector.rb,
lib/puppet/util/symbolic_file_mode.rb,
lib/puppet/util/command_line/trollop.rb,
lib/puppet/util/command_line/puppet_option_parser.rb

Overview

MultiMatch allows multiple values to be tested at once in a case expression. This class is needed since Array does not implement the === operator to mean "each v === other.each v".

This class is useful in situations when the Puppet Type System cannot be used (e.g. in Logging, since it needs to be able to log very early in the initialization cycle of puppet)

Typically used with the constants NOT_NIL TUPLE TRIPLE

which test against single NOT_NIL value, Array with two NOT_NIL, and Array with three NOT_NIL

Defined Under Namespace

Modules: AtFork, Backups, CharacterEncoding, Checksums, ClassGen, Colors, ConstantInflector, Diff, Docs, Errors, Execution, FileParsing, IniConfig, InstanceLoader, Json, Ldap, Libuser, Limits, Logging, MonkeyPatches, POSIX, Package, Platform, Plist, Profiler, ProviderFeatures, PsychSupport, RDoc, RetryAction, RpmCompare, RubyGems, SELinux, SUIDManager, Splayer, SymbolicFileMode, Tagging, Terminal, Warnings, Watcher, Windows, Yaml Classes: Autoload, CommandLine, ExecutionStub, Feature, FileNamespaceAdapter, FileType, FileWatcher, JsonLockfile, Lockfile, Log, Metric, ModuleDirectoriesAdapter, MultiMatch, NetworkDevice, Pidlock, Reference, ResourceTemplate, RunMode, SkipTags, Storage, TagSet, UnixRunMode, WatchedFile, WindowsRunMode

Constant Summary collapse

AbsolutePathWindows = 
/^(?:(?:[A-Z]:#{slash})|(?:#{slash}#{slash}#{label}#{slash}#{label})|(?:#{slash}#{slash}\?#{slash}#{label}))/io
AbsolutePathPosix = 
%r{^/}
RFC_3986_URI_REGEX = 
%r{^(?<scheme>(?:[^:/?#]+):)?(?<authority>//(?:[^/?#]*))?(?<path>[^?#]*)(?:\?(?<query>[^#]*))?(?:#(?<fragment>.*))?$}
ALPHA =

From https://github.com/ruby/ruby/blob/v2_7_3/lib/uri/rfc2396_parser.rb#L24-L46

"a-zA-Z"
ALNUM = 
"#{ALPHA}\\d"
UNRESERVED = 
"\\-_.!~*'()#{ALNUM}"
RESERVED = 
";/?:@&=+$,\\[\\]"
UNSAFE = 
Regexp.new("[^#{UNRESERVED}#{RESERVED}]").freeze
HEX = 
"a-fA-F\\d"
ESCAPED = 
Regexp.new("%[#{HEX}]{2}").freeze
PUPPET_STACK_INSERTION_FRAME =

Matches the frame where Puppet::Pops::PuppetStack.stack appears in a Ruby backtrace. The format varies by Ruby version and implementation:

Ruby 3.3:  in `stack'
Ruby 3.4+: in 'Puppet::Pops::PuppetStack.stack'  (qualified for module method)
JRuby 10+: in 'stack'                            (unqualified)
/puppet_stack\.rb.*in ['`](?:Puppet::Pops::PuppetStack\.)?stack'/
DEFAULT_POSIX_MODE =

Replace a file, securely. This takes a block, and passes it the file handle of a file open for writing. Write the replacement content inside the block and it will safely replace the target file.

This method will make no changes to the target file until the content is successfully written and the block returns without raising an error.

As far as possible the state of the existing file, such as mode, is preserved. This works hard to avoid loss of any metadata, but will result in an inode change for the file.

Arguments: filename, default_mode, staging_location

The filename is the file we are going to replace.

The default_mode is the mode to use when the target file doesn't already exist; if the file is present we copy the existing mode/owner/group values across. The default_mode can be expressed as an octal integer, a numeric string (ie '0664') or a symbolic file mode.

The staging_location is a location to render the temporary file before moving the file to it's final location.

0o644
DEFAULT_WINDOWS_MODE = 
nil
HttpProxy =

for backwards compatibility

Puppet::HTTP::Proxy

Constants included from POSIX

POSIX::LOCALE_ENV_VARS, POSIX::USER_ENV_VARS

Constants included from SymbolicFileMode

SymbolicFileMode::SetGIDBit, SymbolicFileMode::SetUIDBit, SymbolicFileMode::StickyBit, SymbolicFileMode::SymbolicMode, SymbolicFileMode::SymbolicSpecialToBit

Class Method Summary collapse

Methods included from POSIX

get_posix_field, gid, groups_of, idfield, methodbyid, methodbyname, search_posix_field, uid

Methods included from SymbolicFileMode

display_mode, normalize_symbolic_mode, symbolic_mode_to_int, valid_symbolic_mode?

Class Method Details

.absolute_path?(path, platform = nil) ⇒ Boolean

Returns:

  • (Boolean) 


258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
 
# File 'lib/puppet/util.rb', line 258

def absolute_path?(path, platform = nil)
  unless path.is_a?(String)
    Puppet.warning("Cannot check if #{path} is an absolute path because it is a '#{path.class}' and not a String'")
    return false
  end

  # Ruby only sets File::ALT_SEPARATOR on Windows and the Ruby standard
  # library uses that to test what platform it's on.  Normally in Puppet we
  # would use Puppet.features.microsoft_windows?, but this method needs to
  # be called during the initialization of features so it can't depend on
  # that.
  #
  # @deprecated Use ruby's built-in methods to determine if a path is absolute.
  platform ||= Puppet::Util::Platform.windows? ? :windows : :posix
  regex = case platform
          when :windows
            AbsolutePathWindows
          when :posix
            AbsolutePathPosix
          else
            raise Puppet::DevError, _("unknown platform %{platform} in absolute_path") % { platform: platform }
          end

  !!(path =~ regex)
end

.benchmark(*args) ⇒ Object

execute a block of work and based on the logging level provided, log the provided message with the seconds taken The message 'msg' should include string ' in %seconds seconds' as part of the message and any content should escape any percent signs '%' so that they are not interpreted as formatting commands escaped_str = str.gsub(/%/, '%%')

Parameters:

  • msg (String) —

    the message to be formated to assigned the %seconds seconds take to execute, other percent signs '%' need to be escaped

  • level (Symbol) —

    the logging level for this message

  • object (Object) —

    The object use for logging the message

Raises:



172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/puppet/util.rb', line 172

def benchmark(*args)
  msg = args.pop
  level = args.pop
  object = if args.empty?
             if respond_to?(level)
               self
             else
               Puppet
             end
           else
             args.pop
           end

  # TRANSLATORS 'benchmark' is a method name and should not be translated
  raise Puppet::DevError, _("Failed to provide level to benchmark") unless level

  unless level == :none or object.respond_to? level
    raise Puppet::DevError, _("Benchmarked object does not respond to %{value}") % { value: level }
  end

  # Only benchmark if our log level is high enough
  if level != :none and Puppet::Util::Log.sendlevel?(level)
    seconds = Benchmark.realtime {
      yield
    }
    object.send(level, msg % { seconds: "%0.2f" % seconds })
    seconds
  else
    yield
  end
end

.chuser ⇒ Object

Change the process to a different user



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/puppet/util.rb', line 112

def self.chuser
  group = Puppet[:group]
  if group
    begin
      Puppet::Util::SUIDManager.change_group(group, true)
    rescue => detail
      Puppet.warning _("could not change to group %{group}: %{detail}") % { group: group.inspect, detail: detail }
      $stderr.puts _("could not change to group %{group}") % { group: group.inspect }

      # Don't exit on failed group changes, since it's
      # not fatal
      # exit(74)
    end
  end

  user = Puppet[:user]
  if user
    begin
      Puppet::Util::SUIDManager.change_user(user, true)
    rescue => detail
      $stderr.puts _("Could not change to user %{user}: %{detail}") % { user: user, detail: detail }
      exit(74)
    end
  end
end

.clear_environment(mode = default_env) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Use ENV instead



62
63
64
65
 
# File 'lib/puppet/util.rb', line 62

def clear_environment(mode = default_env)
  Puppet.deprecation_warning(_("Puppet::Util.clear_environment is deprecated and will be removed in a future version. Use ENV.clear directly instead."))
  ENV.clear
end

.create_erb(content) ⇒ Object 



39
40
41
 
# File 'lib/puppet/util.rb', line 39

def create_erb(content)
  ERB.new(content, trim_mode: '-')
end

.default_env ⇒ Object 



32
33
34
35
36
 
# File 'lib/puppet/util.rb', line 32

def default_env
  Puppet.features.microsoft_windows? ?
    :windows :
    :posix
end

.deterministic_rand(seed, max) ⇒ Object 



736
737
738
 
# File 'lib/puppet/util.rb', line 736

def deterministic_rand(seed, max)
  deterministic_rand_int(seed, max).to_s
end

.deterministic_rand_int(seed, max) ⇒ Object 



741
742
743
 
# File 'lib/puppet/util.rb', line 741

def deterministic_rand_int(seed, max)
  Random.new(seed).rand(max)
end

.exit_on_fail(message, code = 1) { ... } ⇒ Object

Executes a block of code, wrapped with some special exception handling. Causes the ruby interpreter to exit if the block throws an exception.

Parameters:

  • message (String) —

    a message to log if the block fails

  • code (Integer) (defaults to: 1) —

    the exit code that the ruby interpreter should return if the block fails

Yields:



717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
 
# File 'lib/puppet/util.rb', line 717

def exit_on_fail(message, code = 1)
  yield
# First, we need to check and see if we are catching a SystemExit error.  These will be raised
#  when we daemonize/fork, and they do not necessarily indicate a failure case.
rescue SystemExit => err
  raise err

# Now we need to catch *any* other kind of exception, because we may be calling third-party
#  code (e.g. webrick), and we have no idea what they might throw.
rescue Exception => err
  ## NOTE: when debugging spec failures, these two lines can be very useful
  # puts err.inspect
  # puts Puppet::Util.pretty_backtrace(err.backtrace)
  Puppet.log_exception(err, "#{message}: #{err}")
  Puppet::Util::Log.force_flushqueue()
  exit(code)
end

.format_backtrace_array(primary_stack, puppetstack = []) ⇒ Object

arguments may be a Ruby stack, with an optional Puppet stack argument, or just a Puppet stack. stacks may be an Array of Strings "/foo.rb:0 in `blah'" or an Array of Arrays that represent a frame: ["/foo.pp", 0]



548
549
550
551
552
553
554
555
556
557
558
559
560
 
# File 'lib/puppet/util.rb', line 548

def self.format_backtrace_array(primary_stack, puppetstack = [])
  primary_stack.flat_map do |frame|
    frame = format_puppetstack_frame(frame) if frame.is_a?(Array)
    primary_frame = resolve_stackframe(frame)

    if primary_frame =~ PUPPET_STACK_INSERTION_FRAME && !puppetstack.empty?
      [resolve_stackframe(format_puppetstack_frame(puppetstack.shift)),
       primary_frame]
    else
      primary_frame
    end
  end
end

.format_puppetstack_frame(file_and_lineno) ⇒ Object 



576
577
578
 
# File 'lib/puppet/util.rb', line 576

def self.format_puppetstack_frame(file_and_lineno)
  file_and_lineno.join(':')
end

.get_env(name, mode = default_env) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Use ENV instead



46
47
48
49
 
# File 'lib/puppet/util.rb', line 46

def get_env(name, mode = default_env)
  Puppet.deprecation_warning(_("Puppet::Util.get_env is deprecated and will be removed in a future version. Use ENV[] directly instead."))
  ENV.fetch(name, nil)
end

.get_environment(mode = default_env) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Use ENV instead



54
55
56
57
 
# File 'lib/puppet/util.rb', line 54

def get_environment(mode = default_env)
  Puppet.deprecation_warning(_("Puppet::Util.get_environment is deprecated and will be removed in a future version. Use ENV.to_hash directly instead."))
  ENV.to_hash
end

.logmethods(klass, useself = true) ⇒ Object

Create instance methods for each of the log levels. This allows the messages to be a little richer. Most classes will be calling this method.



141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
 
# File 'lib/puppet/util.rb', line 141

def self.logmethods(klass, useself = true)
  Puppet::Util::Log.eachlevel { |level|
    klass.send(:define_method, level, proc { |args|
      args = args.join(" ") if args.is_a?(Array)
      if useself

        Puppet::Util::Log.create(
          :level => level,
          :source => self,
          :message => args
        )
      else

        Puppet::Util::Log.create(
          :level => level,
          :message => args
        )
      end
    })
  }
end

.merge_environment(env_hash, mode = default_env) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Use ENV instead



78
79
80
81
 
# File 'lib/puppet/util.rb', line 78

def merge_environment(env_hash, mode = default_env)
  Puppet.deprecation_warning(_("Puppet::Util.merge_environment is deprecated and will be removed in a future version. Use ENV.merge! directly instead."))
  ENV.merge!(env_hash.transform_keys(&:to_s))
end

.path_to_uri(path) ⇒ Object

Convert a path to a file URI



286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
 
# File 'lib/puppet/util.rb', line 286

def path_to_uri(path)
  return unless path

  params = { :scheme => 'file' }

  if Puppet::Util::Platform.windows?
    path = path.tr('\\', '/')

    unc = %r{^//([^/]+)(/.+)}.match(path)
    if unc
      params[:host] = unc[1]
      path = unc[2]
    elsif path =~ %r{^[a-z]:/}i
      path = '/' + path
    end
  end

  # have to split *after* any relevant escaping
  params[:path], params[:query] = uri_encode(path).split('?')
  search_for_fragment = params[:query] ? :query : :path
  if params[search_for_fragment].include?('#')
    params[search_for_fragment], _, params[:fragment] = params[search_for_fragment].rpartition('#')
  end

  begin
    URI::Generic.build(params)
  rescue => detail
    raise Puppet::Error, _("Failed to convert '%{path}' to URI: %{detail}") % { path: path, detail: detail }, detail.backtrace
  end
end

.pretty_backtrace(backtrace = caller(1), puppetstack = []) ⇒ Object

utility method to get the current call stack and format it to a human-readable string (which some IDEs/editors will recognize as links to the line numbers in the trace)



540
541
542
 
# File 'lib/puppet/util.rb', line 540

def self.pretty_backtrace(backtrace = caller(1), puppetstack = [])
  format_backtrace_array(backtrace, puppetstack).join("\n")
end

.replace_file(file, default_mode, staging_location: nil, validate_callback: nil, &block) ⇒ Object

Raises:



606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
 
# File 'lib/puppet/util.rb', line 606

def replace_file(file, default_mode, staging_location: nil, validate_callback: nil, &block)
  raise Puppet::DevError, _("replace_file requires a block") unless block_given?

  if default_mode
    unless valid_symbolic_mode?(default_mode)
      raise Puppet::DevError, _("replace_file default_mode: %{default_mode} is invalid") % { default_mode: default_mode }
    end

    mode = symbolic_mode_to_int(normalize_symbolic_mode(default_mode))
  elsif Puppet::Util::Platform.windows?
    mode = DEFAULT_WINDOWS_MODE
  else
    mode = DEFAULT_POSIX_MODE
  end

  begin
    file = Puppet::FileSystem.pathname(file)

    # encoding for Uniquefile is not important here because the caller writes to it as it sees fit
    if staging_location
      tempfile = Puppet::FileSystem::Uniquefile.new(Puppet::FileSystem.basename_string(file), staging_location)
    else
      tempfile = Puppet::FileSystem::Uniquefile.new(Puppet::FileSystem.basename_string(file), Puppet::FileSystem.dir_string(file))
    end

    effective_mode =
      unless Puppet::Util::Platform.windows?
        # Grab the current file mode, and fall back to the defaults.

        if Puppet::FileSystem.exist?(file)
          stat = Puppet::FileSystem.lstat(file)
          tempfile.chown(stat.uid, stat.gid)
          stat.mode
        else
          mode
        end
      end

    # OK, now allow the caller to write the content of the file.
    yield tempfile

    if effective_mode
      # We only care about the bottom four slots, which make the real mode,
      # and not the rest of the platform stat call fluff and stuff.
      tempfile.chmod(effective_mode & 0o7777)
    end

    # Now, make sure the data (which includes the mode) is safe on disk.
    tempfile.flush
    begin
      tempfile.fsync
    rescue NotImplementedError
      # fsync may not be implemented by Ruby on all platforms, but
      # there is absolutely no recovery path if we detect that.  So, we just
      # ignore the return code.
      #
      # However, don't be fooled: that is accepting that we are running in
      # an unsafe fashion.  If you are porting to a new platform don't stub
      # that out.
    end

    tempfile.close

    if validate_callback
      validate_callback.call(tempfile.path)
    end

    if Puppet::Util::Platform.windows?
      # Windows ReplaceFile needs a file to exist, so touch handles this
      unless Puppet::FileSystem.exist?(file)
        Puppet::FileSystem.touch(file)
        if mode
          Puppet::Util::Windows::Security.set_mode(mode, Puppet::FileSystem.path_string(file))
        end
      end
      # Yes, the arguments are reversed compared to the rename in the rest
      # of the world.
      Puppet::Util::Windows::File.replace_file(FileSystem.path_string(file), tempfile.path)

    else
      # MRI Ruby checks for this and raises an error, while JRuby removes the directory
      # and replaces it with a file. This makes the our version of replace_file() consistent
      if Puppet::FileSystem.exist?(file) && Puppet::FileSystem.directory?(file)
        raise Errno::EISDIR, _("Is a directory: %{directory}") % { directory: file }
      end

      File.rename(tempfile.path, Puppet::FileSystem.path_string(file))
    end
  ensure
    # in case an error occurred before we renamed the temp file, make sure it
    # gets deleted
    if tempfile
      tempfile.close!
    end
  end

  # Ideally, we would now fsync the directory as well, but Ruby doesn't
  # have support for that, and it doesn't matter /that/ much...

  # Return something true, and possibly useful.
  file
end

.resolve_stackframe(frame) ⇒ Object 



562
563
564
565
566
567
568
569
570
571
572
573
574
 
# File 'lib/puppet/util.rb', line 562

def self.resolve_stackframe(frame)
  _, path, rest = /^(.*):(\d+.*)$/.match(frame).to_a
  if path
    path = begin
      Pathname(path).realpath
    rescue
      path
    end
    "#{path}:#{rest}"
  else
    frame
  end
end

.rfc2396_escape(str) ⇒ Object 



457
458
459
460
461
462
463
464
465
 
# File 'lib/puppet/util.rb', line 457

def rfc2396_escape(str)
  str.gsub(UNSAFE) do |match|
    tmp = ''.dup
    match.each_byte do |uc|
      tmp << sprintf('%%%02X', uc)
    end
    tmp
  end.force_encoding(Encoding::US_ASCII)
end

.safe_posix_fork(stdin = $stdin, stdout = $stdout, stderr = $stderr, &block) ⇒ Object 



475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
 
# File 'lib/puppet/util.rb', line 475

def safe_posix_fork(stdin = $stdin, stdout = $stdout, stderr = $stderr, &block)
  Kernel.fork do
    STDIN.reopen(stdin)
    STDOUT.reopen(stdout)
    STDERR.reopen(stderr)

    $stdin = STDIN
    $stdout = STDOUT
    $stderr = STDERR

    begin
      d = Dir.new('/proc/self/fd')
      ignore_fds = ['.', '..', d.fileno.to_s]
      d.each_child do |f|
        next if ignore_fds.include?(f) || f.to_i < 3

        begin
          IO.new(f.to_i).close
        rescue
          nil
        end
      end
    rescue Errno::ENOENT, Errno::ENOTDIR # /proc/self/fd not found, /proc/self not a dir
      3.upto(256) { |fd|
        begin
          IO.new(fd).close
        rescue
          nil
        end
      }
    end

    block.call if block
  end
end

.set_env(name, value = nil, mode = default_env) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Use ENV instead



70
71
72
73
 
# File 'lib/puppet/util.rb', line 70

def set_env(name, value = nil, mode = default_env)
  Puppet.deprecation_warning(_("Puppet::Util.set_env is deprecated and will be removed in a future version. Use ENV[]= directly instead."))
  ENV[name] = value
end

.skip_external_facts ⇒ Object

Executes a block of code, wrapped around Facter.load_external(false) and Facter.load_external(true) which will cause Facter to not evaluate external facts.



748
749
750
751
752
753
754
755
756
757
 
# File 'lib/puppet/util.rb', line 748

def skip_external_facts
  return yield unless Puppet.runtime[:facter].load_external?

  begin
    Puppet.runtime[:facter].load_external(false)
    yield
  ensure
    Puppet.runtime[:facter].load_external(true)
  end
end

.symbolizehash(hash) ⇒ Object 



512
513
514
515
516
517
518
519
 
# File 'lib/puppet/util.rb', line 512

def symbolizehash(hash)
  newhash = {}
  hash.each do |name, val|
    name = name.intern if name.respond_to? :intern
    newhash[name] = val
  end
  newhash
end

.thinmark ⇒ Object

Just benchmark, with no logging.



523
524
525
526
527
 
# File 'lib/puppet/util.rb', line 523

def thinmark
  Benchmark.realtime {
    yield
  }
end

.uri_encode(path, opts = { :allow_fragment => false }) ⇒ String

Percent-encodes a URI string per RFC3986 - https://tools.ietf.org/html/rfc3986

Properly handles escaping rules for paths, query strings and fragments independently

The output is safe to pass to URI.parse or URI::Generic.build and will correctly round-trip through URI.unescape

Parameters:

  • A (String path) —

    URI string that may be in the form of:

    http://foo.com/bar?query file://tmp/foo bar //foo.com/bar?query /bar?query bar?query bar . C:WindowsTemp

    Note that with no specified scheme, authority or query parameter delimiter ? that a naked string will be treated as a path.

    Note that if query parameters need to contain data such as & or = that this method should not be used, as there is no way to differentiate query parameter data from query delimiters when multiple parameters are specified

  • Options (Hash{Symbol=>String} opts) —

    to alter encoding

  • opts (Hash) (defaults to: { :allow_fragment => false }) —

    a customizable set of options

Options Hash (opts):

  • :allow_fragment (Array<Symbol>) —

    defaults to false. When false will treat # as part of a path or query and not a fragment delimiter

Returns:

  • (String) —

    a new string containing appropriate portions of the URI encoded per the rules of RFC3986. In particular, path will not encode +, but will encode space as %20 query will encode + as %2B and space as %20 fragment behaves like query

Raises:

  • (ArgumentError) 


412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
 
# File 'lib/puppet/util.rb', line 412

def uri_encode(path, opts = { :allow_fragment => false })
  raise ArgumentError, _('path may not be nil') if path.nil?

  encoded = ''.dup

  # parse uri into named matches, then reassemble properly encoded
  parts = path.match(RFC_3986_URI_REGEX)

  encoded += parts[:scheme] unless parts[:scheme].nil?
  encoded += parts[:authority] unless parts[:authority].nil?

  # path requires space to be encoded as %20 (NEVER +)
  # + should be left unencoded
  # URI::parse and URI::Generic.build don't like paths encoded with CGI.escape
  # URI.escape does not change / to %2F and : to %3A like CGI.escape
  #
  encoded += rfc2396_escape(parts[:path]) unless parts[:path].nil?

  # each query parameter
  unless parts[:query].nil?
    query_string = parts[:query].split('&').map do |pair|
      # can optionally be separated by an =
      pair.split('=').map do |v|
        uri_query_encode(v)
      end.join('=')
    end.join('&')
    encoded += '?' + query_string
  end

  encoded += ((opts[:allow_fragment] ? '#' : '%23') + uri_query_encode(parts[:fragment])) unless parts[:fragment].nil?

  encoded
end

.uri_query_encode(query_string) ⇒ String

Percent-encodes a URI query parameter per RFC3986 - https://tools.ietf.org/html/rfc3986

The output will correctly round-trip through URI.unescape

Parameters:

  • A (String query_string) —

    URI query parameter that may contain reserved characters that must be percent encoded for the key or value to be properly decoded as part of a larger query string:

    query encodes as : query

    query_with_special=chars like&and * and# plus+this encodes as: query_with_special%3Dchars%20like%26and%20%2A%20and%23%20plus%2Bthis

    Note: Also usable by fragments, but not suitable for paths

Returns:

  • (String) —

    a new string containing an encoded query string per the rules of RFC3986.

    In particular, query will encode + as %2B and space as %20



362
363
364
365
366
367
368
369
370
371
372
 
# File 'lib/puppet/util.rb', line 362

def uri_query_encode(query_string)
  return nil if query_string.nil?

  # query can encode space to %20 OR +
  # + MUST be encoded as %2B
  # in RFC3968 both query and fragment are defined as:
  # = *( pchar / "/" / "?" )
  # CGI.escape turns space into + which is the most backward compatible
  # however it doesn't roundtrip through URI.unescape which prefers %20
  CGI.escape(query_string).gsub('+', '%20')
end

.uri_to_path(uri) ⇒ Object

Get the path component of a URI



319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
 
# File 'lib/puppet/util.rb', line 319

def uri_to_path(uri)
  return unless uri.is_a?(URI)

  # CGI.unescape doesn't handle space rules properly in uri paths
  # URI.unescape does, but returns strings in their original encoding
  path = uri_unescape(uri.path.encode(Encoding::UTF_8))

  if Puppet::Util::Platform.windows? && uri.scheme == 'file'
    if uri.host && !uri.host.empty?
      path = "//#{uri.host}" + path # UNC
    else
      path.sub!(%r{^/}, '')
    end
  end

  path
end

.uri_unescape(str) ⇒ Object 



468
469
470
471
472
 
# File 'lib/puppet/util.rb', line 468

def uri_unescape(str)
  enc = str.encoding
  enc = Encoding::UTF_8 if enc == Encoding::US_ASCII
  str.gsub(ESCAPED) { [::Regexp.last_match(0)[1, 2]].pack('H2').force_encoding(enc) }
end

.which(bin) ⇒ String

Resolve a path for an executable to the absolute path. This tries to behave in the same manner as the unix which command and uses the PATH environment variable.

Parameters:

  • bin (String) —

    the name of the executable to find.

Returns:

  • (String) —

    the absolute path to the found executable.



212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
 
# File 'lib/puppet/util.rb', line 212

def which(bin)
  if absolute_path?(bin)
    return bin if FileTest.file? bin and FileTest.executable? bin
  else
    exts = ENV.fetch('PATHEXT', nil)
    exts = exts ? exts.split(File::PATH_SEPARATOR) : %w[.COM .EXE .BAT .CMD]
    ENV.fetch('PATH').split(File::PATH_SEPARATOR).each do |dir|
      dest = File.expand_path(File.join(dir, bin))
    rescue ArgumentError => e
      # if the user's PATH contains a literal tilde (~) character and HOME is not set, we may get
      # an ArgumentError here.  Let's check to see if that is the case; if not, re-raise whatever error
      # was thrown.
      if e.to_s =~ /HOME/ and (ENV['HOME'].nil? || ENV.fetch('HOME', nil) == "")
        # if we get here they have a tilde in their PATH.  We'll issue a single warning about this and then
        # ignore this path element and carry on with our lives.
        # TRANSLATORS PATH and HOME are environment variables and should not be translated
        Puppet::Util::Warnings.warnonce(_("PATH contains a ~ character, and HOME is not set; ignoring PATH element '%{dir}'.") % { dir: dir })
      elsif e.to_s =~ /doesn't exist|can't find user/
        # ...otherwise, we just skip the non-existent entry, and do nothing.
        # TRANSLATORS PATH is an environment variable and should not be translated
        Puppet::Util::Warnings.warnonce(_("Couldn't expand PATH containing a ~ character; ignoring PATH element '%{dir}'.") % { dir: dir })
      else
        raise
      end
    else
      if Puppet::Util::Platform.windows? && File.extname(dest).empty?
        exts.each do |ext|
          destext = File.expand_path(dest + ext)
          return destext if FileTest.file? destext and FileTest.executable? destext
        end
      end
      return dest if FileTest.file? dest and FileTest.executable? dest
    end
  end
  nil
end

.withenv(hash, mode = :posix) ⇒ Object

Run some code with a specific environment. Resets the environment back to what it was at the end of the code.

Parameters:

  • hash (Hash{String,Symbol => String}) —

    Environment variables to override the current environment.

  • mode (Symbol) (defaults to: :posix) —

    ignored



89
90
91
92
93
94
95
96
97
 
# File 'lib/puppet/util.rb', line 89

def withenv(hash, mode = :posix)
  saved = ENV.to_hash
  begin
    ENV.merge!(hash.transform_keys(&:to_s))
    yield
  ensure
    ENV.replace(saved)
  end
end

.withumask(mask) ⇒ Object

Execute a given chunk of code with a new umask.



101
102
103
104
105
106
107
108
109
 
# File 'lib/puppet/util.rb', line 101

def self.withumask(mask)
  cur = File.umask(mask)

  begin
    yield
  ensure
    File.umask(cur)
  end
end