sparkle_formation 2.0.2 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: cbb4f29d2f9a0a89eab9ce978f32c653324714e5
-  data.tar.gz: 8cd5b31636c808b98590f80f94611d1bad9b1095
+  metadata.gz: 7ed2f1e3bec855db611f4a8fcd7c3e3c509aa209
+  data.tar.gz: d6dc132ef582d52c55080c4a4e80d60fbb28c702
 SHA512:
-  metadata.gz: 19eeadefa0b8119e8fe5dd9422950c5a18a707edad34ea4b7e867f322570ab1c5e12aea13e0a04f4cc1c1ac5640fe3030b89096a87fbd6b2ec247cca92ff7881
-  data.tar.gz: c6a22c34f4f5de2cb35e039d538a7880205fbe3882c470e26c136713ebf6f5cbc4bbaa4789497230960dee1dc74d69bd7af83d380d3045477cb5f96791171e5b
+  metadata.gz: 09bd692653d5f7816a332fc2d7f772760bac7e13e34e8314518f99ec48604146a5c8bdf5ce3a321a4599307dcbf6b5673800979a9497c75e708722772882c4c0
+  data.tar.gz: e4958183360a572b03aff5ebeab2a9c2ea6db984f8db91bb146b0d26b59665290096a43a0d05e425ecdcfd6c096bb080205a25c3e44f0ce798f34632a9affe4e

data/CHANGELOG.md

@@ -1,3 +1,8 @@
+# v2.1.0
+* Add template inheritance support (#145)
+* Add layer merging support for templates, components, and dynamics (#145)
+* Update allowed Ruby constraint to require version greater than or equal to 2.1
+
 # v2.0.2
 * Provide useful return value from `#dynamic!` (#137)
 * Implement proper Azure resource generator (#141)

data/docs/building-blocks.md

@@ -205,7 +205,7 @@ the `dynamic!` call:
 ~~~ruby
 SparkleFormation.new(:with_namespace) do
   dynamic!(:aws_opsworks_instance, :foobar,
-    :resource_suffix_name => :instance
+    :resource_name_suffix => :instance
   )
 end
 ~~~

data/docs/inheritance-merging.md

@@ -0,0 +1,159 @@
+---
+title: "Inheritance and Merging"
+category: "dsl"
+weight: 8
+anchors:
+  - title: "Template Inheritance"
+    url: "#template-inheritance"
+  - title: "Template Merging"
+    url: "#template-merging"
+  - title: "Component and Dynamic Merging"
+    url: "#component-and-dynamic-merging"
+  - title: "Registry Items"
+    url: "#registry-items"
+---
+
+## Inheritance and Merging
+
+SparkleFormation includes functionality allowing SparklePacks to
+interact with previous layers when a file is requested from the
+collection. This functionality makes it easy to slightly modify
+files provided within previously registered SparklePacks without
+having to recreate the entire contents of the file. It also allows
+for creation of new templates based on existing templates.
+
+### Template Inheritance
+
+Template inheritance allows a new template to inherit the data structures
+of an existing template. For example, lets start with a simple template:
+
+~~~ruby
+SparkleFormation.new(:simple) do
+  simple_template true
+end
+~~~
+
+The dumped result of this template is:
+
+~~~json
+{
+  "SimpleTemplate": true
+}
+~~~
+
+Suppose that we wanted create a new template that was composed of everything
+described in the `simple` template, but had an extra addition. Instead of
+re-creating the contents in a new file, or attempting to break out components
+or dynamics that may not be ideal, we can inherit the template instead:
+
+~~~ruby
+SparkleFormation.new(:advanced, :inherit => :simple) do
+  advanced.item 'added'
+end
+~~~
+
+When this template is dumped, it will inherit the `simple` template and
+add on to the resultant data structure giving the result:
+
+~~~json
+{
+  "SimpleTemplate": true,
+  "Advanced": {
+    "Item": "added"
+  }
+}
+~~~
+
+Inheritance is not restricted to templates at a common level. A new
+template can inherit templates provided by SparklePacks.
+
+### Template Merging
+
+Template merging is only applicable when SparklePacks are in use. Template
+merging allows direct modification of a specific named template. This strategy
+is extremely useful when packs may be layering functionality into a template,
+or the root pack wants to make a specific adjustment without creating a new
+template.
+
+The default behavior of SparkleFormation when a SparklePack provides a template with
+the same name as a previously loaded SparklePack, it will overwrite the original
+template. In some cases, this may not be the desired effect. If a pack would like
+to make a simple adjustment to the template, this would require duplicating the
+contents of the original template and appending the customization. Merging allows
+adding customization without recreation.
+
+Lets assume we have a core SparklePack loaded and it provides us with the `simple`
+template:
+
+~~~ruby
+SparkleFormation.new(:simple) do
+  simple_template true
+end
+~~~
+
+Now in our root SparklePack we want to make an adjustment to the `simple` template
+directly. We can do this by merging:
+
+~~~ruby
+SparkleFormation.new(:simple, :layering => :merge) do
+  modifier 'spox'
+end
+~~~
+
+When we dump the `simple` template now we get:
+
+~~~json
+{
+  "SimpleTemplate": true,
+  "Modifier": "spox"
+}
+~~~
+
+This sort of merging make two strategies possible:
+
+1. Modifying the final result of a template for a specific need
+2. Modifying at serveral layers to allow SparklePacks to be additive
+
+### Component and Dynamic Merging
+
+Merging behavior for components and dynamics follows the same pattern as templates.
+Adding the `:layering => :merge` option will cause the item to be merged instead
+of overwritten.
+
+For components:
+
+~~~ruby
+SparkleFormation.component(:name, :layering => :merge)
+~~~
+
+and dynamics:
+
+~~~ruby
+SparkleFormation.dynamic(:name, :layering => :merge)
+~~~
+
+#### Dynamic return value
+
+The return value of a dynamic cannot be inferred. This is due to the freeform nature
+of dynamics leaving the resulting return value up to the author of the dynamic. When
+merging dynamics it can be easy to return the wrong value. The library _could_ take
+care of this and always return the context provided by the initial dynamic, but this
+behavior is problematic: merges could remove the original context, or may want to
+change the return context completely. Returning the proper value is left to the
+author, but SparkleFormation makes it easy to return the previous context.
+
+When the dynamics are merged, SparkleFormation will include an extra key in the
+options `Hash` for the dynamic: `:previous_layer_result`. Now a dynamic can merge
+in extra changes, and ensure the correct value is returned from the call:
+
+~~~ruby
+SparkleFormation.dynamic(:name, :layering => :merge) do |name, args={}|
+  new.things.added 'here'
+  args[:previous_layer_result]
+end
+~~~
+
+### Registry Items
+
+Registry items are exempt from the merging behavior described above. Registry items
+are always overwritten when redefined in higher level SparklePacks.

data/lib/sparkle_formation/error.rb

@@ -5,6 +5,9 @@ class SparkleFormation
   # SparkleFormation specific errors
   class Error < StandardError
 
+    # Inheritance error
+    class CircularInheritance < Error; end
+
     # File not found error
     class NotFound < KeyError
       attr_reader :name

data/lib/sparkle_formation/sparkle.rb

@@ -110,11 +110,14 @@ class SparkleFormation
               ).last
             end
 
-            def component(name, &block)
+            def component(name, args={}, &block)
               part_data[:component].push(
                 ::Smash.new(
                   :name => name,
                   :block => block,
+                  :args => Smash[
+                    args.map(&:to_a)
+                  ],
                   :type => :component
                 )
               ).last

data/lib/sparkle_formation/sparkle_collection.rb

@@ -6,6 +6,8 @@ class SparkleFormation
   # leak on long running processes with long lasting collections
   class SparkleCollection < Sparkle
 
+    autoload :Rainbow, 'sparkle_formation/sparkle_collection/rainbow'
+
     # Create a new collection of sparkles
     #
     # @return [self]
@@ -68,7 +70,10 @@ class SparkleFormation
       memoize("components_#{checksum}") do
         Smash.new.tap do |hsh|
           sparkles.each do |sprkl|
-            hsh.merge!(sprkl.components)
+            sprkl.components.each_pair do |c_name, c_value|
+              hsh[c_name] ||= Rainbow.new(c_name, :component)
+              hsh[c_name].add_layer(c_value)
+            end
           end
         end
       end
@@ -79,7 +84,10 @@ class SparkleFormation
       memoize("dynamics_#{checksum}") do
         Smash.new.tap do |hsh|
           sparkles.each do |sprkl|
-            hsh.merge!(sprkl.dynamics)
+            sprkl.dynamics.each_pair do |c_name, c_value|
+              hsh[c_name] ||= Rainbow.new(c_name, :dynamic)
+              hsh[c_name].add_layer(c_value)
+            end
           end
         end
       end
@@ -101,7 +109,10 @@ class SparkleFormation
       memoize("templates_#{checksum}") do
         Smash.new.tap do |hsh|
           sparkles.each do |sprkl|
-            hsh.merge!(sprkl.templates)
+            sprkl.templates.each_pair do |c_name, c_value|
+              hsh[c_name] ||= Rainbow.new(c_name, :template)
+              hsh[c_name].add_layer(c_value)
+            end
           end
         end
       end
@@ -113,20 +124,21 @@ class SparkleFormation
     # @param name [String, Symbol] name of item
     # @return [Smash] requested item
     # @raises [NameError, Error::NotFound]
-    def get(*args)
+    def get(type, name)
+      type_name = Sparkle::TYPES[type.to_s]
+      unless(type_name)
+        raise ArgumentError.new "Unknown file type requested from collection `#{type}`"
+      end
       result = nil
       error = nil
-      sparkles.each do |sprkl|
-        begin
-          result = sprkl.get(*args)
-        rescue Error::NotFound => error
-        end
-      end
-      if(result)
-        result
-      else
-        raise error
+      result = send(type_name)[name]
+      unless(result)
+        error_klass = Error::NotFound.const_get(
+          Bogo::Utility.camel(type)
+        )
+        raise error_klass.new(:name => name)
       end
+      result
     end
 
     protected

data/lib/sparkle_formation/sparkle_collection/rainbow.rb

@@ -0,0 +1,92 @@
+require 'sparkle_formation'
+require 'forwardable'
+
+class SparkleFormation
+
+  class SparkleCollection
+
+    # Contains a layered number of a specific item defined via
+    # a Sparkle. Items higher in the spectrum (greater layer index)
+    # have higher precedence than those below. This can be used for
+    # properly generating the end result based on merging or knockout rules.
+    class Rainbow
+
+      # Valid types for a rainbow
+      VALID_TYPES = [
+        :template,
+        :component,
+        :dynamic
+      ].freeze
+
+      extend Forwardable
+      def_delegators :top, *(Smash.public_instance_methods - Object.public_instance_methods)
+
+      # @return [String]
+      attr_reader :name
+      # @return [Symbol]
+      attr_reader :type
+      # @return [Array<Hash>]
+      attr_reader :spectrum
+
+      # Create a new rainbow
+      #
+      # @param name [String, Symbol] name of item
+      # @param type [String, Symbol] type of item
+      # @return [self]
+      def initialize(name, type)
+        unless(VALID_TYPES.include?(type.to_sym))
+          raise ArgumentError.new "Invalid type provdied for Rainbow instance `#{type}`"
+        end
+        @name = name.to_s
+        @type = type.to_sym
+        @spectrum = []
+      end
+
+      # Add a new layer to the top of the spectrum
+      #
+      # @param item [Hash]
+      # @return [self]
+      def add_layer(item)
+        unless(item.is_a?(Hash))
+          raise TypeError.new "Expecting type `Hash` but received type `#{item.class}`"
+        end
+        spectrum << item.to_smash
+        self
+      end
+
+      # Fetch item defined at given layer
+      #
+      # @param idx [Integer]
+      # @return [Hash]
+      def layer_at(idx)
+        if(idx <= spectrum.size)
+          spectrum.at(idx)
+        else
+          raise KeyError.new "Invalid layer requested for #{type} - #{name} (index: #{idx})"
+        end
+      end
+
+      # Generates a list of items to be processed in
+      # order to achieve the correct result based on
+      # expected merging behavior
+      #
+      # @return [Array<Hash>]
+      def monochrome
+        Array.new.tap do |result|
+          spectrum.each do |item|
+            unless(item.get(:args, :layering).to_s == 'merge')
+              result.clear
+            end
+            result << item
+          end
+        end
+      end
+
+      # @return [Hash]
+      def top
+        spectrum.last || {}
+      end
+    end
+
+  end
+end

data/lib/sparkle_formation/sparkle_formation.rb

@@ -94,11 +94,14 @@ class SparkleFormation
     # @return [Hashish, SparkleStruct]
     def compile(path, *args)
       opts = args.detect{|i| i.is_a?(Hash) } || {}
-      if(spath = (opts.delete(:sparkle_path) || SparkleFormation.sparkle_path))
-        container = Sparkle.new(:root => spath)
-        path = container.get(:template, path)[:path]
+      unless(path.is_a?(String) && File.file?(path.to_s))
+        if(spath = (opts.delete(:sparkle_path) || SparkleFormation.sparkle_path))
+          container = Sparkle.new(:root => spath)
+          path = container.get(:template, path)[:path]
+        end
       end
       formation = instance_eval(IO.read(path), path, 1)
+      formation.template_path = path
       if(args.delete(:sparkle))
         formation
       else
@@ -213,7 +216,17 @@ class SparkleFormation
       begin
         dyn = struct._self.sparkle.get(:dynamic, dynamic_name)
         raise dyn if dyn.is_a?(Exception)
-        result = struct.instance_exec(*args, &dyn[:block])
+        dyn.monochrome.each do |dynamic_item|
+          if(result)
+            opts = args.detect{|i| i.is_a?(Hash)}
+            if(opts)
+              opts[:previous_layer_result] = result
+            else
+              args.push(:previous_layer_result => result)
+            end
+          end
+          result = struct.instance_exec(*args, &dynamic_item[:block])
+        end
         if(block_given?)
           result.instance_exec(&block)
         end
@@ -364,6 +377,10 @@ class SparkleFormation
   attr_reader :provider
   # @return [Class] Provider resources
   attr_reader :provider_resources
+  # @return [String] local path to template
+  attr_accessor :template_path
+  # @return [Array<String>] black listed templates
+  attr_reader :blacklisted_templates
 
   # Create new instance
   #
@@ -379,19 +396,23 @@ class SparkleFormation
   def initialize(name, options={}, &block)
     @name = name.to_sym
     @component_paths = []
-    @sparkle = SparkleCollection.new
-    @sparkle.set_root(
-      Sparkle.new(
-        Smash.new.tap{|h|
-          s_path = options.fetch(:sparkle_path,
-            self.class.custom_paths[:sparkle_path]
-          )
-          if(s_path)
-            h[:root] = s_path
-          end
-        }
+    if(options[:sparkle_collection])
+      @sparkle = options[:sparkle_collection]
+    else
+      @sparkle = SparkleCollection.new
+      @sparkle.set_root(
+        Sparkle.new(
+          Smash.new.tap{|h|
+            s_path = options.fetch(:sparkle_path,
+              self.class.custom_paths[:sparkle_path]
+            )
+            if(s_path)
+              h[:root] = s_path
+            end
+          }
+        )
       )
-    )
+    end
     self.provider = options.fetch(:provider, @parent ? @parent.provider : :aws)
     if(provider == :aws || !options[:disable_aws_builtins])
       require 'sparkle_formation/aws'
@@ -405,16 +426,105 @@ class SparkleFormation
       stack_resource_type,
       *options.fetch(:stack_resource_types, [])
     ].compact.uniq
+    @blacklisted_templates = [name]
     @components = Smash.new
     @load_order = []
     @overrides = []
     @parent = options[:parent]
+    @seed = Smash.new(
+      :inherit => options[:inherit],
+      :layering => options[:layering]
+    )
     if(block)
       load_block(block)
     end
     @compiled = nil
   end
 
+  # @return [Array<Proc>]
+  def raw_overrides
+    @overrides
+  end
+
+  # Update underlying data structures based on inherit
+  # or layering behavior if defined for this template
+  #
+  # @param options [Hash]
+  # @return [self]
+  def seed_self
+    memoize(:seed) do
+      options = @seed
+      if(options[:inherit] && options[:layering].to_s == 'merge')
+        raise ArgumentError.new 'Cannot merge and inherit!'
+      end
+      if(options[:inherit])
+        inherit_from(options[:inherit])
+      elsif(options[:layering].to_s == 'merge')
+        merge_previous!
+      end
+      true
+    end
+    self
+  end
+
+  # Merge previous layer template structure
+  #
+  # @return [self]
+  def merge_previous!
+    my_index = sparkle.get(:template, name).spectrum.find_index do |item|
+      item[:path] == template_path
+    end
+    template = self.class.compile(sparkle.get(:template, name).layer_at(my_index - 1)[:path], :sparkle)
+    extract_template_data(template)
+  end
+
+  # Inhert template structure
+  #
+  # @param template_name [String] name of template to inherit
+  # @return [self]
+  def inherit_from(template_name)
+    if(blacklisted_templates.map(&:to_s).include?(template_name.to_s))
+      raise Error::CircularInheritance.new "Circular inheritance detected between templates `#{template_name}` and `#{name}`" # rubocop:disable Metrics/LineLength
+    end
+    template = self.class.compile(sparkle.get(:template, template_name)[:path], :sparkle)
+    template.blacklisted_templates.replace(
+      (template.blacklisted_templates + blacklisted_templates).map(&:to_s).uniq
+    )
+    extract_template_data(template)
+  end
+
+  # Extract information from given template and integrate with current instance
+  #
+  # @param template [SparkleFormation]
+  # @return [self]
+  def extract_template_data(template)
+    if(provider != template.provider)
+      raise TypeError.new "This template `#{name}` cannot inherit template `#{template.name}`! Provider mismatch: `#{provider}` != `#{template.provider}`" # rubocop:disable Metrics/LineLength
+    end
+    sparkle.size.times do |idx|
+      template.sparkle.add_sparkle(sparkle.sparkle_at(idx))
+    end
+    template.seed_self
+    blacklisted_templates.replace(
+      (blacklisted_templates + template.blacklisted_templates).map(&:to_s).uniq
+    )
+    @parameters = template.parameters
+    @overrides = template.raw_overrides + raw_overrides
+    new_components = template.components
+    new_load_order = template.load_order
+    load_order.each do |comp_key|
+      if(components[comp_key])
+        original_key = comp_key
+        comp_key = "#{comp_key}_#{Smash.new(:name => name, :path => template_path).checksum}_child"
+        new_components[comp_key] = components[original_key]
+      end
+      new_load_order << comp_key
+    end
+    @components = new_components
+    @load_order = new_load_order
+    self
+  end
+
   # @return [String] provider stack resource type
   def stack_resource_type
     DEFAULT_STACK_RESOURCE
@@ -536,11 +646,13 @@ class SparkleFormation
     args.each do |thing|
       key = File.basename(thing.to_s).sub('.rb', '')
       if(thing.is_a?(String))
+        # NOTE: This needs to be deprecated and removed
+        # TODO: deprecate
         components[key] = self.class.load_component(thing)
+        @load_order << key
       else
-        components[key] = sparkle.get(:component, thing)[:block]
+        @load_order << thing
       end
-      @load_order << key
     end
     self
   end
@@ -565,6 +677,9 @@ class SparkleFormation
       unmemoize(:compile)
     end
     memoize(:compile) do
+      # NOTE: this is where we inject inherit or layering
+      seed_self
+
       set_compile_time_parameters!
       if(provider && SparkleAttribute.const_defined?(camel(provider)))
         const = SparkleAttribute.const_get(camel(provider))
@@ -593,7 +708,13 @@ class SparkleFormation
         compiled.set_state!(compile_state)
       end
       @load_order.each do |key|
-        self.class.build(compiled, &components[key])
+        if(components[key])
+          self.class.build(compiled, &components[key])
+        else
+          sparkle.get(:component, key).monochrome.each do |component_block|
+            self.class.build(compiled, &component_block[:block])
+          end
+        end
       end
       @overrides.each do |override|
         if(override[:args] && !override[:args].empty?)

data/lib/sparkle_formation/version.rb

@@ -1,5 +1,5 @@
 # Unicorns and rainbows
 class SparkleFormation
   # Current library version
-  VERSION = Gem::Version.new('2.0.2')
+  VERSION = Gem::Version.new('2.1.0')
 end

data/sparkle_formation.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |s|
   s.description = 'Ruby DSL for programmatic orchestration API template generation'
   s.license = 'Apache-2.0'
   s.require_path = 'lib'
-  s.required_ruby_version = '>= 2.0'
+  s.required_ruby_version = '>= 2.1'
   s.add_runtime_dependency 'attribute_struct', '>= 0.3.0', '< 0.5'
   s.add_runtime_dependency 'multi_json'
   s.add_runtime_dependency 'bogo'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sparkle_formation
 version: !ruby/object:Gem::Version
-  version: 2.0.2
+  version: 2.1.0
 platform: ruby
 authors:
 - Chris Roberts
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-01-28 00:00:00.000000000 Z
+date: 2016-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: attribute_struct
@@ -158,6 +158,7 @@ files:
 - docs/building-blocks.md
 - docs/compile-time-parameters.md
 - docs/helper-methods.md
+- docs/inheritance-merging.md
 - docs/nested-stacks.md
 - docs/overview.md
 - docs/sparkle-packs.md
@@ -195,6 +196,7 @@ files:
 - lib/sparkle_formation/sparkle_attribute/heat.rb
 - lib/sparkle_formation/sparkle_attribute/rackspace.rb
 - lib/sparkle_formation/sparkle_collection.rb
+- lib/sparkle_formation/sparkle_collection/rainbow.rb
 - lib/sparkle_formation/sparkle_formation.rb
 - lib/sparkle_formation/sparkle_struct.rb
 - lib/sparkle_formation/translation.rb
@@ -215,7 +217,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.0'
+      version: '2.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="