chef 12.19.36 → 14.14.25

data/lib/chef/mixin/params_validate.rb

@@ -1,6 +1,6 @@
 #
 # Author:: Adam Jacob (<adam@chef.io>)
-# Copyright:: Copyright 2008-2016, Chef Software Inc.
+# Copyright:: Copyright 2008-2018, Chef Software Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -18,6 +18,7 @@
 require "chef/constants"
 require "chef/property"
 require "chef/delayed_evaluator"
+require "chef/exceptions"
 
 class Chef
   module Mixin
@@ -34,6 +35,8 @@ class Chef
       # map options are:
       #
       # @param opts [Hash<Symbol,Object>] Validation opts.
+      #   @option opts [String] :validation_message A custom message to return
+      #     should validation fail.
       #   @option opts [Object,Array] :is An object, or list of
       #     objects, that must match the value using Ruby's `===` operator
       #     (`opts[:is].any? { |v| v === value }`). (See #_pv_is.)
@@ -90,16 +93,20 @@ class Chef
         raise ArgumentError, "Options must be a hash" unless opts.kind_of?(Hash)
         raise ArgumentError, "Validation Map must be a hash" unless map.kind_of?(Hash)
 
+        @validation_message ||= {}
+
         map.each do |key, validation|
           unless key.kind_of?(Symbol) || key.kind_of?(String)
             raise ArgumentError, "Validation map keys must be symbols or strings!"
           end
+
           case validation
           when true
             _pv_required(opts, key)
           when false
             true
           when Hash
+            @validation_message[key] = validation.delete(:validation_message) if validation.key?(:validation_message)
             validation.each do |check, carg|
               check_method = "_pv_#{check}"
               if respond_to?(check_method, true)
@@ -124,15 +131,15 @@ class Chef
 
       private
 
-      def explicitly_allows_nil?(key, validation)
-        validation.has_key?(:is) && _pv_is({ key => nil }, key, validation[:is], raise_error: false)
+      def _validation_message(key, default)
+        @validation_message.key?(key) ? @validation_message[key] : default
       end
 
       # Return the value of a parameter, or nil if it doesn't exist.
       def _pv_opts_lookup(opts, key)
-        if opts.has_key?(key.to_s)
+        if opts.key?(key.to_s)
           opts[key.to_s]
-        elsif opts.has_key?(key.to_sym)
+        elsif opts.key?(key.to_sym)
           opts[key.to_sym]
         else
           nil
@@ -142,9 +149,9 @@ class Chef
       # Raise an exception if the parameter is not found.
       def _pv_required(opts, key, is_required = true, explicitly_allows_nil = false)
         if is_required
-          return true if opts.has_key?(key.to_s) && (explicitly_allows_nil || !opts[key.to_s].nil?)
-          return true if opts.has_key?(key.to_sym) && (explicitly_allows_nil || !opts[key.to_sym].nil?)
-          raise Exceptions::ValidationFailed, "Required argument #{key.inspect} is missing!"
+          return true if opts.key?(key.to_s) && (explicitly_allows_nil || !opts[key.to_s].nil?)
+          return true if opts.key?(key.to_sym) && (explicitly_allows_nil || !opts[key.to_sym].nil?)
+          raise Exceptions::ValidationFailed, _validation_message(key, "Required argument #{key.inspect} is missing!")
         end
         true
       end
@@ -167,7 +174,9 @@ class Chef
           to_be.each do |tb|
             return true if value == tb
           end
-          raise Exceptions::ValidationFailed, "Option #{key} must be equal to one of: #{to_be.join(", ")}!  You passed #{value.inspect}."
+          # Ruby will print :something as something, which confuses users so make sure to print them as symbols
+          # by inspecting the value instead of just printing it
+          raise Exceptions::ValidationFailed, _validation_message(key, "Option #{key} must be equal to one of: #{to_be.map { |v| v.inspect }.join(", ")}!  You passed #{value.inspect}.")
         end
       end
 
@@ -186,7 +195,7 @@ class Chef
           to_be.each do |tb|
             return true if value.kind_of?(tb)
           end
-          raise Exceptions::ValidationFailed, "Option #{key} must be a kind of #{to_be}!  You passed #{value.inspect}."
+          raise Exceptions::ValidationFailed, _validation_message(key, "Option #{key} must be a kind of #{to_be}!  You passed #{value.inspect}.")
         end
       end
 
@@ -201,7 +210,7 @@ class Chef
         unless value.nil?
           Array(method_name_list).each do |method_name|
             unless value.respond_to?(method_name)
-              raise Exceptions::ValidationFailed, "Option #{key} must have a #{method_name} method!"
+              raise Exceptions::ValidationFailed, _validation_message(key, "Option #{key} must have a #{method_name} method!")
             end
           end
         end
@@ -233,7 +242,7 @@ class Chef
 
             if value.respond_to?(predicate_method)
               if value.send(predicate_method)
-                raise Exceptions::ValidationFailed, "Option #{key} cannot be #{predicate_method_base_name}"
+                raise Exceptions::ValidationFailed, _validation_message(key, "Option #{key} cannot be #{predicate_method_base_name}")
               end
             end
           end
@@ -293,7 +302,7 @@ class Chef
           Array(regex).flatten.each do |r|
             return true if r.match(value.to_s)
           end
-          raise Exceptions::ValidationFailed, "Option #{key}'s value #{value} does not match regular expression #{regex.inspect}"
+          raise Exceptions::ValidationFailed, _validation_message(key, "Property #{key}'s value #{value} does not match regular expression #{regex.inspect}")
         end
       end
 
@@ -315,7 +324,7 @@ class Chef
         if !value.nil?
           callbacks.each do |message, zeproc|
             unless zeproc.call(value)
-              raise Exceptions::ValidationFailed, "Option #{key}'s value #{value} #{message}!"
+              raise Exceptions::ValidationFailed, _validation_message(key, "Option #{key}'s value #{value} #{message}!")
             end
           end
         end
@@ -332,7 +341,7 @@ class Chef
       def _pv_name_property(opts, key, is_name_property = true)
         if is_name_property
           if opts[key].nil?
-            raise CannotValidateStaticallyError, "name_property cannot be evaluated without a resource." if self == Chef::Mixin::ParamsValidate
+            raise Exceptions::CannotValidateStaticallyError, "name_property cannot be evaluated without a resource." if self == Chef::Mixin::ParamsValidate
             opts[key] = instance_variable_get(:"@name")
           end
         end
@@ -396,15 +405,15 @@ class Chef
       #   x nil      #=> invalid
       #   ```
       #
-      def _pv_is(opts, key, to_be, raise_error: true)
-        return true if !opts.has_key?(key.to_s) && !opts.has_key?(key.to_sym)
+      def _pv_is(opts, key, to_be)
+        return true if !opts.key?(key.to_s) && !opts.key?(key.to_sym)
         value = _pv_opts_lookup(opts, key)
         to_be = [ to_be ].flatten(1)
         errors = []
         passed = to_be.any? do |tb|
           case tb
           when Proc
-            raise CannotValidateStaticallyError, "is: proc { } must be evaluated once for each resource" if self == Chef::Mixin::ParamsValidate
+            raise Exceptions::CannotValidateStaticallyError, "is: proc { } must be evaluated once for each resource" if self == Chef::Mixin::ParamsValidate
             instance_exec(value, &tb)
           when Property
             begin
@@ -427,7 +436,7 @@ class Chef
           unless errors.empty?
             message << " Errors:\n#{errors.map { |m| "- #{m}" }.join("\n")}"
           end
-          raise Exceptions::ValidationFailed, message
+          raise Exceptions::ValidationFailed, _validation_message(key, message)
         end
       end
 
@@ -447,11 +456,11 @@ class Chef
       #   ```
       #
       def _pv_coerce(opts, key, coercer)
-        if opts.has_key?(key.to_s)
-          raise CannotValidateStaticallyError, "coerce must be evaluated for each resource." if self == Chef::Mixin::ParamsValidate
+        if opts.key?(key.to_s)
+          raise Exceptions::CannotValidateStaticallyError, "coerce must be evaluated for each resource." if self == Chef::Mixin::ParamsValidate
           opts[key.to_s] = instance_exec(opts[key], &coercer)
-        elsif opts.has_key?(key.to_sym)
-          raise CannotValidateStaticallyError, "coerce must be evaluated for each resource." if self == Chef::Mixin::ParamsValidate
+        elsif opts.key?(key.to_sym)
+          raise Exceptions::CannotValidateStaticallyError, "coerce must be evaluated for each resource." if self == Chef::Mixin::ParamsValidate
           opts[key.to_sym] = instance_exec(opts[key], &coercer)
         end
       end

data/lib/chef/mixin/path_sanity.rb

@@ -1,6 +1,6 @@
 #
 # Author:: Seth Chisamore (<schisamo@chef.io>)
-# Copyright:: Copyright 2011-2016, Chef Software Inc.
+# Copyright:: Copyright 2011-2017, Chef Software Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -22,25 +22,23 @@ class Chef
 
       def enforce_path_sanity(env = ENV)
         if Chef::Config[:enforce_path_sanity]
-          env["PATH"] = "" if env["PATH"].nil?
-          path_separator = Chef::Platform.windows? ? ";" : ":"
-          existing_paths = env["PATH"].split(path_separator)
-          # ensure the Ruby and Gem bindirs are included
-          # mainly for 'full-stack' Chef installs
-          paths_to_add = []
-          paths_to_add << ruby_bindir unless sane_paths.include?(ruby_bindir)
-          paths_to_add << gem_bindir unless sane_paths.include?(gem_bindir)
-          paths_to_add << sane_paths if sane_paths
-          paths_to_add.flatten!.compact!
-          paths_to_add.each do |sane_path|
-            unless existing_paths.include?(sane_path)
-              env_path = env["PATH"].dup
-              env_path << path_separator unless env["PATH"].empty?
-              env_path << sane_path
-              env["PATH"] = env_path.encode("utf-8", invalid: :replace, undef: :replace)
-            end
-          end
+          env["PATH"] = sanitized_path(env)
+        end
+      end
+
+      def sanitized_path(env = ENV)
+        env_path = env["PATH"].nil? ? "" : env["PATH"].dup
+        path_separator = Chef::Platform.windows? ? ";" : ":"
+        # ensure the Ruby and Gem bindirs are included
+        # mainly for 'full-stack' Chef installs
+        new_paths = env_path.split(path_separator)
+        [ ruby_bindir, gem_bindir ].compact.each do |path|
+          new_paths = [ path ] + new_paths unless new_paths.include?(path)
+        end
+        sane_paths.each do |path|
+          new_paths << path unless new_paths.include?(path)
         end
+        new_paths.join(path_separator).encode("utf-8", invalid: :replace, undef: :replace)
       end
 
       private

data/lib/chef/mixin/powershell_exec.rb

@@ -0,0 +1,105 @@
+#
+# Author:: Stuart Preston (<stuart@chef.io>)
+# Copyright:: Copyright 2018, Chef Software, Inc.
+# License:: Apache License, Version 2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "chef/powershell"
+
+# The powershell_exec mixin provides in-process access to PowerShell engine via
+# a COM interop (installed by the Chef Client installer).
+#
+# powershell_exec returns a Chef::PowerShell object that provides 3 methods:
+#
+# .result - returns a hash representing the results returned by executing the
+#           PowerShell script block
+# .errors - this is an array of string containing any messages written to the
+#           PowerShell error stream during execution
+# .error? - returns true if there were error messages written to the PowerShell
+#           error stream during execution
+#
+# Some examples of usage:
+#
+# > powershell_exec("(Get-Item c:\\windows\\system32\\w32time.dll).VersionInfo"
+#   ).result["FileVersion"]
+#  => "10.0.14393.0 (rs1_release.160715-1616)"
+#
+# > powershell_exec("(get-process ruby).Mainmodule").result["FileName"]
+#  => C:\\opscode\\chef\\embedded\\bin\\ruby.exe"
+#
+# > powershell_exec("$a = $true; $a").result
+#  => true
+#
+# > powershell_exec("not-found").errors
+#  => ["ObjectNotFound: (not-found:String) [], CommandNotFoundException: The
+#  term 'not-found' is not recognized as the name of a cmdlet, function, script
+#  file, or operable program. Check the spelling of the name, or if a path was
+#  included, verify that the path is correct and try again. (at <ScriptBlock>,
+#   <No file>: line 1)"]
+#
+# > powershell_exec("not-found").error?
+#  => true
+#
+# > powershell_exec("get-item c:\\notfound -erroraction stop")
+# WIN32OLERuntimeError: (in OLE method `ExecuteScript': )
+#     OLE error code:80131501 in System.Management.Automation
+#       The running command stopped because the preference variable
+#       "ErrorActionPreference" or common parameter is set to Stop: Cannot find
+#       path 'C:\notfound' because it does not exist.
+#
+# *Why use this and not powershell_out?* Startup time to invoke the PowerShell
+# engine is much faster (over 7X faster in tests) than writing the PowerShell
+# to disk, shelling out to powershell.exe and retrieving the .stdout or .stderr
+# methods afterwards.  Additionally we are able to have a higher fidelity
+# conversation with PowerShell because we are now working with the objects that
+# are returned by the script, rather than having to parse the stdout of
+# powershell.exe to get a result.
+#
+# *How does this work?*  In .NET terms, when you run a PowerShell script block
+# through the engine, behind the scenes you get a Collection<PSObject> returned
+# and simply we are serializing this, adding any errors that were generated to
+# a custom JSON string transferred in memory to Ruby.  The easiest way to
+# develop for this approach is to imagine that the last thing that happens in
+# your PowerShell script block is "ConvertTo-Json".  That's exactly what we are
+# doing here behind the scenes.
+#
+# There are a handful of current limitations with this approach:
+# - Windows UAC elevation is controlled by the token assigned to the account
+#   that Ruby.exe is running under.
+# - Terminating errors will result in a WIN32OLERuntimeError and typically are
+#   handled as an exception.
+# - There are no return/error codes, as we are not shelling out to
+#   powershell.exe but calling a method inline, no errors codes are returned.
+# - There is no settable timeout on powershell_exec method execution.
+# - It is not possible to impersonate another user running powershell, the
+#   credentials of the user running Chef Client are used.
+#
+
+class Chef
+  module Mixin
+    module PowershellExec
+      # Run a command under PowerShell via a managed (.NET) COM interop API.
+      # This implementation requires the managed dll to be registered on the
+      # target machine.
+      #
+      # Requires: .NET Framework 4.0 or higher on the target machine.
+      #
+      # @param script [String] script to run
+      # @return [Chef::PowerShell] output
+      def powershell_exec(script)
+        Chef::PowerShell.new(script)
+      end
+    end
+  end
+end

data/lib/chef/mixin/powershell_out.rb

@@ -74,7 +74,7 @@ class Chef
       # Helper to build a powershell command around the script to run.
       #
       # @param script [String] script to run
-      # @retrurn [String] powershell command to execute
+      # @return [String] powershell command to execute
       def build_powershell_command(script)
         flags = [
           # Hides the copyright banner at startup.
@@ -86,7 +86,7 @@ class Chef
           # always set the ExecutionPolicy flag
           # see http://technet.microsoft.com/en-us/library/ee176961.aspx
           "-ExecutionPolicy Unrestricted",
-          # Powershell will hang if STDIN is redirected
+          # PowerShell will hang if STDIN is redirected
           # http://connect.microsoft.com/PowerShell/feedback/details/572313/powershell-exe-can-hang-if-stdin-is-redirected
           "-InputFormat None",
         ]

data/lib/chef/mixin/properties.rb

@@ -75,6 +75,8 @@ class Chef
         #     will return if the user does not set one. If this is `lazy`, it will
         #     be run in the context of the instance (and able to access other
         #     properties).
+        #   @option options [String] :description A description of the property.
+        #   @option options [String] :introduced The release that introduced this property
         #   @option options [Boolean] :desired_state `true` if this property is
         #     part of desired state. Defaults to `true`.
         #   @option options [Boolean] :identity `true` if this property
@@ -100,14 +102,14 @@ class Chef
 
           options = options.inject({}) { |memo, (key, value)| memo[key.to_sym] = value; memo }
 
-          options[:instance_variable_name] = :"@#{name}" if !options.has_key?(:instance_variable_name)
+          options[:instance_variable_name] = :"@#{name}" if !options.key?(:instance_variable_name)
           options[:name] = name
           options[:declared_in] = self
 
           if type == NOT_PASSED
             # If a type is not passed, the property derives from the
             # superclass property (if any)
-            if properties.has_key?(name)
+            if properties.key?(name)
               property = properties[name].derive(**options)
             else
               property = property_type(**options)
@@ -147,6 +149,10 @@ class Chef
           Property.derive(**options)
         end
 
+        def deprecated_property_alias(from, to, message)
+          Property.emit_deprecated_alias(from, to, message, self)
+        end
+
         #
         # Create a lazy value for assignment to a default value.
         #
@@ -301,6 +307,17 @@ class Chef
         raise ArgumentError, "Property #{name} is not defined in class #{self}" if !property
         property.reset(self)
       end
+
+      #
+      # The description of the property
+      #
+      # @param name [Symbol] The name of the property.
+      # @return [String] The description of the property.
+      def property_description(name)
+        property = self.class.properties[name.to_sym]
+        raise ArgumentError, "Property #{name} is not defined in class #{self}" if !property
+        property.description
+      end
     end
   end
 end

data/lib/chef/mixin/provides.rb

@@ -4,7 +4,7 @@ require "chef/mixin/descendants_tracker"
 class Chef
   module Mixin
     module Provides
-      # TODO no longer needed, remove or deprecate?
+      # @todo no longer needed, remove or deprecate?
       include Chef::Mixin::DescendantsTracker
 
       def provides(short_name, opts = {})
@@ -12,7 +12,8 @@ class Chef
       end
 
       # Check whether this resource provides the resource_name DSL for the given
-      # node.  TODO remove this when we stop checking unregistered things.
+      # node.
+      # @todo remove this when we stop checking unregistered things.
       # FIXME: yard with @yield
       def provides?(node, resource)
         raise NotImplementedError, :provides?

data/lib/chef/mixin/securable.rb

@@ -24,7 +24,7 @@ class Chef
         set_or_return(
           :owner,
           arg,
-          :regex => Chef::Config[:user_valid_regex]
+          regex: Chef::Config[:user_valid_regex]
         )
       end
 
@@ -34,7 +34,7 @@ class Chef
         set_or_return(
           :group,
           arg,
-          :regex => Chef::Config[:group_valid_regex]
+          regex: Chef::Config[:group_valid_regex]
         )
       end
 
@@ -42,7 +42,7 @@ class Chef
         set_or_return(
           :mode,
           arg,
-          :callbacks => {
+          callbacks: {
             "not in valid numeric range" => lambda do |m|
               if m.kind_of?(String)
                 m =~ /^0/ || m = "0#{m}"
@@ -59,17 +59,14 @@ class Chef
         )
       end
 
-      #==WindowsMacros
       # Defines methods for adding attributes to a chef resource to describe
       # Windows file security metadata.
       #
       # This module is meant to be used to extend a class (instead of
       # `include`-ing). A class is automatically extended with this module when
       # it includes WindowsSecurableAttributes.
-      # --
-      # TODO should this be separated into different files?
+      # @todo should this be separated into different files?
       module WindowsMacros
-        # === rights_attribute
         # "meta-method" for dynamically creating rights attributes on resources.
         #
         # Multiple rights attributes can be declared. This enables resources to
@@ -113,16 +110,16 @@ class Chef
             rights = instance_variable_get("@#{name}".to_sym)
             unless permissions.nil?
               input = {
-                :permissions => permissions,
-                :principals => principals,
+                permissions: permissions,
+                principals: principals,
               }
               input.merge!(args_hash) unless args_hash.nil?
 
-              validations = { :permissions => { :required => true },
-                              :principals => { :required => true, :kind_of => [String, Array] },
-                              :applies_to_children => { :equal_to => [ true, false, :containers_only, :objects_only ] },
-                              :applies_to_self => { :kind_of => [ TrueClass, FalseClass ] },
-                              :one_level_deep => { :kind_of => [ TrueClass, FalseClass ] },
+              validations = { permissions: { required: true },
+                              principals: { required: true, kind_of: [String, Array] },
+                              applies_to_children: { equal_to: [ true, false, :containers_only, :objects_only ] },
+                              applies_to_self: { kind_of: [ TrueClass, FalseClass ] },
+                              one_level_deep: { kind_of: [ TrueClass, FalseClass ] },
                             }
               validate(input, validations)
 
@@ -162,7 +159,6 @@ class Chef
         end
       end
 
-      #==WindowsSecurableAttributes
       # Defines #inherits to describe Windows file security ACLs on the
       # including class
       module WindowsSecurableAttributes
@@ -171,7 +167,7 @@ class Chef
           set_or_return(
             :inherits,
             arg,
-            :kind_of => [ TrueClass, FalseClass ]
+            kind_of: [ TrueClass, FalseClass ]
           )
         end
       end