poise 2.0.0

data/lib/poise/helpers/resource_name.rb

@@ -0,0 +1,99 @@
+#
+# Copyright 2013-2015, Noah Kantrowitz
+#
+# 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/mixin/convert_to_class_name'
+
+
+module Poise
+  module Helpers
+    # A resource mixin to automatically set @resource_name.
+    #
+    # @since 1.0.0
+    # @example
+    #   class MyResource < Chef::Resource
+    #     include Poise::Helpers::ResourceName
+    #     provides(:my_resource)
+    #   end
+    module ResourceName
+      def initialize(*args)
+        super
+        # If provides() was explicitly set, unconditionally set @resource_name.
+        # This helps when subclassing core Chef resources which set it
+        # themselves in #initialize.
+        if self.class.resource_name(false)
+          @resource_name = self.class.resource_name
+        else
+          @resource_name ||= self.class.resource_name
+        end
+      end
+
+      # @!classmethods
+      module ClassMethods
+        # Set the DSL name for the the resource class.
+        #
+        # @param name [Symbol] Name of the resource.
+        # @return [void]
+        # @example
+        #   class MyResource < Chef::Resource
+        #     include Poise::Resource::ResourceName
+        #     provides(:my_resource)
+        #   end
+        def provides(name)
+          # Patch self.constantize so this can cope with anonymous classes.
+          # This does require that the anonymous class define self.name though.
+          if self.name && respond_to?(:constantize)
+            old_constantize = instance_method(:constantize)
+            define_singleton_method(:constantize) do |const_name|
+              ( const_name == self.name ) ? self : old_constantize.bind(self).call(const_name)
+            end
+          end
+          # Store the name for later.
+          @provides_name = name
+          # Call the original if present. The defined? is for old Chef.
+          super if defined?(super)
+        end
+
+        # Retreive the DSL name for the resource class. If not set explicitly
+        # via {provides} this will try to auto-detect based on the class name.
+        #
+        # @param auto [Boolean] Try to auto-detect based on class name.
+        # @return [Symbol]
+        def resource_name(auto=true)
+          return @provides_name if @provides_name
+          @provides_name || if name && name.start_with?('Chef::Resource')
+            Chef::Mixin::ConvertToClassName.convert_to_snake_case(name, 'Chef::Resource').to_sym
+          elsif name
+            Chef::Mixin::ConvertToClassName.convert_to_snake_case(name.split('::').last).to_sym
+          end
+        end
+
+        # Used by Resource#to_text to find the human name for the resource.
+        #
+        # @api private
+        def dsl_name
+          resource_name.to_s
+        end
+
+        def included(klass)
+          super
+          klass.extend(ClassMethods)
+        end
+      end
+
+      extend ClassMethods
+    end
+  end
+end

data/lib/poise/helpers/subcontext_block.rb

@@ -0,0 +1,58 @@
+#
+# Copyright 2013-2015, Noah Kantrowitz
+#
+# 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 'poise/subcontext/resource_collection'
+
+
+module Poise
+  module Helpers
+    # A provider mixin to help with creating subcontexts. Mostly for internal
+    # use within Poise.
+    #
+    # @since 1.0.0
+    module SubcontextBlock
+      private
+
+      def subcontext_block(parent_context=nil, &block)
+        # Setup a sub-run-context.
+        parent_context ||= @run_context
+        sub_run_context = parent_context.dup
+        sub_run_context.resource_collection = Poise::Subcontext::ResourceCollection.new(parent_context.resource_collection)
+
+        # Declare sub-resources within the sub-run-context. Since they
+        # are declared here, they do not pollute the parent run-context.
+        begin
+          outer_run_context = @run_context
+          @run_context = sub_run_context
+          instance_eval(&block)
+        ensure
+          @run_context = outer_run_context
+        end
+
+        # Return the inner context to do other things with
+        sub_run_context
+      end
+
+      def global_resource_collection
+        collection = @run_context.resource_collection
+        while collection.respond_to?(:parent) && collection.parent
+          collection = collection.parent
+        end
+        collection
+      end
+    end
+  end
+end

data/lib/poise/helpers/subresources.rb

@@ -0,0 +1,29 @@
+#
+# Copyright 2015, Noah Kantrowitz
+#
+# 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.
+#
+
+
+module Poise
+  module Helpers
+    # Mixins and helpers for managing subresources, resources with a
+    # parent/child relationship.
+    #
+    # @since 2.0.0
+    module Subresources
+      autoload :Child, 'poise/helpers/subresources/child'
+      autoload :Container, 'poise/helpers/subresources/container'
+    end
+  end
+end

data/lib/poise/helpers/subresources/child.rb

@@ -0,0 +1,217 @@
+#
+# Copyright 2013-2015, Noah Kantrowitz
+#
+# 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/resource'
+
+require 'poise/error'
+require 'poise/helpers/subresources/default_containers'
+
+
+module Poise
+  module Helpers
+    module Subresources
+      # A resource mixin for child subresources.
+      #
+      # @since 1.0.0
+      module Child
+        # Little class used to fix up the display of subresources in #to_text.
+        # Without this you get the full parent resource shown for @parent et al.
+        # @api private
+        class ParentRef
+          attr_accessor :resource
+
+          def initialize(resource)
+            @resource = resource
+          end
+
+          def to_text
+            if @resource.nil?
+              'nil'
+            else
+              @resource.to_s
+            end
+          end
+        end
+
+        # @overload parent()
+        #   Get the parent resource for this child. This may be nil if the
+        #   resource is set to parent_optional = true.
+        #   @return [Chef::Resource, nil]
+        # @overload parent(val)
+        #   Set the parent resource. The parent can be set as  resource
+        #   object, a string (either a bare resource name or a type[name]
+        #   string), or a type:name hash.
+        #   @param val [String, Hash, Chef::Resource] Parent resource to set.
+        #   @return [Chef::Resource, nil]
+        def parent(val=nil)
+          _parent(:parent, self.class.parent_type, self.class.parent_optional, self.class.parent_auto, val)
+        end
+
+        # Register ourself with parents in case this is not a nested resource.
+        #
+        # @api private
+        def after_created
+          super
+          self.class.parent_attributes.each_key do |name|
+            parent = self.send(name)
+            parent.register_subresource(self) if parent
+          end
+        end
+
+        private
+
+        # Generic form of the parent getter/setter.
+        #
+        # @since 2.0.0
+        # @see #parent
+        def _parent(name, parent_type, parent_optional, parent_auto, val=nil)
+          # Allow using a DSL symbol as the parent type.
+          if parent_type.is_a?(Symbol)
+            parent_type = Chef::Resource.resource_for_node(parent_type, node)
+          end
+          # Grab the ivar for local use.
+          parent_ref = instance_variable_get(:"@#{name}")
+          if val
+            if val.is_a?(String) && !val.include?('[')
+              raise Poise::Error.new('Cannot use a string parent without defining a parent type') if parent_type == Chef::Resource
+              val = "#{parent_type.resource_name}[#{val}]"
+            end
+            if val.is_a?(String) || val.is_a?(Hash)
+              parent = @run_context.resource_collection.find(val)
+            else
+              parent = val
+            end
+            if !parent.is_a?(parent_type)
+              raise Poise::Error.new("Parent resource is not an instance of #{parent_type.name}: #{val.inspect}")
+            end
+            parent_ref = ParentRef.new(parent)
+          elsif !parent_ref
+            if parent_auto
+              # Automatic sibling lookup for sequential composition.
+              # Find the last instance of the parent class as the default parent.
+              # This is super flaky and should only be a last resort.
+              parent = Poise::Helpers::Subresources::DefaultContainers.find(parent_type, run_context)
+            end
+            # Can't find a valid parent, if it wasn't optional raise an error.
+            raise Poise::Error.new("No parent found for #{self}") unless parent || parent_optional
+            parent_ref = ParentRef.new(parent)
+          else
+            parent = parent_ref.resource
+          end
+          # Store the ivar back.
+          instance_variable_set(:"@#{name}", parent_ref)
+          # Return the actual resource.
+          parent
+        end
+
+        module ClassMethods
+          # @overload parent_type()
+          #   Get the class of the default parent link on this resource.
+          #   @return [Class, Symbol]
+          # @overload parent_type(type)
+          #   Set the class of the default parent link on this resource.
+          #   @param type [Class, Symbol] Class to set.
+          #   @return [Class, Symbol]
+          def parent_type(type=nil)
+            if type
+              raise Poise::Error.new("Parent type must be a class, symbol, or true, got #{type.inspect}") unless type.is_a?(Class) || type.is_a?(Symbol) || type == true
+              @parent_type = type
+            end
+            @parent_type || (superclass.respond_to?(:parent_type) ? superclass.parent_type : Chef::Resource)
+          end
+
+          # @overload parent_optional()
+          #   Get the optional mode for the default parent link on this resource.
+          #   @return [Boolean]
+          # @overload parent_optional(val)
+          #   Set the optional mode for the default parent link on this resource.
+          #   @param val [Boolean] Mode to set.
+          #   @return [Boolean]
+          def parent_optional(val=nil)
+            unless val.nil?
+              @parent_optional = val
+            end
+            if @parent_optional.nil?
+              superclass.respond_to?(:parent_optional) ? superclass.parent_optional : false
+            else
+              @parent_optional
+            end
+          end
+
+          # @overload parent_auto()
+          #   Get the auto-detect mode for the default parent link on this resource.
+          #   @return [Boolean]
+          # @overload parent_auto(val)
+          #   Set the auto-detect mode for the default parent link on this resource.
+          #   @param val [Boolean] Mode to set.
+          #   @return [Boolean]
+          def parent_auto(val=nil)
+            unless val.nil?
+              @parent_auto = val
+            end
+            if @parent_auto.nil?
+              superclass.respond_to?(:parent_auto) ? superclass.parent_auto : true
+            else
+              @parent_auto
+            end
+          end
+
+          # Create a new kind of parent link.
+          #
+          # @since 2.0.0
+          # @param name [Symbol] Name of the relationship. This becomes a method
+          #   name on the resource instance.
+          # @param type [Class] Class of the parent.
+          # @param optional [Boolean] If the parent is optional.
+          # @param auto [Boolean] If the parent is auto-detected.
+          # @return [void]
+          def parent_attribute(name, type: Chef::Resource, optional: false, auto: true)
+            name = :"parent_#{name}"
+            (@parent_attributes ||= {})[name] = type
+            define_method(name) do |val=nil|
+              _parent(name, type, optional, auto, val)
+            end
+          end
+
+          # Return the name of all parent relationships on this class.
+          #
+          # @since 2.0.0
+          # @return [Hash<Symbol, Class>]
+          def parent_attributes
+            {}.tap do |attrs|
+              # Grab superclass's attributes if possible.
+              attrs.update(superclass.parent_attributes) if superclass.respond_to?(:parent_attributes)
+              # Local default parent.
+              attrs[:parent] = parent_type
+              # Extra locally defined parents.
+              attrs.update(@parent_attributes) if @parent_attributes
+              # Remove anything with the type set to true.
+              attrs.reject! {|name, type| type == true }
+            end
+          end
+
+          # @api private
+          def included(klass)
+            super
+            klass.extend(ClassMethods)
+          end
+        end
+
+        extend ClassMethods
+      end
+    end
+  end
+end

data/lib/poise/helpers/subresources/container.rb

@@ -0,0 +1,165 @@
+#
+# Copyright 2013-2015, Noah Kantrowitz
+#
+# 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/dsl/recipe'
+
+require 'poise/helpers/subcontext_block'
+require 'poise/helpers/subresources/default_containers'
+
+
+module Poise
+  module Helpers
+    module Subresources
+      # A resource mixin for subresource containers.
+      #
+      # @since 1.0.0
+      module Container
+        # A resource collection that has much more condensed text output. This
+        # is used to show the value of @subresources during Chef's error formatting.
+        # @api private
+        class NoPrintingResourceCollection < Chef::ResourceCollection
+          def to_text
+            "[#{all_resources.map(&:to_s).join(', ')}]"
+          end
+        end
+
+        include SubcontextBlock
+        include Chef::DSL::Recipe
+
+        attr_reader :subresources
+
+        def initialize(*args)
+          super
+          @subresources = NoPrintingResourceCollection.new
+        end
+
+        def after_created
+          super
+          # Register
+          Poise::Helpers::Subresources::DefaultContainers.register!(self, run_context)
+          unless @subresources.empty?
+            Chef::Log.debug("[#{self}] Adding subresources to collection:")
+            # Because after_create is run before adding the container to the resource collection
+            # we need to jump through some hoops to get it swapped into place.
+            self_ = self
+            order_fixer = Chef::Resource::RubyBlock.new('subresource_order_fixer', @run_context)
+            order_fixer.block do
+              collection = self_.run_context.resource_collection
+              # Delete the current container resource from its current position.
+              collection.all_resources.delete(self_)
+              # Replace the order fixer with the container so it runs before all
+              # subresources.
+              collection.all_resources[collection.iterator.position] = self_
+              # Hack for Chef 11 to reset the resources_by_name position too.
+              # @todo Remove this when I drop support for Chef 11.
+              if resources_by_name = collection.instance_variable_get(:@resources_by_name)
+                resources_by_name[self_.to_s] = collection.iterator.position
+              end
+              # Step back so we re-run the "current" resource, which is now the
+              # container.
+              collection.iterator.skip_back
+            end
+            @run_context.resource_collection.insert(order_fixer)
+            @subresources.each do |r|
+              Chef::Log.debug("   * #{r}")
+              @run_context.resource_collection.insert(r)
+            end
+          end
+        end
+
+        def declare_resource(type, name, created_at=nil, &block)
+          Chef::Log.debug("[#{self}] Creating subresource from #{type}(#{name})")
+          self_ = self
+          # Used to break block context, non-local return from subcontext_block.
+          resource = []
+          # Grab the caller so we can make the subresource look like it comes from
+          # correct place.
+          created_at ||= caller[0]
+          # Run this inside a subcontext to avoid adding to the current resource collection.
+          # It will end up added later, indirected via @subresources to ensure ordering.
+          subcontext_block do
+            namespace = if self.class.container_namespace == true
+              # If the value is true, use the name of the container resource.
+              self.name
+            elsif self.class.container_namespace.is_a?(Proc)
+              instance_eval(&self.class.container_namespace)
+            else
+              self.class.container_namespace
+            end
+            sub_name = if name && !name.empty?
+              if namespace
+                "#{namespace}::#{name}"
+              else
+                name
+              end
+            else
+              # If you pass in nil or '', you just get the namespace or parent name.
+              namespace || self.name
+            end
+            resource << super(type, sub_name, created_at) do
+              # Apply the correct parent before anything else so it is available
+              # in after_created for the subresource.
+              parent(self_) if respond_to?(:parent)
+              # Run the resource block.
+              instance_exec(&block) if block
+            end
+          end
+          # Try and add to subresources. For normal subresources this is handled
+          # in the after_created.
+          register_subresource(resource.first) if resource.first
+          # Return whatever we have
+          resource.first
+        end
+
+        def register_subresource(resource)
+          subresources.lookup(resource)
+        rescue Chef::Exceptions::ResourceNotFound
+          Chef::Log.debug("[#{self}] Adding #{resource} to subresources")
+          subresources.insert(resource)
+        end
+
+        private
+
+        # Thanks Array.flatten, big help you are. Specifically the
+        # method_missing in the recipe DSL will make a flatten on an array of
+        # resources fail, so make this safe.
+        def to_ary
+          nil
+        end
+
+        # @!classmethods
+        module ClassMethods
+          def container_namespace(val=nil)
+            @container_namespace = val unless val.nil?
+            if @container_namespace.nil?
+              # Not set here, look at the superclass of true by default for backwards compat.
+              superclass.respond_to?(:container_namespace) ? superclass.container_namespace : true
+            else
+              @container_namespace
+            end
+          end
+
+          def included(klass)
+            super
+            klass.extend(ClassMethods)
+          end
+        end
+
+        extend ClassMethods
+      end
+    end
+  end
+end