chef 12.4.3-universal-mingw32 → 12.5.1-universal-mingw32

data/lib/chef/resource/action_class.rb

@@ -0,0 +1,83 @@
+#
+# Author:: John Keiser (<jkeiser@chef.io)
+# Copyright:: Copyright (c) 2015 Opscode, 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/exceptions'
+
+class Chef
+  class Resource
+    module ActionClass
+      #
+      # If load_current_value! is defined on the resource, use that.
+      #
+      def load_current_resource
+        if new_resource.respond_to?(:load_current_value!)
+          # dup the resource and then reset desired-state properties.
+          current_resource = new_resource.dup
+
+          # We clear desired state in the copy, because it is supposed to be actual state.
+          # We keep identity properties and non-desired-state, which are assumed to be
+          # "control" values like `recurse: true`
+          current_resource.class.properties.each do |name,property|
+            if property.desired_state? && !property.identity? && !property.name_property?
+              property.reset(current_resource)
+            end
+          end
+
+          # Call the actual load_current_value! method. If it raises
+          # CurrentValueDoesNotExist, set current_resource to `nil`.
+          begin
+            # If the user specifies load_current_value do |desired_resource|, we
+            # pass in the desired resource as well as the current one.
+            if current_resource.method(:load_current_value!).arity > 0
+              current_resource.load_current_value!(new_resource)
+            else
+              current_resource.load_current_value!
+            end
+          rescue Chef::Exceptions::CurrentValueDoesNotExist
+            current_resource = nil
+          end
+        end
+
+        @current_resource = current_resource
+      end
+
+      def self.included(other)
+        other.extend(ClassMethods)
+        other.use_inline_resources
+        other.include_resource_dsl true
+      end
+
+      module ClassMethods
+        #
+        # The Chef::Resource class this ActionClass was declared against.
+        #
+        # @return [Class] The Chef::Resource class this ActionClass was declared against.
+        #
+        attr_accessor :resource_class
+
+        def to_s
+          "#{resource_class} action provider"
+        end
+
+        def inspect
+          to_s
+        end
+      end
+    end
+  end
+end

data/lib/chef/resource/chef_gem.rb

@@ -50,9 +50,9 @@ class Chef
         # Chef::Resource.run_action: Caveat: this skips Chef::Runner.run_action, where notifications are handled
         # Action could be an array of symbols, but probably won't (think install + enable for a package)
         if compile_time.nil?
-          Chef::Log.deprecation "#{self} chef_gem compile_time installation is deprecated"
-          Chef::Log.deprecation "#{self} Please set `compile_time false` on the resource to use the new behavior."
-          Chef::Log.deprecation "#{self} or set `compile_time true` on the resource if compile_time behavior is required."
+          Chef.log_deprecation "#{self} chef_gem compile_time installation is deprecated"
+          Chef.log_deprecation "#{self} Please set `compile_time false` on the resource to use the new behavior."
+          Chef.log_deprecation "#{self} or set `compile_time true` on the resource if compile_time behavior is required."
         end
 
         if compile_time || compile_time.nil?

data/lib/chef/resource/deploy.rb

@@ -27,6 +27,7 @@
 #   migration_command "rake db:migrate"
 #   environment "RAILS_ENV" => "production", "OTHER_ENV" => "foo"
 #   shallow_clone true
+#   depth 1
 #   action :deploy # or :rollback
 #   restart_command "touch tmp/restart.txt"
 #   git_ssh_wrapper "wrap-ssh4git.sh"
@@ -74,6 +75,7 @@ class Chef
         @remote = "origin"
         @enable_submodules = false
         @shallow_clone = false
+        @depth = nil
         @scm_provider = Chef::Provider::Git
         @svn_force_export = false
         @additional_remotes = Hash[]
@@ -97,8 +99,12 @@ class Chef
         @current_path ||= @deploy_to + "/current"
       end
 
-      def depth
-        @shallow_clone ? "5" : nil
+      def depth(arg=@shallow_clone ? 5 : nil)
+        set_or_return(
+          :depth,
+          arg,
+          :kind_of => [ Integer ]
+        )
       end
 
       # note: deploy_to is your application "meta-root."

data/lib/chef/resource/dsc_script.rb

@@ -17,10 +17,12 @@
 #
 
 require 'chef/exceptions'
+require 'chef/dsl/powershell'
 
 class Chef
   class Resource
     class DscScript < Chef::Resource
+      include Chef::DSL::Powershell
 
       provides :dsc_script, os: "windows"
 

data/lib/chef/resource/file/verification.rb

@@ -106,7 +106,13 @@ class Chef
         # We reuse Chef::GuardInterpreter in order to support
         # the same set of options that the not_if/only_if blocks do
         def verify_command(path, opts)
-          command = @command % {:file => path}
+          # First implementation interpolated `file`; docs & RFC claim `path`
+          # is interpolated. Until `file` can be deprecated, interpolate both.
+          Chef.log_deprecation(
+            '%{file} is deprecated in verify command and will not be '\
+            'supported in Chef 13. Please use %{path} instead.'
+          ) if @command.include?('%{file}')
+          command = @command % {:file => path, :path => path}
           interpreter = Chef::GuardInterpreter.for_resource(@parent_resource, command, @command_opts)
           interpreter.evaluate
         end

data/lib/chef/resource/lwrp_base.rb

@@ -74,13 +74,7 @@ class Chef
           resource_class
         end
 
-        # Define an attribute on this resource, including optional validation
-        # parameters.
-        def attribute(attr_name, validation_opts={})
-          define_method(attr_name) do |arg=nil|
-            set_or_return(attr_name.to_sym, arg, validation_opts)
-          end
-        end
+        alias :attribute :property
 
         # Adds +action_names+ to the list of valid actions for this resource.
         # Does not include superclass's action list when appending.

data/lib/chef/resource/registry_key.rb

@@ -93,7 +93,7 @@ class Chef
               raise ArgumentError, "Bad key #{key} in RegistryKey values hash" unless [:name,:type,:data].include?(key)
             end
             raise ArgumentError, "Type of name => #{v[:name]} should be string" unless v[:name].is_a?(String)
-            raise Argument Error "Type of type => #{v[:name]} should be symbol" unless v[:type].is_a?(Symbol)
+            raise ArgumentError, "Type of type => #{v[:type]} should be symbol" unless v[:type].is_a?(Symbol)
           end
           @unscrubbed_values = @values
         elsif self.instance_variable_defined?(:@values)

data/lib/chef/resource/service.rb

@@ -1,7 +1,7 @@
 #
 # Author:: AJ Christensen (<aj@hjksolutions.com>)
 # Author:: Tyler Cloke (<tyler@opscode.com>)
-# Copyright:: Copyright (c) 2008 Opscode, Inc.
+# Copyright:: Copyright (c) 2008-2015 Chef Software, Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -44,7 +44,8 @@ class Chef
         @init_command = nil
         @priority = nil
         @timeout = nil
-        @supports = { :restart => false, :reload => false, :status => false }
+        @run_levels = nil
+        @supports = { :restart => nil, :reload => nil, :status => nil }
       end
 
       def service_name(arg=nil)
@@ -174,6 +175,13 @@ class Chef
         )
       end
 
+      def run_levels(arg=nil)
+        set_or_return(
+          :run_levels,
+          arg,
+          :kind_of => [ Array ] )
+      end
+
       def supports(args={})
         if args.is_a? Array
           args.each { |arg| @supports[arg] = true }

data/lib/chef/resource/subversion.rb

@@ -28,12 +28,17 @@ class Chef
         super
         @svn_arguments = '--no-auth-cache'
         @svn_info_args = '--no-auth-cache'
+        @svn_binary = nil
       end
 
       # Override exception to strip password if any, so it won't appear in logs and different Chef notifications
       def custom_exception_message(e)
         "#{self} (#{defined_at}) had an error: #{e.class.name}: #{svn_password ? e.message.gsub(svn_password, "[hidden_password]") : e.message}"
       end
+
+      def svn_binary(arg=nil)
+        set_or_return(:svn_binary, arg, :kind_of => [String])
+      end
     end
   end
 end

data/lib/chef/resource/windows_script.rb

@@ -16,6 +16,7 @@
 # limitations under the License.
 #
 
+require 'chef/platform/query_helpers'
 require 'chef/resource/script'
 require 'chef/mixin/windows_architecture_helper'
 
@@ -51,9 +52,12 @@ class Chef
       protected
 
       def assert_architecture_compatible!(desired_architecture)
-        if ! node_supports_windows_architecture?(node, desired_architecture)
+        if desired_architecture == :i386 && Chef::Platform.windows_nano_server?
           raise Chef::Exceptions::Win32ArchitectureIncorrect,
-          "cannot execute script with requested architecture '#{desired_architecture.to_s}' on a system with architecture '#{node_windows_architecture(node)}'"
+            "cannot execute script with requested architecture 'i386' on Windows Nano Server"
+        elsif ! node_supports_windows_architecture?(node, desired_architecture)
+          raise Chef::Exceptions::Win32ArchitectureIncorrect,
+            "cannot execute script with requested architecture '#{desired_architecture.to_s}' on a system with architecture '#{node_windows_architecture(node)}'"
         end
       end
     end

data/lib/chef/resource/yum_package.rb

@@ -1,6 +1,6 @@
 #
 # Author:: AJ Christensen (<aj@opscode.com>)
-# Copyright:: Copyright (c) 2008 Opscode, Inc.
+# Copyright:: Copyright (c) 2008-2015 Chef Software, Inc.
 # License:: Apache License, Version 2.0
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -28,6 +28,7 @@ class Chef
         super
         @flush_cache = { :before => false, :after => false }
         @allow_downgrade = false
+        @yum_binary = nil
       end
 
       # Install a specific arch
@@ -57,6 +58,14 @@ class Chef
         )
       end
 
+      def yum_binary(arg=nil)
+        set_or_return(
+          :yum_binary,
+          arg,
+          :kind_of => [ String ]
+        )
+      end
+
     end
   end
 end

data/lib/chef/resource_resolver.rb

@@ -56,7 +56,7 @@ class Chef
     attr_reader :resource_name
     # @api private
     def resource
-      Chef::Log.deprecation("Chef::ResourceResolver.resource deprecated.  Use resource_name instead.")
+      Chef.log_deprecation("Chef::ResourceResolver.resource deprecated.  Use resource_name instead.")
       resource_name
     end
     # @api private
@@ -174,8 +174,8 @@ class Chef
         if handlers.empty?
           handlers = resources.select { |handler| overrode_provides?(handler) && handler.provides?(node, resource_name) }
           handlers.each do |handler|
-            Chef::Log.deprecation("#{handler}.provides? returned true when asked if it provides DSL #{resource_name}, but provides #{resource_name.inspect} was never called!")
-            Chef::Log.deprecation("In Chef 13, this will break: you must call provides to mark the names you provide, even if you also override provides? yourself.")
+            Chef.log_deprecation("#{handler}.provides? returned true when asked if it provides DSL #{resource_name}, but provides #{resource_name.inspect} was never called!")
+            Chef.log_deprecation("In Chef 13, this will break: you must call provides to mark the names you provide, even if you also override provides? yourself.")
           end
         end
         handlers

data/lib/chef/run_context.rb

@@ -25,118 +25,223 @@ require 'chef/log'
 require 'chef/recipe'
 require 'chef/run_context/cookbook_compiler'
 require 'chef/event_dispatch/events_output_stream'
+require 'forwardable'
 
 class Chef
 
   # == Chef::RunContext
   # Value object that loads and tracks the context of a Chef run
   class RunContext
+    #
+    # Global state
+    #
 
-    # Chef::Node object for this run
+    #
+    # The node for this run
+    #
+    # @return [Chef::Node]
+    #
     attr_reader :node
 
-    # Chef::CookbookCollection for this run
+    #
+    # The set of cookbooks involved in this run
+    #
+    # @return [Chef::CookbookCollection]
+    #
     attr_reader :cookbook_collection
 
+    #
     # Resource Definitions for this run. Populated when the files in
     # +definitions/+ are evaluated (this is triggered by #load).
+    #
+    # @return [Array[Chef::ResourceDefinition]]
+    #
     attr_reader :definitions
 
-    ###
-    # These need to be settable so deploy can run a resource_collection
-    # independent of any cookbooks via +recipe_eval+
+    #
+    # Event dispatcher for this run.
+    #
+    # @return [Chef::EventDispatch::Dispatcher]
+    #
+    attr_reader :events
 
-    # The Chef::ResourceCollection for this run. Populated by evaluating
-    # recipes, which is triggered by #load. (See also: CookbookCompiler)
-    attr_accessor :resource_collection
+    #
+    # Hash of factoids for a reboot request.
+    #
+    # @return [Hash]
+    #
+    attr_accessor :reboot_info
 
+    #
+    # Scoped state
+    #
+
+    #
+    # The parent run context.
+    #
+    # @return [Chef::RunContext] The parent run context, or `nil` if this is the
+    #   root context.
+    #
+    attr_reader :parent_run_context
+
+    #
+    # The collection of resources intended to be converged (and able to be
+    # notified).
+    #
+    # @return [Chef::ResourceCollection]
+    #
+    # @see CookbookCompiler
+    #
+    attr_reader :resource_collection
+
+    #
     # The list of control groups to execute during the audit phase
-    attr_accessor :audits
+    #
+    attr_reader :audits
 
+    #
+    # Notification handling
+    #
+
+    #
     # A Hash containing the immediate notifications triggered by resources
     # during the converge phase of the chef run.
-    attr_accessor :immediate_notification_collection
+    #
+    # @return [Hash[String, Array[Chef::Resource::Notification]]] A hash from
+    #   <notifying resource name> => <list of notifications it sent>
+    #
+    attr_reader :immediate_notification_collection
 
+    #
     # A Hash containing the delayed (end of run) notifications triggered by
     # resources during the converge phase of the chef run.
-    attr_accessor :delayed_notification_collection
-
-    # Event dispatcher for this run.
-    attr_reader :events
-
-    # Hash of factoids for a reboot request.
-    attr_reader :reboot_info
+    #
+    # @return [Hash[String, Array[Chef::Resource::Notification]]] A hash from
+    #   <notifying resource name> => <list of notifications it sent>
+    #
+    attr_reader :delayed_notification_collection
 
     # Creates a new Chef::RunContext object and populates its fields. This object gets
     # used by the Chef Server to generate a fully compiled recipe list for a node.
     #
-    # === Returns
-    # object<Chef::RunContext>:: Duh. :)
+    # @param node [Chef::Node] The node to run against.
+    # @param cookbook_collection [Chef::CookbookCollection] The cookbooks
+    #   involved in this run.
+    # @param events [EventDispatch::Dispatcher] The event dispatcher for this
+    #   run.
+    #
     def initialize(node, cookbook_collection, events)
       @node = node
       @cookbook_collection = cookbook_collection
-      @resource_collection = Chef::ResourceCollection.new
-      @audits = {}
-      @immediate_notification_collection = Hash.new {|h,k| h[k] = []}
-      @delayed_notification_collection = Hash.new {|h,k| h[k] = []}
-      @definitions = Hash.new
-      @loaded_recipes = {}
-      @loaded_attributes = {}
       @events = events
-      @reboot_info = {}
 
-      @node.run_context = self
-      @node.set_cookbook_attribute
+      node.run_context = self
+      node.set_cookbook_attribute
+
+      @definitions = Hash.new
+      @loaded_recipes_hash = {}
+      @loaded_attributes_hash = {}
+      @reboot_info = {}
       @cookbook_compiler = nil
+
+      initialize_child_state
     end
 
-    # Triggers the compile phase of the chef run. Implemented by
-    # Chef::RunContext::CookbookCompiler
+    #
+    # Triggers the compile phase of the chef run.
+    #
+    # @param run_list_expansion [Chef::RunList::RunListExpansion] The run list.
+    # @see Chef::RunContext::CookbookCompiler
+    #
     def load(run_list_expansion)
       @cookbook_compiler = CookbookCompiler.new(self, run_list_expansion, events)
-      @cookbook_compiler.compile
+      cookbook_compiler.compile
     end
 
-    # Adds an immediate notification to the
-    # +immediate_notification_collection+. The notification should be a
-    # Chef::Resource::Notification or duck type.
+    #
+    # Initialize state that applies to both Chef::RunContext and Chef::ChildRunContext
+    #
+    def initialize_child_state
+      @audits = {}
+      @resource_collection = Chef::ResourceCollection.new
+      @immediate_notification_collection = Hash.new {|h,k| h[k] = []}
+      @delayed_notification_collection = Hash.new {|h,k| h[k] = []}
+    end
+
+    #
+    # Adds an immediate notification to the +immediate_notification_collection+.
+    #
+    # @param [Chef::Resource::Notification] The notification to add.
+    #
     def notifies_immediately(notification)
       nr = notification.notifying_resource
       if nr.instance_of?(Chef::Resource)
-        @immediate_notification_collection[nr.name] << notification
+        immediate_notification_collection[nr.name] << notification
       else
-        @immediate_notification_collection[nr.declared_key] << notification
+        immediate_notification_collection[nr.declared_key] << notification
       end
     end
 
-    # Adds a delayed notification to the +delayed_notification_collection+. The
-    # notification should be a Chef::Resource::Notification or duck type.
+    #
+    # Adds a delayed notification to the +delayed_notification_collection+.
+    #
+    # @param [Chef::Resource::Notification] The notification to add.
+    #
     def notifies_delayed(notification)
       nr = notification.notifying_resource
       if nr.instance_of?(Chef::Resource)
-        @delayed_notification_collection[nr.name] << notification
+        delayed_notification_collection[nr.name] << notification
       else
-        @delayed_notification_collection[nr.declared_key] << notification
+        delayed_notification_collection[nr.declared_key] << notification
       end
     end
 
+    #
+    # Get the list of immediate notifications sent by the given resource.
+    #
+    # TODO seriously, this is actually wrong.  resource.name is not unique,
+    # you need the type as well.
+    #
+    # @return [Array[Notification]]
+    #
     def immediate_notifications(resource)
       if resource.instance_of?(Chef::Resource)
-        return @immediate_notification_collection[resource.name]
+        return immediate_notification_collection[resource.name]
       else
-        return @immediate_notification_collection[resource.declared_key]
+        return immediate_notification_collection[resource.declared_key]
       end
     end
 
+    #
+    # Get the list of delayed (end of run) notifications sent by the given
+    # resource.
+    #
+    # TODO seriously, this is actually wrong.  resource.name is not unique,
+    # you need the type as well.
+    #
+    # @return [Array[Notification]]
+    #
     def delayed_notifications(resource)
       if resource.instance_of?(Chef::Resource)
-        return @delayed_notification_collection[resource.name]
+        return delayed_notification_collection[resource.name]
       else
-        return @delayed_notification_collection[resource.declared_key]
+        return delayed_notification_collection[resource.declared_key]
       end
     end
 
+    #
+    # Cookbook and recipe loading
+    #
+
+    #
     # Evaluates the recipes +recipe_names+. Used by DSL::IncludeRecipe
+    #
+    # @param recipe_names [Array[String]] The list of recipe names (e.g.
+    #   'my_cookbook' or 'my_cookbook::my_resource').
+    # @param current_cookbook The cookbook we are currently running in.
+    #
+    # @see DSL::IncludeRecipe#include_recipe
+    #
     def include_recipe(*recipe_names, current_cookbook: nil)
       result_recipes = Array.new
       recipe_names.flatten.each do |recipe_name|
@@ -147,7 +252,21 @@ class Chef
       result_recipes
     end
 
+    #
     # Evaluates the recipe +recipe_name+. Used by DSL::IncludeRecipe
+    #
+    # TODO I am sort of confused why we have both this and include_recipe ...
+    #      I don't see anything different beyond accepting and returning an
+    #      array of recipes.
+    #
+    # @param recipe_names [Array[String]] The recipe name (e.g 'my_cookbook' or
+    #   'my_cookbook::my_resource').
+    # @param current_cookbook The cookbook we are currently running in.
+    #
+    # @return A truthy value if the load occurred; `false` if already loaded.
+    #
+    # @see DSL::IncludeRecipe#load_recipe
+    #
     def load_recipe(recipe_name, current_cookbook: nil)
       Chef::Log.debug("Loading Recipe #{recipe_name} via include_recipe")
 
@@ -175,6 +294,15 @@ ERROR_MESSAGE
       end
     end
 
+    #
+    # Load the given recipe from a filename.
+    #
+    # @param recipe_file [String] The recipe filename.
+    #
+    # @return [Chef::Recipe] The loaded recipe.
+    #
+    # @raise [Chef::Exceptions::RecipeNotFound] If the file does not exist.
+    #
     def load_recipe_file(recipe_file)
       if !File.exist?(recipe_file)
         raise Chef::Exceptions::RecipeNotFound, "could not find recipe file #{recipe_file}"
@@ -186,8 +314,19 @@ ERROR_MESSAGE
       recipe
     end
 
-    # Looks up an attribute file given the +cookbook_name+ and
-    # +attr_file_name+. Used by DSL::IncludeAttribute
+    #
+    # Look up an attribute filename.
+    #
+    # @param cookbook_name [String] The cookbook name of the attribute file.
+    # @param attr_file_name [String] The attribute file's name (not path).
+    #
+    # @return [String] The filename.
+    #
+    # @see DSL::IncludeAttribute#include_attribute
+    #
+    # @raise [Chef::Exceptions::CookbookNotFound] If the cookbook could not be found.
+    # @raise [Chef::Exceptions::AttributeNotFound] If the attribute file could not be found.
+    #
     def resolve_attribute(cookbook_name, attr_file_name)
       cookbook = cookbook_collection[cookbook_name]
       raise Chef::Exceptions::CookbookNotFound, "could not find cookbook #{cookbook_name} while loading attribute #{name}" unless cookbook
@@ -198,76 +337,152 @@ ERROR_MESSAGE
       attribute_filename
     end
 
-    # An Array of all recipes that have been loaded. This is stored internally
-    # as a Hash, so ordering is predictable.
     #
-    # Recipe names are given in fully qualified form, e.g., the recipe "nginx"
-    # will be given as "nginx::default"
+    # A list of all recipes that have been loaded.
+    #
+    # This is stored internally as a Hash, so ordering is predictable.
+    #
+    # TODO is the above statement true in a 1.9+ ruby world?  Is it relevant?
+    #
+    # @return [Array[String]] A list of recipes in fully qualified form, e.g.
+    #   the recipe "nginx" will be given as "nginx::default".
+    #
+    # @see #loaded_recipe? To determine if a particular recipe has been loaded.
     #
-    # To determine if a particular recipe has been loaded, use #loaded_recipe?
     def loaded_recipes
-      @loaded_recipes.keys
+      loaded_recipes_hash.keys
     end
 
-    # An Array of all attributes files that have been loaded. Stored internally
-    # using a Hash, so order is predictable.
     #
-    # Attribute file names are given in fully qualified form, e.g.,
-    # "nginx::default" instead of "nginx".
+    # A list of all attributes files that have been loaded.
+    #
+    # Stored internally using a Hash, so order is predictable.
+    #
+    # TODO is the above statement true in a 1.9+ ruby world?  Is it relevant?
+    #
+    # @return [Array[String]] A list of attribute file names in fully qualified
+    #   form, e.g. the "nginx" will be given as "nginx::default".
+    #
     def loaded_attributes
-      @loaded_attributes.keys
+      loaded_attributes_hash.keys
     end
 
+    #
+    # Find out if a given recipe has been loaded.
+    #
+    # @param cookbook [String] Cookbook name.
+    # @param recipe [String] Recipe name.
+    #
+    # @return [Boolean] `true` if the recipe has been loaded, `false` otherwise.
+    #
     def loaded_fully_qualified_recipe?(cookbook, recipe)
-      @loaded_recipes.has_key?("#{cookbook}::#{recipe}")
+      loaded_recipes_hash.has_key?("#{cookbook}::#{recipe}")
     end
 
-    # Returns true if +recipe+ has been loaded, false otherwise. Default recipe
-    # names are expanded, so `loaded_recipe?("nginx")` and
-    # `loaded_recipe?("nginx::default")` are valid and give identical results.
+    #
+    # Find out if a given recipe has been loaded.
+    #
+    # @param recipe [String] Recipe name.  "nginx" and "nginx::default" yield
+    #   the same results.
+    #
+    # @return [Boolean] `true` if the recipe has been loaded, `false` otherwise.
+    #
     def loaded_recipe?(recipe)
       cookbook, recipe_name = Chef::Recipe.parse_recipe_name(recipe)
       loaded_fully_qualified_recipe?(cookbook, recipe_name)
     end
 
+    #
+    # Mark a given recipe as having been loaded.
+    #
+    # @param cookbook [String] Cookbook name.
+    # @param recipe [String] Recipe name.
+    #
+    def loaded_recipe(cookbook, recipe)
+      loaded_recipes_hash["#{cookbook}::#{recipe}"] = true
+    end
+
+    #
+    # Find out if a given attribute file has been loaded.
+    #
+    # @param cookbook [String] Cookbook name.
+    # @param attribute_file [String] Attribute file name.
+    #
+    # @return [Boolean] `true` if the recipe has been loaded, `false` otherwise.
+    #
     def loaded_fully_qualified_attribute?(cookbook, attribute_file)
-      @loaded_attributes.has_key?("#{cookbook}::#{attribute_file}")
+      loaded_attributes_hash.has_key?("#{cookbook}::#{attribute_file}")
     end
 
+    #
+    # Mark a given attribute file as having been loaded.
+    #
+    # @param cookbook [String] Cookbook name.
+    # @param attribute_file [String] Attribute file name.
+    #
     def loaded_attribute(cookbook, attribute_file)
-      @loaded_attributes["#{cookbook}::#{attribute_file}"] = true
+      loaded_attributes_hash["#{cookbook}::#{attribute_file}"] = true
     end
 
     ##
     # Cookbook File Introspection
 
+    #
+    # Find out if the cookbook has the given template.
+    #
+    # @param cookbook [String] Cookbook name.
+    # @param template_name [String] Template name.
+    #
+    # @return [Boolean] `true` if the template is in the cookbook, `false`
+    #   otherwise.
+    # @see Chef::CookbookVersion#has_template_for_node?
+    #
     def has_template_in_cookbook?(cookbook, template_name)
       cookbook = cookbook_collection[cookbook]
       cookbook.has_template_for_node?(node, template_name)
     end
 
+    #
+    # Find out if the cookbook has the given file.
+    #
+    # @param cookbook [String] Cookbook name.
+    # @param cb_file_name [String] File name.
+    #
+    # @return [Boolean] `true` if the file is in the cookbook, `false`
+    #   otherwise.
+    # @see Chef::CookbookVersion#has_cookbook_file_for_node?
+    #
     def has_cookbook_file_in_cookbook?(cookbook, cb_file_name)
       cookbook = cookbook_collection[cookbook]
       cookbook.has_cookbook_file_for_node?(node, cb_file_name)
     end
 
-    # Delegates to CookbookCompiler#unreachable_cookbook?
-    # Used to raise an error when attempting to load a recipe belonging to a
-    # cookbook that is not in the dependency graph. See also: CHEF-4367
+    #
+    # Find out whether the given cookbook is in the cookbook dependency graph.
+    #
+    # @param cookbook_name [String] Cookbook name.
+    #
+    # @return [Boolean] `true` if the cookbook is reachable, `false` otherwise.
+    #
+    # @see Chef::CookbookCompiler#unreachable_cookbook?
     def unreachable_cookbook?(cookbook_name)
-      @cookbook_compiler.unreachable_cookbook?(cookbook_name)
+      cookbook_compiler.unreachable_cookbook?(cookbook_name)
     end
 
+    #
     # Open a stream object that can be printed into and will dispatch to events
     #
-    # == Arguments
-    # options is a hash with these possible options:
-    # - name: a string that identifies the stream to the user. Preferably short.
+    # @param name [String] The name of the stream.
+    # @param options [Hash] Other options for the stream.
+    #
+    # @return [EventDispatch::EventsOutputStream] The created stream.
     #
-    # Pass a block and the stream will be yielded to it, and close on its own
-    # at the end of the block.
-    def open_stream(options = {})
-      stream = EventDispatch::EventsOutputStream.new(events, options)
+    # @yield If a block is passed, it will be run and the stream will be closed
+    #   afterwards.
+    # @yieldparam stream [EventDispatch::EventsOutputStream] The created stream.
+    #
+    def open_stream(name: nil, **options)
+      stream = EventDispatch::EventsOutputStream.new(events, name: name, **options)
       if block_given?
         begin
           yield stream
@@ -280,31 +495,135 @@ ERROR_MESSAGE
     end
 
     # there are options for how to handle multiple calls to these functions:
-    # 1. first call always wins (never change @reboot_info once set).
-    # 2. last call always wins (happily change @reboot_info whenever).
+    # 1. first call always wins (never change reboot_info once set).
+    # 2. last call always wins (happily change reboot_info whenever).
     # 3. raise an exception on the first conflict.
     # 4. disable reboot after this run if anyone ever calls :cancel.
     # 5. raise an exception on any second call.
     # 6. ?
     def request_reboot(reboot_info)
-      Chef::Log::info "Changing reboot status from #{@reboot_info.inspect} to #{reboot_info.inspect}"
+      Chef::Log::info "Changing reboot status from #{self.reboot_info.inspect} to #{reboot_info.inspect}"
       @reboot_info = reboot_info
     end
 
     def cancel_reboot
-      Chef::Log::info "Changing reboot status from #{@reboot_info.inspect} to {}"
+      Chef::Log::info "Changing reboot status from #{reboot_info.inspect} to {}"
       @reboot_info = {}
     end
 
     def reboot_requested?
-      @reboot_info.size > 0
+      reboot_info.size > 0
+    end
+
+    #
+    # Create a child RunContext.
+    #
+    def create_child
+      ChildRunContext.new(self)
     end
 
-    private
+    # @api private
+    attr_writer :resource_collection
 
-    def loaded_recipe(cookbook, recipe)
-      @loaded_recipes["#{cookbook}::#{recipe}"] = true
+    protected
+
+    attr_reader :cookbook_compiler
+    attr_reader :loaded_attributes_hash
+    attr_reader :loaded_recipes_hash
+
+    module Deprecated
+      ###
+      # These need to be settable so deploy can run a resource_collection
+      # independent of any cookbooks via +recipe_eval+
+      def audits=(value)
+        Chef.log_deprecation("Setting run_context.audits will be removed in a future Chef.  Use run_context.create_child to create a new RunContext instead.")
+        @audits = value
+      end
+
+      def immediate_notification_collection=(value)
+        Chef.log_deprecation("Setting run_context.immediate_notification_collection will be removed in a future Chef.  Use run_context.create_child to create a new RunContext instead.")
+        @immediate_notification_collection = value
+      end
+
+      def delayed_notification_collection=(value)
+        Chef.log_deprecation("Setting run_context.delayed_notification_collection will be removed in a future Chef.  Use run_context.create_child to create a new RunContext instead.")
+        @delayed_notification_collection = value
+      end
     end
+    prepend Deprecated
+
+
+    #
+    # A child run context.  Delegates all root context calls to its parent.
+    #
+    # @api private
+    #
+    class ChildRunContext < RunContext
+      extend Forwardable
+      def_delegators :parent_run_context, *%w(
+        cancel_reboot
+        config
+        cookbook_collection
+        cookbook_compiler
+        definitions
+        events
+        has_cookbook_file_in_cookbook?
+        has_template_in_cookbook?
+        load
+        loaded_attribute
+        loaded_attributes
+        loaded_attributes_hash
+        loaded_fully_qualified_attribute?
+        loaded_fully_qualified_recipe?
+        loaded_recipe
+        loaded_recipe?
+        loaded_recipes
+        loaded_recipes_hash
+        node
+        open_stream
+        reboot_info
+        reboot_info=
+        reboot_requested?
+        request_reboot
+        resolve_attribute
+        unreachable_cookbook?
+      )
+
+      def initialize(parent_run_context)
+        @parent_run_context = parent_run_context
+
+        # We don't call super, because we don't bother initializing stuff we're
+        # going to delegate to the parent anyway.  Just initialize things that
+        # every instance needs.
+        initialize_child_state
+      end
 
+      CHILD_STATE = %w(
+        audits
+        audits=
+        create_child
+        delayed_notification_collection
+        delayed_notification_collection=
+        delayed_notifications
+        immediate_notification_collection
+        immediate_notification_collection=
+        immediate_notifications
+        include_recipe
+        initialize_child_state
+        load_recipe
+        load_recipe_file
+        notifies_immediately
+        notifies_delayed
+        parent_run_context
+        resource_collection
+        resource_collection=
+      ).map { |x| x.to_sym }
+
+      # Verify that we didn't miss any methods
+      missing_methods = superclass.instance_methods(false) - instance_methods(false) - CHILD_STATE
+      if !missing_methods.empty?
+        raise "ERROR: not all methods of RunContext accounted for in ChildRunContext! All methods must be marked as child methods with CHILD_STATE or delegated to the parent_run_context. Missing #{missing_methods.join(", ")}."
+      end
+    end
   end
 end