chef-resource 0.2.2

data/files/lib/chef_resource/resource/resource_log.rb

@@ -0,0 +1,197 @@
+module ChefResource
+  module Resource
+    class ResourceLog
+      def initialize(resource)
+        @resource = resource
+      end
+      attr_reader :resource
+
+      # Keep track of descriptions of the current load/update/action
+      attr_accessor :current_load
+      attr_accessor :current_update
+      def current_load_values
+        @current_load_values ||= {}
+      end
+      def current_action_stack
+        @current_action_stack ||= []
+      end
+
+      def debug(str)
+        log(:debug, str)
+      end
+      def info(str)
+        log(:info, str)
+      end
+      def warn(str)
+        log(:warn, str)
+      end
+      def error(str)
+        log(:error, str)
+      end
+      def fatal(str)
+        log(:fatal, str)
+      end
+      def log(level, str)
+      end
+
+      #
+      # Resource phases
+      #
+
+      #
+      # Fired when the resource is created (but identity is not yet defined)
+      #
+      def created
+      end
+
+      #
+      # Fired when the resource identity is defined
+      #
+      def identity_defined
+      end
+
+      #
+      # Fired when the resource desired state is fully defined
+      #
+      def fully_defined
+      end
+
+      #
+      # Resource.load and load_value
+      #
+
+      #
+      # Fired when Resource.load starts
+      #
+      def load_started
+        self.current_load = true
+      end
+
+      #
+      # Fired when Resource.load succeeds
+      #
+      # @param exists if the resource exists, false if it doesn't
+      #
+      def load_succeeded(exists: true)
+        raise "load succeeded when load was never started!" if !current_load
+        self.current_load = false
+      end
+
+      #
+      # Fired when Resource.load fails.
+      #
+      # @param error The error that was raised.
+      #
+      def load_failed(error)
+        raise "load failed when load was never started!" if !current_load
+        self.current_load = false
+      end
+
+      #
+      # Fired when load_value for a given property starts
+      #
+      def load_value_started(name)
+        raise "load_value(#{name}) started twice!" if current_load_values[name]
+        self.current_load_values[name] = true
+      end
+
+      #
+      # Fired when load_value for a given property succeeds
+      #
+      # @param name The name of the property
+      #
+      def load_value_succeeded(name)
+        raise "load_value(name) succeeded but was never started!" if !current_load_values[name]
+        current_load_values.delete(name)
+      end
+
+      #
+      # Fired when Resource.load_value for a given property fails
+      #
+      # @param name The name of the property
+      # @param error The error that was raised
+      #
+      def load_value_failed(name, error)
+        raise "load_value(name) failed but was never started!" if !current_load_values[name]
+        current_load_values.delete(name)
+      end
+
+      #
+      # Resource.update and actions
+      #
+
+      #
+      # Fired when update starts.
+      #
+      def update_started
+        raise "update started twice!" if current_update
+        self.current_update = true
+      end
+
+      #
+      # Fired when the update succeeds.
+      #
+      def update_succeeded
+        raise "update succeeded, but was never started!" if !current_update
+        raise "update succeeded when actions are still running!" if !current_action_stack.empty?
+        self.current_update = nil
+      end
+
+      #
+      # Fired when the update fails.
+      #
+      # @param error [String] The error that was raised
+      #
+      def update_failed(error)
+        raise "update failed when no update is taking place!" if !current_update
+        self.current_action_stack.clear
+        self.current_update = nil
+      end
+
+      #
+      # Fired when an action is skipped due to why-run.
+      #
+      # @param description [String] A description of the action being taken.
+      #
+      def action_skipped(description, update_guaranteed: true)
+        raise "action started when no update is taking place!" if !current_update
+      end
+
+      #
+      # Fired when an action starts.
+      #
+      # @param description [String] A description of the action being taken.
+      # @param update_guaranteed [Boolean] Whether an update is guaranteed on success or not.
+      #
+      def action_started(description, update_guaranteed: true)
+        raise "action started when no update is taking place!" if !current_update
+        current_action_stack.push [ description, update_guaranteed ]
+      end
+
+      #
+      # Fired when an action succeeds.
+      #
+      # @param description [String] A more detailed description of what the action did.
+      # @param updated [Boolean] Whether anything was actually updated.
+      # @return [String, Boolean] The action that succeeded (a pair of [ description, updated ])
+      #
+      def action_succeeded(description: nil, updated: true)
+        raise "action succeeded when no action was started" if current_action_stack.empty?
+        original_description, _ = current_action_stack.pop
+        [ description || original_description, updated ]
+      end
+
+      #
+      # Fired when an action fails.
+      #
+      # @param error [String] The error that was raised.
+      # @return [String] The description of the action that failed.
+      #
+      def action_failed(error)
+        raise "action failed when no action was started" if current_action_stack.empty?
+        original_description, _ = current_action_stack.pop
+        original_description
+      end
+    end
+  end
+end

data/files/lib/chef_resource/resource/resource_type.rb

@@ -0,0 +1,74 @@
+require 'chef_resource/type'
+
+module ChefResource
+  module Resource
+    #
+    # The methods on a Resource class.  Generally extended into the class, and
+    # become class-level methods (Class.default(x))
+    #
+    module ResourceType
+      include Type
+
+      #
+      # Opens a resource for reading and updating.
+      #
+      # This method should be passed enough data to uniquely identify the
+      # resource so it can be retrieved.
+      #
+      # The resulting object is generally *lazily* loaded, and may not hit the
+      # network or file until you read a value.  This allows you to update
+      # values in some cases without incurring the cost of a read.
+      #
+      # @return An open Resource which:
+      # - Is a Resource
+      # - Is a Resource even if the actual value does not exist
+      # - Can be modified for update
+      # - `type.is_valid?(resource, resource)` is true
+      #
+      def open(&define_identity_block)
+        resource = new
+        resource.instance_eval(&define_identity_block)
+        resource.resource_identity_defined if resource.resource_state == :created
+        resource
+      end
+
+      #
+      # Gets the current value of a resource (immediately).  This method must
+      # be passed enough data to uniquely identify the resource so it can be
+      # retrieved.
+      #
+      # The default implementation (ResourceType.get) calls open(*args) { load }
+      #
+      # @return A readonly resource value with values filled in; or nil if the
+      # resource does not exist.
+      #
+      def get(*args, &define_identity_block)
+        resource = open(*args) do
+          instance_eval(&define_identity_block) if define_identity_block
+          load
+        end
+        resource.resource_fully_defined
+        resource
+      end
+
+      #
+      # Updates a resource.  By default, opens the resource, evaluates the
+      # block, and calls update().
+      #
+      # @param open_args Arguments to pass to open()
+      # @param update_block The block to run instance_eval on.
+      #
+      # @example
+      #   FileResource.update('/x/y.txt') do
+      #     mode 0777
+      #   end
+      #
+      def update(*open_args, &update_block)
+        resource = open(*args)
+        resource.instance_eval(&update_block)
+        resource.resource_fully_defined
+        resource.update_resource
+      end
+    end
+  end
+end

data/files/lib/chef_resource/resource/struct_property.rb

@@ -0,0 +1,39 @@
+require 'chef_resource/simple_struct'
+
+module ChefResource
+  module Resource
+    #
+    # Struct properties all create a class for each property.  This is
+    # included in that class, and StructPropertyType is extended in that class.
+    #
+    module StructProperty
+      #
+      # The struct containing this property.
+      #
+      extend SimpleStruct
+      property :parent_struct
+
+      #
+      # The actual value defaults to parent.current_resource.attr_name.  If
+      # parent.current_resource is `nil`, current_resource defaults to `nil`.
+      #
+      def current_resource
+        actual_struct = parent_struct.current_resource
+        actual_struct.public_send(self.class.property_name) if actual_struct
+      end
+
+      #
+      # This property exists if its parent does.
+      #
+      def resource_exists?
+        parent_struct.resource_exists?
+      end
+
+      protected
+
+      def initialize(parent_struct)
+        self.parent_struct = parent_struct
+      end
+    end
+  end
+end

data/files/lib/chef_resource/resource/struct_property_type.rb

@@ -0,0 +1,185 @@
+require 'chef_resource/type'
+require 'chef_resource/simple_struct'
+
+module ChefResource
+  module Resource
+    #
+    # Struct properties all create a class for each property.  This is
+    # included in that class, and StructPropertyType is extended in that class.
+    #
+    module StructPropertyType
+      include Type
+
+      extend SimpleStruct
+
+      #
+      # The name of this property
+      #
+      property :property_name
+
+      #
+      # The type of this property
+      #
+      property :property_type
+
+      #
+      # The parent type (struct type) of this property
+      #
+      property :property_parent_type
+
+      #
+      # True if this is an identity property.
+      #
+      boolean_property :identity
+
+      #
+      # True if this property is required.
+      #
+      # Required identity properties can be specified positionally in `open`,
+      # like so: `FileResource.open('/x/y.txt')` is equivalent to
+      # `FileResource.open(path: '/x/y.txt')`
+      #
+      # By default, this is false for most properties, but true for identity
+      # properties that have no default set.
+      #
+      boolean_property :required, default: "identity? && !defined?(@default)"
+
+      #
+      # A block which loads the property from reality.
+      #
+      # @param value The load proc.  If this is a LazyProc, the block will
+      #   be run in the context of the struct (`struct.instance_eval`) unless
+      #   the block is explicitly set to `should_instance_eval: false`.  If it is not,
+      #   it will always be instance_eval'd.
+      #
+      block_property :load_value
+
+      #
+      # Return a value of this type by coercion or construction.
+      #
+      # @param args The value to coerce or the values to construct with.
+      # @return A value of this Type.
+      #
+      def coerce(parent, *args)
+        property_type.is_a?(ResourceType) ? property_type.coerce(*args) : super
+      end
+
+      #
+      # Emit property methods into the struct class (property_parent_type)
+      #
+      def emit_property_methods
+        name = property_name
+        class_name = CamelCase.from_snake_case(name)
+        property_parent_type.class_eval <<-EOM, __FILE__, __LINE__+1
+          def #{name}(*args)
+            if args.empty?
+              #{class_name}.get_property(self)
+            else
+              #{class_name}.set_property(self, *args)
+            end
+          end
+        EOM
+
+        property_parent_type.class_eval <<-EOM, __FILE__, __LINE__+1
+          def #{name}=(value)
+            #{class_name}.set_property(self, value)
+          end
+        EOM
+      end
+
+      #
+      # Set the property value.
+      #
+      def set_property(struct, *args)
+        if identity?
+          if struct.resource_state && struct.resource_state != :created
+            raise PropertyDefinedError.new("Cannot modify identity property #{property_name} of #{struct.class}: identity properties cannot be modified after the resource's identity is defined.  (State: #{struct.resource_state})", struct, self)
+          end
+        else
+          if struct.resource_state && struct.resource_state != :created && struct.resource_state != :identity_defined
+            raise PropertyDefinedError.new("Cannot modify property #{property_name} of #{struct.class}: identity properties cannot be modified after the resource's identity is defined.  (State: #{struct.resource_state})", struct, self)
+          end
+        end
+        if args.size == 1 && args[0].is_a?(ChefResource::LazyProc)
+          struct.explicit_property_values[property_name] = args[0]
+        else
+          struct.explicit_property_values[property_name] = coerce(struct, *args)
+        end
+      end
+
+      #
+      # Get the property value from the struct.
+      #
+      # First tries to get the desired value.  If there is none, tries to get
+      # the actual value from the struct.  If the actual value doesn't have
+      # the value, it looks for a load_value method.  Finally, if that isn't
+      # there, it runs default.
+      #
+      def get_property(struct)
+        value = struct.explicit_property_values.fetch(property_name) do
+          return current_property_value(struct)
+        end
+        coerce_to_user(struct, value)
+      end
+
+      #
+      # Get the current property value from the struct (i.e. the value not
+      # counting anything the user has actually set--including actual value
+      # and default value).
+      #
+      # @param struct The struct we're loading from
+      #
+      def current_property_value(struct)
+        # Try to grab a known (non-default) value from current_resource
+        has_value, value = explicit_current_property_value(struct)
+        if !has_value
+          value = default(parent: struct)
+        end
+        coerce_to_user(struct, value)
+      end
+
+      #
+      # Ensure the current value of the property is loaded and set.
+      #
+      # @param struct The struct we're loading from
+      # @return [Boolean, Value] `true, <value>` if the current_resource exists and has that explicit value, `false, nil` if not
+      # @raise Any error raised by load_value or load will pass through.
+      #
+      def explicit_current_property_value(struct)
+        # First get current_struct
+        current_struct = struct.is_current_resource? ? struct : struct.current_resource
+        if !current_struct
+          return [ false, nil ]
+        end
+
+        # First, check quickly if we already have it.
+        if current_struct.explicit_property_values.has_key?(property_name)
+          return [ true, current_struct.public_send(property_name) ]
+        end
+
+        if current_struct.resource_exists?
+          # Since we were already brought up, we must already be loaded, yet the
+          # property isn't there.  Use load_value if it has it.
+          if !load_value
+            return [ false, nil ]
+          end
+
+          struct.log.load_value_started(property_name)
+
+          begin
+            value = load_value.get(instance: current_struct, instance_eval_by_default: true)
+            # Set the value (if it gets coerced, catch the result)
+            value = current_struct.public_send(property_name, value)
+            struct.log.load_value_succeeded(property_name)
+            return [ true, value ]
+          rescue
+            # short circuit this from happening again
+            current_struct.explicit_property_values[property_name] = nil
+            struct.log.load_value_failed(property_name, $!)
+            raise
+          end
+        end
+      end
+    end
+  end
+end